OXXO

Start accepting OXXO payments, a popular offline cash payment voucher system in Mexico.

If you want to use a gateway model for accepting OXXO payments, you will need to arrange an agreement with our provider, dLocal, and create merchant details (specifically, x_login and x_trans_key) and a secret key with them. Share these details with our customer support team and we'll get you up and running. If you have already been onboarded for one of our other dLocal payment methods, you can use the same credentials.

Overview

OXXO can be used by either redirecting the customer to a statically hosted ticket (redirect integration method) or by rendering the complete ticket within your own checkout flow (direct integration method).

Payments follow a two-step process:

  1. Request payment
  2. Redirect the customer or render the ticket

Step 1: Request payment 

The POST request

Use the details below to set up your request.

Endpoints

https://api.checkout.com/payments
https://api.sandbox.checkout.com/payments

Header parameters

HeaderValue

Authorization

REQUIRED

secret key

Use the valid secret key of your Checkout.com account. You can find this in the Hub.

Content-Type

REQUIRED

application/json

Body parameters

Field nameDescription

source

OBJECT

REQUIRED

Details about the payment source.

source.type

STRING

REQUIRED

The type of payment source. Set this to oxxo.

source.integration_type

STRING

REQUIRED

The type of integration. Either direct or redirect.

  • direct: a ticket object is returned, which you can use to render a ticket to the customer. No redirect URL is returned.
  • redirect: a redirect URL is returned. Redirect the customer to this URL to proceed with the payment.

source.country

STRING

REQUIRED

The two-letter ISO country code of the country in which the payment instrument is issued/operated. Set this to MX.

source.payer

STRING

REQUIRED

Details about the customer.

source.payer.name

STRING

REQUIRED

The customer's full name.


source.payer.email

STRING

REQUIRED

The customer's email address.

source.payer.document

STRING

REQUIRED

The customer's Mexican personal identity code, specifically the Unique Population Registry Code (CURP).

source.description

STRING

OPTIONAL

A description of the payment.

amount

INTEGER

REQUIRED

The payment amount.

currency

STRING

REQUIRED

The currency in which the payment is being made (three-letter ISO 4217 code). Set this to MXN.

Request example

{
  "source": {
    "type": "oxxo",
    "integration_type": "redirect",
    "country": "MX",
    "payer": {
      "name": "Bruce Wayne",
      "email": "bruce@wayne-enterprises.com",
      "document": "WAKB700101HMCYNR06"
    },
    "description": "simulate OXXO Demo Payment"
  },
  "amount": 100,
  "currency": "MXN"
}
{
  "source": {
    "type": "oxxo",
    "integration_type": "direct",
    "country": "MX",
    "payer": {
      "name": "Bruce Wayne",
      "email": "bruce@wayne-enterprises.com",
      "document": "WAKB700101HMCYNR06"
    },
    "description": "simulate OXXO Demo Payment"
  },
  "amount": 100,
  "currency": "MXN"
}

The POST response

Whether you used the direct or redirect method, you should get a 202 response with the status field set to Pending. This means your request has been accepted.

Response example

{
  "id": "pay_r2vanwtizkeedc5fesx7ydvdzu",
  "status": "Pending",
  "customer": {
    "id": "cus_oxgvscbkycweplf4pvwhedyeg4"
  },
  "_links": {
    "self": {
      "href": "https://api.sandbox.checkout.com/payments/pay_r2vanwtizkeedc5fesx7ydvdzu"
    },
    "redirect": {
      "href": "https://sandbox.dlocal.com/collect/pay/pay/M-4e296cdd-5c0d-4a05-9ae5-850c85a822d6?xtid=CATH-ST-1587996829-1977060731"
    },
    "simulator:payment-succeed": {
      "href": "http://sb-gateway-internal.cko.lon/dlocal-internal/oxxo/payments/pay_r2vanwtizkeedc5fesx7ydvdzu/succeed"
    },
    "simulator:payment-expire": {
      "href": "http://sb-gateway-internal.cko.lon/dlocal-internal/oxxo/payments/pay_r2vanwtizkeedc5fesx7ydvdzu/expire"
    }
  }
}
{
  "id": "pay_gxw65fs6rijepgn4rb5tqqvp5u",
  "status": "Pending",
  "customer": {
    "id": "cus_6unw4ulqvrlenduk4xiurlbiyq"
  },
  "_links": {
    "self": {
      "href": "https://api.sandbox.checkout.com/payments/pay_gxw65fs6rijepgn4rb5tqqvp5u"
    }
  }
}

