Intro

The Openpay API is designed on REST, therefore you’ll find that URLs are oriented to resources and that HTTP response codes are used to indicate errors in the API.

All the API responses are in JSONformat, including the errors.

In the case to use the existents Openpay API clients (Java, Php, C#, Python, Ruby, NodeJS), the responses are specifically of type defined in the clients and their respective languajes.

API Endpoints

Available resourcers

a) By Merchant

/v1/{MERCHANT_ID}/...
/fees
/fees/{FEE_ID}
/charges
/charges/{TRANSACTION_ID}
/payouts
/payouts/{TRANSACTION_ID}
/cards
/cards/{CARD_ID}
/customers
/customers/{CUSTOMER_ID}
/plans
/plans/{PLAN_ID}
/tokens
/tokens/{TOKEN_ID}

b) By Customer

/v1/{MERCHANT_ID}/customers/{CUSTOMER_ID}/...
/cards
/cards/{CARD_ID}
/bankaccounts
/bankaccounts/{BANKACCOUNT_ID}
/charges
/charges/{TRANSACTION_ID}
/payouts
/payouts/{TRANSACTION_ID}
/transfers
/transfers/{TRANSACTION_ID}
/subscriptions
/subscriptions/{SUBSCRIPTION_ID}

The Openpay REST API has a test environment (sandbox) and a production environment. For integrating your system with Openpay, use the credentials that were generated when you signed up. Once you are ready to move to production environment and your request is approved, new credentials will be generated for accessing the production environment.

The following URIs are the basis of the endpoints for the supported environments:

• Testing, URI base:
  Production:
• Production, URI base:
  https://api.openpay.mx

A complete endpoint consists of the base URI of the environment, the identifier of the Merchant and the resource.

For example, if we want to create a new customer, the endpoint would be:

POST https://sandbox-api.openpay.mx/v1/mzdtln0bmtms6o3kck8f/customers

In order to create a complete request is necessary to send the right HTTP headers and the information in JSON format.

Authentication

Authentication example

curl https://sandbox-api.openpay.mx/v1/mzdtln0bmtms6o3kck8f/charges 
   -u sk_e568c42a6c384b7ab02cd47d2e407cab:
El parámetro -u se ocupa para realizar la autenticación HTTP Basic (al agregar dos puntos después de la llave privada se previene el uso de contraseña)

Production

Solo es necesario usar la URI base https://api.openpay.mx

Para realizar peticiones a la API de Openpay, es necesario enviar la llave de API (API Key) en todas tus llamadas a nuestros servidores. La llave la puedes obtener desde el dashboard.

There are 2 types of API keys:

• Private.- For calls between servers and full access to all API operations (should never be shared).

• Public.- should only be used in JavaScript calls. This key is only allowed to create cards or create tokens.

For API authentication you must use the basic access authentication, where the API key is the username. The password is not required and it should be left blank for purposes of simplicity

Errors

Openpay returns JSON objects in the service responses.

Error Object

Object example

{
    "category" : "request",
    "description" : "The customer with id 'm4hqp35pswl02mmc567' does not exist",
    "http_code" : 404,
    "error_code" : 1005,
    "request_id" : "1981cdb8-19cb-4bad-8256-e95d58bc035c",
    "fraud_rules": [
        "Billing <> BIN Country for VISA/MC"
    ]
}

Error codes

General

Storage

Cards

Accounts

Charges

Charges can be made to cards, stores and banks. Each charge is assigned with an unique identifier in the system.

You can do card charges by using a saved card id, using a token or you can send the card information at the time of invocation.

Cambios por disposiciones oficiales para la prevención de fraude E-commerce

Toda integración que se realice mediante SDK o peticiones directas al API de Openpay, es de carácter obligatorio enviar el header X-Forwarded-For donde se deberá indicar la IP del dispositivo del cliente. En las pestañas de las diferentes tecnologías ubicadas del lado derecho se encuentra la definición de cómo debe ser enviado.

With a card id or token

Definition

Comercio
POST https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/charges
Cliente
POST https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/customers/{CUSTOMER_ID}/charges

Merchant request example

curl https://sandbox-api.openpay.mx/v1/mzdtln0bmtms6o3kck8f/charges 
   -u sk_e568c42a6c384b7ab02cd47d2e407cab: 
   -H "Content-type: application/json" 
   -X POST -d '{
   "source_id" : "kqgykn96i7bcs1wwhvgw",
   "method" : "card",
   "amount" : 100,
   "currency" : "MXN",
   "description" : "Cargo inicial a mi cuenta",
   "order_id" : "oid-00051",
   "device_session_id" : "kR1MiQhz2otdIuUlQkbEyitIqVMiI16f",
   "customer" : {
        "name" : "Juan",
        "last_name" : "Vazquez Juarez",
        "phone_number" : "4423456723",
        "email" : "juan.vazquez@empresa.com.mx"
   }
}'

Response example

{
   "id":"trzjaozcik8msyqshka4",
   "amount":100.00,
   "authorization":"801585",
   "method":"card",
   "operation_type":"in",
   "transaction_type":"charge",
   "card":{
      "id":"kqgykn96i7bcs1wwhvgw",
      "type":"debit",
      "brand":"visa",
      "address":null,
      "card_number":"411111XXXXXX1111",
      "holder_name":"Juan Perez Ramirez",
      "expiration_year":"20",
      "expiration_month":"12",
      "allows_charges":true,
      "allows_payouts":true,
      "creation_date":"2014-05-26T11:02:16-05:00",
      "bank_name":"Banamex",
      "bank_code":"002"
   },
   "status":"completed",
   "currency":"USD",
   "exchange_rate" : {
      "from" : "USD",
      "date" : "2014-11-21",
      "value" : 13.61,
      "to" : "MXN"
   },
   "creation_date":"2014-05-26T11:02:45-05:00",
   "operation_date":"2014-05-26T11:02:45-05:00",
   "description":"Cargo inicial a mi cuenta",
   "error_message":null,
   "order_id":"oid-00051"
}

This type of charge requires a saved card or a previously generated token. To save cards read Create a card and to use tokens visit the Creation of tokens.

Once you have a saved card or token use the source_id property to send the identifier.

The device_session_id property must be generated using JavaScript API, see Fraud detection using device data.

Customized antifraud system
You can send extra data to Openpay in order to increase number of variables and get better results in antifraud detection for your transactions.

Request

Response

Returns a transaction object with the charge information or with an error response..

With redirect

Definition

Comercio
POST https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/charges
Cliente
POST https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/customers/{CUSTOMER_ID}/charges

Merchant request example

curl https://sandbox-api.openpay.mx/v1/mzdtln0bmtms6o3kck8f/charges 
   -u sk_e568c42a6c384b7ab02cd47d2e407cab: 
   -H "Content-type: application/json" 
   -X POST -d '{
   "method" : "card",
   "amount" : 100,
   "description" : "Cargo inicial a mi cuenta",
   "order_id" : "oid-00051",
   "customer" : {
        "name" : "Juan",
        "last_name" : "Vazquez Juarez",
        "phone_number" : "4423456723",
        "email" : "juan.vazquez@empresa.com.mx"
   },
   "confirm" : "false",
   "send_email":"false",
   "redirect_url":"http://www.openpay.mx/index.html"
}'

Response example

{
  "id": "trq7yrthx5vc4gtjdkwg",
  "authorization": null,
  "method": "card",
  "operation_type": "in",
  "transaction_type": "charge",
  "status": "charge_pending",
  "conciliated": false,
  "creation_date": "2016-09-09T18:52:02-05:00",
  "operation_date": "2016-09-09T18:52:02-05:00",
  "description": "Cargo desde terminal virtual de 111",
  "error_message": null,
  "amount": 100,
  "currency": "MXN",
  "payment_method": {
    "type": "redirect",
    "url": "https://sandbox-api.openpay.mx/v1/mexzhpxok3houd5lbvz1/charges/trq7yrthx5vc4gtjdkwg/card_capture"
  },
  "customer": {
    "name": "Juan",
    "last_name": "Vazquez Juarez",
    "email": "juan.vazquez@empresa.com.mx",
    "phone_number": "4423456723",
    "creation_date": "2016-09-09T18:52:02-05:00",
    "clabe": null,
    "external_id": null
  }
}

This type of charge don’t requires a saved card or a previously generated token

Request

Response

Returns a transaction object with the charge information or with an error response..

Charge via store

Definition

Comercio
POST https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/charges
Cliente
POST https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/customers/{CUSTOMER_ID}/charges

Customer request example

curl https://sandbox-api.openpay.mx/v1/mzdtln0bmtms6o3kck8f/customers/ag4nktpdzebjiye1tlze/charges 
   -u sk_e568c42a6c384b7ab02cd47d2e407cab: 
   -H "Content-type: application/json" 
   -X POST -d '{
   "method" : "store",
   "amount" : 100,
   "description" : "Cargo con tienda",
   "order_id" : "oid-00053",
   "due_date" : "2014-05-20T13:45:00"
} '

Response example

{
   "id":"trnirkiyobo5qfex55ef",
   "amount":100.00,
   "authorization":null,
   "method":"store",
   "operation_type":"in",
   "transaction_type":"charge",
   "status":"in_progress",
   "currency":"MXN",
   "creation_date":"2014-05-26T13:48:25-05:00",
   "operation_date":"2014-05-26T13:48:25-05:00",
   "due_date":"2014-05-28T13:45:00-05:00",
   "description":"Cargo con tienda",
   "error_message":null,
   "order_id":"oid-00053",
   "customer_id":"ag4nktpdzebjiye1tlze",
   "payment_method":{
      "type":"store",
      "reference":"000020TRNIRKIYOBO5QFEX55EF0100009",
      "paybin_reference":"0101990000001065",
      "barcode_url":"https://sandbox-api.openpay.mx/barcode/000020TRNIRKIYOBO5QFEX55EF0100009?width=1&height=45&text=false",
      "barcode_paybin_url":"https://sandbox-api.openpay.mx/barcode/0101990000001065?width=1&height=45&text=false"
   }
}

For payments at a convenience store you should create a charge type request by indicating storeas method. This will generate a response with a reference number and a URL with a barcode, which you must use to create a receipt so your customer can make the payment in one of the convenience stores. The barcode is Code 128 type.

Request

Response

Returns a transaction object with the charge information or with an error response..

Charge via bank

Definition

Comercio
POST https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/charges
Cliente
POST https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/customers/{CUSTOMER_ID}/charges

Customer request example

curl https://sandbox-api.openpay.mx/v1/mzdtln0bmtms6o3kck8f/customers/ag4nktpdzebjiye1tlze/charges 
   -u sk_e568c42a6c384b7ab02cd47d2e407cab: 
   -H "Content-type: application/json" 
   -X POST -d '{
   "method" : "bank_account",
   "amount" : 100,
   "description" : "Cargo con banco",
   "order_id" : "oid-00055",
   "due_date"
} '

Response example

{
   "id":"trnzf2xjwpupjfryyj23",
   "amount":100.00,
   "authorization":null,
   "method":"bank_account",
   "operation_type":"in",
   "transaction_type":"charge",
   "status":"in_progress",
   "currency":"MXN",
   "creation_date":"2014-05-26T13:51:25-05:00",
   "operation_date":"2014-05-26T13:51:25-05:00",
   "description":"Cargo con banco",
   "error_message":null,
   "order_id":"oid-00055",
   "customer_id":"ag4nktpdzebjiye1tlze",
   "payment_method":{
      "type":"bank_transfer",
      "agreement" : "1411217",
      "bank":"BBVA Bancomer",
      "clabe":"012914002014112176",
      "name":"11030021342311520255"
   }
}

