OxxoPay® Recurrent

1. Introduction 2

2. First Steps 2

3. Configure the library 3

4. Creation of the Customer 3

4.1 Create a client and his reference in a request 3

5. How to create a Webhook in your Admin. 5

6. Events 7
6.1 Events for validation and authorization 7
6.1.1 inbound_payment.lookup 8
6.1.2 inbound_payment.payment_attempt 9
6.1.3 Data types 10
6.2 charge.paid 11

7. Errors 13
7.1 Errors List 13

8. Tests in “sandbox” 14
8.1 Trigger the event inbound_payment.lookup 14
8.1.1 Example cURL 14
8.2Trigger the event inbound_payment.payment_attempt 15
8.1.1 Example cURL 15
8.3 Event charge.paid 15

Page 1 - Document version 1.0.0

1. Introduction

We created OXXO Pay® Recurrent so you can receive recurring payments from your
customers. In this way your clients will be able to pay the number of times they need, and you
authorize.

With OXXO Pay® Recurrent, each of your clients will have a unique reference to make several
payments using the same reference. In contrast, with OXXO Pay® your customers must
continue generating a reference for each purchase.

The flow is depicted in the next flow diagram:

2. First Steps

First you must create a Customer, which will have a personal and unique reference. With it your
client can go to an OXXO store to make the payment. Once at the store, the cashier will ask
your client for your reference and ask your client for the amount of money he wants to pay.
Conekta, together with your business, will validate the payment and when it’s done, we will
notify you in real time.

Consider that to implement OXXO Pay® Recurrent ​we need to be in constant

communication, through your webhooks to make the corresponding payment validation and
ask for authorization of the charges that your clients want to make. This will give you more
control over the flow of your customers' money.

Next we show you the new flow of OXXO Pay® Recurrent to start receiving money, remember
to have the support of a programmer for the implementation to be successful.

Page 2 - Document version 1.0.0

3. Configure the library
This implementation can be done in test mode (sandbox). However it is essential to have the
private key to launch into production mode. If you don’t change the test keys to production,
none of the transactions will be deposited in your real balance.

4. Creation of the Customer

After configuring the test keys and the API version, you must create an object: Customer which
will contain all the payment methods for each of your clients. You can also add a payment
method to an existing Customer.

4.1 Create a client and his reference in a request

// Create a customer with a reference.

curl -​H​ ​"Accept: application/vnd.conekta-v2.0.0+json"​ \

-​H​ ​"Content-type: application/json"​ \
-​u​ key_YOUR_PRIVATE_API_KEY: \
-X ​POST​ -​d​ '{
​"name"​: ​"Oxxo recc"​,
​"email"​: ​"user@example.com"​,
​"phone"​: ​"52134659439"​,
​"payment_sources"​: [{
​"type"​: ​"oxxo_recurrent",
​"expires_at"​: ​1553273553
}]
}' https:​//api.conekta.io/customers

Now you are ready to generate a unique reference per client. If your business has a mobile app,
remember to choose the bar code option as the main payment method. You must also activate
the numeric reference option, in case your client needs to dictate the number to the OXXO
cashier.

Page 3 - Document version 1.0.0

Response:
{
"livemode":​false​,
"name":​"Oxxo recc"​,
"email":​"user@example.com"​,
"phone":​"52134659439"​,
"id":​"cus_2jP5P8huCTWqcTtrn"​,
"object":​"customer"​,
"created_at":​1538686075​,
"corporate":​false​,
"custom_id":​""​,
"payment_sources":{
"object":​"list"​,
"has_more":​false​,
"total":​1​,
"data":[{
"id":​"off_ref_2jP5P8huCTWqcTtro"​,
"object":​"payment_source"​,
"type":​"oxxo_recurrent"​,
"provider":​"Oxxo"​,
"reference":​"99000000083594"​,
"barcode":​"99000000083594"​,
"barcode_url":​"https://sandbox_reference.png"​,
"expires_at":​0​,
"created_at":​1538686075​,
"parent_id":​"cus_2jP5P8huCTWqcTtrn"
}]
}}

