Introduction

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 JSON format, 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:

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:

The -u parameter is responsible for the HTTP basic authentication (adding two points after the private key prevents the use of password)
<? 
//Sandbox is used by default 
$openpay = Openpay::getInstance('moiep6umtcnanql3jrxp', 'sk_3433941e467c4875b178ce26348b0fac'); 
?>
//Sandbox
final OpenpayAPI api = new OpenpayAPI("https://sandbox-api.openpay.mx", "moiep6umtcnanql3jrxp", "sk_3433941e467c4875b178ce26348b0fac");

//Production
final OpenpayAPI api = new OpenpayAPI("https://api.openpay.mx", "moiep6umtcnanql3jrxp", "sk_3433941e467c4875b178ce26348b0fac");
var Openpay = require('openpay');
var openpay = new Openpay('moiep6umtcnanql3jrxp','sk_3433941e467c4875b178ce26348b0fac');
//Sandbox
OpenpayAPI openpayAPI = new OpenpayAPI("sk_3433941e467c4875b178ce26348b0fac", "moiep6umtcnanql3jrxp");
openpayAPI.Production = false; // Default value = false

//Produtcion
OpenpayAPI openpayAPI = new OpenpayAPI("sk_3433941e467c4875b178ce26348b0fac", "moiep6umtcnanql3jrxp");
openpayAPI.Production = true;
#Sandbox
openpay=OpenpayApi.new("moiep6umtcnanql3jrxp","sk_3433941e467c4875b178ce26348b0fac")

#Production
openpay=OpenpayApi.new("moiep6umtcnanql3jrxp","sk_3433941e467c4875b178ce26348b0fac", true)


#Define the timeout for the requests
#This cllient uses a default 90 secs timeout. In order to configure the timeout used to create request to the openpay services, you need to clearly define the kind of environment, followed by the new timeout value for the request:

#Syntax:
#   openpay_prod=OpenpayApi.new(merchant_id,private_key,isProduction,timeout)
#Example:
#   openpay_prod=OpenpayApi.new(merchant_id,private_key,false,30)

Production

You only need to use the URI base https://api.openpay.mx
<? 
Openpay::setProductionMode(true); 
?>
//You only need to use the URI base https://api.openpay.mx
openpayAPI.Production = true;
openpay.setProductionReady(true);
#You only need to pass a "true" value as the third argument when creating the OpenpayApi object. 

To make requests to the Openpay API, is necessary to send the API Key on all your calls to our servers. You can get the key from the dashboard.

There are 2 types of API keys:

For API authentication you must use the [basic access authentication]http://es.wikipedia.org/wiki/Autenticación_de_acceso_básica), 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"
    ]
}
//For Java every operation will return an instance of the "OpenpayServiceException" class which will have the error information. ```