For a charge via bank you must create a charge type request by indicating bank_accountas method. This will generate a response with a Bancomer CIE agreement number, a CLABE account number and a reference, you have to indicate these data in a receipt so your customer can do the wire transfer via SPEI.

Request

Response

Returns a transaction object with the charge information or with an error response..

With Alipay

Definition

Comercio
POST https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/charges
Cliente
POST https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/customers/{CUSTOMER_ID}/charges

Customer request example

curl https://sandbox-api.openpay.mx/v1/mzdtln0bmtms6o3kck8f/charges 
   -u sk_e568c42a6c384b7ab02cd47d2e407cab: 
   -H "Content-type: application/json" 
   -X POST -d '{
   "description": "Cargo Alipay",
   "amount": "2000.00",
   "method": "alipay",
   "redirect_url" : "http://www.example.com/myRedirectUrl"
} '

Response example

{
    "id": "truq1dwjz0kmssvpbrlj",
    "authorization": null,
    "operation_type": "in",
    "method": "alipay",
    "transaction_type": "charge",
    "status": "charge_pending",
    "conciliated": false,
    "creation_date": "2018-06-14T12:42:11-05:00",
    "operation_date": "2018-06-14T12:42:11-05:00",
    "description": "Cargo Alipay",
    "error_message": null,
    "order_id": null,
    "due_date": "2018-06-15T12:42:11-05:00",
    "payment_method": {
        "type": "redirect",
        "url": "https://sandbox-api.openpay.mx/v1/mzdtln0bmtms6o3kck8f/charges/truq1dwjo0kmssvqbrlj/redirect/"
    },
    "amount": 2000,
    "currency": "MXN",
    "fee": {
        "amount": 2.00  ,
        "tax": 0,
        "currency": "MXN"
    }
}

To start a transaction using Alipay you should create a charge type request by indicating alipayas method. This will generate a response with an URL which will redirect the customer to the Alipay website where they can then enter their account details, or scan the QR Code in their mobile app.

Request

Response

Returns a transaction object with the charge information or with an error response..

Charge with IVR

Definition

Comercio
POST https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/charges
Cliente
POST https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/customers/{CUSTOMER_ID}/charges

Merchant request example

curl https://sandbox-api.openpay.mx/v1/mzdtln0bmtms6o3kck8f/charges 
   -u sk_e568c42a6c384b7ab02cd47d2e407cab: 
   -H "Content-type: application/json" 
   -X POST -d '{
   "method" : "card",
   "confirm": "ivr",
   "amount" : 100,
   "currency" : "MXN",
   "description" : "Cargo IVR",
   "order_id" : "oid-00051",
   "customer" : {
        "name" : "Juan",
        "last_name" : "Vazquez Juarez",
        "phone_number" : "4423456723",
        "email" : "juan.vazquez@empresa.com.mx"
   }
}'

Response example

{
    "id": "tranxr78lb4i58xaliu2",
    "authorization": null,
    "operation_type": "in",
    "transaction_type": "charge",
    "status": "charge_pending",
    "conciliated": false,
    "creation_date": "2020-10-16T12:22:25-05:00",
    "operation_date": "2020-10-16T12:22:25-05:00",
    "description": "Cargo IVR",
    "error_message": null,
    "order_id": "ord-323",
    "due_date": "2020-10-17T00:59:59-05:00",
    "payment_method": {
        "type": "ivr",
        "phone_number": "525588969143",
        "ivr_key": 676105,
        "attempts": 0
    },
    "amount": 100.00,
    "currency": "MXN",
    "customer": {
        "name": "JUAN",
        "last_name": "PEREZ",
        "email": "juan.urbina@hotmail.com",
        "phone_number": "45155352828",
        "address": null,
        "creation_date": "2020-10-16T12:22:25-05:00",
        "external_id": null,
        "clabe": null
    },
    "method": "card"
}

Customized antifraud system
You can send extra data to Openpay in order to increase number of variables and get better results in antifraud detection for your transactions.

Request

Response

Returns a transaction object with the charge information or with an error response..

Confirming a charge

Definition

Comercio
POST https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/charges/{TRANSACTION_ID}/capture
Cliente
POST https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/customers/{CUSTOMER_ID}/charges/{TRANSACTION_ID}/capture

Customer request example

curl https://sandbox-api.openpay.mx/v1/mzdtln0bmtms6o3kck8f/customers/ag4nktpdzebjiye1tlze/charges/tryqihxac3msedn4yxed/capture 
   -u sk_e568c42a6c384b7ab02cd47d2e407cab: 
   -H "Content-type: application/json" 
   -X POST -d '{
    "amount" : 100.00
} '

Response example

{
   "id":"tryqihxac3msedn4yxed",
   "amount":100.00,
   "authorization":"801585",
   "method":"card",
   "operation_type":"in",
   "transaction_type":"charge",
   "card":{
      "type":"debit",
      "brand":"visa",
      "address":null,
      "card_number":"411111XXXXXX1111",
      "holder_name":"Juan Perez Ramirez",
      "expiration_year":"20",
      "expiration_month":"12",
      "allows_charges":true,
      "allows_payouts":true,
      "bank_name":"Banamex",
      "bank_code":"002"
   },
   "status":"completed",
   "currency":"MXN",
   "creation_date":"2014-05-26T14:00:17-05:00",
   "operation_date":"2014-05-26T14:00:17-05:00",
   "description":"Cargo inicial a mi cuenta",
   "error_message":null,
   "order_id":null,
   "customer_id":"ag4nktpdzebjiye1tlze"
}

Confirm a charge created with the capture = "false"property, this method is the second part of the create a charge with a card (id or token) and it can confirm the amount captured on the first call or a lesser amount.

Request

Response

Returns a transaction object with the charge information or with an error response..

Refunding a charge

Definition

Comercio
POST https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/charges/{TRANSACTION_ID}/refund
Cliente
POST https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/customers/{CUSTOMER_ID}/charges/{TRANSACTION_ID}/refund

Customer request example

curl https://sandbox-api.openpay.mx/v1/mzdtln0bmtms6o3kck8f/customers/ag4nktpdzebjiye1tlze/charges/tr6cxbcefzatd10guvvw/refund 
   -u sk_e568c42a6c384b7ab02cd47d2e407cab: 
   -H "Content-type: application/json" 
   -X POST -d '{
   "description" : "devolución",
   "amount" : 100.00
} '

Response example

{
   "id":"tr6cxbcefzatd10guvvw",
   "amount":100.00,
   "authorization":"801585",
   "method":"card",
   "operation_type":"in",
   "transaction_type":"charge",
   "card":{
      "type":"debit",
      "brand":"visa",
      "address":null,
      "card_number":"411111XXXXXX1111",
      "holder_name":"Juan Perez Ramirez",
      "expiration_year":"20",
      "expiration_month":"12",
      "allows_charges":true,
      "allows_payouts":true,
      "bank_name":"Banamex",
      "bank_code":"002"
   },
   "status":"completed",
   "refund":{
      "id":"trcbsmjkroqmjobxqhpb",
      "amount":100.00,
      "authorization":"801585",
      "method":"card",
      "operation_type":"out",
      "transaction_type":"refund",
      "status":"completed",
      "currency":"MXN",
      "creation_date":"2014-05-26T13:56:21-05:00",
      "operation_date":"2014-05-26T13:56:21-05:00",
      "description":"devolucion",
      "error_message":null,
      "order_id":null,
      "customer_id":"ag4nktpdzebjiye1tlze"
   },
   "currency":"MXN",
   "creation_date":"2014-05-26T11:56:25-05:00",
   "operation_date":"2014-05-26T11:56:25-05:00",
   "description":"Cargo inicial a mi cuenta",
   "error_message":null,
   "order_id":"oid-00052",
   "customer_id":"ag4nktpdzebjiye1tlze"
}

You can use this method if you want to make a charge refund to a card. The amount to be returned will be the total charge or a lower amount. Note that the refund may be delayed in the statement of your customer for 1-3 business days.

Request

Response

Returns a transaction object with the charge information or with an error response..

Obtener un cargo

Definition

Comercio
GET https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/charges/{TRANSACTION_ID}
Comercio
GET https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/customers/{CUSTOMER_ID}/charges/{TRANSACTION_ID}

Customer request example

curl https://sandbox-api.openpay.mx/v1/mzdtln0bmtms6o3kck8f/customers/ag4nktpdzebjiye1tlze/charges/tr6cxbcefzatd10guvvw 
   -u sk_e568c42a6c384b7ab02cd47d2e407cab:

Response example

{
   "id":"tr6cxbcefzatd10guvvw",
   "amount":100.00,
   "authorization":"801585",
   "method":"card",
   "operation_type":"in",
   "transaction_type":"charge",
   "card":{
      "type":"debit",
      "brand":"visa",
      "address":null,
      "card_number":"411111XXXXXX1111",
      "holder_name":"Juan Perez Ramirez",
      "expiration_year":"20",
      "expiration_month":"12",
      "allows_charges":true,
      "allows_payouts":true,
      "bank_name":"Banamex",
      "bank_code":"002"
   },
   "status":"completed",
   "refund":{
      "id":"trcbsmjkroqmjobxqhpb",
      "amount":100.00,
      "authorization":"801585",
      "method":"card",
      "operation_type":"out",
      "transaction_type":"refund",
      "status":"completed",
      "currency":"MXN",
      "creation_date":"2014-05-26T13:56:21-05:00",
      "operation_date":"2014-05-26T13:56:21-05:00",
      "description":"devolucion",
      "error_message":null,
      "order_id":null,
      "customer_id":"ag4nktpdzebjiye1tlze"
   },
   "currency":"MXN",
   "creation_date":"2014-05-26T11:56:25-05:00",
   "operation_date":"2014-05-26T11:56:25-05:00",
   "description":"Cargo inicial a mi cuenta",
   "error_message":null,
   "order_id":"oid-00052",
   "customer_id":"ag4nktpdzebjiye1tlze"
}

Returns a transaction object with the charge information or with an error response.

Request

Response

Returns a transaction object with the charge information or with an error response..

List of charges

Definition

Comercio
GET https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/charges
Comercio
GET https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/customers/{CUSTOMER_ID}/charges

Customer request example

curl -g "https://sandbox-api.openpay.mx/v1/mzdtln0bmtms6o3kck8f/customers/ag4nktpdzebjiye1tlze/charges?creation[gte]=2013-11-01&limit=2" 
   -u sk_e568c42a6c384b7ab02cd47d2e407cab:  

Response example

[
   {
      "id":"tryqihxac3msedn4yxed",
      "amount":100.00,
      "authorization":"801585",
      "method":"card",
      "operation_type":"in",
      "transaction_type":"charge",
      "card":{
         "type":"debit",
         "brand":"visa",
         "address":null,
         "card_number":"411111XXXXXX1111",
         "holder_name":"Juan Perez Ramirez",
         "expiration_year":"20",
         "expiration_month":"12",
         "allows_charges":true,
         "allows_payouts":true,
         "bank_name":"Banamex",
         "bank_code":"002"
      },
      "status":"completed",
      "currency":"MXN",
      "creation_date":"2014-05-26T14:00:17-05:00",
      "operation_date":"2014-05-26T14:00:17-05:00",
      "description":"Cargo inicial a mi cuenta",
      "error_message":null,
      "order_id":null,
      "customer_id":"ag4nktpdzebjiye1tlze"
   },
   {
      "id":"trnzf2xjwpupjfryyj23",
      "amount":100.00,
      "authorization":null,
      "method":"bank_account",
      "operation_type":"in",
      "transaction_type":"charge",
      "status":"in_progress",
      "currency":"MXN",
      "creation_date":"2014-05-26T13:51:25-05:00",
      "operation_date":"2014-05-26T13:51:25-05:00",
      "description":"Cargo con banco",
      "error_message":null,
      "order_id":"oid-00055",
      "customer_id":"ag4nktpdzebjiye1tlze",
      "payment_method":{
         "type":"bank_transfer",
         "agreement" : "1411217",
         "bank":"BBVA Bancomer",
         "clabe":"012914002014112176",
         "name":"11030021342311520255"
      }
   }
]