Page 4 - Document version 1.0.0

5. How to create a Webhook in your Admin.
As we mentioned previously, our platform must be in constant communication with you through
Webhooks in order to:

1)​ Validate that the user's reference is correct and can make payments.
2)​ Approve the amount that the user wants to pay.
3)​ Notify a payment.

A Webhook is a system of notifications, where your web platform must define a URL, so that our
API sends HTTP requests and can notify you of the different events that we’re going to specify
later. Therefore, you must create a Webhook from your Admin. In this way you will be activating
the notification of events.

In the Admin. open the main menu of your account, located in the upper right corner, and select
the ​Webhooks​ section.

Page 5 - Document version 1.0.0

Within that section you will see a button named create webhook, when clicking a modal with a
form will be opened in which you’ll have to place the url of the webhook where you want to
receive the events of Oxxo Pay® Recurrent. You must fill it with your information paying
attention to the checkbox “Subscribe to Oxxo Pay® Recurrent events” (​Subscribir a eventos
de Oxxo Pay® Recurrent​.)

After creating a reference for your clients and adding a Webhook to your Admin, you will be
ready to receive payments.

Page 6 - Document version 1.0.0

6. Events
OXXO Pay® Recurrent sends three types of events for the different moments (which are
mentioned below) when your client tries to make a payment:

a. When your customers give the reference to the cashier of the OXXO stores, our platform
will communicate with your system to validate that the reference given by the user in
OXXO is correct, or if it’s a user that you have blocked, our API will send a notification to
the OXXO cashier and the user will not be able to make any charge.
b. After validating the reference, the OXXO cashier will ask your customer what amount
you wish to deposit. For this moment our platform will communicate again with your
system to confirm if you authorize this amount.
c. When you authorize the amount and your client makes the payment, finally our platform
will communicate to notify you that a payment has been made.

All this communication will be made through your webhooks which you must integrate from your
Admin account and format your response.

6.1 Events for validation and authorization

Event Type Description

inbound_payment.lookup This event notifies you that a user is in the OXXO

with the intention of paying and your validation is
needed to confirm the reference.

inbound_payment.payment_attempt With this event we’ll ask your authorization to

complete the payment.

charge.paid With this event we’ll notify you that the order has
been paid without setbacks.

Page 7 - Document version 1.0.0

6.1.1 inbound_payment.lookup

Upon receiving this event you’ll know that your customer at the OXXO store requesting a
payment and we must validate that the reference / client is valid and can continue with the
payment process, for which we’ll send you the relevant information of that user within the
payload of the event:
{
"object": {
"payment_method": {
"service_name": ​"OxxoPay"​,
"barcode_url":​"https://barcode/url.png"​,
"object": ​"cash_payment"​,
"type": ​"oxxo"​,
"expires_at": ​1541289600​,
"reference": ​"8400003726321"
},
"charge_id": ​"5bb675388a268e0ef4a56a42"​,
"livemode": ​true​,
"created_at": ​0​,
"object": ​"inbound_payment"​,
"amount": ​0​,
"currency": ​"MXN"​,
"fee": ​3480​,
"customer_id": ​"cus_2jP5P8huCTWqcTtrn"
},
"previous_attributes": {}
"livemode": ​true​,
"webhook_status": ​"not_applicable"​,
"webhook_logs": [],
"id": ​"5b438f82583eb80d50b4652c"​,
"object": ​"event"​,
"type": ​"inbound_payment.lookup"​,
"created_at": ​1531154306
}

When your platform receives this event, you must answer with the approval of the validation of
the reference with the following format:
{
"payable": ​true​,
"min_amount": ​5000​,
"max_amount": ​1000000,
}

Page 8 - Document version 1.0.0

 Parameter Type Description

payable boolean This property tells us if the validation of this reference ended
successfully or not.

min_amount integer The minimum amount that the user can pay.

max_amount integer The maximum amount that the user can pay.

Once the reference has been validated, your client can proceed to pay and you will receive the
event inbound_payment.payment_attempt.