Step 2: Redirect the customer or render the ticket 

To complete the payment, you need to provide the customer with a OXXO ticket by following one of two flows:

Redirect the customer 

When using the redirect integration method, make sure your customer is aware that they will be redirected to the ticket page when they click your "Pay now" button, and that they should print or save the ticket.

Using the redirection URL returned in the response above via _links.redirect, redirect your customer to the static, hosted OXXO ticket page. Once redirected, your customer should save or print the ticket.

A button on the page will allow them to return to your shop:

  • If the ticket is still valid, they will be redirected to your success URL.
  • If the ticket has expired, they will be redirected to your failure URL.

Your payment confirmation page should make it clear to the customer that their purchase has not yet been completed. Explain that it has been reserved and is pending payment before the order can be completed and the goods/services can be delivered.

Render the OXXO ticket 

Redirect your customer to your payment confirmation page, where you should summarize their order and render the OXXO ticket so they can complete the payment.

Your payment confirmation page should make it clear to the customer that their purchase has not yet been completed. Explain that it has been reserved and is pending payment before the order can be completed and the goods/services can be delivered.

To get the components necessary to render the ticket, use the 'get payment details' endpoint below. This will return a ticket object which contains the components to display the ticket.

Tips for displaying the ticket:

  • Separate the ticket number into three groups, like this: four digits - five digits - five digits. It makes it easier for customers to dictate it to cashiers.
  • Include the currency and amount on the ticket.
  • Make sure the expiry date is clear and visible, and use the dd/mm/yyyy format.
  • Include payment instructions to help customers unfamiliar with the payment process.
  • store locator is a helpful feature. Just link it to google.com/maps/search/oxxo/.
  • Include a download button so customers can easily save the ticket on their phone.
  • Include a print button for customers who want to print their ticket.

Here's an example:


Get details about a payment 

Using the following endpoint, pass the payment id (for example, pay_hcklpcd45ymepcr7thciirbdaa) from the payment response to get details about the payment.

The GET request

Use the details below to set up your request.

Endpoints

GEThttps://api.checkout.com/payments/{payment_id}
GEThttps://api.sandbox.checkout.com/payments/{payment_id}

Header and path parameters

HeaderValue

Authorization

REQUIRED

secret key

Use the valid secret key of your Checkout.com account. You can find this in the Hub.

Content-Type

REQUIRED

application/json
PathValue

payment_id

REQUIRED

The payment ID found in the response of the initial response

The GET response

The response will differ depending on which integration_type (redirect or direct) you used in the initial payment request.

Response examples

Redirect

{
  "id": "pay_r2vanwtizkeedc5fesx7ydvdzu",
  "requested_on": "2020-04-27T14:13:49Z",
  "source": {
    "type": "oxxo",
    "dlocal_order_id": "dd889cb7f3f1439a960ea165cb48b866",
    "dlocal_payment_id": "D-30150-fdb35d63-f86a-4593-9e43-349d63c37110",
    "integration_type": "redirect",
    "description": "simulate OXXO Demo Payment"
  },
  "amount": 100,
  "currency": "MXN",
  "payment_type": "Regular",
  "status": "Pending",
  "risk": {
    "flagged": false
  },
  "customer": {
    "id": "cus_oxgvscbkycweplf4pvwhedyeg4"
  },
  "_links": {
    "redirect": {
      "href": "https://sandbox.dlocal.com/collect/pay/pay/M-4e296cdd-5c0d-4a05-9ae5-850c85a822d6?xtid=CATH-ST-1587996829-1977060731"
    },
    "simulator:payment-succeed": {
      "href": "http://sb-gateway-internal.cko.lon/dlocal-internal/oxxo/payments/pay_r2vanwtizkeedc5fesx7ydvdzu/succeed"
    },
    "simulator:payment-expire": {
      "href": "http://sb-gateway-internal.cko.lon/dlocal-internal/oxxo/payments/pay_r2vanwtizkeedc5fesx7ydvdzu/expire"
    },
    "self": {
      "href": "https://api.sandbox.checkout.com/payments/pay_r2vanwtizkeedc5fesx7ydvdzu"
    }
  }
}
{
  "id": "pay_r2vanwtizkeedc5fesx7ydvdzu",
  "requested_on": "2020-04-27T14:13:49Z",
  "source": {
    "type": "oxxo",
    "dlocal_order_id": "dd889cb7f3f1439a960ea165cb48b866",
    "dlocal_payment_id": "D-30150-fdb35d63-f86a-4593-9e43-349d63c37110",
    "integration_type": "redirect",
    "description": "simulate OXXO Demo Payment"
  },
  "amount": 100,
  "currency": "MXN",
  "payment_type": "Regular",
  "status": "Captured",
  "approved": true,
  "risk": {
    "flagged": false
  },
  "customer": {
    "id": "cus_oxgvscbkycweplf4pvwhedyeg4"
  },
  "_links": {
    "self": {
      "href": "https://api.sandbox.checkout.com/payments/pay_r2vanwtizkeedc5fesx7ydvdzu"
    },
    "actions": {
      "href": "https://api.sandbox.checkout.com/payments/pay_r2vanwtizkeedc5fesx7ydvdzu/actions"
    },
    "refund": {
      "href": "https://api.sandbox.checkout.com/payments/pay_r2vanwtizkeedc5fesx7ydvdzu/refunds"
    }
  }
}