Gets a list of the charges made by Merchant or customer.

Request

You can search using the following parameters as filters.

Response

Returns an array of transaction objects charges in descending order by creation date.

Payouts or withdrawals

A payout is the transaction that allows to extract funds from a Openpay account and send the funds to a bank account. Payouts can be made from the accounts of the customers or from the Merchant account.

Payout to a registered id

Definition

Comercio
POST https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/payouts
Cliente
POST https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/customers/{CUSTOMER_ID}/payouts

Customer request example

curl https://sandbox-api.openpay.mx/v1/mzdtln0bmtms6o3kck8f/customers/ag4nktpdzebjiye1tlze/payouts 
   -u sk_e568c42a6c384b7ab02cd47d2e407cab: 
   -H "Content-type: application/json" 
   -X POST -d '{
    "method": "bank_account",
    "destination_id": "b3d54sd3mdjf75udjfvoc",
    "amount": 10.50,
    "description": "Retiro de saldo semanal",
    "order_id": "oid-00021"
}' 

Response example

{
   "amount":10.5,
   "authorization":null,
   "method":"bank_account",
   "currency":"MXN",
   "operation_type":"out",
   "transaction_type":"payout",
   "bank_account":{
      "id":"b3d54sd3mdjf75udjfvoc",
      "clabe":"012XXXXXXXXXX24616",
      "bank_code":"012",
      "bank_name":"BANCOMER",
      "alias":null,
      "holder_name":"Mi empresa"
   },
   "status":"in_progress",
   "id":"tm50pl40gf6awvalw1ei",
   "creation_date":"2013-11-15T13:42:00-06:00",
   "description":"Retiro de saldo semanal",
   "error_message":null,
   "order_id":"oid-00021",
   "customer_id":"aayr5jjb1fln44yautef"
}

Sends a payout to a previously registered bank account. Refer to create a bank account

Request

Response

Returns a transaction object with the payout information or with an error response..

Payment to a bank account

Definition

Comercio
POST https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/payouts
Cliente
POST https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/customers/{CUSTOMER_ID}/payouts

Customer request example

curl https://sandbox-api.openpay.mx/v1/mzdtln0bmtms6o3kck8f/customers/asynwirguzkgq2bizogo/payouts 
   -u sk_e568c42a6c384b7ab02cd47d2e407cab: 
   -H "Content-type: application/json" 
   -X POST -d '{
   "method":"bank_account",
   "bank_account":{
      "clabe":"012298026516924616",
      "holder_name":"Mi empresa"
   },
   "amount":100.00,
   "description":"Retiro de saldo semanal",
   "order_id":"oid-1110011"
}' 

Response example

{
   "id":"tr4f2atubqchinw71vfs",
   "amount":10.50,
   "authorization":null,
   "method":"bank_account",
   "operation_type":"out",
   "transaction_type":"payout",
   "status":"in_progress",
   "currency":"MXN",
   "creation_date":"2014-05-26T17:23:03-05:00",
   "operation_date":"2014-05-26T17:23:03-05:00",
   "description":"Retiro de saldo semanal",
   "error_message":null,
   "order_id":"oid-1110011",
   "bank_account":{
      "clabe":"012XXXXXXXXXX24616",
      "bank_code":"012",
      "bank_name":"BANCOMER",
      "alias":null,
      "holder_name":"Mi empresa"
   },
   "customer_id":"asynwirguzkgq2bizogo"
}

Sends a payment to a bank account.

Request

Response

Returns a transaction object with the payout information or with an error response..

Get a payout

Definition

Comercio
GET https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/payouts/{TRANSACTION_ID}
Comercio
GET https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/customers/{CUSTOMER_ID}/payouts/{TRANSACTION_ID}

Customer request example

curl https://sandbox-api.openpay.mx/v1/mzdtln0bmtms6o3kck8f/customers/asynwirguzkgq2bizogo/payouts/trwpxhrgfeub9eqdyvqz 
   -u sk_e568c42a6c384b7ab02cd47d2e407cab:

Response example

{
   "id":"trwpxhrgfeub9eqdyvqz",
   "amount":10.50,
   "authorization":"TRWPXHRGFEUB9EQDYVQZ",
   "method":"bank_account",
   "operation_type":"out",
   "transaction_type":"payout",
   "bank_account":{
      "clabe":"012XXXXXXXXXX24616",
      "bank_code":"012",
      "bank_name":"BANCOMER",
      "alias":null,
      "holder_name":"Mi empresa"
   },
   "status":"completed",
   "currency":"MXN",
   "creation_date":"2014-05-26T17:04:26-05:00",
   "operation_date":"2014-05-26T17:06:28-05:00",
   "description":"Retiro de saldo semanal",
   "error_message":null,
   "order_id":"oid-00021",
   "customer_id":"asynwirguzkgq2bizogo"
}

Returns de information of the payout. You must know the payout id.

Request

Response

Returns a transaction object with the payout information or with an error response..

Cancel a payout

Definition

Comercio
DELETE https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/payouts/{TRANSACTION_ID}
Comercio
DELETE https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/customers/{CUSTOMER_ID}/payouts/{TRANSACTION_ID}

Customer request example

curl -X DELETE https://sandbox-api.openpay.mx/v1/mzdtln0bmtms6o3kck8f/customers/asynwirguzkgq2bizogo/payouts/trozeipf364jqrsbt3ej 
   -u sk_e568c42a6c384b7ab02cd47d2e407cab:

Response example

{
   "id":"trozeipf364jqrsbt3ej",
   "amount":10.50,
   "authorization":"TROZEIPF364JQRSBT3EJ",
   "method":"bank_account",
   "operation_type":"out",
   "transaction_type":"payout",
   "bank_account":{
      "clabe":"012XXXXXXXXXX24616",
      "bank_code":"012",
      "bank_name":"BANCOMER",
      "alias":null,
      "holder_name":"Mi empresa"
   },
   "status":"cancelled",
   "currency":"MXN",
   "creation_date":"2014-05-26T17:04:26-05:00",
   "operation_date":"2014-05-26T17:06:28-05:00",
   "description":"Retiro de saldo semanal",
   "error_message":null,
   "order_id":"oid-00021",
   "customer_id":"asynwirguzkgq2bizogo"
}

Cancels a payout in in_progress status, it means not yet completed. You must know the payout id.

Request

Response

Returns a transaction object with the cancelled payout or with an error response..

List of payouts

Definition

Comercio
GET https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/payouts
Comercio
GET https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/customers/{CUSTOMER_ID}/payouts

Request example

curl -g "https://sandbox-api.openpay.mx/v1/mzdtln0bmtms6o3kck8f/customers/asynwirguzkgq2bizogo/payouts?creation[gte]=2013-11-01&limit=2&payout_type=AUTOMATIC" 
   -u sk_e568c42a6c384b7ab02cd47d2e407cab: 

Response example

[
   {
      "id":"tr4f2atubqchinw71vfs",
      "amount":10.50,
      "authorization":"TR4F2ATUBQCHINW71VFS",
      "method":"bank_account",
      "operation_type":"out",
      "transaction_type":"payout",
      "status":"completed",
      "currency":"MXN",
      "creation_date":"2014-05-26T17:23:03-05:00",
      "operation_date":"2014-05-26T17:26:27-05:00",
      "description":"Retiro de saldo semanal",
      "error_message":null,
      "order_id":"oid-1110011",
      "bank_account":{
         "clabe":"012XXXXXXXXXX24616",
         "bank_code":"012",
         "bank_name":"BANCOMER",
         "alias":null,
         "holder_name":"Mi empresa"
      },
      "customer_id":"asynwirguzkgq2bizogo"
   },
   {
      "id":"trwpxhrgfeub9eqdyvqz",
      "amount":10.50,
      "authorization":"TRWPXHRGFEUB9EQDYVQZ",
      "method":"bank_account",
      "operation_type":"out",
      "transaction_type":"payout",
      "bank_account":{
         "clabe":"012XXXXXXXXXX24616",
         "bank_code":"012",
         "bank_name":"BANCOMER",
         "alias":null,
         "holder_name":"Mi empresa"
      },
      "status":"completed",
      "currency":"MXN",
      "creation_date":"2014-05-26T17:04:26-05:00",
      "operation_date":"2014-05-26T17:06:28-05:00",
      "description":"Retiro de saldo semanal",
      "error_message":null,
      "order_id":"oid-00021",
      "customer_id":"asynwirguzkgq2bizogo"
   }
]

Gets a list of payouts made at Merchant or customer level.

Request

You can search using the following parameters as filters.

Response

Returns a list of transaction objects payouts in descending order by creation date.

Summary Payouts

Definition

GET https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/reports/payout/{TRANSACTION_ID}

Request example

curl https://sandbox-api.openpay.mx/v1/mzdtln0bmtms6o3kck8f/reports/payout/trwpxhrgfeub9eqdyvqz 
   -u sk_e568c42a6c384b7ab02cd47d2e407cab:

Response example

{
  "in": 2700,
  "out": 2400,
  "charged_adjustments": 0,
  "refunded_adjustments": 0
}

Return the summary of the payout. You must know the payout id.

Request

Response

Returns a summary payouts object with the summary of the payout or a error response..

Summary Payout Object

Object example

{
   "in":2700,
   "out":2400,
   "charged_adjustments":0,
   "refunded_adjustments":0
}

Payout Detail

Definition

GET https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/reports/payout/{TRANSACTION_ID}/detail

Request example

curl https://sandbox-api.openpay.mx/v1/mzdtln0bmtms6o3kck8f/reports/payout/trwpxhrgfeub9eqdyvqz/detail?detail_type=IN 
   -u sk_e568c42a6c384b7ab02cd47d2e407cab:

Response example

[
  {
    "id": "trqcwapqeilg596zwrvr",
    "authorization": "7BXqDL1fjb",
    "method": "bank_account",
    "operation_type": "in",
    "transaction_type": "charge",
    "status": "completed",
    "conciliated": true,
    "creation_date": "2016-09-13T12:57:34-05:00",
    "operation_date": "2016-09-13T12:57:34-05:00",
    "description": "mexzhpxok3houd5lbvz1",
    "error_message": null,
    "order_id": null,
    "bank_account": {
      "clabe": "113XXXXXXXXXX09568",
      "bank_code": "113",
      "bank_name": "VE POR MAS",
      "rfc": "OPE130906HN4",
      "holder_name": "persona003"
    },
    "amount": 700,
    "currency": "MXN"
  },
  {
    "id": "tru6lsl6xpvseqp87vjd",
    "authorization": "FPVYiN4nyw",
    "method": "card",
    "operation_type": "in",
    "transaction_type": "charge",
    "card": {
      "type": "debit",
      "brand": "mastercard",
      "address": null,
      "card_number": "555555XXXXXX4444",
      "holder_name": "persona003",
      "expiration_year": null,
      "expiration_month": null,
      "allows_charges": false,
      "allows_payouts": false,
      "bank_name": "MASARI",
      "bank_code": "602"
    },
    "status": "completed",
    "conciliated": true,
    "creation_date": "2016-09-13T12:57:16-05:00",
    "operation_date": "2016-09-13T12:57:16-05:00",
    "description": "mexzhpxok3houd5lbvz1",
    "error_message": null,
    "order_id": null,
    "amount": 2000,
    "currency": "MXN"
  }
]