6.1.2 inbound_payment.payment_attempt
Upon receiving this event you will know that there’s a customer trying to pay at an Oxxo store
and you must give authorization for the payment. In this event you’ll receive the amount that the
user wishes to deposit.

{
"data": {
"object": {
"payment_method": {
"service_name": ​"OxxoPay"​,
"barcode_url":
"https://s3.amazonaws.com/cash_payment_barcodes/84000045432316.png"​,
"object": ​"cash_payment"​,
"type": ​"oxxo"​,
"expires_at": ​1541289600​,
"reference": ​"84000045432316"
},
"charge_id": ​"5bb6755d8a268e0ed9a56acb"​,
"livemode": ​true​,
"created_at": ​1538684253​,
"object": ​"inbound_payment"​,
"amount": ​110700​,
"currency": ​"MXN"​,
"fee": ​3480​,
"customer_id": ​"cus_2jHUgfTB4pYmjmHpB"
},
"previous_attributes": {}

},
"livemode": ​true​,
"webhook_status": ​"not_applicable"​,
"webhook_logs": [],

Page 9 - Document version 1.0.0

 "id": ​"5b439072583eb80d50b46534"​,
"object": ​"event"​,
"type": ​"inbound_payment.payment_attempt"​,
"created_at": ​1531154546
}

When receiving this event you must answer by sending the payment authorization

{
"payable": ​true
}

6.1.3 Data types

Parameter Type

service_name String

object String

type String

expires_at Integer (Unix timestamp)

reference String

charge_id String

livemode Boolean

created_at Integer (Unix timestamp)

object String

amount Number (Integer)

currency String

fee Number (Integer)

customer_id String

livemode Boolean

Page 10 - Document version 1.0.0

 webhook_status String

id String

object String

type String

created_at Integer (Unix timestamp)

6.2 charge.paid
With this event we will notify you that the payment was executed without problems and then you
can notify your customers about the success of their payments.

This and only this event is the one that you must use to confirm that a payment has been
made.

{
"data": {
"object": {
"id": ​"5c0968098a268e02ab8aa3f7",
"livemode": ​true​,
"created_at": ​1544120329​,
"currency": ​"MXN"​,
"description": ​null​,
"reference_id": ​null​,
"failure_code": ​null​,
"failure_message": ​null​,
"monthly_installments": ​null​,
"device_fingerprint": ​null​,
"refunds": [],
"payment_method": {
"barcode": ​"XXXXXXXXX"​,
"reference": ​"XXXXXXXXX"​,
"barcode_url":
"https://s3.amazonaws.com/cash_payment_barcodes/XXXXXXXXX.png"​,
"object": ​"cash_payment"​,
"type": ​"oxxo"​,
"expires_at": ​1546732800​,
"store_name": ​"OXXO"
},
"details": {
"name": ​"Juan Perez"​,
"phone": ​null​,
"email": ​"juan_perez@conekta.com"​,

Page 11 - Document version 1.0.0

 "line_items": [],
"coupons": [],
"object": ​"details"
},
"object": ​"charge"​,
"status": ​"paid"​,
"amount": ​350000​,
"paid_at": ​1544120362​,
"fee": ​10150​,
"customer_id": ​"cus_2j35ehQaF1jZEcWH7"​,
"subscription_id": ​""​,
"amount_refunded": ​null
},
"previous_attributes": {}
},
"livemode": ​true​,
"webhook_status": ​"not_applicable"​,
"webhook_logs": [],
"id": ​"5b439072583eb80d50b46534"​,
"object": ​"event"​,
"type": ​"charge.paid"​,
"created_at": ​1531154546
}

Page 12 - Document version 1.0.0

7. Errors
In the case that you reject a transaction, the response to the events must change and must
contain a property called failure_code. With this we’ll send a special message to the cashier
depending on the code sent.
{
"payable": ​false​,
"failure_code": ​15
}

7.1 Errors List

failure_code Description (It may appear in spanish) - Translation

01 Referencia no encontrada – Reference not found

02 Cantidad inválida – Invalid Quantity

03 Referencia expirada – Expired Reference