```csharp
//For C Sharp,  every operation will return an instance of the "OpenpayException" class which will have the error information.
#For Ruby, every operation can return any of the following exceptions:

# => OpenpayException: For generic errors, like invalid resources, etc.
# => OpenpayConnectionException: For errors related with server connection problems.
# => OpenpayTransactionException: For errors during operations implementation.
Property Description
category string
request: Indicates an error caused by data sent by the customer. For example, an invalid request, an attempt at a transaction without funds or a transfer to an account that does not exist.

internal: Indicates an error on Openpay side, and will occur very rarely.

gateway: Indicates an error during the transaction of funds from one card to the Openpay account or from the account to a bank or card.
error_code numeric
Openpay numeric error code indicating a problem happened.
description string
Error description.
http_code string
HTTP error code of the response.
request_id string
Request identifier.
fraud_rules array
Array with antifraud rules broken according to fraud detection rules.

Error codes

General

Code HTTP Error Cause
1000 500 Internal Server Error An internal error occurred on the Openpay server
1001 400 Bad Request The format of the request is not JSON, the fields do not have the correct format, or the request does not have fields that are required.
1002 401 Unauthorized The call is not authenticated or the authentication is incorrect.
1003 422 Unprocessable Entity The operation could not be completed because the value of one or more of the parameters is incorrect.
1004 503 Service Unavailable A necessary for processing the transaction service is unavailable.
1005 404 Not Found One of the resources requested does not exist.
1006 409 Conflict A transaction with the same order ID already exists.
1007 402 Payment Required The transfer of funds from a bank account or card to the Openpay account was not accepted.
1008 423 Locked One of the accounts required in the request is deactivated.
1009 413 Request Entity too large The request body is too large.
1010 403 Forbidden The public key is used to make a call but it requires the private key, or it ‘s using the private key from JavaScript.

Storage

Code HTTP Error Cause
2001 409 Conflict The bank account with this CLABE is already registered on the customer.
2002 409 Conflict The card with this number is already registered on the customer.
2003 409 Conflict Customer with this external identifier (External ID) already exists.
2004 422 Unprocessable Entity The check digit card number is invalid according to the Luhn algorithm.
2005 400 Bad Request The expiration date of the card is prior to the current date.
2006 400 Bad Request Security code card (CVV2) was not provided.
2007 412 Precondition Failed The card number is a test number and can only be used in Sandbox.
2008 412 Precondition Failed The consulted card is not valid for points.

Cards

Code HTTP Error Cause
3001 402 percent Required The card was declined.
3002 402 Payment Required The card has expired.
3003 402 Payment Required The card has insufficient funds.
3004 402 Payment Required The card has been identified as a stolen card.
3005 402 Payment Required The card has been identified as a fraudulent card.
3006 412 Precondition Failed The operation is not allowed for this customer or this transaction.
3008 412 Precondition Failed The card is not supported in online transactions.
3009 402 Payment Required The card was reported missing.
3010 402 Payment Required The bank has restricted the card.
3011 402 Payment Required The bank has requested that the card is retained. Contact the bank.
3012 412 Precondition Failed A bank authorization is required to make this payment.

Accounts

Code HTTP Error Cause
4001 412 Preconditon Failed The Openpay account has not enough funds.

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.

With a card id or token

Definition

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

Customer
POST https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/customers/{CUSTOMER_ID}/charges
<?
Merchant
$openpay->charges->create(chargeRequest);

Customer
$customer = $openpay->customers->get($customerId);
$customer->charges->create(chargeRequest);
?>
//Customer
openpayAPI.charges().create(String customerId, CreateCardChargeParams request);

//Merchant
openpayAPI.charges().create(CreateCardChargeParams request);
// Merchant
openpay.charges.create(chargeRequest, callback);

// Customer
openpay.customers.charges.create(customerId, chargeRequest, callback);
//Customer
openpayAPI.ChargeService.Create(string customer_id, ChargeRequest request);

//Merchant
openpayAPI.ChargeService.Create(ChargeRequest request);
#Customer
@charges=@openpay.create(:charges)
@charges.create(request_hash, customer_id)

#Merchant
@charges=@openpay.create(:charges)
@charges.create(request_hash)

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,
   "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"
   }
}'
<?
$openpay = Openpay::getInstance('mzdtln0bmtms6o3kck8f', 'sk_e568c42a6c384b7ab02cd47d2e407cab');
$customer = array(
     'name' => 'Juan',
     'last_name' => 'Vazquez Juarez',
     'phone_number' => '4423456723',
     'email' => 'juan.vazquez@empresa.com.mx');

$chargeRequest = array(
    'method' => 'card',
    'source_id' => 'kqgykn96i7bcs1wwhvgw',
    'amount' => 100,
    'description' => 'Cargo inicial a mi merchant',
    'order_id' => 'oid-00051'
    'device_session_id' => 'kR1MiQhz2otdIuUlQkbEyitIqVMiI16f',
    'customer' => $customer);

$charge = $openpay->charges->create($chargeRequest);
?>
OpenpayAPI api = new OpenpayAPI("https://sandbox-api.openpay.mx", "sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
CreateCardChargeParams request = new CreateCardChargeParams();
Customer customer = new Customer();
customer.setName("Juan");
customer.setLastName("Vazquez Juarez");
customer.setPhoneNumber("4423456723");
customer.setEmail("juan.vazquez@empresa.com.mx");

request.cardId("kqgykn96i7bcs1wwhvgw"); // =source_id
request.amount(new BigDecimal("100.00"));
request.description("Cargo inicial a mi merchant");
request.orderId("oid-00051");
request.deviceSessionId("kR1MiQhz2otdIuUlQkbEyitIqVMiI16f");
request.setCustomer(customer);

Charge charge = api.charges().create(request);
OpenpayAPI api = new OpenpayAPI("sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
Customer customer = new Customer();
customer.Name = "Juan";
customer.LastName = "Vazquez Juarez";
customer.PhoneNumber = "4423456723";
customer.Email = "juan.vazquez@empresa.com.mx";

ChargeRequest request = new ChargeRequest();
request.Method = "card";
request.SourceId = "kwkoqpg6fcvfse8k8mg2";
request.Amount = new Decimal(100.00);
request.Description = "Cargo inicial a mi merchant";
request.OrderId = "oid-00051";
request.DeviceSessionId = "kR1MiQhz2otdIuUlQkbEyitIqVMiI16f";
request.Customer = customer;

Charge charge = api.ChargeService.Create(request);
var chargeRequest = {
   'source_id' : 'kqgykn96i7bcs1wwhvgw',
   'method' : 'card',
   'amount' : 100,
   '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'
   }
}

openpay.charges.create(chargeRequest, function(error, charge) {
  // ...
});
@openpay=OpenpayApi.new("moiep6umtcnanql3jrxp","sk_3433941e467c4875b178ce26348b0fac")
@charges=@openpay.create(:charges)
customer_hash={
    "name" => "Juan",
    "last_name" => "Vazquez Juarez",
    "phone_number" => "4423456723",
    "email" => "juan.vazquez@empresa.com.mx"
}
request_hash={
    "method" => "card",
    "source_id" => "kqgykn96i7bcs1wwhvgw",
    "amount" => 100.00,
    "description" => "Cargo inicial a mi merchant",
    "order_id" => "oid-00051",
    "device_session_id" => "kR1MiQhz2otdIuUlQkbEyitIqVMiI16f",
    "customer" => customer_hash
}

response_hash=@charges.create(request_hash.to_hash)

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",
      "customer_id":"ag4nktpdzebjiye1tlze"
   },
   "status":"completed",
   "currency":"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 section.

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

Property Description
method string (required)
It must contain the card value in order to specify the charge will be made from card.
source_id string (required, length = 45)
Saved ID card or token id created from where the funds are withdrawn.
cvv2 numeric (length = 3 or 4)
Security code as it appears on the back of the card. Usually 3 digits.
It’s used only charges with Stored Cards.
amount numeric (required)
Amount to charge. Must be an amount greater than zero, with up to two decimal digits.
description string (required, length = 250)
A description associated to the charge.
order_id string (optional, length = 100)
Unique identifier of charge. Must be unique among all transactions.
device_session_id string (required, length = 255)
Identifier of the device generated by the antifraud tool.
capture boolean (optional, default = true)
Indicates whether the charge is made immediately or not , when the value is false the charge is handled as authorized (or pre-authorization) and the amount is only to be confirmed or canceled in a second call.
customer object (required)
Customer information who is charged. You can use the same parameters used in the creation of a customer but an account for the customer will not be created.

Note: This parameter can be used only by creating the charge at the merchant level

To create a customer and keep a record of their charges history refer to create a customer and do the charge at the customer level.
payment_plan object (opcional)
Plan data months without interest is desired as use in the charge. Refer to PaymentPlan Object.
metadata list(key, value) (optional)
Field list to send antifraud system, It must be according to Rules to send custom antifraud fields.
use_card_points string (optional, default = NONE)
ONLY_POINTS Charge only with points (Points card)
MIXEDCharge with points and pesos
NONE Charge only with pesos
The values that indicate points must be used only if the points_card property is true, otherwise an error will occur.
send_email boolean (optional)
Used in redirect charges. Indicates if is need send a email that redirect to the openpay payment form.
redirect_url string (optional)
Used in redirect charges. It indicates the url to which redirect after a successful transaction in the openpay payment form.
use_3d_secure boolean (optional)
Used to specify if 3D Secure should be used.

Response

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

With redirect

Definition

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

Customer
POST https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/customers/{CUSTOMER_ID}/charges
<?
Merchant
$openpay->charges->create(chargeRequest);

Customer
$customer = $openpay->customers->get($customerId);
$customer->charges->create(chargeRequest);
?>
//Customer
openpayAPI.charges().create(String customerId, CreateCardChargeParams request);

//Merchant
openpayAPI.charges().create(CreateCardChargeParams request);
// Merchant
openpay.charges.create(chargeRequest, callback);

// Customer
openpay.customers.charges.create(customerId, chargeRequest, callback);
//Customer
openpayAPI.ChargeService.Create(string customer_id, ChargeRequest request);

//Merchant
openpayAPI.ChargeService.Create(ChargeRequest request);
#Customer
@charges=@openpay.create(:charges)
@charges.create(request_hash, customer_id)

#Merchant
@charges=@openpay.create(:charges)
@charges.create(request_hash)

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"
}'
<?
$openpay = Openpay::getInstance('mzdtln0bmtms6o3kck8f', 'sk_e568c42a6c384b7ab02cd47d2e407cab');
$customer = array(
     'name' => 'Juan',
     'last_name' => 'Vazquez Juarez',
     'phone_number' => '4423456723',
     'email' => 'juan.vazquez@empresa.com.mx');

$chargeRequest = array(
    "method" : "card",
    'amount' => 100,
    'description' => 'Cargo terminal virtual a mi merchant',
    'customer' => $customer,
    'send_email' => false,
    'confirm' => false,
    'redirect_url' => 'http://www.openpay.mx/index.html')
;

$charge = $openpay->charges->create($chargeRequest);
?>
OpenpayAPI api = new OpenpayAPI("https://sandbox-api.openpay.mx", "sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
CreateCardChargeParams request = new CreateCardChargeParams();
Customer customer = new Customer();
customer.setName("Juan");
customer.setLastName("Vazquez Juarez");
customer.setPhoneNumber("4423456723");
customer.setEmail("juan.vazquez@empresa.com.mx");

request.amount(new BigDecimal("100.00"));
request.description("Cargo inicial a mi merchant");
request.orderId("oid-00051");
request.setCustomer(customer);
request.setSendEmail(false);
request.setConfirm(false);
request.setRedirectUrl("http://www.openpay.mx/index.html");

Charge charge = api.charges().create(request);
OpenpayAPI api = new OpenpayAPI("sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
ChargeRequest request = new ChargeRequest();
Customer customer = new Customer();
customer.Name = "Juan";
customer.LastName = "Vazquez Juarez";
customer.PhoneNumber = "4423456723";
customer.Email = "juan.vazquez@empresa.com.mx";

request.Method = "card";
request.Amount = new Decimal(100.00);
request.Description = "Cargo inicial a mi merchant";
request.OrderId = "oid-00051";
request.Confirm = false;
request.SendEmail = false;
request.RedirectUrl = "http://www.openpay.mx/index.html";
request.Customer = customer;

Charge charge = api.ChargeService.Create(request);
var chargeRequest = {
   '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'
   },
  'send_email' : false,
  'confirm' : false,
  'redirect_url' : 'http://www.openpay.mx/index.html')
}

openpay.charges.create(chargeRequest, function(error, charge) {
  // ...
});
@openpay=OpenpayApi.new("moiep6umtcnanql3jrxp","sk_3433941e467c4875b178ce26348b0fac")
@charges=@openpay.create(:charges)
customer_hash={
    "name" => "Juan",
    "last_name" => "Vazquez Juarez",
    "phone_number" => "4423456723",
    "email" => "juan.vazquez@empresa.com.mx"
}

request_hash={
    "method" => "card",
    "amount" => 100.00,
    "description" => "Cargo inicial a mi merchant",
    "order_id" => "oid-00051",
    "customer" => customer_hash,
    "send_email" => false,
    "confirm" => false,
    "redirect_url" => "http://www.openpay.mx/index.html"
}

response_hash=@charges.create(request_hash.to_hash)

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

Property Description
method string (required in card)
It must contain the card value in order to specify the charge will be made from card.
amount numeric (required)
Amount to charge. Must be an amount greater than zero, with up to two decimal digits.
description string (required, length = 250)
A description associated to the charge.
order_id string (optional, length = 100)
Unique identifier of charge. Must be unique among all transactions.
customer object (required)
Customer information who is charged. You can use the same parameters used in the creation of a customer but an account for the customer will not be created.

Note: This parameter can be used only by creating the charge at the merchant level

To create a customer and keep a record of their charges history refer to create a customer and do the charge at the customer level.
confirm boolean (required in false)
Indicates whether the charge is made immediately or not , when the value is false the charge is handled as authorized (or pre-authorization) and the amount is only to be confirmed or canceled in a second call.
send_email boolean (optional)
Indicates if is need send a email that redirect to the openpay payment form.
redirect_url string (required)
It indicates the url to which redirect after a successful transaction in the openpay payment form.

Response

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

Charge via store

Definition

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

Customer
POST https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/customers/{CUSTOMER_ID}/charges
<?
Merchant
$openpay->charges->create(chargeRequest);

Customer
$customer = $openpay->customers->get(customerId);
$customer->charges->create(chargeRequest;
?>
//Customer
openpayAPI.charges().create(String customerId, CreateStoreChargeParams request);

//Merchant
openpayAPI.charges().create(CreateStoreChargeParams request);
//Customer
openpayAPI.ChargeService.Create(string customer_id, ChargeRequest request);

//Merchant
openpayAPI.ChargeService.Create(ChargeRequest request);
//Merchant
openpay.charges.create(chargeRequest, callback);

//Customer
openpay.customers.charges.create(customerId, chargeRequest, callback);
#Customer
@charges=@openpay.create(:charges)
@charges.create(request_hash, customer_id)

#Merchant
@charges=@openpay.create(:charges)
@charges.create(request_hash)

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-28T13:45:00"
}'
<?
$openpay = Openpay::getInstance('mzdtln0bmtms6o3kck8f', 'sk_e568c42a6c384b7ab02cd47d2e407cab');

$chargeRequest = array(
    'method' => 'store',
    'amount' => 100,
    'description' => 'Cargo con tienda',
    'order_id' => 'oid-00053',
    'due_date' => '2014-05-28T13:45:00');

$customer = $openpay->customers->get('ag4nktpdzebjiye1tlze');
$charge = $customer->charges->create($chargeRequest);
?>
OpenpayAPI api = new OpenpayAPI("https://sandbox-api.openpay.mx", "sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
Calendar dueDate = Calendar.getInstance();
dueDate.set(2014, 5, 28, 13, 45, 0);
CreateStoreChargeParams request = new CreateStoreChargeParams();
request.amount(new BigDecimal("100.00"));
request.description("Cargo con tienda");
request.orderId("oid-00053"
request.dueDate(dueDate.getTime());

Charge charge = api.charges().create("ag4nktpdzebjiye1tlze", request);
OpenpayAPI api = new OpenpayAPI("sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
ChargeRequest request = new ChargeRequest();
request.Method = "store";
request.Amount = new Decimal(100.00);
request.Description = "Cargo con tienda";
request.OrderId = "oid-00053";
request.DueDate = new DateTime(2014, 5, 28, 13, 45, 0);

Charge charge = api.ChargeService.Create("ag4nktpdzebjiye1tlze", request);
var storeChargeRequest = {
   'method' : 'store',
   'amount' : 100,
   'description' : 'Cargo con tienda',
   'order_id' : 'oid-00053',
   'due_date' : '2014-05-28T13:45:00'
};

openpay.customers.charges.create('ag4nktpdzebjiye1tlze', storeChargeRequest, function(error, charge) {
  // ...
});
@openpay=OpenpayApi.new("moiep6umtcnanql3jrxp","sk_3433941e467c4875b178ce26348b0fac")
@charges=@openpay.create(:charges)
request_hash={
     "method" => "store",
     "amount" => 100.00,
     "description" => "Cargo con tienda",
     "order_id" => "oid-00053",
     "due_date" => "2014-05-28T13:45:00"
   }

response_hash=@charges.create(request_hash.to_hash, "ag4nktpdzebjiye1tlze")

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 store as 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

Property Description
method string (required)
It must constains the store value in order to specify you want to pay at store.
amount numeric (required)
Amount of charge. Must be an amount greater than zero, with up to two decimal digits.
description string (required, length = 250)
A description associated to the charge.
order_id string (optional, length = 100)
Unique identifier of charge. Must be unique among all transactions.
due_date datetime (optional)
Due date for making the payment in the store in ISO 8601 format.

Example (UTC): 2014-08-01T00:50:00Z
Note: On the server side the date will be changeg to central time

Example (Central Time): 2014-08-01T11:51:23-05:00
customer object (required)
Customer information who is charged. You can use the same parameters used in the creation of a customer but an account for the customer will not be created.

Note: This parameter can be used only by creating the charge at the Merchant level establishing a level trade

To create a customer and keep a record of their charges history refer to create a customer and do the charge at the customer level.

Response

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

Charge via bank

Definition

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

Customer
POST https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/customers/{CUSTOMER_ID}/charges
<?
Merchant
$openpay->charges->create(chargeRequest);

Customer
$customer = $openpay->customers->get(customerId);
$customer->charges->create(chargeRequest);
?>
//Customer
openpayAPI.charges().create(String customerId, CreateBankChargeParams request);

//Merchant
openpayAPI.charges().create(CreateBankChargeParams request);
//Customer
openpayAPI.ChargeService.Create(string customer_id, ChargeRequest request);

//Merchant
openpayAPI.ChargeService.Create(ChargeRequest request);
// Merchant
openpay.charges.create(chargeRequest, callback);

// Customer
openpay.customers.charges.create(customerId, chargeRequest, callback);
#Customer
@charges=@openpay.create(:charges)
@charges.create(request_hash, customer_id)

#Merchant
@charges=@openpay.create(:charges)
@charges.create(request_hash)

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"
} '
<?
$openpay = Openpay::getInstance('mzdtln0bmtms6o3kck8f', 'sk_e568c42a6c384b7ab02cd47d2e407cab');

$chargeRequest = array(
    'method' => 'bank_account',
    'amount' => 100,
    'description' => 'Cargo con banco',
    'order_id' => 'oid-00055');

$customer = $openpay->customers->get('ag4nktpdzebjiye1tlze');
$charge = $customer->charges->create($chargeRequest);
?>
OpenpayAPI api = new OpenpayAPI("https://sandbox-api.openpay.mx", "sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
CreateBankChargeParams request = new CreateBankChargeParams();
request.amount(new BigDecimal("100.00"));
request.description("Cargo con banco");
request.orderId("oid-00053");

Charge charge = api.charges().create("ag4nktpdzebjiye1tlze", request);
OpenpayAPI api = new OpenpayAPI("sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
ChargeRequest request = new ChargeRequest();
request.Method = "bank_account";
request.Amount = new Decimal(100.00);
request.Description = "Cargo con banco";
request.OrderId = "oid-00053";

Charge charge = api.ChargeService.Create("ag4nktpdzebjiye1tlze", request);
var bankChargeRequest = {
   'method' : 'bank_account',
   'amount' : 100,
   'description' : 'Cargo con banco',
   'order_id' : 'oid-00055'
};

openpay.customers.charges.create('ag4nktpdzebjiye1tlze', bankChargeRequest, function(error, charge) {
  // ...
});

@openpay=OpenpayApi.new("moiep6umtcnanql3jrxp","sk_3433941e467c4875b178ce26348b0fac")
@charges=@openpay.create(:charges)
request_hash={
     "method" => "bank_account",
     "amount" => 100.00,
     "description" => "Cargo con banco",
     "order_id" => "oid-00053"
   }

response_hash=@charges.create(request_hash.to_hash, "ag4nktpdzebjiye1tlze")

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_account** as 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

Property Description
method string (required)
It must contain the bank_account value to specify the pay will be made with bank transfer.
amount numeric (required)
Amount of charge. Must be an amount greater than zero, with up to two decimal digits.
description string (required, length = 250)
A description associated to the charge.
order_id string (optional, length = 100)
Unique identifier of charge. Must be unique among all transactions.
due_date datetime (optional)
>Due date for making the bank charge in the ISO 8601 format.

Example (UTC): 2014-08-01T00:50:00Z
Note: On the server side the date will be changed to central time

Example (Central Time): 2014-08-01T11:51:23-05:00
customer object (optional)
Customer information who is charged. You can use the same parameters used in the creation of a customer but an account for the customer will not be created.

Note: This parameter can be used only by creating the charge at the Merchant level establishing a level trade

To create a customer and keep a record of their charges history refer to create a customer and do the charge at the customer level.

Response

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

With Alipay

Definition

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

Customer
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 '{
   "description": "Cargo Alipay",
   "amount": "2000.00",
   "method": "alipay",
   "order_id": "oid-00053",
   "redirect_url" : "http://www.example.com/myRedirectUrl"
} '
<?
$openpay = Openpay::getInstance('mzdtln0bmtms6o3kck8f', 'sk_e568c42a6c384b7ab02cd47d2e407cab');

$chargeRequest = array(
    'method' => 'alipay',
    'amount' => 100,
    'description' => 'Cargo Alipay',
    'order_id' => 'oid-00055',
    'redirect_url' => 'http://www.example.com/myRedirectUrl');

$customer = $openpay->customers->get('ag4nktpdzebjiye1tlze');
$charge = $customer->charges->create($chargeRequest);
?>
OpenpayAPI api = new OpenpayAPI("https://sandbox-api.openpay.mx", "sk_b05586ec98454522ac7d4ccdcaec9128", "mzdtln0bmtms6o3kck8f");
CreateAlipayChargeParams request = new CreateAlipayChargeParams();
request.amount(new BigDecimal("100.00"));
request.description("Cargo Alipay");
request.orderId("oid-00053");
request.redirectUrl("http://www.example.com/myRedirectUrl")

Charge charge = api.charges().createCharge("ag4nktpdzebjiye1tlze", request);
OpenpayAPI api = new OpenpayAPI("sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
ChargeRequest request = new ChargeRequest();
request.Method = "alipay";
request.Amount = new Decimal(100.00);
request.Description = "Cargo Alipay";
request.OrderId = "oid-00053";
request.RedirectUrl ="http://www.example.com/myRedirectUrl";

Charge charge = api.ChargeService.Create("ag4nktpdzebjiye1tlze", request);
var alipayChargeRequest = {
   'method' : 'alipay',
   'amount' : 100,
   'description' : 'Cargo Alipay',
   'order_id' : 'oid-00055',
   'redirect_url' : 'http://www.example.com/myRedirectUrl'
};

openpay.customers.charges.create('ag4nktpdzebjiye1tlze', alipayChargeRequest, function(error, charge) {
  // ...
});
@openpay=OpenpayApi.new("moiep6umtcnanql3jrxp","sk_3433941e467c4875b178ce26348b0fac")
@charges=@openpay.create(:charges)
request_hash={
     "method" => "alipay",
     "amount" => 100.00,
     "description" => "Cargo Alipay",
     "order_id" => "oid-00053",
     "redirect_url" => "http://www.example.com/myRedirectUrl"
   }

response_hash=@charges.create(request_hash.to_hash, "ag4nktpdzebjiye1tlze")

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 alipay as 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

Property Description
method string (required)
It must constains the alipat value in order to specify you want the customer to pay using Alipay.
amount numeric (required)
Amount of charge. Must be an amount greater than zero, with up to two decimal digits.
description string (required, length = 250)
A description associated to the charge.
order_id string (optional, length = 100)
Unique identifier of charge. Must be unique among all transactions.
due_date datetime (optional)
Due date for making the payment in Alipay in ISO 8601 format. The customer may have an additional 15 minutes after this date after they login to their Alipay account to complete payment.

Example (UTC): 2014-08-01T00:50:00Z
Note: On the server side the date will be changeg to central time

Example (Central Time): 2014-08-01T11:51:23-05:00
customer object (required)
Customer information who is charged. You can use the same parameters used in the creation of a customer but an account for the customer will not be created.

Note: This parameter can be used only by creating the charge at the Merchant level establishing a level trade

To create a customer and keep a record of their charges history refer to create a customer and do the charge at the customer level.
redirect_url string (required)
It indicates the url to which redirect after a successful transaction in the openpay payment form, when a request is receiven in this url, merchant must get id attribute to request for the transaction final result.

Response

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

Confirming a charge

Definition

Merchant
POST https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/charges/{TRANSACTION_ID}/capture

Customer
POST https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/customers/{CUSTOMER_ID}/charges/{TRANSACTION_ID}/capture
<?
Merchant
$charge = $openpay->charges->get(transactionId);
$charge->capture(captureData);

Customer
$customer = $openpay->customers->get(customerId);
$charge = $customer->charges->get(transactionId);
$charge->capture(captureData);
?>
//Customer
openpayAPI.charges().confirmCapture(String customerId, ConfirmCaptureParams request);

//Merchant
openpayAPI.charges().confirmCapture(ConfirmCaptureParams request);
//Customer
openpayAPI.ChargeService.Capture(string customer_id, string transaction_id, Decimal? amount);

//Merchant
openpayAPI.ChargeService.Capture(string transaction_id, Decimal? amount);
// Merchant
openpay.charges.capture(transactionId, captureRequest, callback);

// Customer
openpay.customers.charges.capture(customerId, transactionId, captureRequest, callback);
#Customer
@charges=@openpay.create(:charges)
@charges.capture(transaction_id, customer_id)

#Merchant
@charges=@openpay.create(:charges)
@charges.capture(transaction_id)

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
} '
<?
$openpay = Openpay::getInstance('mzdtln0bmtms6o3kck8f', 'sk_e568c42a6c384b7ab02cd47d2e407cab');

$captureData = array('amount' => 100.00);

$customer = $openpay->customers->get('ag4nktpdzebjiye1tlze');
$charge = $customer->charges->get('tryqihxac3msedn4yxed');
$charge->capture($captureData);
?>
OpenpayAPI api = new OpenpayAPI("https://sandbox-api.openpay.mx", "sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
ConfirmCaptureParams request = new ConfirmCaptureParams();
request.chargeId("tryqihxac3msedn4yxed");
request.amount(new BigDecimal("100.00"));

Charge charge = api.charges().confirmCapture("ag4nktpdzebjiye1tlze", request);
OpenpayAPI api = new OpenpayAPI("sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
Charge charge = api.ChargeService.Capture("ag4nktpdzebjiye1tlze", "tryqihxac3msedn4yxed", new Decimal(100.00));
var captureRequest = {
  'amount' : 100.00
};

openpay.customers.charges.capture('ag4nktpdzebjiye1tlze', 'tryqihxac3msedn4yxed', captureRequest,
    function(error, charge){
  // ...
});
@openpay=OpenpayApi.new("moiep6umtcnanql3jrxp","sk_3433941e467c4875b178ce26348b0fac")
@charges=@openpay.create(:charges)

response_hash=@charges.capture("tryqihxac3msedn4yxed", "ag4nktpdzebjiye1tlze")

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

Property Description
amount numeric (required)
Amount to confirm. It can be less than or equal to the amount given with up to two decimal digits

Response

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

Refunding a charge

Definition

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

Customer
POST https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/customers/{CUSTOMER_ID}/charges/{TRANSACTION_ID}/refund
<?
Merchant
$charge = $openpay->charges->get(transactionId);
$charge->refund(refundData);

Customer
$customer = $openpay->customers->get(customerId);
$charge = $customer->charges->get(transactionId);
$charge->refund(refundData);
?>
//Customer
openpayAPI.charges().refund(String customerId, RefundParams request);

//Merchant
openpayAPI.charges().refund(RefundParams request);
//Customer
openpayAPI.ChargeService.Refund(string customer_id, string transaction_id, string description);

//Merchant
openpayAPI.ChargeService.Refund(string transaction_id, string description);
// Merchant
openpay.charges.refund(transactionId, refundRequest, callback);

// Customer
openpay.customers.charges.refund(customerId, transactionId, refundRequest, callback);
#Customer
@charges=@openpay.create(:charges)
@charges.refund(transaction_id, request_hash, customer_id)

#Merchant
@charges=@openpay.create(:charges)
@charges.refund(transaction_id, request_hash)

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
} '
<?
$openpay = Openpay::getInstance('mzdtln0bmtms6o3kck8f', 'sk_e568c42a6c384b7ab02cd47d2e407cab');

$refundData = array(
    'description' => 'devolución',
    'amount' => 100);

$customer = $openpay->customers->get('ag4nktpdzebjiye1tlze');
$charge = $customer->charges->get('tr6cxbcefzatd10guvvw');
$charge->refund($refundData);
?>
OpenpayAPI api = new OpenpayAPI("https://sandbox-api.openpay.mx", "sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
RefundParams request = new RefundParams();
request.chargeId("tryqihxac3msedn4yxed");
request.description("Monto de cargo devuelto");
request.amount(new BigDecimal("100.00"));

Charge charge = api.charges().refund("ag4nktpdzebjiye1tlze", request);
OpenpayAPI api = new OpenpayAPI("sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
Charge charge = api.ChargeService.Refund("ag4nktpdzebjiye1tlze", "tryqihxac3msedn4yxed", "Monto de cargo devuelto", , new Decimal(100.00));
var refundRequest = {
   'description' : 'devolución',
   'amount' : 100.00
};

openpay.customers.charges.refund('ag4nktpdzebjiye1tlze', 'tryqihxac3msedn4yxed', refundRequest,
    function(error, charge) {
  // ...
});
@openpay=OpenpayApi.new("moiep6umtcnanql3jrxp","sk_3433941e467c4875b178ce26348b0fac")
@charges=@openpay.create(:charges)

request_hash={
     "description" => "Monto de cargo devuelto",
     "amount" => 100.00
   }

response_hash=@charges.refund("tryqihxac3msedn4yxed", request_hash.to_hash, "ag4nktpdzebjiye1tlze")

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

Property Description
description string (optional, length = 250)
Text to describe the refund reason.
amount numeric (opcional)
Amount to refund. Must be an amount greater than zero and lesser or equal than the original amount, with up to two decimal digits.

Response

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

Get a charge

Definition

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

Merchant
GET https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/customers/{CUSTOMER_ID}/charges/{TRANSACTION_ID}
<?
Merchant
$charge = $openpay->charges->get(transactionId);

Customer
$customer = $openpay->customers->get(customerId);
$charge = $customer->charges->get(transactionId);
?>
//Customer
openpayAPI.charges().get(String customerId, String transactionId);

//Merchant
openpayAPI.charges().get(String transactionId);
//Customer
openpayAPI.ChargeService.Get(string customer_id, string transaction_id);

//Merchant
openpayAPI.ChargeService.Get(string transaction_id);
// Merchant
openpay.charges.get(transactionId, callback);

// Customer
openpay.customers.charges.get(customerId, transactionId, callback);
#Customer
@charges=@openpay.create(:charges)
@charges.get(transaction_id, customerId)

#Merchant
@charges=@openpay.create(:charges)
@charges.get(transaction_id)

Customer request example

curl https://sandbox-api.openpay.mx/v1/mzdtln0bmtms6o3kck8f/customers/ag4nktpdzebjiye1tlze/charges/tr6cxbcefzatd10guvvw \
   -u sk_e568c42a6c384b7ab02cd47d2e407cab:
<?
$openpay = Openpay::getInstance('mzdtln0bmtms6o3kck8f', 'sk_e568c42a6c384b7ab02cd47d2e407cab');

$customer = $openpay->customers->get('ag4nktpdzebjiye1tlze');
$charge = $customer->charges->get('tr6cxbcefzatd10guvvw');
?>
OpenpayAPI api = new OpenpayAPI("https://sandbox-api.openpay.mx", "sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
Charge charge = api.charges().get("ag4nktpdzebjiye1tlze", "tr6cxbcefzatd10guvvw");
OpenpayAPI api = new OpenpayAPI("sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
Charge charge = api.ChargeService.Get("ag4nktpdzebjiye1tlze", "tryqihxac3msedn4yxed");
openpay.customers.charges.get('ag4nktpdzebjiye1tlze', 'tr6cxbcefzatd10guvvw', function(error, charge){
  // ...
});
@openpay=OpenpayApi.new("moiep6umtcnanql3jrxp","sk_3433941e467c4875b178ce26348b0fac")
@charges=@openpay.create(:charges)

response_hash=@charges.get("tr6cxbcefzatd10guvvw", "ag4nktpdzebjiye1tlze")

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 the information of a charge generated at any moment, only by knowing the charge id.

Request

Property Description
transaction_id string (required, length = 45)
Charge Id.

Response

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

List of charges

Definition

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

Merchant
GET https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/customers/{CUSTOMER_ID}/charges
<?
Merchant
$chargeList = $openpay->charges->getList(searchParams);

Customer
$customer = $openpay->customers->get(customerId);
$chargeList = $customer->charges->getList(searchParams);
?>
//Customer
openpayAPI.charges().list(String customerId, SearchParams request);

//Merchant
openpayAPI.charges().list(SearchParams request);
//Customer
openpayAPI.ChargeService.List(string customer_id, SearchParams request = null);

//Merchant
openpayAPI.ChargeService.List(SearchParams request = null);
// Merchant
openpay.charges.list(callback);
openpay.charges.list(searchParams, callback);

// Customer
openpay.customers.charges.list(customerId, callback);
openpay.customers.charges.list(customerId, searchParams, callback);
#Customer
@charges=@openpay.create(:charges)
@charges.all(customer_id)

#Merchant
@charges=@openpay.create(:charges)
@charges.all

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:
<?
$openpay = Openpay::getInstance('mzdtln0bmtms6o3kck8f', 'sk_e568c42a6c384b7ab02cd47d2e407cab');

$searchParams = array(
    'creation[gte]' => '2013-11-01',
    'creation[lte]' => '2014-11-01',
    'offset' => 0,
    'limit' => 2);

$customer = $openpay->customers->get('ag4nktpdzebjiye1tlze');
$chargeList = $customer->charges->getList($searchParams);
?>
final Calendar dateGte = Calendar.getInstance();
final Calendar dateLte = Calendar.getInstance();
dateGte.set(2014, 5, 1, 0, 0, 0);
dateLte.set(2014, 5, 15, 0, 0, 0);

OpenpayAPI api = new OpenpayAPI("https://sandbox-api.openpay.mx", "sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
SearchParams request = new SearchParams();
request.creationGte(dateGte.getTime());
request.creationLte(dateLte.getTime());
request.offset(0);
request.limit(100);
request.amount(new BigDecimal("100.00"));

List<Charge> charges = api.charges().list("ag4nktpdzebjiye1tlze", request);
OpenpayAPI api = new OpenpayAPI("sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
SearchParams request = new SearchParams();
request.CreationGte = new Datetime(2014, 5, 1);
request.CreationLte = new DateTime(2014, 5, 15);
request.Offset = 0;
request.Limit = 100;
request.Amount = new Decimal(100.00);

List<Charge> charges= openpayAPI.ChargeService.List("ag4nktpdzebjiye1tlze", request);
var searchParams = {
  'creation[gte]' : '2013-11-01',
  'limit' : 2
};

openpay.customers.charges.list('ag4nktpdzebjiye1tlze',searchParams, function(error, chargeList) {
  // ...
});
@openpay=OpenpayApi.new("moiep6umtcnanql3jrxp","sk_3433941e467c4875b178ce26348b0fac")
@charges=@openpay.create(:charges)

response_hash=@charges.all("ag4nktpdzebjiye1tlze")

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.

Property Description
order_id string
Unique order id generated by the merchant and associated to the transaction by the order_id field of the charge request.
creation date
Same as creation date. Format yyyy-mm-dd
creation[gte] date
After the creation date. Format yyyy-mm-dd
creation[lte] date
Before the creation date. Format yyyy-mm-dd
offset numeric
Number of records to skip at the beginning, default 0.
limit numeric
Number of required records, default 10.
amount numeric
Same as the amount.
amount[gte] numeric
Greater than or equal to the amount.
amount[lte] numeric
Less than or equal to the amount.
status TransactionStatus
Estado de la transacción (IN_PROGRESS,COMPLETED,REFUNDED,CHARGEBACK_PENDING,CHARGEBACK_ACCEPTED,CHARGEBACK_ADJUSTMENT,CHARGE_PENDING,CANCELLED,FAILED).

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

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

Customer
POST https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/customers/{CUSTOMER_ID}/payouts
<?
Customer
$customer = $openpay->customers->get(customerId);
$payout = $customer->payouts->create(payoutRequest);

Merchant
$payout = $openpay->payouts->create(payoutRequest);
?>
//Customer
openpayAPI.payouts().create(String customerId, CreateBankPayoutParams request);

//Merchant
openpayAPI.payouts().create(CreateBankPayoutParams request);
//Customer
openpayAPI.PayoutService.Create(string customer_id, PayoutRequest request);

//Merchant
openpayAPI.PayoutService.Create(PayoutRequest request);
// Merchant
openpay.payouts.create(payoutRequest, callback);

// Customer
openpay.customers.payouts.create(customerId, payoutRequest, callback);
#Customer
@payouts=@openpay.create(:payouts)
@payouts.create(request_hash, customer_id)

#Merchant
@payouts=@openpay.create(:payouts)
@payouts.create(request_hash)

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"
}' 
<?
$openpay = Openpay::getInstance('mzdtln0bmtms6o3kck8f', 'sk_e568c42a6c384b7ab02cd47d2e407cab');

$payoutRequest = array(
    'method' => 'bank_account',
    'destination_id' => 'b3d54sd3mdjf75udjfvoc',
    'amount' => 1000,
    'description' => 'Retiro de saldo semanal',
    'order_id' => 'ORDEN-00021');

$customer = $openpay->customers->get('ag4nktpdzebjiye1tlze');
$payout = $customer->payouts->create($payoutRequest);
?>
OpenpayAPI api = new OpenpayAPI("https://sandbox-api.openpay.mx", "sk_e568c42a6c384b7ab02cd47d2e407cab", "mzdtln0bmtms6o3kck8f");
CreateBankPayoutParams request = new CreateBankPayoutParams();
request.bankAccountId("b3d54sd3mdjf75udjfvoc"); // = destination_id
request.amount(new BigDecimal("10.50"));
request.description("Retiro de saldo semanal");
request.orderId("oid-00021");

Payout payout = api.payouts().create("ag4nktpdzebjiye1tlze", request);
OpenpayAPI api = new OpenpayAPI("sk_e568c42a6c384b7ab02cd47d2e407cab", "mzdtln0bmtms6o3kck8f");
PayoutRequest request = new PayoutRequest();
request.Method = "bank_account";
request.DestinationId = "b3d54sd3mdjf75udjfvoc";
request.Amount = new Decimal(10.50;
request.Description = "Retiro de saldo semanal";
request.OrderId = "oid-00021;

Payout = api.PayoutService.Create("ag4nktpdzebjiye1tlze", request);
var payoutRequest = {
    'method': 'bank_account',
    'destination_id': 'b3d54sd3mdjf75udjfvoc',
    'amount': 10.50,
    'description': 'Retiro de saldo semanal',
    'order_id': 'oid-00021'
};

openpay.customers.payouts.create('ag4nktpdzebjiye1tlze', payoutRequest, function(error, payout) {
  // ...
});
@openpay=OpenpayApi.new("mzdtln0bmtms6o3kck8f","sk_e568c42a6c384b7ab02cd47d2e407cab")
@payouts=@openpay.create(:payouts)
request_hash={
     "method" => "bank_account",
     "destination_id" => "b3d54sd3mdjf75udjfvoc",   
     "amount" => 10.50,
     "description" => "Retiro de saldo semanal",
     "order_id" => "oid-00021"
   }

response_hash=@payouts.create(request_hash.to_hash, "ag4nktpdzebjiye1tlze")

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

Property Description
method string (required)
It must contain the value bank_account.
destination_id string (required, length = 45)
ID of the registered bank account.
amount numeric (required)
Amount of payout. Must be an amount greater than zero, with up to two decimal digits.
description string (required, length = 250)
A description associated to the payment.
order_id string (optional, length = 100)
Unique identifier of payout. Must be unique among all transactions.

Response

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

Payment to a bank account

Definition

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

Customer
POST https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/customers/{CUSTOMER_ID}/payouts
<?
Customer
$customer = $openpay->customers->get(customerId);
$payout = $customer->payouts->create(payoutRequest);

Merchant
$payout = $openpay->payouts->create(payoutRequest);
?>
//Customere
openpayAPI.payouts().create(String customerId, CreateBankPayoutParams request);

//Comercio
openpayAPI.payouts().create(CreateBankPayoutParams request);
//Customer
openpayAPI.PayoutService.Create(string customer_id, PayoutRequest request);

//Merchant
openpayAPI.PayoutService.Create(PayoutRequest request);
// Merchant
openpay.payouts.create(payoutRequest, callback);

// Customer
openpay.customers.payouts.create(customerId, payoutRequest, callback);
#Customer
@payouts=@openpay.create(:payouts)
@payouts.create(request_hash, customer_id)

#Merchant
@payouts=@openpay.create(:payouts)
@payouts.create(request_hash)

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"
}' 
<?
$openpay = Openpay::getInstance('mzdtln0bmtms6o3kck8f', 'sk_e568c42a6c384b7ab02cd47d2e407cab');

$payoutRequest = array(
    'method' => 'bank_account',
    'bank_account' => array(
        'clabe' => '012298026516924616',
        'holder_name' => 'Mi empresa'),
    'amount' => 100.00,
    'description' => 'Retiro de saldo semanal',
    'order_id' => 'ORDEN-00021');

$customer = $openpay->customers->get('asynwirguzkgq2bizogo');
$payout = $customer->payouts->create($payoutRequest);
?>
OpenpayAPI api = new OpenpayAPI("https://sandbox-api.openpay.mx", "sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
CreateBankPayoutParams request = new CreateBankPayoutParams();
BankAccount bankAccount = new BankAccount();
bankAccount.holderName("Mi empresa");
bankAccount.alias(null);
bankAccount.clabe("012XXXXXXXXXX24616");
request.bankAccount(bankAccount);
request.amount(new BigDecimal("10.50"));
request.description("Retiro de saldo semanal");
request.orderId("oid-1110011");

Payout payout = api.payouts().create("ag4nktpdzebjiye1tlze", request);
OpenpayAPI api = new OpenpayAPI("sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
PayoutRequest request = new PayoutRequest();
request.Method = "bank_account";
BankAccount bankAccount = new BankAccount();
bankAccount.HolderName = "Mi empresa";
bankAccount.Alias = null;
bankAccount.CLABE = "012XXXXXXXXXX24616";
request.BankAccount = bankAccount;
request.Amount = new Decimal(10.50);
request.Description = "Retiro de saldo semanal";
request.OrderId = "oid-1110011";

Payout = api.PayoutService.Create("ag4nktpdzebjiye1tlze", request);
var payoutRequest = {
   'method':'bank_account',
   'bank_account':{
      'clabe':'012298026516924616',
      'holder_name':'Mi empresa'
   },
   'amount':10.50,
   'description':'Retiro de saldo semanal',
   'order_id':'oid-1110011'
};

openpay.customers.payouts.create('ag4nktpdzebjiye1tlze', payoutRequest, function(error, payout) {
  // ...
});
@openpay=OpenpayApi.new("mzdtln0bmtms6o3kck8f","sk_e568c42a6c384b7ab02cd47d2e407cab")
@payouts=@openpay.create(:payouts)
bank_account_hash={
     "holder_name" => "Mi empresa",
     "alias" => nil,
     "clabe" => "012XXXXXXXXXX24616"
   }
request_hash={
     "method" => "bank_account",
     "bank_account" => bank_account_hash,
     "amount" => 10.50,
     "description" => "Retiro de saldo semanal",
     "order_id" => "oid-1110011"
   }

response_hash=@payouts.create(request_hash.to_hash, "ag4nktpdzebjiye1tlze")

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

Property Description
method string (required)
It must contain the bank_account value.
bank_account object (required)
Data of the bank account where the funds will be sent.

clabe.- CLABE account number where the funds will be sent.
holder_name.- Name of the account owner .
amount numeric (required)
Amount of payout. Must be an amount greater than zero, with up to two decimal digits.
description string (required, length = 250)
A description associated to the payment.
order_id string (optional, length = 100)
Unique identifier of payout. Must be unique among all transactions.

Response

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

Get a payout

Definition

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

Customer
GET https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/customers/{CUSTOMER_ID}/payouts/{TRANSACTION_ID}
<?
Merchant
$payout = $openpay->payouts->get(transactionId);

Customer
$customer = $openpay->customers->get(customerId);
$payout = $customer->payouts->get(transactionId);
?>
//Customer
openpayAPI.payouts().get(String customerId, String transactionId);

//Merchant
openpayAPI.payouts().get(String transactionId);
//Customer
openpayAPI.PayoutService.Get(string customer_id, string transaction_id);

//Merchant
openpayAPI.PayoutService.Get(string transaction_id);
// Merchant
openpay.payouts.get(transactionId, callback);

// Customer
openpay.customers.payouts.get(customerId, transactionId, callback);
#Customer
@payouts=@openpay.create(:payouts)
@payouts.get(transaction_id, customer_id)

#Merchant
@payouts=@openpay.create(:payouts)
@payouts.get(transaction_id)

Customer request example

curl https://sandbox-api.openpay.mx/v1/mzdtln0bmtms6o3kck8f/customers/asynwirguzkgq2bizogo/payouts/trwpxhrgfeub9eqdyvqz \
   -u sk_e568c42a6c384b7ab02cd47d2e407cab:
<?
$openpay = Openpay::getInstance('mzdtln0bmtms6o3kck8f', 'sk_e568c42a6c384b7ab02cd47d2e407cab');

$customer = $openpay->customers->get('asynwirguzkgq2bizogo');
$payout = $customer->payouts->get('trwpxhrgfeub9eqdyvqz');
?>
OpenpayAPI api = new OpenpayAPI("https://sandbox-api.openpay.mx", "sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
Payout payout = api.payouts().get("ag4nktpdzebjiye1tlze", "tr6cxbcefzatd10guvvw");
OpenpayAPI api = new OpenpayAPI("sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
Payout = api.PayoutService.Get("ag4nktpdzebjiye1tlze", "tr6cxbcefzatd10guvvw");
openpay.customers.payouts.get('ag4nktpdzebjiye1tlze', 'tr6cxbcefzatd10guvvw', function(error, payout) {
  // ...
});
@openpay=OpenpayApi.new("mzdtln0bmtms6o3kck8f","sk_e568c42a6c384b7ab02cd47d2e407cab")
@payouts=@openpay.create(:payouts)

response_hash=@payouts.get("tr6cxbcefzatd10guvvw", "asynwirguzkgq2bizogo")

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

Property Description
transaction_id string (required, length = 45)
Id of the payout you want to get.

Response

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

Cancel a payout

Definition

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

Customer
DELETE https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/customers/{CUSTOMER_ID}/payouts/{TRANSACTION_ID}
<?
Merchant
$payout = $openpay->payouts->delete(transactionId);

Customer
$customer = $openpay->customers->get(customerId);
$payout = $customer->payouts->delete(transactionId);
?>
//Customer
openpayAPI.payouts().cancel(String customerId, String transactionId);

//Merchant
openpayAPI.payouts().cancel(String transactionId);
//Customer
openpayAPI.PayoutService.Cancel(string customer_id, string transaction_id);

//Merchant
openpayAPI.PayoutService.Cancel(string transaction_id);
// Merchant
openpay.payouts.delete(transactionId, callback);

// Customer
openpay.customers.payouts.delete(customerId, transactionId, callback);
#Customer
@payouts=@openpay.create(:payouts)
@payouts.delete(transaction_id, customer_id)

#Merchant
@payouts=@openpay.create(:payouts)
@payouts.delete(transaction_id)

Customer request example

curl -X DELETE https://sandbox-api.openpay.mx/v1/mzdtln0bmtms6o3kck8f/customers/asynwirguzkgq2bizogo/payouts/trozeipf364jqrsbt3ej \
   -u sk_e568c42a6c384b7ab02cd47d2e407cab:
<?
$openpay = Openpay::getInstance('mzdtln0bmtms6o3kck8f', 'sk_e568c42a6c384b7ab02cd47d2e407cab');

$customer = $openpay->customers->get('asynwirguzkgq2bizogo');
$payout = $customer->payouts->delete('trozeipf364jqrsbt3ej');
?>
OpenpayAPI api = new OpenpayAPI("https://sandbox-api.openpay.mx", "sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
Payout payout = api.payouts().cancel("ag4nktpdzebjiye1tlze", "trozeipf364jqrsbt3ej");
OpenpayAPI api = new OpenpayAPI("sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
Payout = api.PayoutService.Cancel("ag4nktpdzebjiye1tlze", "trozeipf364jqrsbt3ej");
openpay.customers.payouts.delete('ag4nktpdzebjiye1tlze', 'tr6cxbcefzatd10guvvw', function(error, payout) {
  // ...
});
@openpay=OpenpayApi.new("mzdtln0bmtms6o3kck8f","sk_e568c42a6c384b7ab02cd47d2e407cab")
@payouts=@openpay.create(:payouts)

response_hash=@payouts.delete("trozeipf364jqrsbt3ej", "asynwirguzkgq2bizogo")

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-00025",
   "customer_id":"asynwirguzkgq2bizogo"
}

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

Request

Property Description
transaction_id string (required, length = 45)
Payout Id you want to cancel.

Response

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

List of payouts

Definition

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

Customer
GET https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/customers/{CUSTOMER_ID}/payouts
<?
Merchant
$payoutList = $openpay->payouts->getList(searchParams);

Customer
$customer = $openpay->customers->get(customerId);
$payoutList = $customer->payouts->getList(searchParams);
?>
//Customer
openpayAPI.payouts().list(String customerId, SearchParams request);

//Merchant
openpayAPI.payouts().list(SearchParams request);
//Customer
openpayAPI.PayoutService.List(string customer_id, SearchParams request = null);

//Merchant
openpayAPI.PayoutService.List(SearchParams request = null);
// Merchant
openpay.payouts.list(callback);
openpay.payouts.list(searchParams, callback);

// Customer
openpay.customers.payouts.list(customerId, callback);
openpay.customers.payouts.list(customerId, searchParams, callback);
#Customer
@payouts=@openpay.create(:payouts)
@payouts.all(customer_id)

#Merchant
@payouts=@openpay.create(:payouts)
@payouts.all

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: 
<?
$openpay = Openpay::getInstance('mzdtln0bmtms6o3kck8f', 'sk_e568c42a6c384b7ab02cd47d2e407cab');

$searchParams = array(
    'creation[gte]' => '2013-11-01',
    'creation[lte]' => '2017-12-31',
    'payout_type' => 'AUTOMATIC',
    'offset' => 0,
    'limit' => 2);

$customer = $openpay->customers->get('asynwirguzkgq2bizogo');
$payoutList = $customer->payouts->getList($searchParams);
?>
final Calendar dateGte = Calendar.getInstance();
final Calendar dateLte = Calendar.getInstance();
dateGte.set(2014, 5, 1, 0, 0, 0);
dateLte.set(2014, 5, 15, 0, 0, 0);

OpenpayAPI api = new OpenpayAPI("https://sandbox-api.openpay.mx", "sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
SearchParams request = new SearchParams();
request.creationGte(dateGte.getTime());
request.creationLte(dateLte.getTime());
request.offset(0);
request.limit(100);
request.amount(new BigDecimal("100.00"));

List<Payout> payouts = api.payouts().list("ag4nktpdzebjiye1tlze", request);
OpenpayAPI api = new OpenpayAPI("sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
SearchParams request = new SearchParams();
request.CreationGte = new Datetime(2014, 5, 1);
request.CreationLte = new DateTime(2014, 5, 15);
request.Offset = 0;
request.Limit = 100;
request.Amount = new Decimal(100.00);

List<Payout> payouts = api.PayoutService.List("ag4nktpdzebjiye1tlze", request);
var searchParams = {
  'creation[gte]' : '2013-11-01',
  'payout_type' : 'AUTOMATIC',
  'limit' : 2
};

openpay.customers.payouts.list('asynwirguzkgq2bizogo', searchParams, function(error, list) {
  // ...
});
@openpay=OpenpayApi.new("mzdtln0bmtms6o3kck8f","sk_e568c42a6c384b7ab02cd47d2e407cab")
@payouts=@openpay.create(:payouts)

response_hash=@payouts.all("asynwirguzkgq2bizogo")

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.

Property Description
creation date
Same as creation date. Format yyyy-mm-dd
creation[gte] date
After the creation date. Format yyyy-mm-dd
creation[lte] date
Before the creation date. Format yyyy-mm-dd
offset numeric
Number of records to skip at the beginning, default 0.
limit numeric
Number of required records, default 10.
amount numeric
Same as the amount.
amount[gte] numeric
Greater than or equal to the amount.
amount[lte] numeric
Less than or equal to the amount.
payout_type string (opfional, ALL, AUTOMATIC o MANUAL)
Payout type used to filter the transactions

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}
<?
$transactionsPayout = $openpay->transactionsPayout->get(transactionId);
?>
openpayAPI.transactionsPayout().getResume(String transactionId);
openpayAPI.PayoutReportService.Get(string transaction_id);
openpay.transactionsPayout.get(transactionId, callback);
@transactionsPayout=@openpay.create(:transactionsPayout)
@transactionsPayout.get(transaction_id)

Request example

curl https://sandbox-api.openpay.mx/v1/mzdtln0bmtms6o3kck8f/reports/payout/trwpxhrgfeub9eqdyvqz \
   -u sk_e568c42a6c384b7ab02cd47d2e407cab:
<?
$openpay = Openpay::getInstance('mzdtln0bmtms6o3kck8f', 'sk_e568c42a6c384b7ab02cd47d2e407cab');

$payout = $openpay->transactionsPayout->get('trwpxhrgfeub9eqdyvqz');
?>
OpenpayAPI api = new OpenpayAPI("https://sandbox-api.openpay.mx", "sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");

TransactionsPayoutResume payoutResume = transactionsPayout().getResume("tr6cxbcefzatd10guvvw");
OpenpayAPI api = new OpenpayAPI("sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");

PayoutSummary payoutSummary = api.PayoutReportService.Get("tr6cxbcefzatd10guvvw");
openpay.transactionsPayout.get('tr6cxbcefzatd10guvvw', function(error, payout) {
  // ...
});
@openpay=OpenpayApi.new("mzdtln0bmtms6o3kck8f","sk_e568c42a6c384b7ab02cd47d2e407cab")
@transactionsPayout=@openpay.create(:transactionsPayout)

response_hash=@transactionsPayout.get("tr6cxbcefzatd10guvvw")

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

Property Description
transaction_id string (required, length = 45)
Id of the payout you want to get.

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
}
Property Description
in numeric
Total amount in, Must be an amount with up to two decimal digits.
out numeric
Total amount out, Must be an amount with up to two decimal digits.
charged_adjustments numeric
Total amount of adjustment charges, Must be an amount with up to two decimal digits.
refunded_adjustments numeric
Total amount of refund charges, Must be an amount with up to two decimal digits.

Payout Detail

Definition

GET https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/reports/payout/{TRANSACTION_ID}/detail
<?
$transactionsPayout = $openpay->transactionsPayout->getDetails(transactionId, searchParams);
?>
openpayAPI.transactionsPayout().getDetails(String transactionId, TransactionsPayoutType transactionsPayoutType, PaginationParams paginationParams);
openpayAPI.PayoutReportService.Detail(string transaction_id, PayoutReportDetailSearchParams searchParams);
openpay.transactionsPayout.getDetails(transactionId, searchParams, callback);
@transactionsPayout=@openpay.create(:transactionsPayout)
@transactionsPayout.getDetails(transaction_id, searchParams)

Request example

curl https://sandbox-api.openpay.mx/v1/mzdtln0bmtms6o3kck8f/reports/payout/trwpxhrgfeub9eqdyvqz/detail?detail_type=IN \
   -u sk_e568c42a6c384b7ab02cd47d2e407cab:
<?
$openpay = Openpay::getInstance('mzdtln0bmtms6o3kck8f', 'sk_e568c42a6c384b7ab02cd47d2e407cab');

$searchParams = array(
    'payout_type' => 'IN',
    'offset' => 0,
    'limit' => 100);

$payout = $openpay->transactionsPayout->getDetails('trwpxhrgfeub9eqdyvqz', $searchParams);
?>
OpenpayAPI api = new OpenpayAPI("https://sandbox-api.openpay.mx", "sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");

      PaginationParams paginationParams = new PaginationParams();
      paginationParams.offset(0);
      paginationParams.limit(100);

List<GenericTransaction> payoutTransactions = transactionsPayout().getDetails("tr6cxbcefzatd10guvvw", TransactionsPayoutType.IN, paginationParams);
OpenpayAPI api = new OpenpayAPI("sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
PayoutReportDetailSearchParams searchParams = new PayoutReportDetailSearchParams();
searchParams.DetailType = "IN";
searchParams.Offset = 0;
searchParams.Limit = 100;

List<Transaction> transactions = api.PayoutReportService.Detail("tr6cxbcefzatd10guvvw", searchParam);
var searchParams = {
  'detail_type' : 'IN',
  'offset' : 0,
  'limit' : 100
};

openpay.transactionsPayout.get('tr6cxbcefzatd10guvvw', searchParams, function(error, payout) {
  // ...
});
@openpay=OpenpayApi.new("mzdtln0bmtms6o3kck8f","sk_e568c42a6c384b7ab02cd47d2e407cab")
@transactionsPayout=@openpay.create(:transactionsPayout)

search_params_hash={
     "detail_type" => "IN",
     "offset" => 0,
     "limit" => 100
   }

response_hash=@transactionsPayout.getDetails("tr6cxbcefzatd10guvvw", search_params_hash.to_hash)

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.

Petición

Propiedad Descripción
transaction_id string (required, length = 45)
Id of the payout you want to get.
detail_type string (IN, OUT, CHARGED_ADJUSTMENTS, REFUNDED_ADJUSTMENTS)
The detail type.
offset numeric
Number of records to skip at the beginning, default 0.
limit numeric
Number of required records, default 10.

Response

Return a list of transaction objects in descending order by creation date 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"
}
Property Description
id string
Customer unique identifier.
creation_date datetime
Date and time when the customer was created in ISO 8601 format.
name string
Name of the customer.
last_name string
Last name of the customer.
email string
Email of the customer.
phone_number numeric
Telephone number of the customer.
status string
Account status of the customer can be active or deleted. If the account is on deleted status, no transaction is allowed.
balance numeric
Account balance with two decimal digits.
clabe numeric
CLABE account used to receive funds by transfer from any bank in Mexico.
address object
Address of the customer. It is usually used as shipping address.
store object*
Contains reference string to go to Store and make deposits, the url to generate barcode is contained too.

Create a new customer

Definition

POST https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/customers
<?
$customer = $openpay->customers->add(customerData);
?>
openpayAPI.customers().create(Customer customer);
openpayAPI.CustomerService.Create(Customer customer);
openpay.customers.create(customerRequest, callback);
@customers=@openpay.create(:customers)
@customers.create(request_hash)

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 
   }' 
<?
$openpay = Openpay::getInstance('mzdtln0bmtms6o3kck8f', 'sk_e568c42a6c384b7ab02cd47d2e407cab');

$customerData = array(
     'external_id' => '',
     'name' => 'customer name',
     'last_name' => '',
     'email' => 'customer_email@me.com',
     'requires_account' => false,
     'phone_number' => '44209087654',
     'address' => array(
         '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'
      )
   );

$customer = $openpay->customers->add($customerData);
?>
OpenpayAPI api = new OpenpayAPI("https://sandbox-api.openpay.mx", "sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
Customer request = new Customer();
request.externalId("idExterno0101");
request.name("Julian Gerardo");
request.lastName("López Martínez");
request.email("julian.martinez@gmail.com");
request.phoneNumber("4421432915");
request.requiresAccount(false);
Address address = new Address();
address.city("Queretaro");
address.countryCode("MX");
address.state("Queretaro");
address.postalCode("79125");
address.line1("Av. Pie de la cuesta #12");
address.line2("Desarrollo San Pablo");
address.line3("Qro. Qro.");
request.address(address);

request = api.customers().create(request);
OpenpayAPI api = new OpenpayAPI("sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
Customer request = new Customer();
request.ExternalId = "idExterno0101";
request.Name = "Julian Gerardo";
request.LastName = "López Martínez";
request.Email = "julian.martinez@gmail.com";
request.PhoneNumber = "4421432915";
request.RequiresAccount = false;
Address address = new Address();
address.City = "Queretaro";
address.CountryCode = "MX";
address.State = "Queretaro";
address.PostalCode = "79125";
address.Line1 = "Av. Pie de la cuesta #12";
address.Line2 = "Desarrollo San Pablo";
address.Line3 = "Qro. Qro.";
request.Address = address;

request = api.CustomerService.Create(request);
var customerRequest = {
   'name': 'customer name',
   'email': 'customer_email@me.com',
   'requires_account': false 
   };

openpay.customers.create(customerRequest, function(error, customer) {
  // ... 
});
@openpay=OpenpayApi.new("mzdtln0bmtms6o3kck8f","sk_e568c42a6c384b7ab02cd47d2e407cab")
@customers=@openpay.create(:customers)
address_hash={
      "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"
   }
request_hash={
     "external_id" => nil,
     "name" => "customer name",
     "last_name" => nil,
     "email" => "customer_email@me.com",
     "requires_account" => false,
     "phone_number" => "44209087654",
     "address" => address_hash
   }

response_hash=@customers.create(request_hash.to_hash)

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

Property Description
external_id string (optional, length = 100)
Unique external identifier of the customer assigned for the Merchant.
name string (required, length = 100)
Name of the customer.
last_name string (optional, length = 100)
Last name of the customer.
email string (required, length = 100)
Email of the customer.
requires_account boolean (optional, default = true)
Send it with false value if you need to create the customer without an account to manage the balance.
phone_number string (optional, length = 100)
Telephone number of the customer.
address object (optional)
Address of the customer. It is usually used as shipping address.

Response

Returns a customer object when all the data were sent correctly, or returns an error response if a problem happened.

Update a customer

Definition

PUT https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/customers/{CUSTOMER_ID}
<?
$customer = $openpay->customers->get(customerId);
$customer->save();
?>
openpayAPI.customers().update(Customer customer);
openpayAPI.CustomerService.Update(Customer customer);
openpay.customers.update(customerId, customerRequest, callback);
@customers=@openpay.create(:customers)
@customers.update(request_hash)

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"
 }' 
<?
$openpay = Openpay::getInstance('moiep6umtcnanql3jrxp', 'sk_3433941e467c1055b178ce26348b0fac');

$customer = $openpay->customers->get('a9ualumwnrcxkl42l6mh');
$customer->name = 'Juan';
$customer->last_name = 'Godinez';
$customer->save();
?>
OpenpayAPI api = new OpenpayAPI("https://sandbox-api.openpay.mx", "sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
Customer request = new Customer();
request.name("Julian Gerardo");
request.lastName("López Martínez");
request.email("julian.martinez@gmail.com");
request.phoneNumber("4421432915");
Address address = new Address();
address.city("Queretaro");
address.countryCode("10");
address.state("Queretaro");
address.postalCode("79125");
address.line1("Av. Pie de la cuesta #12");
address.line2("Desarrollo San Pablo");
address.line3("Qro. Qro.");
request.address(address);

request = api.customers().update(request);
OpenpayAPI api = new OpenpayAPI("sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
Customer request = new Customer();
request.Name = "Julian Gerardo";
request.LastName = "López Martínez";
request.Email = "julian.martinez@gmail.com";
request.PhoneNumber = "4421432915";
Address address = new Address();
address.City = "Queretaro";
address.CountryCode = "MX";
address.State = "Queretaro";
address.PostalCode = "79125";
address.Line1 = "Av. Pie de la cuesta #12";
address.Line2 = "Desarrollo San Pablo";
address.Line3 = "Qro. Qro.";
request.Address = address;

request = api.CustomerService.Update(request);
var customerRequest = {
    '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'
    }
};

openpay.customers.update('anbnldwgni1way3yp2dw', customerRequest, function(error, customer) {
  // ... 
});
@openpay=OpenpayApi.new("mzdtln0bmtms6o3kck8f","sk_e568c42a6c384b7ab02cd47d2e407cab")
@customers=@openpay.create(:customers)
address_hash={
      "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"
   }
request_hash={
     "external_id" => nil,
     "name" => "customer name",
     "last_name" => nil,
     "email" => "customer_email@me.com",
     "phone_number" => "44209087654",
     "address" => address_hash
   }

response_hash=@customers.update(request_hash.to_hash)

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

Property Description
name string (required, length = 100)
Name of the customer.
last_name string (optional, length = 100)
Last name of the customer.
email string (required, length = 100)
Email of the customer.
phone_number string (optional, length = 100)
Telephone number of the customer.
address object (optional)
Address of the customer. It is usually used as shipping address.

Response

Returns a customer object 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}
<?
$customer = $openpay->customers->get(customerId);
?>
openpayAPI.customers().get(String customerId);
openpayAPI.CustomerService.Update(string customer_id);
openpay.customers.get(customerId, callback);
@customers=@openpay.create(:customers)
@customers.get(customer_id)

Request example

curl https://sandbox-api.openpay.mx/v1/mzdtln0bmtms6o3kck8f/customers/anbnldwgni1way3yp2dw \
   -u sk_e568c42a6c384b7ab02cd47d2e407cab: \
   -H "Content-type: application/json" 
<?
$openpay = Openpay::getInstance('moiep6umtcnanql3jrxp', 'sk_3433941e467c1055b178ce26348b0fac');

$customer = $openpay->customers->get('a9ualumwnrcxkl42l6mh');
?>
OpenpayAPI api = new OpenpayAPI("https://sandbox-api.openpay.mx", "sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
Customer customer = api.customers().get("a9pvykxz4g5rg0fplze0");
OpenpayAPI api = new OpenpayAPI("sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
Customer customer = api.CustomerService.Update("a9pvykxz4g5rg0fplze0");
openpay.customers.get('a9pvykxz4g5rg0fplze0', function(error, customer) {
  // ... 
});
@openpay=OpenpayApi.new("mzdtln0bmtms6o3kck8f","sk_e568c42a6c384b7ab02cd47d2e407cab")
@customers=@openpay.create(:customers)

response_hash=@customers.get("asynwirguzkgq2bizogo")

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

Property Description
id string (required, legth = 45)
Unique identifier of the customer.

Response

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

Delete a customer

Definition

DELETE https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/customers/{CUSTOMER_ID}
<?
$customer = $openpay->customers->get(customerId);
$customer->delete();
?>
openpayAPI.customers().delete(String customerId);
openpayAPI.CustomerService.Delete(string customer_id);
openpay.customers.delete(customerId, callback);
@customers=@openpay.create(:customers)
@customers.delete(customer_id)

Request example

curl https://sandbox-api.openpay.mx/v1/mzdtln0bmtms6o3kck8f/customers/anbnldwgni1way3yp2dw \
   -u sk_e568c42a6c384b7ab02cd47d2e407cab: \
   -H "Content-type: application/json" \
   -X DELETE
<?
$openpay = Openpay::getInstance('moiep6umtcnanql3jrxp', 'sk_3433941e467c1055b178ce26348b0fac');

$customer = $openpay->customers->get('a9ualumwnrcxkl42l6mh');
$customer->delete();
?>
OpenpayAPI api = new OpenpayAPI("https://sandbox-api.openpay.mx", "sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
api.customers().delete("a9pvykxz4g5rg0fplze0");
OpenpayAPI api = new OpenpayAPI("sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
api.CustomerService.Delete("a9pvykxz4g5rg0fplze0");
openpay.customers.delete('a9pvykxz4g5rg0fplze0', function(error) {
  // ... 
});
@openpay=OpenpayApi.new("mzdtln0bmtms6o3kck8f","sk_e568c42a6c384b7ab02cd47d2e407cab")
@customers=@openpay.create(:customers)

response_hash=@customers.delete("asynwirguzkgq2bizogo")

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

Request

Property Description
id string (required, length = 45)
Unique identifier of the customer you want to delete.

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
<?
$customerList = $openpay->customers->getList(findDataRequest);
?>
openpayAPI.customers().list(SearchParams request);
openpayAPI.CustomerService.List(SearchParams request = null);
openpay.customers.list(callback);
openpay.customers.list(searchParams, callback);
@customers=@openpay.create(:customers)
@customers.all

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" 
<?
$openpay = Openpay::getInstance('moiep6umtcnanql3jrxp', 'sk_3433941e467c1055b178ce26348b0fac');

$findDataRequest = array(
    'creation[gte]' => '2013-01-01',
    'creation[lte]' => '2013-12-31',
    'offset' => 0,
    'limit' => 5);

$customerList = $openpay->customers->getList($findDataRequest);
?>
final Calendar dateGte = Calendar.getInstance();
final Calendar dateLte = Calendar.getInstance();
dateGte.set(2014, 5, 1, 0, 0, 0);
dateLte.set(2014, 5, 15, 0, 0, 0);

OpenpayAPI api = new OpenpayAPI("https://sandbox-api.openpay.mx", "sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
SearchParams request = new SearchParams();
request.creationGte(dateGte.getTime());
request.creationLte(dateLte.getTime());
request.offset(0);
request.limit(100);

List<Customer> customers = api.customers().list(request);
OpenpayAPI api = new OpenpayAPI("sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
SearchParams request = new SearchParams();
request.CreationGte = new Datetime(2014, 5, 1);
request.CreationLte = new DateTime(2014, 5, 15);
request.Offset = 0;
request.Limit = 100;

List<Customer> customers = api.CustomerService.List(request);
var searchParams = {
  'creation[gte]' : '2013-11-01',
  'limit' : 2
};

openpay.customers.list(searchParams, function(error, list) {
  // ...
});
@openpay=OpenpayApi.new("mzdtln0bmtms6o3kck8f","sk_e568c42a6c384b7ab02cd47d2e407cab")
@customers=@openpay.create(:customers)

response_hash=@customers.all

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": "OPENPAY02DQ35DRE4",
       "barcode_url": "https://sandbox-api.openpay.mx/barcode/OPENPAY02DQ35DRE4?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.

Property Description
external_id string
Unique customer id generated by the merchant and associated to the customer by the external_id field of the create customer request
creation date
Same as the customer creation date. Format yyyy-mm-dd
creation[gte] date
After the customer creation date .Format yyyy-mm-dd
creation[lte] date
Before the customer creation date.Format yyyy-mm-dd
offset numeric
Number of records to skip at the beginning, default 0.
limit numeric
Number of required records, default 10.

Response

Returns an array of customer object.

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
<?
$customer = $openpay->customers->get(customerId);
$transfer = $customer->transfers->create(transferDataRequest);
?>
openpayAPI.transfers().create(String customerId, CreateTransferParams request);
openpayAPI.TransferService.Create(string from_customer_id, TransferRequest request);
openpay.customers.transfers.create(customerId, transferRequest, callback);
@transfers=@openpay.create(:transfers)
@transfers.create(request_hash, from_customer_id)

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"
}' 
<?
$openpay = Openpay::getInstance('moiep6umtcnanql3jrxp', 'sk_3433941e467c1055b178ce26348b0fac');

$transferDataRequest = array(
    'customer_id' => 'aqedin0owpu0kexr2eor',
    'amount' => 12.50,
    'description' => 'Cobro de Comisión',
    'order_id' => 'ORDEN-00061');

$customer = $openpay->customers->get('a9ualumwnrcxkl42l6mh');
$transfer = $customer->transfers->create($transferDataRequest);
?>
OpenpayAPI api = new OpenpayAPI("https://sandbox-api.openpay.mx", "sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
CreateTransferParams request = new CreateTransferParams();
request.toCustomerId("ah1ki9jmb50mvlsf9gqn");
request.amount(new BigDecimal("100.00"));
request.description("Transferencia del Customer 1 al Customer 2");
request.orderId("idOrdExt-0101");

Transfer transfer = api.transfers().create("a9pvykxz4g5rg0fplze0", request);
OpenpayAPI api = new OpenpayAPI("sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
TransferRequest request = new TransferRequest();
request.CustomerId = "ah1ki9jmb50mvlsf9gqn";
request.Amount = new Decimal(100.00);
request.Description = "Transferencia del Customer 1 al Customer 2";
request.OrderId = "idOrdExt-0101";

Transfer transfer = api.TransferService.Create("a9pvykxz4g5rg0fplze0", request);
var transferRequest = {                                          
  'customer_id' : 'dvocf97jd20es3tw5laz',
  'amount' : 12.50,          
  'description' : 'Transferencia entre cuentas',
  'order_id' : 'oid-1245'
};

openpay.customers.transfers.create('ag4nktpdzebjiye1tlze', transferRequest, function(error, transfer) {
  // ...
});
@openpay=OpenpayApi.new("mzdtln0bmtms6o3kck8f","sk_e568c42a6c384b7ab02cd47d2e407cab")
@transfers=@openpay.create(:transfers)
request_hash={
     "customer_id" => "dvocf97jd20es3tw5laz",
     "amount" => 12.50,
     "description" => "Transferencia entre cuentas",
     "order_id" => "oid-1245"
   }

response_hash=@transfers.create(request_hash.to_hash, "ag4nktpdzebjiye1tlze")

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

Property Description
customer_id string (required, length = 45)
The Openpay ID of the customer you want to send the funds.
amount numeric (required)
Amount to transfer. It must be an amount greater than one peso with up to two decimal digits.
description string (required, length = 250)
A description associated to the transfer.
order_id string (optional, length = 100)
Unique identifier of the transfer. It will be assigned to the withdrawal transaction.

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}
<?
$customer = $openpay->customers->get(customerId);
$transfer = $customer->transfers->get(transactionId);
?>
openpayAPI.transfers().get(String customerId, String transactionId);
openpayAPI.TransferService.Get(string customer_id, string transaction_id);
openpay.customers.transfers.get(customerId, transactionId, callback);
@transfers=@openpay.create(:transfers)
@transfers.get(transaction_id, customer_id)

Request example

curl https://sandbox-api.openpay.mx/v1/mzdtln0bmtms6o3kck8f/customers/ag4nktpdzebjiye1tlze/transfers/twpmbike2jejex3pahzd \
   -u sk_e568c42a6c384b7ab02cd47d2e407cab: \
   -H "Content-type: application/json" 
<?
$openpay = Openpay::getInstance('moiep6umtcnanql3jrxp', 'sk_3433941e467c1055b178ce26348b0fac');

$customer = $openpay->customers->get('a9ualumwnrcxkl42l6mh');
$transfer = $customer->transfers->get('tyxesptjtx1bodfdjmlb');
?>
OpenpayAPI api = new OpenpayAPI("https://sandbox-api.openpay.mx", "sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
Transfer transfer = api.transfers().get("a9pvykxz4g5rg0fplze0", "tr6cxbcefzatd10guvvw");
OpenpayAPI api = new OpenpayAPI("sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
Transfer transfer = api.TransferService.Get("a9pvykxz4g5rg0fplze0", "tr6cxbcefzatd10guvvw");
openpay.customers.transfers.get('ag4nktpdzebjiye1tlze', 'twpmbike2jejex3pahzd', function(error, transfer) {
  // ...
});
@openpay=OpenpayApi.new("mzdtln0bmtms6o3kck8f","sk_e568c42a6c384b7ab02cd47d2e407cab")
@transfers=@openpay.create(:transfers)

response_hash=@transfers.get("twpmbike2jejex3pahzd", "ag4nktpdzebjiye1tlze")

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

Property Description
customer_id string (required, length = 45)
Identifier of the customer.
transaction_id string (required, length = 45)
Identifier of the transfer.

Response

Returns a transaction object

List of transfers

Definition

GET https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/customers/{CUSTOMER_ID}/transfers
<?
$customer = $openpay->customers->get(customerId);
$transferList = $customer->transfers->getList(findDataRequest);
?>
openpayAPI.transfers().list(String customerId, SearchParams request);
openpayAPI.TransferService.List(string customer_id, SearchParams request = null);
openpay.customers.transfers.list(customerId, callback);
openpay.customers.transfers.list(customerId, searchParams, callback);
@transfers=@openpay.create(:transfers)
@transfers.all(customer_id)

Request example

curl -g "https://sandbox-api.openpay.mx/v1/mzdtln0bmtms6o3kck8f/customers/ag4nktpdzebjiye1tlze/transfers?limit=2" \
   -u sk_e568c42a6c384b7ab02cd47d2e407cab: 
<?
$openpay = Openpay::getInstance('moiep6umtcnanql3jrxp', 'sk_3433941e467c1055b178ce26348b0fac');

$findDataRequest = array(
    'creation[gte]' => '2013-01-01',
    'creation[lte]' => '2013-12-31',
    'offset' => 0,
    'limit' => 5);

$customer = $openpay->customers->get('a9ualumwnrcxkl42l6mh');
$transferList = $customer->transfers->getList($findDataRequest);
?>
final Calendar dateGte = Calendar.getInstance();
final Calendar dateLte = Calendar.getInstance();
dateGte.set(2014, 5, 1, 0, 0, 0);
dateLte.set(2014, 5, 15, 0, 0, 0);

OpenpayAPI api = new OpenpayAPI("https://sandbox-api.openpay.mx", "sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
SearchParams request = new SearchParams();
request.creationGte(dateGte.getTime());
request.creationLte(dateLte.getTime());
request.offset(0);
request.limit(100);

List<Transfer> transfers = api.transfers().list("a9pvykxz4g5rg0fplze0", request);
OpenpayAPI api = new OpenpayAPI("sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
SearchParams request = new SearchParams();
request.CreationGte = new Datetime(2014, 5, 1);
request.CreationLte = new DateTime(2014, 5, 15);
request.Offset = 0;
request.Limit = 100;

List<Transfer> transfers = api.TransferService.List("a9pvykxz4g5rg0fplze0", request);
var searchParams = {
  'limit' : 2
};

openpay.customers.transfers.list('ag4nktpdzebjiye1tlze', searchParams, function(error, list) {
  // ...
});
@openpay=OpenpayApi.new("mzdtln0bmtms6o3kck8f","sk_e568c42a6c384b7ab02cd47d2e407cab")
@transfers=@openpay.create(:transfers)

response_hash=@transfers.all("asynwirguzkgq2bizogo")

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.

Property Description
creation date
Same as creation date. Format yyyy-mm-dd
creation[gte] date
After the creation date. Format yyyy-mm-dd
creation[lte] date
Before the creation date. Format yyyy-mm-dd
offset numeric
Number of records to skip at the beginning, default 0.
limit numeric
Number of required records, default 10.

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

Within the Openpay platform you can add cards to the customer’s account, delete them, recover some in specific and list them.

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
}
Property Description
id string
Unique identifier of the card.
creation_date datetime
Date and time when the card was created in ISO 8601 format.
holder_name string
Name of the cardholder.
card_number numeric
Card Number, it can be 16 or 19 digits.
cvv2 numeric
Security code as it appears on the back of the card. Usually 3 digits..
expiration_month numeric
Expiration month as it appears on the card.
expiration_year numeric
Expiration year as it appears on the card.
address object
Billing address of cardholder.
allows_charges boolean
It allows to know if you can make charges to the card.
allows_payouts boolean
It allows to know if you can send payments to the card.
brand string
Card brand: visa, mastercard, carnet or american express.
type string
Card Type: debit, credit, cash, etc.
bank_name string
Name of the issuing bank.
bank_code string
Code of the issuing bank.
customer_id string
Customer identifier to which the card belongs. If the card is at Merchant level this value is null.
points_card boolean
Indicates whether the card allows the use of reward points.

Create a card

Definition

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

Customer
POST https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/customers/{CUSTOMER_ID}/cards
<?
//Customer
$customer = $openpay->customers->get(customerId);
$card = $customer->cards->add(cardDataRequest);

//Merchant
$card = $openpay->cards->add(cardDataRequest);
?>
//Customer
openpayAPI.cards().create(String customerId, Card request);

//Merchant
openpayAPI.cards().create(Card request);
//Customer
openpayAPI.CardService.Create(string customer_id, Card card);

//Merchant
openpayAPI.CardService.Create(Card card);
// Merchant
openpay.cards.create(cardRequest, callback);

// Customer
openpay.customers.cards.create(customerId, cardRequest, callback);
#Customer
@cards=@openpay.create(:cards)
@cards.create(request_hash, customer_id)

#Merchant
@cards=@openpay.create(:cards)
@cards.create(request_hash)

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"
 }' 
<?
$openpay = Openpay::getInstance('moiep6umtcnanql3jrxp', 'sk_3433941e467c1055b178ce26348b0fac');

$cardDataRequest = array(
    'holder_name' => 'Teofilo Velazco',
    'card_number' => '4916394462033681',
    'cvv2' => '123',
    'expiration_month' => '12',
    'expiration_year' => '15',
    'device_session_id' => 'kR1MiQhz2otdIuUlQkbEyitIqVMiI16f',
    'address' => array(
            'line1' => 'Privada Rio No. 12',
            'line2' => 'Co. El Tintero',
            'line3' => '',
            'postal_code' => '76920',
            'state' => 'Querétaro',
            'city' => 'Querétaro.',
            'country_code' => 'MX'));

$customer = $openpay->customers->get('a9ualumwnrcxkl42l6mh');
$card = $customer->cards->add($cardDataRequest);
?>
OpenpayAPI api = new OpenpayAPI("https://sandbox-api.openpay.mx", "sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
Card request = new Card();
request.holderName("Juan Perez Ramirez");
request.cardNumber("4111111111111111");
request.cvv2("110");
request.expirationMonth(12);
request.expirationYear(20);
request.deviceSessionId("kR1MiQhz2otdIuUlQkbEyitIqVMiI16f");
Address address = new Address();
address.city("Queretaro");
address.countryCode("10");
address.state("Queretaro");
address.postalCode("79125");
address.line1("Av. Pie de la cuesta #12");
address.line2("Desarrollo San Pablo");
address.line3("Qro. Qro.");
request.address(address);

request = api.cards().create("a9pvykxz4g5rg0fplze0", request);
OpenpayAPI api = new OpenpayAPI("sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
Card request = new Card();
request.HolderName = "Juan Perez Ramirez";
request.CardNumber = "4111111111111111";
request.Cvv2 = "110";
request.ExpirationMonth = "12";
request.ExpirationYear = "20";
request.DeviceSessionId = "kR1MiQhz2otdIuUlQkbEyitIqVMiI16f";
Address address = new Address();
address.City = "Queretaro";
address.CountryCode = "MX";
address.State = "Queretaro";
address.PostalCode = "79125";
address.Line1 = "Av. Pie de la cuesta #12";
address.Line2 = "Desarrollo San Pablo";
address.Line3 = "Qro. Qro.";
request.Address = address;

request = api.CardService.Create("a9pvykxz4g5rg0fplze0", request);
var cardRequest = {
   'card_number':'4111111111111111',
   'holder_name':'Juan Perez Ramirez',
   'expiration_year':'20',
   'expiration_month':'12',
   'cvv2':'110',
   'device_session_id':'kR1MiQhz2otdIuUlQkbEyitIqVMiI16f'
};

openpay.customers.cards.create('a9pvykxz4g5rg0fplze0', cardRequest, function(error, card)  {
    // ...    
});
@openpay=OpenpayApi.new("mzdtln0bmtms6o3kck8f","sk_e568c42a6c384b7ab02cd47d2e407cab")
@cards=@openpay.create(:cards)
address_hash={
      "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"
   }
request_hash={
     "holder_name" => "Juan Perez Ramirez",
     "card_number" => "411111XXXXXX1111",
     "cvv2" => "110",
     "expiration_month" => "12",
     "expiration_year" => "20",
     "device_session_id" => "kR1MiQhz2otdIuUlQkbEyitIqVMiI16f",
     "address" => address_hash
   }

response_hash=@cards.create(request_hash.to_hash, "asynwirguzkgq2bizogo")

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

Property Description
holder_name string (required, length = 80)
Name of the cardholder.
card_number numeric (required)
Card Number, it can be 16 or 19 digits.
cvv2 numeric (required)
Security code as it appears on the back of the card. Usually 3 digits.
expiration_month numeric (required)
Expiration month as it appears on the card.
expiration_year numeric (required)
Expiration year as it appears on the card.
device_session_id string (optional, length = 255)
Device identifier generated by antifraud tool.
address object
Billing address of cardholder.

Response

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

Create a card with token

Definition

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

Customer
POST https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/customers/{CUSTOMER_ID}/cards
<?
//Customer
$customer = $openpay->customers->get(customerId);
$card = $customer->cards->add(cardDataRequest);

//Merchant
$card = $openpay->cards->add(cardDataRequest);
?>
//Customer
openpayAPI.cards().create(String customerId, Card card);

//Merchant
openpayAPI.cards().create(Card card);
//Customer
openpayAPI.CardService.Create(string customer_id, Card request);

//Merchant
openpayAPI.CardService.Create(Card request);
// Merchant
openpay.cards.create(cardRequest, callback);

// Customer
openpay.customers.cards.create(customerId, cardRequest, callback);
#Customer
@cards=@openpay.create(:cards)
@cards.create(request_hash, customer_id)

#Merchant
@cards=@openpay.create(:cards)
@cards.create(request_hash)

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"
   }' 
<?
$openpay = Openpay::getInstance('moiep6umtcnanql3jrxp', 'sk_3433941e467c1055b178ce26348b0fac');

$cardDataRequest = array(
    'token_id' => 'tokgslwpdcrkhlgxqi9a',
    'device_session_id' => '8VIoXj0hN5dswYHQ9X1mVCiB72M7FY9o'
    );

$customer = $openpay->customers->get('a9ualumwnrcxkl42l6mh');
$card = $customer->cards->add($cardDataRequest);
?>
OpenpayAPI api = new OpenpayAPI("https://sandbox-api.openpay.mx", "sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
Card request = new Card();
request.tokenId("tokgslwpdcrkhlgxqi9a");
request.deviceSessionId("8VIoXj0hN5dswYHQ9X1mVCiB72M7FY9o");

request = api.cards().create("a9pvykxz4g5rg0fplze0", request);
OpenpayAPI api = new OpenpayAPI("sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
Card request = new Card();
request.TokenId = "tokgslwpdcrkhlgxqi9a";
request.DeviceSessionId = "8VIoXj0hN5dswYHQ9X1mVCiB72M7FY9o";

request = api.CardService.Create("a9pvykxz4g5rg0fplze0", request);
var cardRequest = {
  'token_id' : 'tokgslwpdcrkhlgxqi9a',
  'device_session_id' : '8VIoXj0hN5dswYHQ9X1mVCiB72M7FY9o'
}

openpay.customers.cards.create('a9pvykxz4g5rg0fplze0', cardRequest, function(error, card)  {
  // ...
});
@openpay=OpenpayApi.new("mzdtln0bmtms6o3kck8f","sk_e568c42a6c384b7ab02cd47d2e407cab")
@cards=@openpay.create(:cards)
request_hash={
     "token_id" => "tokgslwpdcrkhlgxqi9a",
     "device_session_id" => "8VIoXj0hN5dswYHQ9X1mVCiB72M7FY9o"
   }

response_hash=@cards.create(request_hash.to_hash, "asynwirguzkgq2bizogo")

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

Property Description
token_id string (required, length = 45)
Token identifier generated in the the browser or in the customer’s device.
device_session_id string (required, length = 255)
Identifier of the device generated by the antifraud tool.

Response

Returns a card object

Get a card

Definition

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

Customer
GET https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/customers/{CUSTOMER_ID}/cards/{CARD_ID}
<?
//Customer
$customer = $openpay->customers->get(customerId);
$card = $customer->cards->get(cardId);

//Merchant
$card = $openpay->cards->get(cardId);
?>
//Customer
openpayAPI.cards().get(String customerId, String cardId);

//Merchant
openpayAPI.cards().get(String cardId);
//Customer
openpayAPI.CardService.Get(string customer_id, string card_id);

//Merchant
openpayAPI.CardService.Get(string card_id);
// Merchant
openpay.cards.get(cardId, callback);

// Customer
openpay.customers.cards.get(customerId, cardId, callback);
#Customer
@cards=@openpay.create(:cards)
@cards.get(card_id, customer_id)

#Merchant
@cards=@openpay.create(:cards)
@cards.get(card_id)

Request example

curl https://sandbox-api.openpay.mx/v1/mzdtln0bmtms6o3kck8f/customers/ag4nktpdzebjiye1tlze/cards/ktrpvymgatocelsciak7 \
   -u sk_e568c42a6c384b7ab02cd47d2e407cab: \
   -H "Content-type: application/json" 
<?
$openpay = Openpay::getInstance('moiep6umtcnanql3jrxp', 'sk_3433941e467c1055b178ce26348b0fac');

$customer = $openpay->customers->get('a9ualumwnrcxkl42l6mh');
$card = $customer->cards->get('k9pn8qtsvr7k7gxoq1r5');
?>
OpenpayAPI api = new OpenpayAPI("https://sandbox-api.openpay.mx", "sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
Card card = api.cards().get("a9pvykxz4g5rg0fplze0", "ktrpvymgatocelsciak7");
OpenpayAPI api = new OpenpayAPI("sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
Card card = api.CardService.Get("a9pvykxz4g5rg0fplze0", "ktrpvymgatocelsciak7");
openpay.customers.cards.get('a9pvykxz4g5rg0fplze0', 'ktrpvymgatocelsciak7', function(error, card){
  // ...
});
@openpay=OpenpayApi.new("mzdtln0bmtms6o3kck8f","sk_e568c42a6c384b7ab02cd47d2e407cab")
@cards=@openpay.create(:cards)

response_hash=@cards.get("ktrpvymgatocelsciak7", "asynwirguzkgq2bizogo")

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

Property Description
id string (required, length = 45)
Card unique identifier.

Response

Returns a card object

Card points

Definition

Merchant
GET https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/cards/{CARD_ID}/points

Customer
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
$customer = $openpay->customers->get(customerId);
$pointsBalance = $customer->cards->get(cardId)->get("points");

//Merchant
$pointsBalance = $openpay->cards->get(cardId)->get("points");

//Token
$pointsBalance = $openpay->get("tokens")->get(tokenId)->get("points");
?>
//Customer
openpayAPI.cards().points(String customerId, String cardId);

//Merchant
openpayAPI.cards().points(String cardId);
//Customer
openpayAPI.CardService.Points(string customer_id, string cardId);

//Merchant
openpayAPI.CardService.Points(string cardId);
// Merchant
openpay.cards.getPoints(cardId, callback);

// Customer
openpay.cards.getPoints(customerId, cardId, callback);
// Merchant
@cards=@openpay.create(:cards)
@cards.getPoints(card_id)

// Customer
@cards=@openpay.create(:cards)
@cards.getPoints(card_id, customer_id)

Customer request example

curl -g "https://sandbox-api.openpay.mx/v1/mzdtln0bmtms6o3kck8f/customers/ag4nktpdzebjiye1tlze/cards/ktrpvymgatocelsciak7/points" \
   -u sk_e568c42a6c384b7ab02cd47d2e407cab:
<?
$openpay = Openpay::getInstance('moiep6umtcnanql3jrxp', 'sk_3433941e467c1055b178ce26348b0fac');
$cardId =  'tfghdfghtertdfbsd';
$customer = $openpay->customers->get('a9ualumwnrcxkl42l6mh');
$pointsBalance = $customer->cards->get(cardId)->get("points");
?>
OpenpayAPI api = new OpenpayAPI("https://sandbox-api.openpay.mx", "sk_b05586ec98454522ac7d4ccdcaec9128",
"maonhzpqm8xp2ydssovf");
PointsBalance points = api.cards().points("a9pvykxz4g5rg0fplze0", "knasugabhdgq456wr");
OpenpayAPI api = new OpenpayAPI("sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
PointsBalance points = api.CardService.Points("a9pvykxz4g5rg0fplze0", "knasugabhdgq456wr");
openpay.customers.cards.getPoints('ag4nktpdzebjiye1tlze', 'tnasugabhdgq456wr', function(error, list){
  // ...
});
@openpay=OpenpayApi.new("mzdtln0bmtms6o3kck8f","sk_e568c42a6c384b7ab02cd47d2e407cab")
@cards=@openpay.create(:cards)

response_hash=@cards.getPoints("asynwirguzkgq2bizogo","tnasugabhdgq456wr")

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.

Property Description
id string (required, length = 45)
Unique identifier card

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

Property Description
id string (required, length = 45)
Identifier token

Response

Property Description
points_type Points type accepted by the card (Santander, Scotiabank or Bancomer)
remaining_points Number of remaining points
remaining_mxn Balance remaining points in pesos

Delete a card

Definition

Merchant
DELETE https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/cards/{CARD_ID}

Customer
DELETE https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/customers/{CUSTOMER_ID}/cards/{CARD_ID}
<?
//Customer
$customer = $openpay->customers->get(customerId);
$card = $customer->cards->get(cardId);
$card->delete();

//Merchant
$card = $openpay->cards->get(cardId);
$card->delete();
?>
//Customer
openpayAPI.cards().delete(String customerId, String cardId);

//Merchant
openpayAPI.cards().delete(String cardId);
//Customer
openpayAPI.CardService.Delete(string customer_id, string card_id);

//Merchant
openpayAPI.CardService.Delete(string card_id);
// Merchant
openpay.cards.delete(cardId, callback);

// Customer
openpay.customers.cards.delete(customerId, cardId, callback);
#Customer
@cards=@openpay.create(:cards)
@cards.delete(card_id, customer_id)

#Merchant
@cards=@openpay.create(:cards)
@cards.delete(card_id)

Request example

curl https://sandbox-api.openpay.mx/v1/mzdtln0bmtms6o3kck8f/customers/ag4nktpdzebjiye1tlze/cards/ktrpvymgatocelsciak7 \
   -u sk_e568c42a6c384b7ab02cd47d2e407cab: \
   -X DELETE
<?
$openpay = Openpay::getInstance('moiep6umtcnanql3jrxp', 'sk_3433941e467c1055b178ce26348b0fac');

$customer = $openpay->customers->get('a9ualumwnrcxkl42l6mh');
$card = $customer->cards->get('k9pn8qtsvr7k7gxoq1r5');
$card->delete();
?>
OpenpayAPI api = new OpenpayAPI("https://sandbox-api.openpay.mx", "sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
api.cards().delete("a9pvykxz4g5rg0fplze0", "ktrpvymgatocelsciak7");
OpenpayAPI api = new OpenpayAPI("sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
api.CardService.Delete("a9pvykxz4g5rg0fplze0", "ktrpvymgatocelsciak7");
openpay.customers.cards.delete('a9pvykxz4g5rg0fplze0', 'ktrpvymgatocelsciak7', function(error) {
  // ...
});
@openpay=OpenpayApi.new("mzdtln0bmtms6o3kck8f","sk_e568c42a6c384b7ab02cd47d2e407cab")
@cards=@openpay.create(:cards)

response_hash=@cards.delete("ktrpvymgatocelsciak7", "asynwirguzkgq2bizogo")

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

Property Description
id string (required, length = 45)
Card unique identifier.

Response

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

List of cards

Definition

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

Customer
GET https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/customers/{CUSTOMER_ID}/cards
<?
//Customer
$customer = $openpay->customers->get(customerId);
$cardList = $customer->cards->getList(findDataRequest);

//Merchant
$cardList = $openpay->cards->getList(findDataRequest);
?>
//Customer
openpayAPI.cards().list(String customerId, SearchParams request);

//Merchant
openpayAPI.cards().list(SearchParams request);
//Customer
openpayAPI.CardService.List(string customer_id, SearchParams request = null);

//Merchant
openpayAPI.CardService.List(SearchParams request = null);
// Merchant
openpay.cards.list(callback);
openpay.cards.list(searchParams, callback);

// Customer
openpay.cards.list(customerId, callback);
openpay.cards.list(customerId, searchParams, callback);
#Customer
@cards=@openpay.create(:cards)
@cards.all(customer_id)

#Merchant
@cards=@openpay.create(:cards)
@cards.all

Request example

curl -g "https://sandbox-api.openpay.mx/v1/mzdtln0bmtms6o3kck8f/customers/ag4nktpdzebjiye1tlze/cards?limit=2" \
   -u sk_e568c42a6c384b7ab02cd47d2e407cab: 
<?
$openpay = Openpay::getInstance('moiep6umtcnanql3jrxp', 'sk_3433941e467c1055b178ce26348b0fac');

$findDataRequest = array(
    'creation[gte]' => '2013-01-01',
    'creation[lte]' => '2013-12-31',
    'offset' => 0,
    'limit' => 5);

$customer = $openpay->customers->get('a9ualumwnrcxkl42l6mh');
$cardList = $customer->cards->getList($findDataRequest);
?>
final Calendar dateGte = Calendar.getInstance();
final Calendar dateLte = Calendar.getInstance();
dateGte.set(2014, 5, 1, 0, 0, 0);
dateLte.set(2014, 5, 15, 0, 0, 0);

OpenpayAPI api = new OpenpayAPI("https://sandbox-api.openpay.mx", "sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
SearchParams request = new SearchParams();
request.creationGte(dateGte.getTime());
request.creationLte(dateLte.getTime());
request.offset(0);
request.limit(100);
List<Card> cards = api.cards().list("a9pvykxz4g5rg0fplze0", request);
OpenpayAPI api = new OpenpayAPI("sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
SearchParams request = new SearchParams();
request.CreationGte = new Datetime(2014, 5, 1);
request.CreationLte = new DateTime(2014, 5, 15);
request.Offset = 0;
request.Limit = 100;

List<Card> cards = api.CardService.List("a9pvykxz4g5rg0fplze0", request);
var searchParams = {
  'limit' : 2
};

openpay.customers.cards.list('ag4nktpdzebjiye1tlze', searchParams, function(error, list){
  // ...
});
@openpay=OpenpayApi.new("mzdtln0bmtms6o3kck8f","sk_e568c42a6c384b7ab02cd47d2e407cab")
@cards=@openpay.create(:cards)

response_hash=@cards.all("asynwirguzkgq2bizogo")

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.

Property Description
creation date
Same as creation date. Format yyyy-mm-dd
creation[gte] date
After the creation date. Format yyyy-mm-dd
creation[lte] date
Before the creation date. Format yyyy-mm-dd
offset numeric
Number of records to skip at the beginning, default 0.
limit numeric
Number of required records, default 10.

Response

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

Updating a card

Definition

Merchant
PUT https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/cards/{CARD_ID}

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

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

Property Description
holder_name string (optional)
Name of the cardholder.
cvv2 string (optional)
Security code as it appears on the back of the card. Usually 3 digits.
expiration_month numeric (optional)
Expiration month as it appears on the card.
expiration_year numeric (optional)
Expiration year as it appears on the card.
merchant_id string (conditional)
Merchant ID to use to validate this card. Required when using a merchant group.

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"
}
Property Description
id string
ID of the bank account.
holder_name string
Holder’s full name.
alias string
Name by which the bank account is identified.
clabe string
CLABE number assigned to the account.
bank_name string
Abbreviated name of the bank where the account resides, based on the following catalog of Bank codes.
bank_code string
Bank code where the account resides, based on the following catalog Bank Codes.
creation_date  datetime
Date and time when the bank account was created in ISO 8601 format.

Create a bank account

Definition

POST https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/customers/{CUSTOMER_ID}/bankaccounts
<?
$customer = $openpay->customers->get(customerId);
$bankaccount = $customer->bankaccounts->add(bankDataRequest);
?>
//Customer
openpayAPI.bankAccounts().create(String customerId, BankAccount request);
//Customer
openpayAPI.BankAccountService.Create(string customer_id, BankAccount request);
openpay.customers.bankaccounts.create(customerId, bankaccountRequest, callback);
#Customer
@bank_accounts=@openpay.create(:bankaccounts)
@bank_accounts.create(request_hash, customer_id)

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"
}'
<?
$openpay = Openpay::getInstance('moiep6umtcnanql3jrxp', 'sk_3433941e467c1055b178ce26348b0fac');

$bankDataRequest = array(
    'clabe' => '072910007380090615',
    'alias' => 'Cuenta principal',
    'holder_name' => 'Teofilo Velazco');

$customer = $openpay->customers->get('a9ualumwnrcxkl42l6mh');
$bankaccount = $customer->bankaccounts->add($bankDataRequest);
?>
OpenpayAPI api = new OpenpayAPI("https://sandbox-api.openpay.mx", "sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
BankAccount request = new BankAccount();
request.holderName("Juan Hernández Sánchez");
request.alias("Cuenta principal");
request.clabe("032XXXXXXXXXX59719");

request = api.bankAccounts().create("a9pvykxz4g5rg0fplze0", request);
OpenpayAPI api = new OpenpayAPI("sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
BankAccount request = new BankAccount();
request.HolderName = "Juan Hernández Sánchez";
request.Alias = "Cuenta principal";
request.CLABE = "032XXXXXXXXXX59719";

request = api.BankAccountService.Create("a9pvykxz4g5rg0fplze0", request);
var bankaccountRequest = {
  'clabe' : '032180000118359719',
  'alias' : 'Cuenta principal',
  'holder_name' : 'Juan Hernández Sánchez'
};

openpay.customers.bankaccounts.create('a9pvykxz4g5rg0fplze0', bankaccountRequest, function(error, bankaccount) {
  // ...
});
@openpay=OpenpayApi.new("mzdtln0bmtms6o3kck8f","sk_e568c42a6c384b7ab02cd47d2e407cab")
@bank_accounts=@openpay.create(:bankaccounts)
request_hash={
     "holder_name" => "Juan Hernández Sánchez",
     "alias" => "Cuenta principal",
     "clabe" => "032XXXXXXXXXX59719"
   }

response_hash=@bank_accounts.create(request_hash.to_hash, "asynwirguzkgq2bizogo")

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

Property Description
holder_name string (required, length = 80)
Holder’s full name.
alias string (optional, length = 45)
Name by which the bank account is identified.
clabe string (required, length = 45)
CLABE number assigned to the account.

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 = $openpay->customers->get(customerId);
$bankaccount = $customer->bankaccounts->get(bankAccountId);
?>
//Customer
openpayAPI.bankAccounts().get(String customerId, String bankAccountId);
//Customer
openpayAPI.BankAccountService.Get(string customer_id, string bank_account_id);
openpay.customers.bankaccounts.get(customerId, bankaccountId, callback);
#Customer 
@bank_accounts=@openpay.create(:bankaccounts)
@bank_accounts.get(customer_id, bankaccount_id)

Request example

curl https://sandbox-api.openpay.mx/v1/mzdtln0bmtms6o3kck8f/customers/ag4nktpdzebjiye1tlze/bankaccounts/buyj4apkwilpp2jfxr9r \
   -u sk_e568c42a6c384b7ab02cd47d2e407cab:
<?
$openpay = Openpay::getInstance('moiep6umtcnanql3jrxp', 'sk_3433941e467c1055b178ce26348b0fac');

$customer = $openpay->customers->get('a9ualumwnrcxkl42l6mh');
$bankaccount = $customer->bankaccounts->get('b4vcouaavwuvkpufh0so');
?>
OpenpayAPI api = new OpenpayAPI("https://sandbox-api.openpay.mx", "sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
BankAccount bankAccount = api.bankAccounts().get("a9pvykxz4g5rg0fplze0", "buyj4apkwilpp2jfxr9r");
OpenpayAPI api = new OpenpayAPI("sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
BankAccount bankAccount = api.BankAccountService.Get("a9pvykxz4g5rg0fplze0", "buyj4apkwilpp2jfxr9r");
openpay.customers.bankaccounts.get('a9pvykxz4g5rg0fplze0', 'buyj4apkwilpp2jfxr9r', function(error, bankaccount){
  // ...
});
@openpay=OpenpayApi.new("mzdtln0bmtms6o3kck8f","sk_e568c42a6c384b7ab02cd47d2e407cab")
@bank_accounts=@openpay.create(:bankaccounts)

response_hash=@bank_accounts.get("asynwirguzkgq2bizogo", "buyj4apkwilpp2jfxr9r")

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

Property Description
id string (required, length = 45)
Unique identifier of the bank account.

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 = $openpay->customers->get(customerId);
$bankaccount = $customer->bankaccounts->get(bankAccountId);
$bankaccount->delete();
?>
//Customer
openpayAPI.bankAccounts().delete(String customerId, String bankAccountId);
//Customer
openpayAPI.BankAccountService.Delete(string customer_id, string bank_account_id);
openpay.customers.bankaccounts.delete(customerId,bankaccountId, callback);
#Customer
@bank_accounts=@openpay.create(:bankaccounts)
@bank_accounts.delete(customer_id, bankaccount_id)

Request example

curl https://sandbox-api.openpay.mx/v1/mzdtln0bmtms6o3kck8f/customers/ag4nktpdzebjiye1tlze/bankaccounts/buyj4apkwilpp2jfxr9r \
   -u sk_e568c42a6c384b7ab02cd47d2e407cab: \
   -X DELETE
<?
$openpay = Openpay::getInstance('moiep6umtcnanql3jrxp', 'sk_3433941e467c1055b178ce26348b0fac');

$customer = $openpay->customers->get('a9ualumwnrcxkl42l6mh');
$bankaccount = $customer->bankaccounts->get('b4vcouaavwuvkpufh0so');
$bankaccount->delete();
?>
OpenpayAPI api = new OpenpayAPI("https://sandbox-api.openpay.mx", "sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
api.bankAccounts().delete("a9pvykxz4g5rg0fplze0", "buyj4apkwilpp2jfxr9r");
OpenpayAPI api = new OpenpayAPI("sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
api.BankAccountService.Delete("a9pvykxz4g5rg0fplze0", "buyj4apkwilpp2jfxr9r");
openpay.customers.bankaccounts.delete('a9pvykxz4g5rg0fplze0','buyj4apkwilpp2jfxr9r', function(error){
  // ...
});
@openpay=OpenpayApi.new("mzdtln0bmtms6o3kck8f","sk_e568c42a6c384b7ab02cd47d2e407cab")
@bank_accounts=@openpay.create(:bankaccounts)

response_hash=@bank_accounts.delete("asynwirguzkgq2bizogo", "buyj4apkwilpp2jfxr9r")

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

Property Description
id string (required, length = 45)
Unique identifier of the bank account.

Response

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

List of bank accounts

Definition

GET https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/customers/{CUSTOMER_ID}/bankaccounts
<?
$customer = $openpay->customers->get(customerId);
$bankaccountList = $customer->bankaccounts->getList(findDataRequest);
?>
//Customer
openpayAPI.bankAccounts().list(String customerId, SearchParams request);
//Customer
openpayAPI.BankAccountService.List(string customer_id, SearchParams request = null);
openpay.customers.bankaccounts.list(customerId, callback);
openpay.customers.bankaccounts.list(customerId, searchParams, callback);
#Customer
@bank_accounts=@openpay.create(:bankaccounts)
@bank_accounts.all(customer_id)

Request example

curl -g "https://sandbox-api.openpay.mx/v1/mzdtln0bmtms6o3kck8f/customers/ag4nktpdzebjiye1tlze/bankaccounts?limit=2" \
   -u sk_e568c42a6c384b7ab02cd47d2e407cab: 
<?
$openpay = Openpay::getInstance('moiep6umtcnanql3jrxp', 'sk_3433941e467c1055b178ce26348b0fac');

$findDataRequest = array(
    'creation[gte]' => '2013-01-01',
    'creation[lte]' => '2013-12-31',
    'offset' => 0,
    'limit' => 5);

$customer = $openpay->customers->get('a9ualumwnrcxkl42l6mh');
$bankaccountList = $customer->bankaccounts->getList($findDataRequest);
?>
final Calendar dateGte = Calendar.getInstance();
final Calendar dateLte = Calendar.getInstance();
dateGte.set(2014, 5, 1, 0, 0, 0);
dateLte.set(2014, 5, 15, 0, 0, 0);

OpenpayAPI api = new OpenpayAPI("https://sandbox-api.openpay.mx", "sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
SearchParams request = new SearchParams();
request.creationGte(dateGte.getTime());
request.creationLte(dateLte.getTime());
request.offset(0);
request.limit(100);

List<BankAccount> bankAccounts = api.bankAccounts().list("a9pvykxz4g5rg0fplze0", request);
OpenpayAPI api = new OpenpayAPI("sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
SearchParams request = new SearchParams();
request.CreationGte = new Datetime(2014, 5, 1);
request.CreationLte = new DateTime(2014, 5, 15);
request.Offset = 0;
request.Limit = 100;

List<BankAccount> banckAccounts = api.BankAccountService.List("a9pvykxz4g5rg0fplze0", request);
var searchParams = {
  'limit' : 2
};

openpay.customers.bankaccounts.list('ag4nktpdzebjiye1tlze', searchParams, function(error, list){
  // ...
});
@openpay=OpenpayApi.new("mzdtln0bmtms6o3kck8f","sk_e568c42a6c384b7ab02cd47d2e407cab")
@bank_accounts=@openpay.create(:bankaccounts)

response_hash=@bank_accounts.all("asynwirguzkgq2bizogo")

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.

Property Description
creation date
Same as creation date. Format yyyy-mm-dd
creation[gte] date
After the creation date. Format yyyy-mm-dd
creation[lte] date
Before the creation date. Format yyyy-mm-dd
offset numeric
Number of records to skip at the beginning, default 0.
limit numeric
Number of required records, default 10.

Response

List of bank account objects registered according to the given parameters, 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
}
Property Description
id string
Unique plan identifier.
creation_date datetime
Date and time in which the plan was created in ISO 8601 format.
name string
Plan name.
amount numeric
Amount that will be applied once the subscription is charged. It has to be more than zero and it can have up to two decimal places.
currency string
Currency used in the operation, by default is MXN (Mexican pesos).
repeat_every numeric
Time units in which the subscription will be charged. For example, repeat_unit=month and repeat_every=2 indicates that it will be charged every 2 months.
repeat_unit string
Describes the charge unit frequency. It can be weekly(week), monthly(month) or yearly (year).
retry_times numeric
Number of attempts to try to charge the subscription. When the attempts have been exhausted, the status field is determined by the field status_after_retry.
status string
Plan status can be active or deleted. If the plan is in deleted state it doesn’t allow to register new subscriptions under this plan but existing subscriptions will be charged.
status_after_retry string
This field indicates the status in which the subscription will be set once all the charge attempts have been exhausted. It can be unpaid or cancelled.
trial_days numeric
Number of trial days this subscription will have by default.

Create a new Plan

Definition

POST https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/plans
<?
$plan = $openpay->plans->add(planDataRequest);
?>
openpayAPI.plans().create(Plan request);
openpayAPI.PlanService.Create(Plan plan);
openpay.plans.create(planRequest, callback);
#Customere
@plans=@openpay.create(:plans)
@plans.create(request_hash)

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"
}' 
<?
$openpay = Openpay::getInstance('moiep6umtcnanql3jrxp', 'sk_3433941e467c1055b178ce26348b0fac');

$planDataRequest = array(
    'amount' => 150.00,
    'status_after_retry' => 'cancelled',
    'retry_times' => 2,
    'name' => 'Plan Curso Verano',
    'repeat_unit' => 'month',
    'trial_days' => '30',
    'repeat_every' => '1',
    'currency' => 'MXN');

$plan = $openpay->plans->add($planDataRequest);
?>
OpenpayAPI api = new OpenpayAPI("https://sandbox-api.openpay.mx", "sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
Plan request = new Plan();
request.name("Curso de ingles");
request.amount(new BigDecimal("100.00"));
request.repeatEvery(1, PlanRepeatUnit.WEEK);
request.retryTimes(3);
request.statusAfterRetry(PlanStatusAfterRetry.UNPAID);
request.trialDays(30);

request = api.plans().create(request);
OpenpayAPI api = new OpenpayAPI("sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
Plan request = new Plan();
request.Name = "Curso de ingles";
request.Amount = new Decimal(100.00);
request.RepeatEvery = 1;
request.RepeatUnit = "week";
request.RetryTimes = 2;
request.StatusAfterRetry = "unpaid";
request.TrialDays = 30;

request = api.PlanService.Create(request);
var planRequest = {
  'amount': 150.00,
  'status_after_retry': 'cancelled',
  'retry_times': 2,
  'name': 'Curso de ingles',
  'repeat_unit': 'month',
  'trial_days': '30',
  'repeat_every': '1'
};

openpay.plans.create(planRequest, function(error, plan){
  // ...
});
@openpay=OpenpayApi.new("mzdtln0bmtms6o3kck8f","sk_e568c42a6c384b7ab02cd47d2e407cab")
@plans=@openpay.create(:plans)
request_hash={
     "name" => "Curso de ingles",
     "amount" => 150.00,
     "repeat_every" => "1",
     "repeat_unit" => "month",
     "retry_times" => 2,
     "status_after_retry" => "cancelled",
     "trial_days" => "30"
   }

response_hash=@plans.create(request_hash.to_hash)

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

Property Description
name string (required, length = 255)
Plan’s name.
amount numeric (required)
Amount that will be charged at subscription. It needs to be more than zero and can have up to two decimal places.
repeat_every numeric (required)
Time units in which the subscription will be charged. For example, repeat_unit=month and repeat_every=2 indicates that it will be charged every 2 months.
repeat_unit numeric (required)
Describes the charge unit frequency. It can be weekly(week), monthly(month) or yearly (year).
retry_times numeric (optional)
Number of attempts to try to charge the subscription. When the attempts have been exhausted, the status field is determined by the field status_after_retry.
status_after_retry string (required, values = “UNPAID/CANCELLED”)
This field indicates the status in which the subscription will be set once all the charge attempts have been exhausted. It can be unpaid or cancelled.
trial_days numeric (required)
Number of trial days this subscription will have by default.

Response

Returns the created plan object or an error in case an issue occurred.

Update existing plans.

Definition

PUT https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/plans/{PLAN_ID}
<?
$plan = $openpay->plans->get(planId);
$plan->save();
?>
openpayAPI.plans().update(Plan request);
openpayAPI.PlanService.Update(Plan plan);
openpay.plans.update(planId, planRequest, callback);
#Customer
@plans=@openpay.create(:plans)
@plans.update(request_hash, 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"
   }' 
<?
$openpay = Openpay::getInstance('moiep6umtcnanql3jrxp', 'sk_3433941e467c1055b178ce26348b0fac');

$plan = $openpay->plans->get('pduar9iitv4enjftuwyl');
$plan->name = 'Plan Curso de Verano 2014';
$plan->save();
?>
OpenpayAPI api = new OpenpayAPI("https://sandbox-api.openpay.mx", "sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
Plan request = new Plan();
request.setId("p8e6x3hafqqsbmnoevrt");
request.name("Curso de ingles");
request.trialDays(30);

request = api.plans().update(request);
OpenpayAPI api = new OpenpayAPI("sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
Plan request = new Plan();
request.Id = "p8e6x3hafqqsbmnoevrt";
request.Name = "Curso de ingles";
request.TrialDays = 30;

request = api.PlanService.Update(request);
var planRequest = {
  'name': 'Curso de aleman',
  'trial_days': 60
};

openpay.plans.update(planId, planRequest, function(error, plan){
  // ...
});
@openpay=OpenpayApi.new("mzdtln0bmtms6o3kck8f","sk_e568c42a6c384b7ab02cd47d2e407cab")
@plans=@openpay.create(:plans)
request_hash={
     "name" => "Curso de ingles",
     "trial_days" => "30"
   }

response_hash=@plans.update(request_hash.to_hash, "p8e6x3hafqqsbmnoevrt")

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

Property Description
name string (optional, length = 80)
Plan’s name.
trial_days numeric (optional)
Number of trial days this subscription will have by default.

Response

Returns a plan object with the updated information or an error response if a problem occurred with the update.

Get a plan

Definition

GET https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/plans/{PLAN_ID}
<?
$plan = $openpay->plans->get(planId);
?>
openpayAPI.plans().get(String planId);
openpayAPI.PlanService.Get(string plan_id);
openpay.plans.get(planId, callback);
#Customer
@plans=@openpay.create(:plans)
@plans.get(plan_id)

Request example

curl https://sandbox-api.openpay.mx/v1/mzdtln0bmtms6o3kck8f/plans/p8e6x3hafqqsbmnoevrt \
   -u sk_e568c42a6c384b7ab02cd47d2e407cab:
<?
$openpay = Openpay::getInstance('moiep6umtcnanql3jrxp', 'sk_3433941e467c1055b178ce26348b0fac');

$plan = $openpay->plans->get('pduar9iitv4enjftuwyl');
?>
OpenpayAPI api = new OpenpayAPI("https://sandbox-api.openpay.mx", "sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
Plan plan = api.plans().get("p8e6x3hafqqsbmnoevrt");
OpenpayAPI api = new OpenpayAPI("sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
Plan plan = api.PlanService.Get("p8e6x3hafqqsbmnoevrt");
openpay.plans.get('p8e6x3hafqqsbmnoevrt', function(error, plan){
  // ...
});
@openpay=OpenpayApi.new("mzdtln0bmtms6o3kck8f","sk_e568c42a6c384b7ab02cd47d2e407cab")
@plans=@openpay.create(:plans)

response_hash=@plans.get("p8e6x3hafqqsbmnoevrt")

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

Property Description
id string (required, length = 45)
Plan identifier.

Response

Returns a plan object

Delete a plan

Definition

DELETE https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/plans/{PLAN_ID}
<?
$customer = $openpay->customers->get(customerId);
$plan = $openpay->plans->get(planId);
$plan->delete();
?>
openpayAPI.plans().delete(String planId);
openpayAPI.PlanService.Delete(string plan_id);
openpay.plans.delete(planId, callback);
#Customer
@plans=@openpay.create(:plans)
@plans.delete(plan_id)

Request example

curl https://sandbox-api.openpay.mx/v1/mzdtln0bmtms6o3kck8f/plans/p8e6x3hafqqsbmnoevrt \
   -u sk_e568c42a6c384b7ab02cd47d2e407cab: \
   -X DELETE
<?
$openpay = Openpay::getInstance('moiep6umtcnanql3jrxp', 'sk_3433941e467c1055b178ce26348b0fac');

$customer = $openpay->customers->get('a9ualumwnrcxkl42l6mh');
$plan = $openpay->plans->get('pduar9iitv4enjftuwyl');
$plan->delete();
?>
OpenpayAPI api = new OpenpayAPI("https://sandbox-api.openpay.mx", "sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
api.plans().delete("p8e6x3hafqqsbmnoevrt");
OpenpayAPI api = new OpenpayAPI("sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
api.PlanService.Delete("p8e6x3hafqqsbmnoevrt");
openpay.plans.delete('p8e6x3hafqqsbmnoevrt', function(error){
  // ...
});
@openpay=OpenpayApi.new("mzdtln0bmtms6o3kck8f","sk_e568c42a6c384b7ab02cd47d2e407cab")
@plans=@openpay.create(:plans)

response_hash=@plans.delete("p8e6x3hafqqsbmnoevrt")

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

Property Description
id string (required, length = 45)
Identifier of the plan that will be deleted.

Response

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

Plan list

Definition

GET https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/plans
<?
$planList = $openpay->plans->getList(findDataRequest);
?>
openpayAPI.plans().list(SearchParams request);
openpayAPI.PlanService.List(SearchParams request = null);
openpay.plans.list(callback);
openpay.plans.list(searchParams, callback);
#Customer
@plans=@openpay.create(:plans)
@plans.all

Request example

curl -g "https://sandbox-api.openpay.mx/v1/mzdtln0bmtms6o3kck8f/plans?limit=10" \
   -u sk_e568c42a6c384b7ab02cd47d2e407cab: 
<?
$openpay = Openpay::getInstance('moiep6umtcnanql3jrxp', 'sk_3433941e467c1055b178ce26348b0fac');

$findDataRequest = array(
    'creation[gte]' => '2013-01-01',
    'creation[lte]' => '2013-12-31',
    'offset' => 0,
    'limit' => 5);

$planList = $openpay->plans->getList($findDataRequest);
?>
final Calendar dateGte = Calendar.getInstance();
final Calendar dateLte = Calendar.getInstance();
dateGte.set(2014, 5, 1, 0, 0, 0);
dateLte.set(2014, 5, 15, 0, 0, 0);

OpenpayAPI api = new OpenpayAPI("https://sandbox-api.openpay.mx", "sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
SearchParams request = new SearchParams();
request.creationGte(dateGte.getTime());
request.creationLte(dateLte.getTime());
request.offset(0);
request.limit(100);

List<Plan> plans = api.plans().list(request);
OpenpayAPI api = new OpenpayAPI("sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
SearchParams request = new SearchParams();
request.CreationGte = new Datetime(2014, 5, 1);
request.CreationLte = new DateTime(2014, 5, 15);
request.Offset = 0;
request.Limit = 100;

List<Plan> plans = api.PlanService.List(request);
var searchParams = {
  'limit' : 10
};

openpay.plans.list(searchParams, function(error, list){
  // ...
});
@openpay=OpenpayApi.new("mzdtln0bmtms6o3kck8f","sk_e568c42a6c384b7ab02cd47d2e407cab")
@plans=@openpay.create(:plans)

response_hash=@plans.all

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:

Property Description
creation date
Same as creation date. Format yyyy-mm-dd.
creation[gte] date
After creation date. Format: yyyy-mm-dd.
creation[lte] date
Before the creation date. Format: yyyy-mm-dd.
offset numeric
Number of records to skip from the beggining, by default is 0.
limit numeric
Number of records to return, by default is 10.

Response

A list of plan objects registered according to the given parameters, sort by creation date in descending order.

Subscriptions

Subscriptions allow to associate customers and cards in order to make recurrent payments.

In order to subscribe a customer first is required to 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"
}
Property Description
id string
Unique subscription identifier.
creation_date datetime
Date and time in which the subscription was created using ISO 8601 format.
cancel_at_period_end string
Indicates if the subscription has been canceled at the end of the period.
charge_date numeric
Date in which the subscription will be charged.
current_period_number string
Indicates the current period to be charged.
period_end_date numeric
Date in which the current period ends, it’s one day before the next charge.
trial_end_date string
Date in which the trial period ends. One day after this date the first charge is applied.
plan_id numeric
Plan identifier in which this subscription will be created.
status string
Subscription status, it can be active, trial, past_due, unpaid or cancelled. If the subscription has a trial period, the trial period is applied, if it doesn’t have or when the trial period ends and the first payment is executed it changes to active. When the charge was unable to be completed it changes to past_due. When all the charge tries has been completed according to the plan configuration it can change to unpaid or cancelled. When it’s marked as unpaid and the subscription wants to be reactivated it’s required to update the subscription payment method(card). In any other case, the status is set to cancelled.
customer_id string
Customer identifier for the subscription owner.
card object
Payment method for the subscription. See card object.

Create a new Subscription

Definition

POST https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/customers/{CUSTOMER_ID}/subscriptions
<?
$customer = $openpay->customers->get(customerId);
$subscription = $customer->subscriptions->add(subscriptionDataRequest);
?>
openpayAPI.subscriptions().create(String customerId, Subscription request);
openpayAPI.SubscriptionService.Create(string customer_id, Subscription request);
openpay.customers.subscriptions.create(customerId, subscriptionRequest, callback);
#Customer
@subscriptions=@openpay.create(:subscriptions)
@subscriptions.create(request_hash, customer_id)

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"
}' 
<?
$openpay = Openpay::getInstance('moiep6umtcnanql3jrxp', 'sk_3433941e467c1055b178ce26348b0fac');

$subscriptionDataRequest = array(
    'trial_end_date' => '2014-01-01', 
    'plan_id' => 'pbi4kb8hpb64x0uud2eb',
    'card' => array(
         'card_number' => '4111111111111111',
         'holder_name' => 'Juan Perez Ramirez',
         'expiration_year' => '20',
         'expiration_month' => '12',
         'cvv2' => '110',
         'device_session_id' => 'kR1MiQhz2otdIuUlQkbEyitIqVMiI16f'));

$customer = $openpay->customers->get('a9ualumwnrcxkl42l6mh');
$subscription = $customer->subscriptions->add($subscriptionDataRequest);
?>
final Calendar trialEndDate = Calendar.getInstance();
trialEndDate.set(2014, 5, 1, 0, 0, 0);

OpenpayAPI api = new OpenpayAPI("https://sandbox-api.openpay.mx", "sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
Subscription request = new Subscription();
request.planId("pbi4kb8hpb64x0uud2eb");
request.trialEndDate(trialEndDate.getTime());
Card card = new Card();
card.cardNumber("4111111111111111");
card.holderName("Juan Perez Ramirez");
card.cvv2("110");
card.expirationMonth(12);
card.expirationYear(20);
card.deviceSessionId("kR1MiQhz2otdIuUlQkbEyitIqVMiI16f");
request.card(card);

request = api.subscriptions().create("a9pvykxz4g5rg0fplze0", request);
OpenpayAPI api = new OpenpayAPI("sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
Subscription request = new Subscription();
request.PlanId = "idPlan-01001";
request.TrialEndDate = new Datetime(2014, 5, 1);
Card card = new Card();
card.HolderName = "Juan Perez Ramirez";
card.CardNumber = "4111111111111111";
card.Cvv2 = "110";
card.ExpirationMonth = "12";
card.ExpirationYear = "20";
card.DeviceSessionId = "kR1MiQhz2otdIuUlQkbEyitIqVMiI16f";
request.Card = card;

request = api.SubscriptionService.Create("a9pvykxz4g5rg0fplze0", request);
var subscriptionRequest = {
   'card':{
      'card_number':'4111111111111111',
      'holder_name':'Juan Perez Ramirez',
      'expiration_year':'20',
      'expiration_month':'12',
      'cvv2':'110',
      'device_session_id':'kR1MiQhz2otdIuUlQkbEyitIqVMiI16f'
   },
   'plan_id':'pbi4kb8hpb64x0uud2eb'
};

openpay.customers.subscriptions.create(customerId, subscriptionRequest, function(error, subscription){
  // ...
});
@openpay=OpenpayApi.new("mzdtln0bmtms6o3kck8f","sk_e568c42a6c384b7ab02cd47d2e407cab")
@subscriptions=@openpay.create(:subscriptions)
card_hash={
     "holder_name" => "Juan Perez Ramirez",
     "card_number" => "4111111111111111",
     "cvv2" => "110",
     "expiration_month" => "12",
     "expiration_year" => "20",
     "device_session_id" => "kR1MiQhz2otdIuUlQkbEyitIqVMiI16f"
   }
request_hash={
     "plan_id" => "pbi4kb8hpb64x0uud2eb",
     "trial_end_date" => "2014-06-20",
     "card" => card_hash
   }

response_hash=@subscriptions.create(request_hash.to_hash, "a9pvykxz4g5rg0fplze0")

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

Property Description
plan_id string (required, length = 45)
Plan identifier in which the subscription will be created.
trial_end_date string (optional, length = 10)
Indicates the customer trial end date. If it’s not indicated the plan will be used to calculate it. If the date is in the past it will be interpreted as a subscription with no trial. Format: yyyy-mm-dd.
source_id string (required if the card is not sent, length = 45)
Card token identifier, or the customer registered card which will be used to charge the subscription.
card object (required if the source_id is not present)
Payment method which will be used to charge the subscription. See card object.

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
<?
$customer = $openpay->customers->get(customerId);
$subscription = $customer->subscriptions->get(subscriptionId);
$subscription->save();
?>
openpayAPI.subscriptions().update(Subscription request);
openpayAPI.SubscriptionService.Update(string customer_id, Subscription subscription);
openpay.customers.subscriptions.update(customerId, subscriptionId, subscriptionRequest, callback);
#Customer
@subscriptions=@openpay.create(:subscriptions)
@subscriptions.update(request_hash, customer_id)

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"
    }
}' 
<?
$openpay = Openpay::getInstance('moiep6umtcnanql3jrxp', 'sk_3433941e467c1055b178ce26348b0fac');

$customer = $openpay->customers->get('a9ualumwnrcxkl42l6mh');
$subscription = $customer->subscriptions->get('s7ri24srbldoqqlfo4vp');
$subscription->trial_end_date = '2014-12-31';
$subscription->save();
?>
final Calendar trialEndDate = Calendar.getInstance();
trialEndDate.set(2014, 5, 1, 0, 0, 0);

OpenpayAPI api = new OpenpayAPI("https://sandbox-api.openpay.mx", "sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
Subscription request = new Subscription();
request.planId("idPlan-01001");
request.trialEndDate(trialEndDate.getTime());
request.sourceId("ktrpvymgatocelsciak7");

request = api.subscriptions().update(request);
OpenpayAPI api = new OpenpayAPI("sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
Subscription request = new Subscription();
request.PlanId = "idPlan-01001";
request.TrialEndDate = new Datetime(2014, 5, 1);;
request.CardId = "ktrpvymgatocelsciak7";

request = api.SubscriptionService.Update("a9pvykxz4g5rg0fplze0", request);
var subscriptionRequest = {
'trial_end_date': '2016-01-11',
  'card': {
    'card_number': '343434343434343',
    'holder_name': 'Juan Perez Ramirez',
    'expiration_year': '20',
    'expiration_month': '12',
    'cvv2':'1234'
  }
};

openpay.customers.subscriptions.update('ag4nktpdzebjiye1tlze', 's0gmyor4yqtyv1miqwr0', subscriptionRequest, 
    function(error, subscription){
  // ...
});
@openpay=OpenpayApi.new("mzdtln0bmtms6o3kck8f","sk_e568c42a6c384b7ab02cd47d2e407cab")
@subscriptions=@openpay.create(:subscriptions)
request_hash={
     "plan_id" => "pbi4kb8hpb64x0uud2eb",
     "cancel_at_period_end" => true,
     "trial_end_date" => "2014-06-20",
     "source_id" => "ktrpvymgatocelsciak7"
   }

response_hash=@subscriptions.update(request_hash.to_hash, "pbi4kb8hpb64x0uud2eb")

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 o an active subscription. Actualiza la información de una suscripción activa.

Request

Property Description
cancel_at_period_end booelan (optional)
Indicates if the subscriptions has to be cancelled at the end of the period.
trial_end_date string (optional, length = 10)
Trial end date. If the value is not indicated, the trial_days value from the plan will be used to calculate it. If a date from the past is sent it will be interpreted as a subscription without trial days. Format: yyyy-mm-dd.
source_id string (optional, length = 45)
Card token identifier, or the customer registered card which will be used to charge the subscription.
card object (optional)
Payment method that will be used to charge the subscription. See card object.

Response

Returns the updated subscription object or an error response if an error occurred during the update.

Get a Subscription

Definition

GET https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/customers/{CUSTOMER_ID}/subscriptions/{SUBSCRIPTION_ID}
<?
$customer = $openpay->customers->get(customerId);
$subscription = $customer->subscriptions->get(subscriptionId);
?>
openpayAPI.subscriptions().get(String customerId, String customerId);
openpayAPI.SubscriptionService.Get(string customer_id, string subscription_id);
openpay.customers.subscriptions.get(customerId, subscriptionId, callback);
#Customer
@subscriptions=@openpay.create(:subscriptions)
@subscriptions.get(subscription_id,customer_id)

Request example

curl https://sandbox-api.openpay.mx/v1/mzdtln0bmtms6o3kck8f/customers/ag4nktpdzebjiye1tlze/subscriptions/s0gmyor4yqtyv1miqwr0 \
   -u sk_e568c42a6c384b7ab02cd47d2e407cab:
<?
$openpay = Openpay::getInstance('moiep6umtcnanql3jrxp', 'sk_3433941e467c1055b178ce26348b0fac');

$customer = $openpay->customers->get('a9ualumwnrcxkl42l6mh');
$subscription = $customer->subscriptions->get('s7ri24srbldoqqlfo4vp');
?>
OpenpayAPI api = new OpenpayAPI("https://sandbox-api.openpay.mx", "sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
Subscription subscription = api.subscriptions().get("a9pvykxz4g5rg0fplze0", "s0gmyor4yqtyv1miqwr0");
OpenpayAPI api = new OpenpayAPI("sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
Subscription subscription = api.SubscriptionService.Get("a9pvykxz4g5rg0fplze0", "s0gmyor4yqtyv1miqwr0");
openpay.customers.subscriptions.get('ag4nktpdzebjiye1tlze', 's0gmyor4yqtyv1miqwr0', function(error, subscription){
  // ...
});
@openpay=OpenpayApi.new("mzdtln0bmtms6o3kck8f","sk_e568c42a6c384b7ab02cd47d2e407cab")
@subscriptions=@openpay.create(:subscriptions)

response_hash=@subscriptions.get("s0gmyor4yqtyv1miqwr0", "pbi4kb8hpb64x0uud2eb")

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

Property Description
id string (required, length = 45)
Subscription identifier.

Response

Returns a subscription object.

Cancel a Subscription

Definition

DELETE https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/customers/{CUSTOMER_ID}/subscriptions/{SUBSCRIPTION_ID}
<?
$customer = $openpay->customers->get(customerId);
$subscription = $customer->subscriptions->get(subscriptionId);
$subscription->delete();
?>
openpayAPI.subscriptions().delete(String customerId, String subscriptionId);
openpayAPI.SubscriptionService.Delete(string customer_id, string subscription_id);
openpay.customers.subscriptions.delete(customerId, subscriptionId, callback);
#Customer
@subscriptions=@openpay.create(:subscriptions)
@subscriptions.delete(subscription_id, customer_id)

Request example

curl https://sandbox-api.openpay.mx/v1/mzdtln0bmtms6o3kck8f/customers/ag4nktpdzebjiye1tlze/subscriptions/s0gmyor4yqtyv1miqwr0 \
   -u sk_e568c42a6c384b7ab02cd47d2e407cab: \
   -X DELETE
<?
$openpay = Openpay::getInstance('moiep6umtcnanql3jrxp', 'sk_3433941e467c1055b178ce26348b0fac');

$customer = $openpay->customers->get('a9ualumwnrcxkl42l6mh');
$subscription = $customer->subscriptions->get('s7ri24srbldoqqlfo4vp');
$subscription->delete();
?>
OpenpayAPI api = new OpenpayAPI("https://sandbox-api.openpay.mx", "sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
api.subscriptions().delete("a9pvykxz4g5rg0fplze0", "s0gmyor4yqtyv1miqwr0");
OpenpayAPI api = new OpenpayAPI("sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
api.SubscriptionService.Delete("a9pvykxz4g5rg0fplze0", "s0gmyor4yqtyv1miqwr0");
openpay.customers.subscriptions.delete('ag4nktpdzebjiye1tlze', 's0gmyor4yqtyv1miqwr0', function(error){
  // ...
});
@openpay=OpenpayApi.new("mzdtln0bmtms6o3kck8f","sk_e568c42a6c384b7ab02cd47d2e407cab")
@subscriptions=@openpay.create(:subscriptions)

@subscriptions.detele("s0gmyor4yqtyv1miqwr0", "pbi4kb8hpb64x0uud2eb")

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

Request

Property Description
id string (required, length = 45)
Subscription identifier to cancel.

Response

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

Subscription list

Definition

GET https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/customers/{CUSTOMER_ID}/subscriptions
<?
$customer = $openpay->customers->get(customerId);
$subscriptionList = $customer->subscriptions->getList(findDataRequest);
?>
openpayAPI.subscriptions().list(String customerId, SearchParams request);
openpayAPI.SubscriptionService.List(string customer_id, SearchParams request = null);
openpay.customers.subscriptions.list(customerId, callback);
openpay.customers.subscriptions.list(customerId, searchParams, callback);
#Customer
@subscriptions=@openpay.create(:subscriptions)
@subscriptions.all(customer_id)

Request example

curl -g "https://sandbox-api.openpay.mx/v1/mzdtln0bmtms6o3kck8f/customers/ag4nktpdzebjiye1tlze/subscriptions?limit=10" \
   -u sk_e568c42a6c384b7ab02cd47d2e407cab: 
<?
$openpay = Openpay::getInstance('moiep6umtcnanql3jrxp', 'sk_3433941e467c1055b178ce26348b0fac');

$findData = array(
    'creation[gte]' => '2013-01-01',
    'creation[lte]' => '2013-12-31',
    'offset' => 0,
    'limit' => 5);

$customer = $openpay->customers->get('a9ualumwnrcxkl42l6mh');
$subscriptionList = $customer->subscriptions->getList($findData);
?>
final Calendar dateGte = Calendar.getInstance();
final Calendar dateLte = Calendar.getInstance();
dateGte.set(2014, 5, 1, 0, 0, 0);
dateLte.set(2014, 5, 15, 0, 0, 0);

OpenpayAPI api = new OpenpayAPI("https://sandbox-api.openpay.mx", "sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
SearchParams request = new SearchParams();
request.creationGte(dateGte.getTime());
request.creationLte(dateLte.getTime());
request.offset(0);
request.limit(100);

List<Subscription> subscriptions = api.subscriptions().list("a9pvykxz4g5rg0fplze0", request);
OpenpayAPI api = new OpenpayAPI("sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
SearchParams request = new SearchParams();
request.CreationGte = new Datetime(2014, 5, 1);
request.CreationLte = new DateTime(2014, 5, 15);
request.Offset = 0;
request.Limit = 100;

List<Subscription> subscriptions = api.SubscriptionService.List("a9pvykxz4g5rg0fplze0", request);
var searchParams = {
  'limit' : 2
};

openpay.customers.subscriptions.list('ag4nktpdzebjiye1tlze', searchParams, function(error, list){
  // ...
});
@openpay=OpenpayApi.new("mzdtln0bmtms6o3kck8f","sk_e568c42a6c384b7ab02cd47d2e407cab")
@subscriptions=@openpay.create(:subscriptions)

@subscriptions.all("pbi4kb8hpb64x0uud2eb")

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:

Property Descriptions
creation date
Same as creation date: Format: yyyy-mm-dd.
creation[gte] date
After the creation date. Format: yyyy-mm-dd.
creation[lte] date
Before the creation date. Format: yyyy-mm-dd.
offset numeric
Number of records to skip from the beggining, by default is 0.
limit numeric
Number of records to return, by default is 10.

Response

A 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
<?
$fee = $openpay->fees->create(feeDataRequest);
?>
openpayAPI.fees().create(CreateFeeParams request);
openpayAPI.FeeService.Create(FeeRequest request);
openpay.fees.create(feeRequest, callback);
#Customer
@fees=@openpay.create(:fees)
@fees.create(request_hash)

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"
}' 
<?
$openpay = Openpay::getInstance('moiep6umtcnanql3jrxp', 'sk_3433941e467c1055b178ce26348b0fac');

$feeDataRequest = array(
    'customer_id' => 'a9ualumwnrcxkl42l6mh',
    'amount' => 12.50,
    'description' => 'Cobro de Comisión',
    'order_id' => 'ORDEN-00063');

$fee = $openpay->fees->create($feeDataRequest);
?>
OpenpayAPI api = new OpenpayAPI("https://sandbox-api.openpay.mx", "sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
CreateFeeParams request = new CreateFeeParams();
request.customerId("a9pvykxz4g5rg0fplze0");
request.amount(new BigDecimal("100.00"));
request.description("Cobro de comisión");
request.orderId("oid-1245");

Fee fee = api.fees().create(request);
OpenpayAPI api = new OpenpayAPI("sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
FeeRequest request = new FeeRequest();
request.CustomerId = "a9pvykxz4g5rg0fplze0";
request.Amount = new Decimal(100.00);
request.Description = "Cobro de comisión";
request.OrderId = "oid-1245;

Fee fee = api.FeeService.Create(request);
var feeRequest = {                                            
     'customer_id' : 'dvocf97jd20es3tw5laz',
     'amount' : 12.50,          
     'description' : 'Cobro de Comisión',
     'order_id' : 'oid-1245'
};

openpay.fees.create(feeRequest, function(error, fee){
  // ...
});
@openpay=OpenpayApi.new("mzdtln0bmtms6o3kck8f","sk_e568c42a6c384b7ab02cd47d2e407cab")
@fees=@openpay.create(:fees)
request_hash={
     "customer_id" => "dvocf97jd20es3tw5laz",
     "amount" => 12.50,
     "description" => "Cobro de Comisión",
     "order_id" => "oid-1245"
   }

response_hash=@fees.create(request_hash.to_hash)

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

Property Description
customer_id string (required, length = 45)
The unique identifier of the customer that you want to charge the fee.
amount numeric (required)
Charge amount. It needs to be more than zero, it can have up to two decimal places.
description string (required, length = 250)
A description associated with the fee charge.
order_id string (optional, length = 100)
Unique fee identifier. It has to be unique among all the transactions.

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
<?
$fee = $openpay->fees->get(transactionId);
$fee->refund(refundData);
?>
openpayAPI.fees().refund(String transactionId, RefundParams request);
openpayAPI.FeeService.Refund(string transaction_id, RefundRequest request);
openpay.fees.refund(transactionId, feeRequest, callback);
#Customer
@fees=@openpay.create(:fees)
@fees.refund(transaction_id, refund_hash)

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" : "Fee Refund"
}' 
<?
$openpay = Openpay::getInstance('moiep6umtcnanql3jrxp', 'sk_3433941e467c1055b178ce26348b0fac');

$refundData = array(
    'description' => 'Fee Refund'
    );

$fee = $openpay->fees->get("trzjaozcik8msyqshka4");
$fee->refund($refundData);
?>
OpenpayAPI api = new OpenpayAPI("https://sandbox-api.openpay.mx", "sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
RefundParams request = new RefundParams();
request.description("Fee Refund");

Fee fee = api.fees().refund("trzjaozcik8msyqshka4", request);
OpenpayAPI api = new OpenpayAPI("sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
RefundRequest request = new RefundRequest();
request.Description = "Fee Refund";

Fee fee = api.FeeService.Refund("trzjaozcik8msyqshka4", request);
var refundRequest = {                                            
     'description' : 'Fee Refund'
};

openpay.fees.refund("trzjaozcik8msyqshka4", refundRequest, function(error, refund){
  // ...
});
@openpay=OpenpayApi.new("mzdtln0bmtms6o3kck8f","sk_e568c42a6c384b7ab02cd47d2e407cab")
@fees=@openpay.create(:fees)
refund_hash={
     "description" => "Fee Refund"
   }

response_hash=@fees.refund("mzdtln0bmtms6o3kck8f", refund_hash.to_hash)

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": "fee refund merchant03",
  "error_message": null,
  "order_id": null,
  "customer_id": "ar2btmquidjhykdaztp6",
  "amount": 11.11,
  "currency": "MXN"
}

Refund a fee to the customer account.

Request

Property Description
description string (optional, length = 250)
A description associated with the fee charge.

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
<?
$feeList = $openpay->fees->getList(findDataRequest);
?>
openpayAPI.fees().list(SearchParams request);
openpayAPI.FeeService.List(SearchParams request = null);
openpay.fees.list(callback);
openpay.fees.list(searchParams, callback);
#Customer
@fees=@openpay.create(:fees)
@fees.all

Ejemplo de petición

curl -g "https://sandbox-api.openpay.mx/v1/mzdtln0bmtms6o3kck8f/fees?limit=10" \
   -u sk_e568c42a6c384b7ab02cd47d2e407cab: 
<?
$openpay = Openpay::getInstance('moiep6umtcnanql3jrxp', 'sk_3433941e467c1055b178ce26348b0fac');

$findData = array(
    'creation[gte]' => '2013-01-01',
    'creation[lte]' => '2013-12-31',
    'offset' => 0,
    'limit' => 5);

$feeList = $openpay->fees->getList($findDataRequest);
?>
final Calendar dateGte = Calendar.getInstance();
final Calendar dateLte = Calendar.getInstance();
dateGte.set(2014, 5, 1, 0, 0, 0);
dateLte.set(2014, 5, 15, 0, 0, 0);

OpenpayAPI api = new OpenpayAPI("https://sandbox-api.openpay.mx", "sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
SearchParams request = new SearchParams();
request.creationGte(dateGte.getTime());
request.creationLte(dateLte.getTime());
request.offset(0);
request.limit(100);

List<Fee> fees = api.fees().list(request);
OpenpayAPI api = new OpenpayAPI("sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
SearchParams request = new SearchParams();
request.CreationGte = new Datetime(2014, 5, 1);
request.CreationLte = new DateTime(2014, 5, 15);
request.Offset = 0;
request.Limit = 100;

List<Fee> fees = api.FeeService.List(request);
var searchParams = {
  'limit' : 10
};

openpay.fees.list(searchParams, function(error, list){
  // ...
});
@openpay=OpenpayApi.new("mzdtln0bmtms6o3kck8f","sk_e568c42a6c384b7ab02cd47d2e407cab")
@fees=@openpay.create(:fees)

response_hash=@fees.all

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:

Property Description
creation date
Same as creation date. Format: yyyy-mm-dd
creation[gte] date
After the creation date. Format: yyyy-mm-dd
creation[lte] date
Before the creation date. Format: yyyy-mm-dd
offset numeric
Number of records to skip from the beginning, by default is 0.
limit numeric
Number of records to return, by default is 10.

Response

Returns an array of transaction object 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"
}
Property Description
id string
Unique webhook identifier number.
url string
Webhook.
user string
User name used for webhook’s basic authentication.
password string
Password for webhook’s basic authentication.
event_types array[string]
List of events where the webhook will be triggered.
status string
Webhook status, it indicates if it’s verified or not (unverified).
Event Category Description
charge.refunded Charge Reports when there is a charge refund.
charge.failed Charge Reports when a charge failed and it wasn’t applied.
charge.cancelled Charge Reports when a charge is cancelled.
charge.created Charge Reports when a charge is scheduled.
charge.succeeded Charge Reports when a charge is applied.
charge.rescored.to.decline Charge Reports when a charge’ score is recalculated and is declined.
subscription.charge.failed Subscription Reports when the charge to a subscription fails.
payout.created Payout Reports when a payout has been scheduled for the next day.
payout.succeeded Payout Reports when a payout has been applied.
payout.failed Payout Reports when a payout has failed.
transfer.succeeded Transfer Reports when a transfer has been performed between to Openpay accounts.
fee.succeeded Fee Reports when a fee is charged successfully to a customer.
fee.refund.succeeded Fee Reports when a fee has been successfully refunded to a customer.
spei.received SPEI Reports when a payout has been received by SPEI for adding funds to the account.
chargeback.created Chargeback Reports when a chargeback of a transaction was receive and a transaction has been initiated.
chargeback.rejected Chargeback Reports when a chargeback has been rejected.
chargeback.accepted Chargeback Reports when a chargeback has been accepted.
order.created Order Reports when an order is created an scheduled.
order.activated Order Reports when an order is activated.
order.payment.received Order Reports when an order is received.
order.completed Order Reports when an order is completed.
order.expired Order Reports when an order has expired.
order.cancelled Order Reports when an order is canceled.
order.payment.cancelled Order Reports when a payment order is canceled.

Webhook Creation

Definition

POST https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/webhooks
<?
$webhook = $openpay->webhooks->add(webhook);
?>
openpayAPI.webhooks().create(Webhook request);
openpayAPI.WebhooksService.Create(Webhook request);
openpay.webhooks.create(webhook, callback);
@webhooks=@openpay.create(:webhooks)
@webhooks.create(request_hash)

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"
    ]
}'
<?
$openpay = Openpay::getInstance('moiep6umtcnanql3jrxp', 'sk_3433941e467c1055b178ce26348b0fac');

$webhook = array(
    'url' => 'http://requestb.in/11vxrsf1',
    'user' => 'juanito',
    'password' => 'passjuanito',
    'event_types' => array(
      'charge.refunded',
      'charge.failed',
      'charge.cancelled',
      'charge.created',
      'chargeback.accepted'
    )
    );

$webhook = $openpay->webhooks->add($webhook);
?>
OpenpayAPI api = new OpenpayAPI("https://sandbox-api.openpay.mx", "sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
Webhook request = new Webhook();
request.url("http://requestb.in/11vxrsf1");
request.user("juanito");
request.password("passjuanito");
request.addEventType("charge.refunded");
request.addEventType("charge.failed");

Webhook webhook = api.webhooks().create(request);
OpenpayAPI api = new OpenpayAPI("sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
Webhook request = new Webhook();
request.Url = "http://requestb.in/11vxrsf1";
request.User = "juanito";
request.Password = "passjuanito";
request.AddEventType("charge.refunded");
request.AddEventType("charge.failed");

Webhook webhook = api.WebhookService.Create(request);
var webhook_params = {                                            
    'url' : 'http://requestb.in/11vxrsf1',
    'user' : 'juanito',
    'password' : 'passjuanito',
    'event_types' : [
      'charge.refunded',
      'charge.failed',
      'charge.cancelled',
      'charge.created',
      'chargeback.accepted'
    ]
};

openpay.webhooks.create(webhook_params, function(error, webhook){
  // ...
});
@openpay=OpenpayApi.new("mzdtln0bmtms6o3kck8f","sk_e568c42a6c384b7ab02cd47d2e407cab")
@webhooks=@openpay.create(:webhooks)
request_hash={
    "url" => "http://requestb.in/11vxrsf1",
    "user" => "juanito",
    "password" => "passjuanito",
    "event_types" => [
      "charge.refunded",
      "charge.failed",
      "charge.cancelled",
      "charge.created",
      "chargeback.accepted"
    ]
   }

response_hash=@webhooks.create(request_hash.to_hash)

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.

Request

Request Description
url string
Webhook URL
user string
Username for basic webhook authentication.
password string
Password for basic webhook authentication.
event_types array[string]
List of events where the webhook will be triggered.

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}
<?
$webhook = $openpay->webhooks->get(webhookId);
?>
openpayAPI.webhooks().get(String webhookId);
openpayAPI.WebhooksService.Get(string webhookId);
openpay.webhooks.get(webhookId, callback);
@webhooks=@openpay.create(:webhooks)
@webhooks.get(webhookId)

Request example

curl https://sandbox-api.openpay.mx/v1/mzdtln0bmtms6o3kck8f/webhooks/wxvanstudf4ssme8khmc \
   -u sk_e568c42a6c384b7ab02cd47d2e407cab: \
   -H "Content-type: application/json"
<?
$openpay = Openpay::getInstance('moiep6umtcnanql3jrxp', 'sk_3433941e467c1055b178ce26348b0fac');

$webhook = $openpay->webhooks->get('wxvanstudf4ssme8khmc');
?>
OpenpayAPI api = new OpenpayAPI("https://sandbox-api.openpay.mx", "sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
Webhook webhook = api.webhooks().get("wxvanstudf4ssme8khmc");
OpenpayAPI api = new OpenpayAPI("sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
Webhook webhook = api.WebhooksService.Get("wxvanstudf4ssme8khmc");
openpay.webhooks.get('wxvanstudf4ssme8khmc', function(error, webhook){
  // ...
});
@openpay=OpenpayApi.new("mzdtln0bmtms6o3kck8f","sk_e568c42a6c384b7ab02cd47d2e407cab")
@webhooks=@openpay.create(:webhooks)

response_hash=@webhooks.get("wxvanstudf4ssme8khmc")

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

Property Description
id string (required, length = 45)
Unique webhook identifier

Response

Returns a webhook object

Delete a Webhook

Definition

DELETE https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/webhooks/{WEBHOOK_ID}
<?
$webhook = $openpay->webhooks->get(webhookId);
$webhook->delete();
?>
openpayAPI.webhooks().delete(String webhookId);
openpayAPI.WebhooksService.Delete(string webhook_id);
openpay.webhooks.delete(webhookId, callback);
@webhooks=@openpay.create(:webhooks)
@webhooks.delete(webhook_id)

Customer request example

curl https://sandbox-api.openpay.mx/v1/mzdtln0bmtms6o3kck8f/webhooks/wxvanstudf4ssme8khmc \
   -u sk_e568c42a6c384b7ab02cd47d2e407cab: \
   -X DELETE
<?
$openpay = Openpay::getInstance('moiep6umtcnanql3jrxp', 'sk_3433941e467c1055b178ce26348b0fac');

$webhook = $openpay->webhooks->get('wxvanstudf4ssme8khmc');
$webhook->delete();
?>
OpenpayAPI api = new OpenpayAPI("https://sandbox-api.openpay.mx", "sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
api.webhooks().delete("wxvanstudf4ssme8khmc");
OpenpayAPI api = new OpenpayAPI("sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
api.WebhooksService.Delete("wxvanstudf4ssme8khmc");
openpay.webhooks.delete('wxvanstudf4ssme8khmc', function(error) {
  // ...
});
@openpay=OpenpayApi.new("mzdtln0bmtms6o3kck8f","sk_e568c42a6c384b7ab02cd47d2e407cab")
@webhooks=@openpay.create(:webhooks)

response_hash=@webhooks.delete("wxvanstudf4ssme8khmc")

Delete a webhook from the merchant.

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

Request

Property Description
id string (required, length = 45)
Webhook unique identifier.

Response

If the webhook was deleted correctly the response will be empty, if the webhook cannot be deleted an error object will be returned including the error message.

Webhook list

Definition

GET https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/webhooks
<?
$webhookList = $openpay->webhooks->getList();
?>
openpayAPI.webhooks().list();
openpayAPI.WebhooksService.List();
openpay.webhooks.list(callback);
@webhooks=@openpay.create(:webhooks)
@webhooks.all

Request example

curl https://sandbox-api.openpay.mx/v1/mzdtln0bmtms6o3kck8f/webhooks \
   -u sk_e568c42a6c384b7ab02cd47d2e407cab: \
   -H "Content-type: application/json"
<?
$openpay = Openpay::getInstance('moiep6umtcnanql3jrxp', 'sk_3433941e467c1055b178ce26348b0fac');

$webhookList = $openpay->webhooks->getList();
?>
OpenpayAPI api = new OpenpayAPI("https://sandbox-api.openpay.mx", "sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
List<Webhook> webhooks = api.webhooks().list();
OpenpayAPI api = new OpenpayAPI("sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
List<Webhook> webhooks = api.WebhooksService.List();
openpay.webhooks.list(function(error, list){
  // ...
});
@openpay=OpenpayApi.new("mzdtln0bmtms6o3kck8f","sk_e568c42a6c384b7ab02cd47d2e407cab")
@webhooks=@openpay.create(:webhooks)

response_hash=@webhooks.all

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 objects 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

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
    }
}
Property Description
id string
Token identifier. This is the ID that you should use to perform operations.
card object
Card associated with the token. See card object.

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

Property Description
holder_name string (required)
Account holder name.
card_number numeric (required)
Card number between 16 to 19 digits.
cvv2 numeric (required)
Security code like it appears in the back of the card. Generally 3 digits.
expiration_month numeric (required)
Expiration month, like it appears in the card.
expiration_year numeric (required)
Expiration year, like it appears in the card.
address object (optional)
Invoice address of the card owner.

Response

Returs the created token object or an error response if an error ocurred 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

Property Description
id string (required, length = 45)
Token ID

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" 
} 
Property Description
id string
Unique identifier assigned on creation.
creation_date datetime
Transaction creation date in ISO 8601 format.
name string
Registered merchant name.
email string
Email account registered for the merchant.
phone string
Phone number registered for the merchant.
status string
Merchant account status, it can be active or deleted. If the account is in deletate status no transactions are allowed.
balance numeric
Balance in the account with two decimal placess.
clabe numeric
Linked CLABE account where funds can be received from any bank in Mexico using SPEI.

Request a Merchant Object

Definition

GET https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}
<?
// =============================
// Not yet implemented.
// =============================
?>
openpayAPI.merchant().get();

// =============================
// Not yet implemented.
// =============================
openpay.merchant.get(callback);

Ruby

# =============================
# Not yet implemented.
# =============================

Request example:

curl https://sandbox-api.openpay.mx/v1/mzdtln0bmtms6o3kck8f \
   -u sk_e568c42a6c384b7ab02cd47d2e407cab:
OpenpayAPI api = new OpenpayAPI("https://sandbox-api.openpay.mx", "sk_b05586ec98454522ac7d4ccdcaec9128", "maonhzpqm8xp2ydssovf");
Merchant merchant = api.merchant().get();
openpay.merchant.get(function(error, merchant){
  // ...
});

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

Property Description
id string (required, longitude = 45)
unique merchant identifier.

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
    }
  }
Property Description
id_store string
Unique identifier assigned at the time of its creation.
id string
nique identifier by chain.
name datetime
Store name.
last_update string
Last date of update in format ISO 8601.
geolocation oject
Store geographical representation by coordinates, latitude and longitude.
address object
Store address.
paynet_chain object
Paynet chain to which it belongs.

Get list of shops by location

Definition

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

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.

Resquest

Property Description
latitud numeric (required)
Latitude of geographical location Store
longitud numeric (required)
Longitud of geographical location Store
kilometers numeric (required)
Radius distance in kilometers search
amount numeric (required)
Purchase amount

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":"Winning payments",
   "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"
   }
}
Property Description
id string
Unique identifier assigned by Openpay at the moment of creation.
authorization string
Authorization number created by the processor entity.
transaction_type string
Transaction type: fee, charge, payout, transfer.
operation_type string
Operation type in the account: in, out.
method string
Transaction method type: card, bank o customer.
creation_date datetime
Transaction creation date in ISO 8601 format.
order_id string
Unique transaction and reference number.
status string
Current transaction status. Possible values: completed, in_progress, failed.
amount numeric
Transaction full amount, including two decimal places.
description string
Transaction description.
error_message string
If the transaction is in failed status, this field will include the error message.
customer_id string
Unique identifier for the customer who this transaction belongs. If the value is null the transaction belongs to Merchant account.
currency string
Currency used in the operation by default is MXN (Mexican pesos).
bank_account object
Bank account data used for the transaction. See the BankAccount object.
card object
Credit card data used in the transaction. See the Card object.
card_points object
Contains information about the reward points used for payment, if they were used. See the CardPoints object

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" 
}
Property Description
line1 string (required)
The first line is the card owner address. It’s commonly used to indicate street address and number.
line2 string
Second addres line, commonly use to indicate interior number, suite number or county.
line3 string
Third address line, commonly use to to indicate the neighborhood.
postal_code string (required)
Zip code
state string (required)
State
city string (required)
City
country_code string (required)
Country code, in the two character format: ISO_3166-1.

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"
}
Property Description
reference string
Payment reference to go stores and make deposits to Openpay account
barcode_url string
It is the url that generates the bar code of reference.
paybin_reference string
Paybin reference to go store and make deposits to Openpay
barcode_paybin_url string
It is the url that generates the bar code of paybin reference.

PaymentPlan Object

Object example:

{
   "payments":"6"
}
Property Description
payments numeric
Plan data months without interest is desired as use in the charge (3, 6, 9, 12, 18).

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
}
Property Description
used numeric
Amount of points used in the payment.
remaining numeric
Amount of points remaining in the card after the payment.
amount numeric
Transaction amount paid using points.
caption string (opcional)
A message to be shown to the customer in their ticket or receipt.

Object Geolocation

Object example:

{
  "lng": -100.421865,
  "lat": 20.618171,
  "place_id": "ChIJwSN2wpNa04URsDryLW517lg"
}
Property Description
lng numeric
Longitud, geographical coordinate.
lat numeric
Latitud, geographical coordinate.
place_id string
Unique identifier of google maps

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
}
Property Description
name string
Chain name.
logo string
URL logo image chain.
thumb string
URL thumbnail image chain.
max_amount numeric
Maximum payment amount that accept chain stores

Object Transaction Status

Value Description
IN_PROGRESS Transaction is in progress
COMPLETED Transaction was succesfully completed
REFUNDED Transaction that has been refunded
CHARGEBACK_PENDING Transaction that has a pending chargeback
CHARGEBACK_ACCEPTED Transaction that has an accepted chargeback
CHARGEBACK_ADJUSTMENT Transaction that has an ajust for chargeback
CHARGE_PENDING Transaction that is waiting to be paid
CANCELLED Transaction that was not paid and has been cancelled
FAILED Transaction that was paid but ocurred an error

Electronic Invoice

Generation of CFDI Object

Field Description
openpay_transaction_id Optional
Id of the transaction in openpay
invoice_id Required
Invoice identifier / trade purchase order
tipo_comprobante Optional (default (I) income)
Voucher Type Object.
serie Optional (1-25 Alphanumeric)
series invoice in case of handling
folio Optional payment (1-40 Alphanumeric)
Folio of the invoice in case of handling
total Required (Decimal)
Total invoice
subtotal Required (Decimal)
Subtotal of the invoice
forma_pago Required
Way to pay
Only the payment code corresponding to the payment method must be sent.
Form of Payment Object.
metodo_pago Required
Payment method
Payment Method Object.
lugar_expedicion Required (5 digits)
Postal Code of the Place of Expedition
descuento Optional (Decimal)
Discount amount.
observaciones Optional (Alphanumeric)
Observations
total_trasladados Optional (Decimal)
Total taxes transferred if they exist
total_retenidos Optional (Decimal)
Total taxes withheld if there are
moneda Required (3 Alphanumeric)
Currency in which the sale was made in case it is different from MXN. (ISO 4217)
tipo_de_cambio Required (Decimal)
Exchange rate of the currency in which the sale was made. 1.00 in case the currency is MXN.
receptor Required (Receiver Object)
Node that contains the data of the recipient of the invoice
conceptos Required (Arrangement of Concept Object)
Arrangement of concepts included in the invoice
cfdi_relacionados Optional (Related Object)
Related invoices
complements Optional (Complements Object)
Complements

Voucher Type Object

Tax receipt type Fiscal Document
(I) entry
  • Invoice.
  • Fee.
  • Charge note.
  • Donations.
  • Lease.
  • (E) egress
  • Credit note.
  • Note of refund.
  • paysheet.
  • Assimilables.
  • (T) transfer
  • Letter porte.
  • (N) paysheet
  • paysheet.
  • (P) Payment
  • Payment.
  • Form of Payment Object

    Key Description
    01 Cash.
    02 Cheque nominative.
    03 Electronic funds transfer.
    04 Credit card.
    05 Electronic Wallet.
    06 Electronic Money.
    08 Pantry vouchers.
    12 Dation in payment.
    13 Payment by subrogation.
    14 Payment by consignment.
    15 Condonation.
    17 Compensation.
    23 Novation.
    24 Confusion.
    25 Debt remittance.
    26 Prescription or expiration.
    27 To the satisfaction of the creditor.
    28 Debit Card.
    29 Service Card.
    30 Application of advances.
    99 Others.

    Payment Method Object

    Key Description
    PUE Payment only exhibition
    PPD Partial or deferred payments

    DoctoRelacionado Object

    Key Description
    id_documento Required (16-36 Alphanumeric)
    Document identifier (uuid).
    serie Optional (1-25 Alphanumeric)
    Document series.
    folio Optional (1-40 Alphanumeric)
    Folio of the document.
    moneda_d_r Required (3 Alphabetical)
    Currency Code (ISO 4217).
    tipo_cambio_d_r Optional (Decimal)
    Exchange rate.
    metodo_de_pago_d_r Optional
    Payment method.
    num_parcialidad Optional
    Partiality number.
    imp_saldo_ant Optional (Decimal)
    Amount of the previous balance.
    imp_pagado Optional (Decimal)
    Amount paid.
    imp_saldo_insoluto Optional (Decimal)
    Amount of the outstanding balance.

    Concept Object

    Key Description
    Identificador Required (1-100 Alphanumeric)
    Concept identifier.
    cantidad Required (Decimal)
    Amount of the concept.
    unidad Optional (1-20 Alphanumeric)
    Unit of the concept.
    clave_unidad Required (Alphanumeric, Key Unit Catalog)
    Unit key.
    descripcion Required (1-1000 Alphanumeric)
    Description of the concept.
    valor_unitario Required (Decimal)
    Unit value of the concept.
    importe Required (Decimal)
    Amount of the transferred tax.
    clave Required (1-10 Numérico)
    Key of the product.
    descuento Optional (Decimal)
    Discount amount.
    traslados Optional (Arrangement Tax Object)
    Transfer tax list.
    retenciones Optional (Arrangement Tax Object)
    Retention tax list.

    Tax Object

    Key Description
    impuesto Required
    Tax
    Tax Type Object.
    tipo_factor Required
    Type of factor

    Codes:
  • Rate
  • Quota
  • Exempt
  • tasa Required
    Decimal
    Rate that will be used to calculate the tax
    importe Required
    Tax amount calculated
    base Optional
    Amount on which the Tax will be applied

    Tax Type Object

    Code Description
    001 ISR
    002 IVA
    003 IEPS

    Receiver Object

    Field Description
    nombre Required (1-254 Alphanumeric)
    Name of the recipient of the invoice.
    rfc Required
    RFC of the invoice recipient.
    email Optional
    Invoice recipient’s email.
    residencia_fiscal Optional
    Postal code of the fiscal residence.
    uso_cfdi Required (3 Alphanumeric)
    Object Use of CFDI.
    pais Optional (3 Alphanumeric)
    Country code (ISO 3166-1 alpha-3). It should not be sent if the RFC is registered with the SAT or is a national generic RFC.

    Use of CFDI Object

    Code Description
    G01 Acquisition of merchandise.
    G02 Returns, discounts or bonuses.
    G03 Expenses in general.
    I01 Buildings.
    I02 Office furniture and equipment for investments.
    I03 Transportation equipment.
    I04 Computer equipment and accessories.
    I05 Dices, dies, molds, matrices and tooling.
    I06 Telephone communications.
    I07 Satellite communications.
    I08 Other machinery and equipment.
    D01 Medical and dental fees and hospital expenses.
    D02 Medical expenses due to disability or disability.
    D03 Funeral expenses.
    D04 Donations.
    D05 Real interest actually paid for mortgage credits (house room).
    D06 Voluntary contributions to SAR.
    D07 Premiums for medical expenses insurance.
    D08 Mandatory school transportation expenses.
    D09 Deposits in accounts for savings, premiums based on pension plans.
    D10 Payments for educational services (tuition fees).
    P01 To define.
    Field Description
    tipo_relacion Required
    Type relationship
    Object Type of Relationship.
    relacionados Required (Object arrangement CfdiRelacionado) CFDI Object Related.

    Type of Relationship Object

    Code Description
    01 Credit note of related documents.
    02 Debit note of related documents.
    03 Return of merchandise on previous invoices or transfers.
    04 Replacement of previous CFDIs.
    05 Goods transfers previously invoiced.
    06 Invoice generated by previous transfers.
    07 CFDI by advance payment.
    Field Description
    uuid Required (36 Alphanumeric)
    UUID of the related invoice

    Complements Object

    Field Description
    aerolineas Optional (Object Complement Airlines)
    Complement for Airline.
    pagos Optional (Object Complement Payment)
    Complement of payments.
    donatarias Optional (Object Complement Donee)
    Complement of donee.

    Complement Airlines Object

    Field Description
    tua Required (Decimal)
    Airport use fee
    otrosCargos Optional (Arrangement of Charge Airlines Object)
    Complement of payments.

    Charge Airlines Object

    Field Description
    codigo_cargo Optional
    Charge code.
    descripcion_cargo Optional
    Charge description.
    importe Optional (Decimal)
    Charge amount.

    Complement Payment Object

    Field Description
    fecha_pago Required
    Date of the operation.
    forma_de_pago Required
    Way to pay.
    moneda_p Required (Decimal)
    Amount of the charge.
    tipo_cambio_p Required (Decimal)
    Exchange rate of the currency in which the sale was made. 1.00 in case the currency is MXN.
    monto Required (Decimal)
    Payment amount.
    num_operacion Optional (1-100 Alphanumeric)
    Payment number.
    rfc_emisor_cta_ord Optional
    RFC of the issuer.
    nom_banco_ord_ext Optional (1-300 Alphanumeric)
    Name of the bank.
    cta_ordenante Optional (10-50 Alphanumeric)
    Ordering account.
    rfc_emisor_cta_ben Beneficiary.
    cta_beneficiario Optional (10-50 Alphanumeric)
    Beneficiary account.
    tipo_cad_pago Optional (único valor válido 01)
    Type of payment chain.
    cert_pago Optional (byte[])
    Payment certificate.
    sello_pago Optional (byte[])
    Payment stamp.
    cad_pago Optional (1-8192 Alphanumeric)
    Chain.
    docto_relacionados Optional (Arrangement DoctoRelacionado Object).

    Complement Donee Object

    Field Description
    no_autorizacion Required
    Authorization number
    fecha_autorizacion Required
    Authorization date (YYYY-MM-DD)
    leyenda Required
    Caption

    Request Response Generation Object

    Field Description
    invoice_id Identifier of the invoice sent in the request.
    request_id Request ID generated by Openpay.
    date Date on which the generation was requested
    status PENDING, OK, ERROR.
    fiscal_status ACTIVE, CANCELLED.
    message Status description.

    Notifications Object

    Field Description
    invoice_id Identifier of the invoice sent in the request.
    serie Invoice series.
    folio Folio of the invoice.
    transaction_id Openpay transaction identifier linked to the invoice.
    creation_date Application date.
    issue_date Issue date of the invoice.
    uuid UUID of the invoice.
    receiver_rfc RFC of the invoice recipient.
    total Total invoice.
    subtotal Subtotal of the invoice.
    status PENDING, OK, ERROR.
    fiscal_status ACTIVE, CANCELLED.
    cancellation_date Date of cancellation of the invoice in case it is canceled.
    public_xml_link Link to download the XML of the invoice.
    public_pdf_link Link to download the PDF of the invoice.
    link_expiration_date Expiration of the download leagues, once expired the xml / pdf can be downloaded from the dashboard.
    message Detail of the status of the invoice.