Returns a list of the transactions involved in a payout. You must know the payout id.

Request

Response

Returns a list of transaction objects or a error response..

Customers

Customers are Openpay resources that are handled within the Merchant account and can represent users, customers or partners according to the type of Merchant.

You can add cards and bank accounts to the customers so you can make transactions like Charges, Transfers or Payouts.

Customer object

Object example

{
   "id":"cz4nkhrlcu9k7qd4lwqx",
   "creation_date":"2013-11-08T12:04:46-06:00",
   "name":"Rodrigo",
   "last_name":"Velazco Perez",
   "email":"rodrigo.velazco@payments.com", 
   "phone_number":"4425667045",
   "external_id":"cliente1",
   "status":"active",
   "balance":103,
   "address":{
      "line1":"Av. 5 de febrero No. 1080 int Roble 207",
      "line2":"Carrillo puerto",
      "line3":"Zona industrial carrillo puerto",
      "postal_code":"06500",
      "state":"Querétaro",
      "city":"Querétaro",
      "country_code":"MX"
   },
   "store": {
       "reference": "OPENPAY02DQ35YOY7",
       "barcode_url": "https://sandbox-api.openpay.mx/barcode/OPENPAY02DQ35YOY7?width=1&height=45&text=false"
   },
   "clabe": "646180109400423323"
}

Create a new customer

Definition

POST https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/customers

Request example

curl https://sandbox-api.openpay.mx/v1/mzdtln0bmtms6o3kck8f/customers 
   -u sk_e568c42a6c384b7ab02cd47d2e407cab: 
   -H "Content-type: application/json" 
   -X POST -d '{
   "name": "customer name",
   "email": "customer_email@me.com",
   "requires_account": false 
   }' 

Response example

{
   "id":"anbnldwgni1way3yp2dw",
   "name":"customer name",
   "last_name":null,
   "email":"customer_email@me.com",
   "phone_number":null,
   "address":null,
   "creation_date":"2014-05-20T16:47:47-05:00",
   "external_id":null,
   "store": {
       "reference": "OPENPAY02DQ35YOY7",
       "barcode_url": "https://sandbox-api.openpay.mx/barcode/OPENPAY02DQ35YOY7?width=1&height=45&text=false"
   },
   "clabe": "646180109400423323"
}

Create a customer object.

Request

Response

Returns a object customer when all the data were sent correctly, or returns an error response. if an error occurred during the creation.

Update a customer

Definition

PUT https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/customers/{CUSTOMER_ID}

Request example

curl https://sandbox-api.openpay.mx/v1/mzdtln0bmtms6o3kck8f/customers/anbnldwgni1way3yp2dw 
   -u sk_e568c42a6c384b7ab02cd47d2e407cab: 
   -H "Content-type: application/json" 
   -X PUT -d '{
   "name": "customer name",
   "email": "customer_email@me.com",
   "address":{
      "city":"Queretaro",
      "state":"Queretaro",
      "line1":"Calle 10",
      "postal_code":"76000",
      "line2":"col. san pablo",
      "line3":"entre la calle 1 y la 2",
      "country_code":"MX"
   },
   "phone_number":"44209087654"
 }' 

Response example

{
   "id":"anbnldwgni1way3yp2dw",
   "name":"customer name",
   "last_name":null,
   "email":"customer_email@me.com",
   "phone_number":"44209087654",
   "address":{
      "line1":"Calle 10",
      "line2":"col. san pablo",
      "line3":"entre la calle 1 y la 2",
      "state":"Queretaro",
      "city":"Queretaro",
      "postal_code":"76000",
      "country_code":"MX"
   },
   "store": {
       "reference": "OPENPAY02DQ35YOY7",
       "barcode_url": "https://sandbox-api.openpay.mx/barcode/OPENPAY02DQ35YOY7?width=1&height=45&text=false"
   },
   "clabe": "646180109400423323",
   "creation_date":"2014-05-20T16:47:47-05:00",
   "external_id":null
}

Updates one or more data of the customer.

Request

Response

Returns a object customer with the updated info, or returns an error response. if a problem happened while updating.

Get an existing customer

Definition

GET https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/customers/{CUSTOMER_ID}

Request example

curl https://sandbox-api.openpay.mx/v1/mzdtln0bmtms6o3kck8f/customers/anbnldwgni1way3yp2dw 
   -u sk_e568c42a6c384b7ab02cd47d2e407cab: 
   -H "Content-type: application/json" 

Response example

{
   "id":"anbnldwgni1way3yp2dw",
   "name":"customer name",
   "last_name":null,
   "email":"customer_email@me.com",
   "phone_number":"44209087654",
   "address":{
      "line1":"Calle 10",
      "line2":"col. san pablo",
      "line3":"entre la calle 1 y la 2",
      "state":"Queretaro",
      "city":"Queretaro",
      "postal_code":"76000",
      "country_code":"MX"
   },
   "store": {
       "reference": "OPENPAY02DQ35YOY7",
       "barcode_url": "https://sandbox-api.openpay.mx/barcode/OPENPAY02DQ35YOY7?width=1&height=45&text=false"
   },
   "clabe": "646180109400423323",
   "creation_date":"2014-05-20T16:47:47-05:00",
   "external_id":null
}

Gets the current information of an existing customer. You only need to specify the id returned when creating the customer.

Request

Response

If the identifier exists, it returns a object customer with the customer information.

Delete a customer

Definition

DELETE https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/customers/{CUSTOMER_ID}

Request example

curl https://sandbox-api.openpay.mx/v1/mzdtln0bmtms6o3kck8f/customers/anbnldwgni1way3yp2dw 
   -u sk_e568c42a6c384b7ab02cd47d2e407cab: 
   -H "Content-type: application/json" 
   -X DELETE

Deletes a customer permanently. All the related subscriptions will be canceled. Openpay keeps the operations records.

Request

Response

If the customer is deleted correctly, it returns an empty response, if the customer can not be deleted it returns a error object explaining the reason.

List of customers

Definition

GET https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/customers

Request example

curl -g "https://sandbox-api.openpay.mx/v1/mzdtln0bmtms6o3kck8f/customers?creation[gte]=2013-11-01&limit=2" 
   -u sk_e568c42a6c384b7ab02cd47d2e407cab: 
   -H "Content-type: application/json" 

Response example

[{
   "id":"cpjdhf754ythr65yu9k7q",
   "creation_date":"2013-11-08T12:04:46-06:00",
   "name":"Rodrigo",
   "last_name":"Velazco Perez",
   "email":"rodrigo.velazco@payments.com",
   "phone_number":"4425667045",
   "status":"active",
   "balance":142.5,
   "store": {
       "reference": "OPENPAY02DQ35YOY7",
       "barcode_url": "https://sandbox-api.openpay.mx/barcode/OPENPAY02DQ35YOY7?width=1&height=45&text=false"
   },
   "clabe": "646180109400423323"
}, {
   "id":"cz4nkhrlcu9k7qd4lwqx",
   "creation_date":"2013-11-07T14:54:46-06:00",
   "name":"Eriberto",
   "last_name":"Rodriguez Lopez",
   "email":"eriberto.rodriguez@payments.com",
   "phone_number":"442",
   "status":"active",
   "balance":103,
   "store": {
       "reference": "OPENPAY02DQWERWJ3",
       "barcode_url": "https://sandbox-api.openpay.mx/barcode/OPENPAY02DQWERWJ3?width=1&height=45&text=false"
   },
   "clabe": "646180109400423323"
}]

Returns a list of registered customers, if you want to delimit the result you may use filters.

Request

You can search using the following parameters as filters.

Response

Returns an array of customer object.

Wire transfers

The transfers allow to send funds between accounts of your customers.

Transfers between customers

Definition

POST https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/customers/{CUSTOMER_ID}/transfers

Request example

curl https://sandbox-api.openpay.mx/v1/mzdtln0bmtms6o3kck8f/customers/ag4nktpdzebjiye1tlze/transfers 
   -u sk_e568c42a6c384b7ab02cd47d2e407cab: 
   -H "Content-type: application/json" 
   -X POST -d '{                                            
     "customer_id" : "dvocf97jd20es3tw5laz",
     "amount" : 12.50,          
     "description" : "Transferencia entre cuentas",
     "order_id" : "oid-1245"
}' 

Response example

{
   "amount":12.50,
   "authorization":null,
   "method":"customer",
   "operation_type":"out",
   "currency":"MXN",
   "transaction_type":"transfer",
   "status":"completed",
   "id":"twpmbike2jejex3pahzd",
   "creation_date":"2013-11-15T10:33:19-06:00",
   "description":"Transferencia entre cuentas",
   "error_message":null,
   "order_id":"oid-1245",
   "customer_id":"a9pvykxz4g5rg0fplze0",
   "store": {
       "reference": "OPENPAY02DQ35YOY7",
       "barcode_url": "https://sandbox-api.openpay.mx/barcode/OPENPAY02DQ35YOY7?width=1&height=45&text=false"
   },
   "clabe": "646180109400423323"
}

Makes the transfer of funds from one account of the customer to another. The funds will be charged to an origin account and added to a destination account, which will create two transactions.

Request

Response

If the transaction is successful, the response will contain a transaction object. This object represents the withdrawal of the account of the current customer. On error, the error object will be returned.

Get a transfer

Definition

GET https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/customers/{CUSTOMER_ID}/transfers/{TRANSACTION_ID}

Request example

curl https://sandbox-api.openpay.mx/v1/mzdtln0bmtms6o3kck8f/customers/ag4nktpdzebjiye1tlze/transfers/twpmbike2jejex3pahzd 
   -u sk_e568c42a6c384b7ab02cd47d2e407cab: 
   -H "Content-type: application/json" 

Response example

{
   "amount":12.50,
   "authorization":null,
   "method":"customer",
   "operation_type":"out",
   "currency":"MXN",
   "transaction_type":"transfer",
   "status":"completed",
   "id":"twpmbike2jejex3pahzd",
   "creation_date":"2013-11-15T10:33:19-06:00",
   "description":"Transferencia entre cuentas",
   "error_message":null,
   "order_id":"oid-1245",
   "customer_id":"dvocf97jd20es3tw5laz"
}

With the customer identifier and the transfer identifier, you can get the details of the transaction. The output transaction will be on the customer from which the transfer was made, and the entry transaction will be on the customer that received the amount.

Request

Response

Returns a transaction object

List of transfers

Definition

GET https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/customers/{CUSTOMER_ID}/transfers

Request example

curl -g "https://sandbox-api.openpay.mx/v1/mzdtln0bmtms6o3kck8f/customers/ag4nktpdzebjiye1tlze/transfers?limit=2" 
   -u sk_e568c42a6c384b7ab02cd47d2e407cab: 

Response example

[
   {
      "amount":130.00,
      "authorization":null,
      "method":"customer",
      "currency":"MXN",
      "operation_type":"out",
      "transaction_type":"transfer",
      "status":"completed",
      "id":"a74mbe4e2j5gc6gfahzd",
      "creation_date":"2013-09-18T00:31:19-06:00",
      "description":"Una descripcion",
      "error_message":null,
      "order_id":"20131115103317",
      "customer_id":"afk4csrazjp1udezj1po"
   },
   {
      "amount":130.00,
      "authorization":null,
      "method":"customer",
      "currency":"MXN",
      "operation_type":"in",
      "transaction_type":"transfer",
      "status":"completed",
      "id":"a74mbe4e2j5gc6gfahzd",
      "creation_date":"2013-09-18T00:31:19-06:00",
      "description":"Una descripcion",
      "error_message":null,
      "order_id":null,
      "customer_id":"agdn58ngcnogqmzruz1i"
   }
]