13 Referencia inactiva – Inactive Reference

14 Referencia cancelada – Canceled Reference

15 Usuario bloqueado – Blocked User

16 Cantidad no permitida – Forbidden Quantity

17 Comercio no disponible – Merchant unavailable

18 Comercio fuera de horario – Merchant after hours

19 No autorizado – Not authorized

Page 13 - Document version 1.0.0

8. Tests in “sandbox”

To test the entire flow of events we provide a special endpoint with which you can trigger these
events and verify that the behavior of your validation and payment authorization rules are
working correctly.
URL: https:​//api.conekta.io/orders/test

8.1 Trigger the event inbound_payment.lookup

At this point in the tutorial you should already have a client with a reference created. The
endpoint will trigger the event with the information that you have passed in the parameters, in
this case for the event inbound_payment.lookup you must send the type of the event and the
reference.
{
"event_type": ​"inbound_payment.lookup"​,
"reference": ​"99000000001273"
}

In this way we will be simulating the point of sale of OXXO, carrying out a validation of a
reference.

8.1.1 Example cURL

curl --request ​POST​ \

--url https:​//api.conekta.io/orders/test \
--header ​'accept​: application/vnd.conekta-v2​.0.0​+json' \
-u ​YOUR_PRIVATE_API_KEY​: \
--header ​'content​-​type​: application/json' \
--data '{ ​"event_type"​: ​"inbound_payment.lookup"​, ​"reference"​:
"99000000001273"​ }'

Page 14 - Document version 1.0.0

8.2Trigger the event inbound_payment.payment_attempt
After carrying out the validation test it’s necessary to carry out the proof of payment
authorization, the concept is identical to the validation test, except that in this test we must send
the amount (all amounts must be in cents).

{
"event_type": ​"inbound_payment.payment_attempt"​,
"reference": ​"99000000001273"​,
"amount": ​"10000"
}

8.1.1 Example cURL

curl --request ​POST​ \

--url https:​//api.conekta.io/orders/test \
--header ​'accept​: application/vnd.conekta-v2​.0.0​+json' \
-u ​YOUR_PRIVATE_API_KEY​: \
--header ​'content​-​type​: application/json' \
--data '{ ​"event_type"​: ​"inbound_payment.payment_attempt"​,
"reference"​: ​"99000000001273"​, ​"amount"​: ​"10000"​ }'

8.3 Event charge.paid

After making the payment authorization you‘ll receive an event that the order you requested
was correctly paid and there was no setback. You’ll receive this notification approximately 5
minutes later.

This and only this event is the one you should use to confirm that a payment has been
made.

When you finish confirming that you’re receiving the events and that your business rules are
working, you can change the keys to the private ones and start receiving money from your
customers through OXXO.

Take into account that this is the only event you must use to confirm that a payment has been
made.

Page 15 - Document version 1.0.0

Payload:
{
"object": {
"id": ​"5bb2b9f7sRjd5jld55eb5"​,
"livemode": ​true​,
"created_at": ​1538439671​,
"currency": ​"MXN"​,
"description": ​null​,
"reference_id": ​null​,
"failure_code": ​null​,
"failure_message": ​null​,
"monthly_installments": ​null​,
"device_fingerprint": ​null​,
"refunds": [],
"payment_method": {
"barcode": ​"934853593"​,
"reference": ​"86040021372688"​,
"barcode_url": ​null​,
"object": ​"cash_payment"​,
"type": ​"oxxo"​,
"expires_at": ​1541116800​,
"store_name": ​"OXXO"
},
"details": {
"name": ​"User Dom"​,
"phone": ​"5512986543"​,
"email": ​"guser@gmail.com"​,
"line_items": [],
"object": ​"details"
},
"object": ​"charge"​,
"status": ​"paid"​,
"amount": ​30000​,
"paid_at": ​1538439696​,
"fee": ​766​,
"customer_id": ​"cus_2jN8zCLdzghBS3Cqb"​,
"subscription_id": ​""​,
"amount_refunded": ​null
},
"previous_attributes": {}
}

Page 16 - Document version 1.0.0