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

Before you can accept OXXO payments, you will need to arrange an agreement with our OXXO 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 our other dLocal payment method, Boleto Bancário, you can use the same credentials.

Process an OXXO payment

For OXXO payments, funds are settled directly from dLocal to your account, with Checkout.com acting as a gateway.

You can process an OXXO payment in two steps:

  1. Request an OXXO payment
  2. Redirect the customer

Step 1: Request an OXXO payment

The request

Use the details below to set up your request.

Endpoints

Live

https://api.checkout.com/payments

Sandbox

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

Header parameters

Header
Value

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 name
Description

amount
Integer
required

The payment amount

currency
String
required

The three-letter ISO 4217 currency code. Set this to MXN.

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 OXXO integration. Set this to redirect.

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 payer

source.payer.name
String
required

The payer's full name
<= 100 characters

source.payer.email
String
required

The payer's email address
<= 100 characters

source.payer.document
String
required

The payer's unique identification code in Mexico (CURP)
<= 100 characters

Request example

{
  "amount": 100,
  "currency": "MXN",
  "source": {
    "type": "oxxo",
    "integration_type": "redirect",
    "country": "MX",
    "payer": {
      "name": "Bruce Wayne",
      "email": "[email protected]",
      "document": "WAKB700101HMCYNR06"
    }
  }
}

The response

If you receive a 202 Success response with a status field set to Pending, your request was successful.

Response example

{
  "id": "pay_zk4yjue6o2qennaq6x7bt74s5y",
  "status": "Pending",
  "customer": {
    "id": "cus_yhxfa2zmp37urkzkf6zm2mnk4e"
  },
  "_links": {
    "self": {
      "href": "https://qa.ckotech.co/gateway/payments/pay_zk4yjue6o2qennaq6x7bt74s5y"
    },
    "redirect": {
      "href": "https://sandbox.dlocal.com/collect/pay/pay/M-0fca0430-1b2c-11ea-8d66-7fb82c3fe391?xtid=CATH-ST-1575968664-146277466"
    }
  }
}

Step 2: Redirect the customer

Redirect your customer to the redirect link’s href in the response. The customer will be redirected to an OXXO ticket page and presented with a barcode they can use to make a cash payment in an OXXO store. They can then return to your store's success page (or failure page, if the payment has expired).

If the payment is successful, you'll get a payment_captured webhook notification. If it's not, you'll be notified by a payment_expired webhook.

OXXO payment requests expire after seven days, by default.

Get details about an OXXO payment

Use the payment_id found in the payment response, or the cko-session-id from the success/failure URL (e.g., https://www.checkout.com/order/succeeded?cko-session-id=sid_vii64oquze5u3h2x6hh4rurc4y) to retrieve details about the payment.

The request

Use the details below to set up your request.

Endpoint

Live

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

Sandbox

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

Header and path parameters

Header
Value

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

Path
Value

payment_id
Required

The payment ID, found in the payment response, or the session ID from the success/failure URL.

The response

Response example

{
  "id": "pay_zk4yjue6o2qennaq6x7bt74s5y",
  "requested_on": "2019-12-10T09:04:24Z",
  "source": {
    "type": "oxxo"
  },
  "amount": 100,
  "currency": "MXN",
  "payment_type": "Regular",
  "status": "Captured",
  "approved": true,
  "risk": {
    "flagged": false
  },
  "customer": {
    "id": "cus_yhxfa2zmp37urkzkf6zm2mnk4e"
  },
  "_links": {
    "self": {
      "href": "https://qa.ckotech.co/gateway/payments/pay_zk4yjue6o2qennaq6x7bt74s5y"
    },
    "actions": {
      "href": "https://qa.ckotech.co/gateway/payments/pay_zk4yjue6o2qennaq6x7bt74s5y/actions"
    },
    "refund": {
      "href": "https://qa.ckotech.co/gateway/payments/pay_zk4yjue6o2qennaq6x7bt74s5y/refunds"
    }
  }
}

OXXO refunds and chargebacks

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

The customer will be contacted directly to complete the refund, and then the payment status will update to refunded and you will receive a payment_refunded (or payment_refund_declined, if unsuccessful) webhook notification.

There is no chargeback mechanism for OXXO.

OXXO webhooks

When using OXXO, you may receive the following webhooks.

Webhook
Description

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.
  1. Create an OXXO transaction as above, following the redirect link in the response to OXXO's website.

  2. Click PAY.

  3. Click RETURN.

  4. You should then be redirected to your predefined success page.

Testing OXXO refunds
To test a refund, create a refund request in sandbox with our API as normal, and then contact the dLocal team so they can complete the process from their side. You will then receive a payment_refunded notification.

Can we help?

Thanks for using Checkout.com. If you need help or have a question, message our support team at [email protected].

Updated 7 days ago

OXXO


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.