It allows to consult the entry and output transactions of a customer.

Request

You can search using the following parameters as filters.

Response

List of transaction objects of the transfers made, each one with the identifier of the customer that made it. The transactions will be listed in descending order by creation date.

Cards

Dentro de la plataforma Openpay podrás agregar tarjetas a la cuenta del cliente, eliminarlas, recuperar alguna en específico y listarlas.

You can store multiple debit and / or credit cards at Merchant or customer level for making charges later without the need to enter the information again.

Card Object

Object example

{
   "type":"debit",
   "brand":"mastercard",
   "address":{
      "line1":"Av 5 de Febrero",
      "line2":"Roble 207",
      "line3":"col carrillo",
      "state":"Queretaro",
      "city":"Querétaro",
      "postal_code":"76900",
      "country_code":"MX"
   },
   "id":"kgipbqixvjg3gbzowl7l",
   "card_number":"1111",
   "holder_name":"Juan Perez Ramirez",
   "expiration_year":"20",
   "expiration_month":"12",
   "allows_charges":true,
   "allows_payouts":false,
   "creation_date":"2013-12-12T17:50:00-06:00",
   "bank_name":"DESCONOCIDO",
   "bank_code":"000",
   "customer_id":"a2b79p8xmzeyvmolqfja",
   "points_card":true
}

Create a card

Definition

Comercio
POST https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/cards
Cliente
POST https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/customers/{CUSTOMER_ID}/cards

Customer request example

curl https://sandbox-api.openpay.mx/v1/mzdtln0bmtms6o3kck8f/customers/ag4nktpdzebjiye1tlze/cards 
   -u sk_e568c42a6c384b7ab02cd47d2e407cab: 
   -H "Content-type: application/json" 
   -X POST -d '{
   "card_number":"4111111111111111",
   "holder_name":"Juan Perez Ramirez",
   "expiration_year":"20",
   "expiration_month":"12",
   "cvv2":"110",
   "device_session_id" : "kR1MiQhz2otdIuUlQkbEyitIqVMiI16f"
 }' 

Response example

{
   "id":"ktrpvymgatocelsciak7",
   "type":"debit",
   "brand":"visa",
   "card_number":"411111XXXXXX1111",
   "holder_name":"Juan Perez Ramirez",
   "expiration_year":"20",
   "expiration_month":"12",
   "allows_charges":true,
   "allows_payouts":true,
   "creation_date":"2014-05-21T17:31:01-05:00",
   "bank_name":"Banamex",
   "customer_id":"ag4nktpdzebjiye1tlze",
   "bank_code":"002"
}

When a card is created the customer must be specified, if the customer is not specified the card will be registered for the Merchant account. Once the card is saved, it can not obtain the number and security code.

When saving a card, an ID will be created which can be used to make card charges, payouts to a card or just for getting the not sensitive card information.

You can use the antifraud system implementation. The device_session_id property must be generated using JavaScript API, see Fraud detection using device data.

Request

Response

Returns a card object when it is created correctly or returns an error response. if an error occurred during the creation.

Create a card with token

Definition

Comercio
POST https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/cards
Cliente
POST https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/customers/{CUSTOMER_ID}/cards

Customer request example

curl https://sandbox-api.openpay.mx/v1/mzdtln0bmtms6o3kck8f/customers/ag4nktpdzebjiye1tlze/cards 
   -u sk_e568c42a6c384b7ab02cd47d2e407cab: 
   -H "Content-type: application/json" 
   -X POST -d '{
      "token_id":"tokgslwpdcrkhlgxqi9a",
      "device_session_id":"8VIoXj0hN5dswYHQ9X1mVCiB72M7FY9o"
   }' 

Response example

{
   "type":"credit",
   "brand":"visa",
   "id":"kso4st83wxaibffyt6su",
   "card_number":"4242",
   "holder_name":"Juan Perez Ramirez",
   "expiration_year":"15",
   "expiration_month":"12",
   "allows_charges":true,
   "allows_payouts":false,
   "creation_date":"2014-02-12T10:57:09-06:00",
   "bank_name":"BANCOMER",
   "bank_code":"012",
   "customer_id":"a2b79p8xmzeyvmolqfja"
}

Creates a card from a token obtained from the browser or from the customer’s device. This way prevents the sensitive card information passes through your servers.

Request

Response

Returns a card object

Get a card

Definition

Comercio
GET https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/cards/{CARD_ID}
Cliente
GET https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/customers/{CUSTOMER_ID}/cards/{CARD_ID}

Customer request example

curl https://sandbox-api.openpay.mx/v1/mzdtln0bmtms6o3kck8f/customers/ag4nktpdzebjiye1tlze/cards/ktrpvymgatocelsciak7 
   -u sk_e568c42a6c384b7ab02cd47d2e407cab: 
   -H "Content-type: application/json" 

Response example

{
   "id":"ktrpvymgatocelsciak7",
   "type":"debit",
   "brand":"visa",
   "card_number":"411111XXXXXX1111",
   "holder_name":"Juan Perez Ramirez",
   "expiration_year":"20",
   "expiration_month":"12",
   "allows_charges":true,
   "allows_payouts":true,
   "creation_date":"2014-05-21T17:31:01-05:00",
   "bank_name":"Banamex",
   "customer_id":"ag4nktpdzebjiye1tlze",
   "bank_code":"002"
}

It obtains the details of the card by using its id.

Request

Response

Returns a card object

Card points

Definition

Comercio
GET https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/cards/{CARD_ID}/points
Cliente
GET https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/customers/{CUSTOMER_ID}/cards/{CARD_ID}/points
Token
GET https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/tokens/{TOKEN_ID}/points

Customer request example

curl -g "https://sandbox-api.openpay.mx/v1/mzdtln0bmtms6o3kck8f/customers/ag4nktpdzebjiye1tlze/cards/ktrpvymgatocelsciak7/points" 
   -u sk_e568c42a6c384b7ab02cd47d2e407cab:

Response example

[
   {
      "points_type": "santander",
      "remaining_points":"300",
      "remaining_mxn":"22.5"
   }
]

Returns the card point balance. Is applicable only for Santander, Scotiabank and Bancomer points.

Request

You can get the card points of a merchant or customer using the card id.

Also you can get the card points of a merchant using the token.

Response

Delete a card

Definition

Comercio
DELETE https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/cards/{CARD_ID}
Cliente
DELETE https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/customers/{CUSTOMER_ID}/cards/{CARD_ID}

Customer request example

curl https://sandbox-api.openpay.mx/v1/mzdtln0bmtms6o3kck8f/customers/ag4nktpdzebjiye1tlze/cards/ktrpvymgatocelsciak7 
   -u sk_e568c42a6c384b7ab02cd47d2e407cab: 
   -X DELETE

Deletes a card of the customer or Merchant. After deleting it won’t be possible to make movements with that card, however, all records of the transactions you have made will be kept and will be available on the dashboard.

To remove it is only necessary to provide the card identifier.

Request

Response

If the card is removed correctly the answer is empty, if it can not be deleted a error object explaining the reason.

List of cards

Definition

Comercio
GET https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/customers
Cliente
GET https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/customers/{CUSTOMER_ID}/cards

Customer request example

curl -g "https://sandbox-api.openpay.mx/v1/mzdtln0bmtms6o3kck8f/customers/ag4nktpdzebjiye1tlze/cards?limit=2" 
   -u sk_e568c42a6c384b7ab02cd47d2e407cab: 

Response example

[
   {
      "id":"kxq1rpdymlcpxekvjsxm",
      "card_number":"1118",
      "holder_name":"Pedro Paramo",
      "expiration_year":"15",
      "expiration_month":"12",
      "allows_charges":true,
      "allows_payouts":true,
      "creation_date":"2013-11-20T09:22:25-06:00",
      "bank_name":"BBVA BANCOMER",
      "bank_code":"012",
      "type":"debit",
      "brand":"mastercard"
   },
   {
      "id":"kgjy0jiami01kkpdoywr",
      "card_number":"1111",
      "holder_name":"Pedro Paramo",
      "expiration_year":"15",
      "expiration_month":"12",
      "allows_charges":true,
      "allows_payouts":true,
      "creation_date":"2013-11-19T13:26:12-06:00",
      "bank_name":"BBVA BANCOMER",
      "bank_code":"012",
      "type":"debit",
      "brand":"mastercard"
   }
]

Returns a list of registered Merchant or customer cards, if you want to narrow the result you can use filters.

Request

You can search using the following parameters as filters.

Response

List of card objects registered according to the parameters provided, sorted by creation date in descending order.

Updating a card

Definition

Comercio
PUT https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/cards/{CARD_ID}
Cliente
PUT https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/customers/{CUSTOMER_ID}/cards/{CARD_ID}

Customer request example

curl https://sandbox-api.openpay.mx/v1/mzdtln0bmtms6o3kck8f/customers/ag4nktpdzebjiye1tlze/cards/kysc8pycq8hnlzivk1x4 
   -u sk_e568c42a6c384b7ab02cd47d2e407cab: 
   -H "Content-type: application/json" 
   -X PUT -d '{
      "cvv2":"000"
   }' 

Response example

{
}

Updates the card data from the browser or from the customer’s device. It also allows to send a cvv2 code that will be used in the next transaction done with this card. This prevents sensitive information from passing through your servers.

Request

Response

Returns an empty JSON object. Please consider that this response may be extended in the future.

Bank Accounts

You can store multiple bank accounts by Merchant or customer for withdraw funds later.

Bank account object

Object example

{
   "id":"brppwl9nwmruogk2do0j",
   "clabe":"032180000118359719",
   "bank_code":"032",
   "bank_name":"IXE",
   "alias":null,
   "holder_name":"Juan Hernández Sánchez",
   "creation_date":"2013-11-14T12:29:18-06shell00"
}

Create a bank account

Definition

POST https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/customers/{CUSTOMER_ID}/bankaccounts

Customer request example

curl https://sandbox-api.openpay.mx/v1/mzdtln0bmtms6o3kck8f/customers/ag4nktpdzebjiye1tlze/bankaccounts 
   -u sk_e568c42a6c384b7ab02cd47d2e407cab: 
   -H "Content-type: application/json" 
   -X POST -d '{
   "clabe":"032180000118359719",
   "alias":"Cuenta principal",
   "holder_name":"Juan Hernández Sánchez"
}'

Response example

{
   "id":"buyj4apkwilpp2jfxr9r",
   "clabe":"032XXXXXXXXXX59719",
   "bank_code":"032",
   "bank_name":"IXE",
   "alias":"Cuenta principal",
   "holder_name":"Juan Hernández Sánchez",
   "creation_date":"2014-05-22T11:02:10-05:00"
}

Creates and assigns a bank account to a specific customer.

Request

Response

Returns a bank account object or an error when a there is a problem.

Get a bank account

Definition

GET https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/customers/{CUSTOMER_ID}/bankaccounts/{BANK_ACCOUNT_ID}

Customer request example

curl https://sandbox-api.openpay.mx/v1/mzdtln0bmtms6o3kck8f/customers/ag4nktpdzebjiye1tlze/bankaccounts/buyj4apkwilpp2jfxr9r 
   -u sk_e568c42a6c384b7ab02cd47d2e407cab:

Response example