Direct

{
  "id": "pay_gxw65fs6rijepgn4rb5tqqvp5u",
  "requested_on": "2020-03-17T09:14:17Z",
  "source": {
    "type": "boleto",
    "dlocal_order_id": "c0e6cc2bf24c43c79fbbee55df293f5c",
    "dlocal_payment_id": "D-30150-e59f330d-4b92-487c-a09a-3307be2184b7",
    "ticket": {
      "type": "REFERENCE_CODE",
      "number": "9800-0004-8206-53",
      "expiration_date": "2020-02-10T23:59:00.000+0000",
      "image_url": "https://sandbox.dlocal.com/gmf/payments/M-cd028b60-4824-11ea-8d66-7fb82c3fe391"
    }
  },
  "amount": 100,
  "currency": "BRL",
  "payment_type": "Regular",
  "status": "Pending",
  "risk": {
    "flagged": false
  },
  "customer": {
    "id": "cus_6unw4ulqvrlenduk4xiurlbiyq"
  },
  "_links": {
    "self": {
      "href": "https://api.sandbox.checkout.com/payments/pay_gxw65fs6rijepgn4rb5tqqvp5u"
    }
  }
}


Refunds and chargebacks

Refund a payment

You can refund an OXXO payment using our refund API. Partial and multiple – as well as full – refunds are allowed.

The customer will get an email (the email address is taken from the source.payer.email property in the initial payment request) from dLocal asking for their banking details. Once the customer has provided their details, dLocal will transfer the money to the customer's bank account.

The payment status will update to refunded and you will receive a payment_refunded (or payment_refund_declined, if unsuccessful) webhook notification.

A refund processing fee may apply.

Chargebacks

There is no chargeback mechanism for OXXO.

Webhooks

When using OXXO, you may receive the following webhooks.

WebhooksDescription
payment_pending

Sent when a payment request is successfully initiated.

payment_capture_pending

Sent when the acquirer is in the process of accepting the payment.

payment_captured

Sent when the payment has been successfully approved.

payment_expired

Sent when the customer has failed to complete the payment.

payment_declined

Sent when there was a failure in creating the payment.

payment_refund_pending

Sent when a refund is successfully initiated.

payment_refunded

Sent when a refund is successfully processed.

payment_refund_declined

Sent when a refund is declined.

Testing OXXO

To start testing, you'll need to:

  • create a test account, and
  • contact your Customer Success manager or integrations engineer to activate OXXO payments in the sandbox environment.

In your sandbox environment, you can test payment capture and expiration, as well as refund success and failure.

In order to test these actions, pass the string "simulate" as part of the source.description field in the initial payment request.

When you do, you will receive additional hypermedia links in the _links object in the payment response and in the 'get payment details' response.

Use the URLs contained in the simulator:payment-succeedsimulator:payment-expiresimulator:refund-succeed and simulator:refund-fail hypermedia objects to simulate the respective action/state change on the test payment.

You can only test the redirect payment flow in sandbox.

Can we help?

Thanks for using Checkout.com. If you need help or have a question, message our Support team at support@checkout.com.