{
   "id":"buyj4apkwilpp2jfxr9r",
   "clabe":"032XXXXXXXXXX59719",
   "bank_code":"032",
   "bank_name":"IXE",
   "alias":"Cuenta principal",
   "holder_name":"Juan Hernández Sánchez",
   "creation_date":"2014-05-22T11:02:10-05:00"
}

It obtains the details of the bank account assigned to a customer.

Request

Response

Returns a bank account object

Delete a bank account

Definition

DELETE https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/customers/{CUSTOMER_ID}/bankaccounts/{BANK_ACCOUNT_ID}

Customer request example

curl https://sandbox-api.openpay.mx/v1/mzdtln0bmtms6o3kck8f/customers/ag4nktpdzebjiye1tlze/bankaccounts/buyj4apkwilpp2jfxr9r 
   -u sk_e568c42a6c384b7ab02cd47d2e407cab: 
   -X DELETE

Deletes the bank account associated with the customer. The transactions that are associated with this account are unchanged and will continue for you to consult them.

Request

Response

If the bank account is removed correctly the answer is empty, if it can not be deleted a error object explaining the reason.

List of bank accounts

Definition

GET https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/customers/{CUSTOMER_ID}/bankaccounts

Customer request example

curl -g "https://sandbox-api.openpay.mx/v1/mzdtln0bmtms6o3kck8f/customers/ag4nktpdzebjiye1tlze/bankaccounts?limit=2" 
   -u sk_e568c42a6c384b7ab02cd47d2e407cab: 

Response example

[{
   "id":"brppwl9nwmruogk2do0j",
   "clabe":"032180000118359719",
   "bank_code":"032",
   "bank_name":"IXE",
   "alias":null,
   "holder_name":"Juan Hernández Sánchez",
   "creation_date":"2013-11-14T12:29:18-06:00"
},
{
   "id":"bb0zt72rxoyiwz9jzzai",
   "clabe":"012680012426485980",
   "bank_code":"012",
   "bank_name":"BANCOMER",
   "alias":null,
   "holder_name":"Juan Hernández Sánchez",
   "creation_date":"2013-11-14T18:07:45-06:00"
}]

Returns the details of all the bank accounts of the customer specified on the request.

Request

You can search using the following parameters as filters.

Response

List of objetos cuenta bancaria registered according to the parameters provided, sorted by creation date in descending order.

Plans

Plans are an Openpay resource that allows create templates for subscriptions. Using plans you can define the amount and frequency of recurrent charges.

Plan Object

Object example

{
    "name": "Curso de ingles",
    "status": "active",
    "amount": 150,
    "currency": "MXN",
    "id": "patpflacwilazguj6bem",
    "creation_date": "2013-12-13T09:43:52-06:00",
    "repeat_every": 1,
    "repeat_unit": "month",
    "retry_times": 2,
    "status_after_retry": "cancelled",
    "trial_days": 30
}

Create a new Plan

Definition

POST https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/plans

Request example

curl https://sandbox-api.openpay.mx/v1/mzdtln0bmtms6o3kck8f/plans 
   -u sk_e568c42a6c384b7ab02cd47d2e407cab: 
   -H "Content-type: application/json" 
   -X POST -d '{
  "amount": 150.00,
  "status_after_retry": "cancelled",
  "retry_times": 2,
  "name": "Curso de ingles",
  "repeat_unit": "month",
  "trial_days": "30",
  "repeat_every": "1"
}' 

Response example

{
   "id":"p8e6x3hafqqsbmnoevrt",
   "name":"Curso de ingles",
   "status":"active",
   "amount":150.00,
   "currency":"MXN",
   "creation_date":"2014-05-22T12:29:31-05:00",
   "repeat_every":1,
   "repeat_unit":"month",
   "retry_times":2,
   "status_after_retry":"cancelled",
   "trial_days":30
}

Creates a new plan for allowing customers to subscribe.

Request

Response

Returns a plan object or an error when a there is a problem.

Update existing plans.

Definition

PUT https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/plans/{PLAN_ID}

Request example

curl https://sandbox-api.openpay.mx/v1/mzdtln0bmtms6o3kck8f/plans/p8e6x3hafqqsbmnoevrt 
   -u sk_e568c42a6c384b7ab02cd47d2e407cab: 
   -H "Content-type: application/json" 
   -X PUT -d '{
      "name": "Curso de aleman",
      "trial_days": "60"
   }' 

Response example

{
   "id":"p8e6x3hafqqsbmnoevrt",
   "name":"Curso de aleman",
   "status":"active",
   "amount":150.00,
   "currency":"MXN",
   "creation_date":"2014-05-22T12:29:31-05:00",
   "repeat_every":1,
   "repeat_unit":"month",
   "retry_times":2,
   "status_after_retry":"cancelled",
   "trial_days":60
}

Updates the plan information. It requires a plan id and only certain fields can be updated.

Request

Response

Returns a plan object with the updated information or an error response. if a problem happened while updating.

Get a plan

Definition

GET https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/plans/{PLAN_ID}

Request example

curl https://sandbox-api.openpay.mx/v1/mzdtln0bmtms6o3kck8f/plans/p8e6x3hafqqsbmnoevrt 
   -u sk_e568c42a6c384b7ab02cd47d2e407cab:

Response example

{
   "id":"p8e6x3hafqqsbmnoevrt",
   "name":"Curso de aleman",
   "status":"active",
   "amount":150.00,
   "currency":"MXN",
   "creation_date":"2014-05-22T12:29:31-05:00",
   "repeat_every":1,
   "repeat_unit":"month",
   "retry_times":2,
   "status_after_retry":"cancelled",
   "trial_days":60
}

It gets the plan details.

Request

Response

Returns a plan object

Delete a plan

Definition

DELETE https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/plans/{PLAN_ID}

Request example

curl https://sandbox-api.openpay.mx/v1/mzdtln0bmtms6o3kck8f/plans/p8e6x3hafqqsbmnoevrt 
   -u sk_e568c42a6c384b7ab02cd47d2e407cab: 
   -X DELETE

When a plan is deleted it won’t allow to create more subscriptions associated with it, however the subscriptions already associated will continue to be charged.

Request

Response

If the plan is deleted correctly the response will be empty, if it cannot be deleted an error object explaining the reason.

Plan list

Definition

GET https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/plans

Request example

curl -g "https://sandbox-api.openpay.mx/v1/mzdtln0bmtms6o3kck8f/plans?limit=10" 
   -u sk_e568c42a6c384b7ab02cd47d2e407cab: 

Response example

[
    {
        "name": "Curso de aleman",
        "status": "active",
        "amount": 150,
        "currency": "MXN",
        "id": "patpflacwilazguj6bem",
        "creation_date": "2013-12-13T09:43:52-06:00",
        "repeat_every": 1,
        "repeat_unit": "month",
        "retry_times": 2,
        "status_after_retry": "cancelled",
        "trial_days": 60
    },
    {
        "name": "Curso de ingles",
        "status": "active",
        "amount": 150,
        "currency": "MXN",
        "id": "pjl7wfryrrd1tznr0fnl",
        "creation_date": "2013-12-13T11:36:40-06:00",
        "repeat_every": 1,
        "repeat_unit": "month",
        "retry_times": 2,
        "status_after_retry": "cancelled",
        "trial_days": 30
    }
]

Returns the details of all active plans.

Request

You can search using the following parameters:

Response

List of plan objects registered according to the parameters provided, sorted by creation date in descending order.

Subscriptions

Subscriptions allow you to associate a customer and a card so that recurring charges can be made.

In order to subscribe a client it is necessary to first create a plan.

Subscription object

Object example

{
    "status": "trial",
    "card": {
        "type": "debit",
        "brand": "mastercard",
        "card_number": "1111",
        "holder_name": "Juan Perez Ramirez",
        "expiration_year": "20",
        "expiration_month": "12",
        "allows_charges": true,
        "allows_payouts": false,
        "creation_date": "2013-12-13T12:39:46-06:00",
        "bank_name": "DESCONOCIDO",
        "customer_id": null,
        "bank_code": "000"
    },
    "id": "svxdm1suclzipbi4pavm",
    "cancel_at_period_end": false,
    "charge_date": "2014-01-12",
    "creation_date": "2013-12-13T12:39:46-06:00",
    "current_period_number": 0,
    "period_end_date": "2014-01-11",
    "trial_end_date": "2014-01-11",
    "plan_id": "pjl7wfryrrd1tznr0fnl",
    "customer_id": "a2b79p8xmzeyvmolqfja"
}

Create a new Subscription

Definition

POST https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/customers/{CUSTOMER_ID}/subscriptions

Request example

curl https://sandbox-api.openpay.mx/v1/mzdtln0bmtms6o3kck8f/customers/ag4nktpdzebjiye1tlze/subscriptions 
   -u sk_e568c42a6c384b7ab02cd47d2e407cab: 
   -H "Content-type: application/json" 
   -X POST -d '{
   "card":{
      "card_number":"4111111111111111",
      "holder_name":"Juan Perez Ramirez",
      "expiration_year":"20",
      "expiration_month":"12",
      "cvv2":"110",
      "device_session_id":"kR1MiQhz2otdIuUlQkbEyitIqVMiI16f"
   },
   "plan_id":"pbi4kb8hpb64x0uud2eb"
}' 

Response example

{
   "id":"s0gmyor4yqtyv1miqwr0",
   "status":"trial",
   "card":{
      "type":"debit",
      "brand":"visa",
      "address":null,
      "card_number":"411111XXXXXX1111",
      "holder_name":"Juan Perez Ramirez",
      "expiration_year":"20",
      "expiration_month":"12",
      "allows_charges":true,
      "allows_payouts":true,
      "bank_name":"Banamex",
      "bank_code":"002"
   },
   "cancel_at_period_end":false,
   "charge_date":"2014-06-21",
   "creation_date":"2014-05-22T15:56:18-05:00",
   "current_period_number":0,
   "period_end_date":"2014-06-20",
   "trial_end_date":"2014-06-20",
   "plan_id":"pbi4kb8hpb64x0uud2eb",
   "customer_id":"ag4nktpdzebjiye1tlze"
}

Create a new subscription for an existing customer. You can use an existing card or you can send the info of the card where the charges will be made, in these you can include the property device_session_id to use the antifraud tool, see Fraud detection using device data.

Request

Response

Returns the created subscription object or an error response. if an error occurred during the creation.

Updating a Subscription

Definition

PUT https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/customers/{CUSTOMER_ID}/subscriptions

Request example

curl https://sandbox-api.openpay.mx/v1/mzdtln0bmtms6o3kck8f/customers/ag4nktpdzebjiye1tlze/subscriptions/s0gmyor4yqtyv1miqwr0 
   -u sk_e568c42a6c384b7ab02cd47d2e407cab: 
   -H "Content-type: application/json" 
   -X PUT -d '{
  "trial_end_date": "2016-01-11",
   "card": {
        "card_number": "343434343434343",
        "holder_name": "Juan Perez Ramirez",
        "expiration_year": "20",
        "expiration_month": "12",
        "cvv2":"1234"
    }
}' 

Response example

{
   "id":"s0gmyor4yqtyv1miqwr0",
   "status":"trial",
   "card":{
      "type":"credit",
      "brand":"american_express",
      "address":null,
      "card_number":"343434XXXXX4343",
      "holder_name":"Juan Perez Ramirez",
      "expiration_year":"20",
      "expiration_month":"12",
      "allows_charges":true,
      "allows_payouts":false,
      "bank_name":"AMERICAN EXPRESS",
      "bank_code":"103"
   },
   "cancel_at_period_end":false,
   "charge_date":"2016-01-12",
   "creation_date":"2014-05-22T15:56:18-05:00",
   "current_period_number":0,
   "period_end_date":"2016-01-11",
   "trial_end_date":"2016-01-11",
   "plan_id":"pbi4kb8hpb64x0uud2eb",
   "customer_id":"ag4nktpdzebjiye1tlze"
}

Updates the information of an active subscription.

Request

Response

Returns the created subscription object actualizado o una error response. if a problem happened while updating.

Get a Subscription

Definition

GET https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/customers/{CUSTOMER_ID}/subscriptions/{SUBSCRIPTION_ID}

Request example

curl https://sandbox-api.openpay.mx/v1/mzdtln0bmtms6o3kck8f/customers/ag4nktpdzebjiye1tlze/subscriptions/s0gmyor4yqtyv1miqwr0 
   -u sk_e568c42a6c384b7ab02cd47d2e407cab:

Response example

{
   "id":"s0gmyor4yqtyv1miqwr0",
   "status":"trial",
   "card":{
      "type":"credit",
      "brand":"american_express",
      "address":null,
      "card_number":"343434XXXXX4343",
      "holder_name":"Juan Perez Ramirez",
      "expiration_year":"20",
      "expiration_month":"12",
      "allows_charges":true,
      "allows_payouts":false,
      "bank_name":"AMERICAN EXPRESS",
      "bank_code":"103"
   },
   "cancel_at_period_end":false,
   "charge_date":"2016-01-12",
   "creation_date":"2014-05-22T15:56:18-05:00",
   "current_period_number":0,
   "period_end_date":"2016-01-11",
   "trial_end_date":"2016-01-11",
   "plan_id":"pbi4kb8hpb64x0uud2eb",
   "customer_id":"ag4nktpdzebjiye1tlze"
}

Gets the details of a customer subscription.

Request

Response

Returns a subscription object

Cancel a Subscription

Definition

DELETE https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/customers/{CUSTOMER_ID}/subscriptions/{SUBSCRIPTION_ID}

Request example

curl https://sandbox-api.openpay.mx/v1/mzdtln0bmtms6o3kck8f/customers/ag4nktpdzebjiye1tlze/subscriptions/s0gmyor4yqtyv1miqwr0 
   -u sk_e568c42a6c384b7ab02cd47d2e407cab: 
   -X DELETE

Immediately cancels a customer subscription. No more charges will be made to the card and all pending charges will be cancelled.

Request

Response

If the response was successfully cancelled the response will be empty. Otherwise an error object explaining the reason.

Subscription list

Definition

GET https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/customers/{CUSTOMER_ID}/subscriptions

Request example

curl -g "https://sandbox-api.openpay.mx/v1/mzdtln0bmtms6o3kck8f/customers/ag4nktpdzebjiye1tlze/subscriptions?limit=10" 
   -u sk_e568c42a6c384b7ab02cd47d2e407cab: 

Response example

[
   {
      "id":"s0gmyor4yqtyv1miqwr0",
      "status":"trial",
      "card":{
         "type":"credit",
         "brand":"american_express",
         "address":null,
         "card_number":"343434XXXXX4343",
         "holder_name":"Juan Perez Ramirez",
         "expiration_year":"20",
         "expiration_month":"12",
         "allows_charges":true,
         "allows_payouts":false,
         "bank_name":"AMERICAN EXPRESS",
         "bank_code":"103"
      },
      "cancel_at_period_end":false,
      "charge_date":"2016-01-12",
      "creation_date":"2014-05-22T15:56:18-05:00",
      "current_period_number":0,
      "period_end_date":"2016-01-11",
      "trial_end_date":"2016-01-11",
      "plan_id":"pbi4kb8hpb64x0uud2eb",
      "customer_id":"ag4nktpdzebjiye1tlze"
   }
]

Returns all the subscriptions active for an specific customer.

Request

You can search using the following parameters:

Response

List of subscription objects for a customer. Sort by creation date in descending order.

Fees

If the customer accounts were created to handle their own balance, a fee can be charged which will be shown in the Merchant account.

Charging a Fee

Definition

POST https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/fees

Request example

curl https://sandbox-api.openpay.mx/v1/mzdtln0bmtms6o3kck8f/fees 
   -u sk_e568c42a6c384b7ab02cd47d2e407cab: 
   -H "Content-type: application/json" 
   -X POST -d '{                                            
     "customer_id" : "dvocf97jd20es3tw5laz",
     "amount" : 12.50,          
     "description" : "Cobro de Comisión",
     "order_id" : "oid-1245"
}' 

Response example

{
   "amount":12.50,
   "authorization":null,
   "method":"customer",
   "operation_type":"out",
   "currency":"MXN",
   "transaction_type":"fee",
   "status":"completed",
   "id":"th8tafyrkakdbyry3kxi",
   "creation_date":"2013-11-18T10:33:03-06:00",
   "description":"Cobro de comisión",
   "error_message":null,
   "order_id":"oid-1245",
   "customer_id":"dvocf97jd20es3tw5laz"
}

Charge a fee to the customer account.

Request

Response

The transaction object of the fee including the creation date and id or an error response..

Refund Fee

Definition

POST https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/fees/{TRANSACTION_ID}/refund

Request example

curl https://sandbox-api.openpay.mx/v1/mzdtln0bmtms6o3kck8f/fees/trzjaozcik8msyqshka4/refund 
   -u sk_e568c42a6c384b7ab02cd47d2e407cab: 
   -H "Content-type: application/json" 
   -X POST -d '{                                            
     "description" : "Devolución de Comisión"
}' 

Response example

{
  "id": "th8tafyrkakdbyry3kxi",
  "authorization": null,
  "method": "customer",
  "operation_type": "in",
  "transaction_type": "refund",
  "status": "completed",
  "conciliated": true,
  "creation_date": "2016-09-06T11:56:57-05:00",
  "operation_date": "2016-09-06T11:56:57-05:00",
  "description": "devolución de comisión merchant03",
  "error_message": null,
  "order_id": null,
  "customer_id": "ar2btmquidjhykdaztp6",
  "amount": 11.11,
  "currency": "MXN"
}

Refund a fee to the customer account.

Request

Response

The transaction object of the refund including the creation date and id or an error response..

Fee list

Definition

GET https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/fees

Request example

curl -g "https://sandbox-api.openpay.mx/v1/mzdtln0bmtms6o3kck8f/fees?limit=10" 
   -u sk_e568c42a6c384b7ab02cd47d2e407cab: 

Response example

[
   {
      "amount":30.00,
      "authorization":null,
      "method":"customer",
      "operation_type":"out",
      "currency":"MXN",
      "transaction_type":"fee",
      "status":"completed",
      "id":"th8tafyrkakdbyry3kxi",
      "creation_date":"2013-11-18T10:33:03-06:00",
      "description":"Cobro de comisión",
      "error_message":null,
      "order_id":"oid-1367",
      "customer_id":"dvocf97jd20es3tw5laz"
   },
   {
      "amount":12.00,
      "authorization":null,
      "method":"customer",
      "operation_type":"out",
      "currency":"MXN",
      "transaction_type":"fee",
      "status":"completed",
      "id":"tdzottaaohuhosf4cdv9",
      "creation_date":"2013-11-17T05:35:00-06:00",
      "description":"Cobro de comisión",
      "error_message":null,
      "order_id":"oid-1366",
      "customer_id":"afk4csrazjp1udezj1po"
   }
]

Returns the details of every fee charged by the Merchant.

Request

It can be done using the following parameters:

Response

Returns an array of transaction objects for the charged fees in descending order, each one with the identifier of the customer to whom it was made.

Webhooks

Weebhooks allow to notify a Merchant party when an event has occurred in the platform, so the Merchant can take the corresponding actions.

Webhook Object

Object example

  {
    "id" : "wxvanstudf4ssme8khmc",
    "url" : "http://requestb.in/11vxrsf1",
    "user" : "juanito",
    "password" : "passjuanito",
    "event_types" : [
      "charge.refunded",
      "charge.failed",
      "charge.cancelled",
      "charge.created",
      "chargeback.accepted"
    ],
    "status":"verified"
}

Valid Webhook service features

• Endpoint: Domains only (No IPs). example: https://notifications.merchant.com
• Port: 443/TCP, 1518/TCP, 1519/TCP, 8443/TCP y 10443/TCP
• Protocol: HTTPS/TLS_1.2
• Certificate: Valid (Signed by public CA and match with domain).

Webhook Creation

Definition

POST https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/webhooks

Request example

curl https://sandbox-api.openpay.mx/v1/mzdtln0bmtms6o3kck8f/webhooks 
   -u sk_e568c42a6c384b7ab02cd47d2e407cab: 
   -H "Content-type: application/json" 
   -X POST -d '{
    "url" : "http://requestb.in/11vxrsf1",
    "user" : "juanito",
    "password" : "passjuanito",
    "event_types" : [
      "charge.refunded",
      "charge.failed",
      "charge.cancelled",
      "charge.created",
      "chargeback.accepted"
    ]
}'

Response example

{
  "id" : "wkn0t30zfxpmhr5usgfa",
  "url" : "http://requestb.in/qt3bq0qt",
  "user" : "juanito",
  "event_types" : [
    "charge.succeeded",
    "charge.created",
    "charge.cancelled",
    "charge.failed"
  ],
  "status" : "verified"
}

When you save webhooks an ID will be generated that can be used to eliminate it or simply get not sensitive webhook information.

At the time of saving the webhook, an id will be generated that can be used to eliminate or simply obtain the non-sensitive information from the webhook.

Request

Response

Returns a webhook object when it was successfully created or an error response if there was an error on creation.

Get a Webhook

Definition

GET https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/webhooks/{WEBHOOK_ID}

Request example

curl https://sandbox-api.openpay.mx/v1/mzdtln0bmtms6o3kck8f/webhooks/wxvanstudf4ssme8khmc 
   -u sk_e568c42a6c384b7ab02cd47d2e407cab: 
   -H "Content-type: application/json"

Response example

  {
    "id" : "wxvanstudf4ssme8khmc",
    "url" : "http://requestb.in/11vxrsf1",
    "user" : "juanito",
    "event_types" : [
      "verification",
      "charge.refunded",
      "charge.failed",
      "charge.cancelled",
      "charge.created",
      "charge.succeeded",
      "subscription.charge.failed",
      "payout.created",
      "payout.succeeded",
      "payout.failed",
      "transfer.succeeded",
      "fee.succeeded",
      "spei.received",
      "chargeback.created",
      "chargeback.rejected",
      "chargeback.accepted"
    ],
    "status" : "verified"
  }

Get a list of the webhook details by ID.

Request

Response

Returns a webhook object

Delete a Webhook

Definition

DELETE https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/webhooks/{WEBHOOK_ID}

Customer request example

curl https://sandbox-api.openpay.mx/v1/mzdtln0bmtms6o3kck8f/webhooks/wxvanstudf4ssme8khmc 
   -u sk_e568c42a6c384b7ab02cd47d2e407cab: 
   -X DELETE

Delete a webhook from the merchant.

To delete a webhook you only need to provide the ID.

Request

Response

If the webhook was deleted correctly the response will be empty, if the webhook cannot be deleted an error object explaining the reason.

Webhook list

Definition

GET https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/webhooks

Request example

curl https://sandbox-api.openpay.mx/v1/mzdtln0bmtms6o3kck8f/webhooks 
   -u sk_e568c42a6c384b7ab02cd47d2e407cab: 
   -H "Content-type: application/json"

Response example

[
  {
    "id" : "wDashboard185",
    "event_types" : [
      "verification",
      "charge.refunded",
      "charge.failed",
      "charge.cancelled",
      "charge.created",
      "charge.succeeded",
      "subscription.charge.failed",
      "payout.created",
      "payout.succeeded",
      "payout.failed",
      "transfer.succeeded",
      "fee.succeeded",
      "spei.received",
      "chargeback.created",
      "chargeback.rejected",
      "chargeback.accepted"
    ],
    "url" : "http://requestb.in/11vxrsf1",
    "status" : "verified"
  },
  {
    "id" : "wDashboard186",
    "event_types" : [
      "verification",
      "charge.refunded",
      "charge.failed",
      "charge.cancelled",
      "charge.created",
      "charge.succeeded",
      "subscription.charge.failed"
    ],
    "url" : "http://requestb.in/1fhpiog1",
    "status" : "verified"
  }
]

Returns a list registered by the merchant.

Request

Response

The list of webhook object registered according to the given parameters.

Tokens

The objective is to created tokens from the user browser or device to capture the card information so this doesn’t go through your server and you can avoid or reduce the PCI certification process.

To use this API functionality we recommend using our JavaScript library for your Web application and our Android and iOS SDK for mobile apps.

Features

• Tokens are created at Merchant level.
• Tokens are not link to any customer.
• After a token has been created it can only be use once to make a charge.

Token Object

Object example

{
      "id":"tokfa4swch8gr4icy2ma",
      "card":{
         "card_number":"1111",
         "holder_name":"Juan Perez Ramirez",
         "expiration_year":"20",
         "expiration_month":"04",
         "address":{
            "line1":"Av 5 de febrero",
            "line2":"Roble 207",
            "line3":"Queretaro",
            "state":"Queretaro",
            "city":"Queretaro",
            "postal_code":"76900",
            "country_code":"MX"
         },
         "creation_date":"2014-01-30T13:53:11-06:00",
         "brand":"visa",
         "points_card":false
      }
   }

Create a new token

Definition

POST https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/tokens

Request example

curl https://sandbox-api.openpay.mx/v1/mzdtln0bmtms6o3kck8f/tokens 
   -u sk_e568c42a6c384b7ab02cd47d2e407cab: 
   -H "Content-type: application/json" 
   -X POST -d '{
   "card_number":"4111111111111111",
   "holder_name":"Juan Perez Ramirez",
   "expiration_year":"20",
   "expiration_month":"12",
   "cvv2":"110",
   "address":{
      "city":"Querétaro",
      "country_code":"MX",
      "postal_code":"76900",
      "line1":"Av 5 de Febrero",
      "line2":"Roble 207",
      "line3":"col carrillo",
      "state":"Queretaro"
   }
}' 

Response example

{
   "id":"k1n0mscnjwhxqia8q7cm",
   "card":{
      "card_number":"411111XXXXXX1111",
      "holder_name":"Juan Perez Ramirez",
      "expiration_year":"20",
      "expiration_month":"12",
      "address":{
         "line1":"Av 5 de Febrero",
         "line2":"Roble 207",
         "line3":"col carrillo",
         "state":"Queretaro",
         "city":"Querétaro",
         "postal_code":"76900",
         "country_code":"MX"
      },
      "creation_date":null,
      "brand":"visa"
   }
}

To create a token using Openpay you need to send the object with the info that will be stored. Once the token it’s stored, you can’t get the number and secutirty code because this information is encrypted.

Request

Repuesta

Returns the created token object or an error response. if an error occurred during the creation.

Get a Token

Definition

GET https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/tokens/{TOKEN_ID}

Request example

curl https://sandbox-api.openpay.mx/v1/mzdtln0bmtms6o3kck8f/tokens/k1n0mscnjwhxqia8q7cm 
   -u sk_e568c42a6c384b7ab02cd47d2e407cab:

Response example

{
   "id":"k1n0mscnjwhxqia8q7cm",
   "card":{
      "card_number":"411111XXXXXX1111",
      "holder_name":"Juan Perez Ramirez",
      "expiration_year":"20",
      "expiration_month":"12",
      "address":{
         "line1":"Av 5 de Febrero",
         "line2":"Roble 207",
         "line3":"col carrillo",
         "state":"Queretaro",
         "city":"Querétaro",
         "postal_code":"76900",
         "country_code":"MX"
      },
      "creation_date":null,
      "brand":"visa"
   }
}

Gets the token details. The ID is required.

Request

Response

Returns a token object

Merchant

The merchant object allows you to query info related to your account using the API,

Merchant Object

Object example:

{ 
   "id": "m9lrykwsmljagrfb38rs", 
   "creationDate": "2013-11-13T16:58:40-06:00", 
   "name": "Promociones en linea", 
   "email": "contacto@enlinea.com.mx", 
   "phone": "(321) 222-2222", 
   "status": "active", 
   "balance": 1000, 
   "clabe": "646180109400000542" 
} 

Request a Merchant Object

Definition

GET https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}

Request example

curl https://sandbox-api.openpay.mx/v1/mzdtln0bmtms6o3kck8f 
   -u sk_e568c42a6c384b7ab02cd47d2e407cab:

Response example

{
   "name":"Demo Openpay",
   "email":"demo@openpay.mx",
   "phone":"(442) 258-1039",
   "status":"active",
   "balance":218.73,
   "clabe":"646180109400135624",
   "id":"mzdtln0bmtms6o3kck8f",
   "creation_date":"2014-01-23T10:45:53-06:00"
}

Returns the merchant account details. Only the unique merchant identifier is required.

Request

Response

If the identifier is correct it will return a merchant object.

Stores

The object represents a convenience store

Store object

Object example:

{
    "id_store": 4913,
    "id": 115,
    "name": "0503 SAN PABLO -QRO",
    "last_update": "2016-02-04T00:52:16-06:00",
    "status": "active",
    "geolocation": {
      "lng": -100.421865,
      "lat": 20.618171,
      "place_id": "ChIJwSN2wpNa04URsDryLW517lg"
    },
    "address": {
      "line1": "AV. 5 DE FEBRERO KM 7.5 NO 1341",
      "line2": "SAN PABLO",
      "line3": null,
      "state": "QUERETARO",
      "city": "QUERETARO",
      "postal_code": "76030",
      "country_code": "MX"
    },
    "paynet_chain": {
      "name": "EXTRA",
      "logo": "http://www.openpay.mx/logotipos/extra.png",
      "thumb": "http://www.openpay.mx/thumb/extra.png",
      "max_amount": 99999.99
    }
  }

Get list of shops by location

Definition

GET https://api.openpay.mx/stores?latitud={latitud}&longitud={longitud}&kilometers={radio}&amount={monto}

Request example

curl https://api.openpay.mx/stores?latitud=20.618975&longitud=-100.422290&kilometers=1.5&amount=4000 
   -u sk_e568c42a6c384b7ab02cd47d2e407cab:

Response example

[
  {
    "id_store": 4913,
    "id": 115,
    "name": "0503 SAN PABLO -QRO",
    "last_update": "2016-02-04T00:52:16-06:00",
    "status": "active",
    "geolocation": {
      "lng": -100.421865,
      "lat": 20.618171,
      "place_id": "ChIJwSN2wpNa04URsDryLW517lg"
    },
    "address": {
      "line1": "AV. 5 DE FEBRERO KM 7.5 NO 1341",
      "line2": "SAN PABLO",
      "line3": null,
      "state": "QUERETARO",
      "city": "QUERETARO",
      "postal_code": "76030",
      "country_code": "MX"
    },
    "paynet_chain": {
      "name": "EXTRA",
      "logo": "http://www.openpay.mx/logotipos/extra.png",
      "thumb": "http://www.openpay.mx/thumb/extra.png",
      "max_amount": 99999.99
    }
  },
  {
    "id_store": 4726,
    "id": 68,
    "name": "ASTURIANO TECNOLOGICO",
    "last_update": "2016-02-04T00:52:16-06:00",
    "status": "active",
    "geolocation": {
      "lng": -100.410136,
      "lat": 20.61632,
      "place_id": "EktQcm9sIFRlY25vbMOzZ2ljbyBOdGUgOTk5LCBTYW4gUGFibG8sIFNhbnRpYWdvIGRlIFF1ZXLDqXRhcm8sIFFyby4sIE3DqXhpY28"
    },
    "address": {
      "line1": "PROLONGACION TECNOLOGICO NORTE #999",
      "line2": "SAN PABLO",
      "line3": null,
      "state": "QUERETARO",
      "city": "QUERETARO",
      "postal_code": "76159",
      "country_code": "MX"
    },
    "paynet_chain": {
      "name": "EL ASTURIANO",
      "logo": "http://www.openpay.mx/logotipos/asturiano.png",
      "thumb": "http://www.openpay.mx/thumb/asturiano.png",
      "max_amount": 99999.99
    }
  }
]

Gets the trade account details. Only it required to indicate the unique id of trade to be obtained.

Request

Response

If there are stores close range a settlement with stores found it is returned.

Common Objects

Information for objects shared in request and response.

Transaction Object

Object example:

{
   "id":"trehwr2zarltvae56vxl",
   "authorization":null,
   "transaction_type":"payout",
   "operation_type":"out",
   "currency":"MXN",
   "method":"bank",
   "creation_date":"2013-11-14T18:29:35-06:00",
   "order_id":"000001",
   "status":"in_progress",
   "amount":500,
   "description":"Pago de ganancias",
   "error_message":null,
   "customer_id":"afk4csrazjp1udezj1po",
   "bank_account":{
      "rfc":ONE316015PM1,
      "mobile":null,
      "alias":null,
      "bank_name":"BANCOMER",
      "creation_date":"2013-11-14T18:29:34-06:00",
      "clabe":"012XXXXXXXXXX24616",
      "holder_name":"Juan Tapia Trejo",
      "bank_code":"012"
   }
}

Address Object

Object example:

{
   "line1":"Av 5 de Febrero",
   "line2":"Roble 207",
   "line3":"col carrillo",
   "state":"Queretaro",
   "city":"Querétaro",
   "postal_code":"76900",
   "country_code":"MX" 
}

Store object

Object example:

{
   "reference":"OPENPAY02DQ35YOY7",
   "barcode_url":"https://sandbox-api.openpay.mx/barcode/OPENPAY02DQ35YOY7?width=1&height=45&text=false",
   "paybin_reference":"0101990000001065",
   "barcode_paybin_url":"https://sandbox-api.openpay.mx/barcode/0101990000001065?width=1&height=45&text=false"
}

PaymentPlan Object

Object example:

{
   "payments":"6"
}

Cardpoints Object

Object example:

{
    "used": 134,
    "remaining": 300,
    "caption": "TRANSACCION APROBADA. ME OBLIGO EN LOS TERMINOS Y CONDICIONES DEL PROGRAMA RECOMPENSAS SANTANDER. PARA CUALQUIER DUDA O ACLARACION LLAME AL 01800 RECOMPE (73-266-73).",
    "amount": 10
}

Object Geolocation

Object example:

{
  "lng": -100.421865,
  "lat": 20.618171,
  "place_id": "ChIJwSN2wpNa04URsDryLW517lg"
}

Object PaynetChain

Object example:

{
      "name": "EXTRA",
      "logo": "http://www.openpay.mx/logotipos/extra.png",
      "thumb": "http://www.openpay.mx/thumb/extra.png",
      "max_amount": 99999.99
    }

Object Transaction Status

Electronic Invoice

Generation of CFDI Object

Voucher Type Object

Form of Payment Object

Payment Method Object

DoctoRelacionado Object

Concept Object

Tax Object

Tax Type Object

Receiver Object

Object Use of CFDI

Related Object

Object Type of Relationship

CFDI Object Related

Complements Object

Complement Airlines Object

Charge Airlines Object

Complement Payment Object

Complement Donee Object

Request Response Generation Object

Notifications Object