Introduction
This document contains the API definition to be used by Radixx and Sky for their Sky integration.
Direct card charge (Transbank “Transacción Completa” and GlobalCollect)
Create a new Token
You can follow this link for the API documentation on creating tokens. You can also see how to use the Openpay Javascript library to create tokens here.
For Global Collect Risk Assessment, please send the billing address with the Card information, and use the following fields for the required data:
Property | Description |
---|---|
line1 | string (required, length = 50) Use this field to send the Billing Address’ Street. |
line2 | string (required, length = 15) Use this field to send the Billing Address’ House number. |
line3 | string (optionalm length = 50) This field is optional and can be used for any extra address information, such as apartment number. |
postal_code | string (required, length = 10, use “00000” if not available) Postal Code |
state | string (length = 35, use “N/A” if not available) State |
city | string (length = 40) City |
country_code | string (length = 10) Country code in ISO 3166-1 alpha-2 format |
Retrieve Transbank “Shares” (Installments)
This is used to allow the customer to pay using installments. Openpay will return an array with the available installments of the ones requested. Unavailable installments won’t appear in this array.
This step is optional, and should only be called when using Transbank.
Definition
POST /v1/{merchantId}/tokens/{tokenId}/shares
or
POST /v1/{merchantId}/cards/{cardId}/shares
Request example
{
"amount": "6000",
"currency" : "CLP"
"shares": [3, 6, 9, 12]
}
Response example
{
"amount" : "6000",
"currency" : "CLP",
"available" : [
{
"share_id": "1234",
"shares" : "3",
"share_amount": "2000"
},
{
"share_id": "5678",
"shares" : "6",
"share_amount": "1000"
},
{
"share_id": "9012",
"shares" : "9",
"share_amount": "677"
},
{
"share_id": "3456",
"shares" : "12",
"share_amount": "510",
"deferred" : [
{
"months" : 1,
"amount" : 511.00
},
{
"months" : 2,
"amount" : 512.00
}
]
}
]
}
Request
Property | Description |
---|---|
amount | numeric (required) The total amount of the transaction. |
currency | string (required, length = 3) The currency of the charge. It must be either “CLP” or “USD”. |
shares | numeric array (required) Number of installments to search for. |
Response
Returns a Shares object with the installment information, or an error response.
Shares object
Object Example
{
"amount" : "6000",
"currency" : "CLP",
"available" : [
{
"share_id": "1234",
"shares" : 3,
"share_amount": 2000.00
},
{
"share_id": "5678",
"shares" : 6,
"share_amount": 1000.00
},
{
"share_id": "9012",
"shares" : 9,
"share_amount": 677.00
},
{
"share_id": "3456",
"shares" : 12,
"share_amount": 510.00,
"deferred" : [
{
"months" : 1,
"amount" : 511.00
},
{
"months" : 2,
"amount" : 512.00
}
]
}
]
}
Property | Description |
---|---|
amount | numeric The total transaction amount. |
currency | string The currency of the payment to make. |
available | array of Share objects Information of the available installments. |
Share object
Object Example
{
"share_id": "1234",
"shares" : 15,
"share_amount": 2000.00,
"deferred" : [
{
"months" : 1,
"amount" : 2001.00
},
{
"months" : 2,
"amount" : 2002.00
}
]
}
Property | Description |
---|---|
share_id | String Contains the Share ID returned by Transbank needed to use this number of installments. It is required to complete a charge with installments. |
shares | numeric Number of installments requested. |
share_amount | numeric The amount that the customer will pay each month according to Transbank. |
deferred | Array of Deferred Share objects Available shares to defer payment by 1, 2, or 3 months. Only included when the share allows deferring payments. |
Deferred Share object
Object Example
{
"months": 1,
"amount" : 2001.00
}
Property | Description |
---|---|
months | numeric The number of months that the payment can be deferred. |
amount | numeric The amount that the customer will pay each month if they choose to defer the payment. |
Charge a card
Definition
POST /v1/{MERCHANT_ID}/charges
Request example
{
"source_id": "kvnqhttcsw86tqqdqg1u",
"method": "card",
"amount": 6000,
"currency": "CLP",
"provider": {
"data": {
"share_id": "1234",
"point_of_sale" : "web_retail"
}
},
"description": "B4JOW2 Origin-Destination 2016-04-01 32:34",
"order_id": "B4JOW2-20160401-1205",
"customer": {
"name": "Juan",
"last_name": "Vazquez Juarez",
"phone_number": "1234567890",
"email": "juan.vazquez@empresa.com.mx"
},
"gc_risk_assessment": {
"airline_data": {
"airline_code": "123",
"airline_name": "Sky",
"passenger_name": "Juan Vazquez Juarez",
"pnr": "4FW1O2",
"flight_date": "2016-02-01",
"agency_number": 12345678,
"flight_legs": [
{
"carrier_code": "12",
"airline_class": "1",
"origin": "ABC",
"destination": "DEF",
"departure_date": "2015-01-01",
"departure_time": "12:55",
"flight_number": 123,
"fare": "FARE",
"fare_basis": "FAREBASIS",
"allow_stopover": true
}
],
"is_third_party": false,
"ticket_number": "1231212345678",
"ticket_issue_date": "2016-02-01",
"is_eticket": false,
"is_restricted_ticket": true,
"ticket_delivery_method": "eticket",
"airline_customer_id": "123456",
"is_registered_customer": false,
"airline_invoice_number": "123123"
},
"metadata": {
"reservation_number": "123456"
}
}
}
Response example
{
"id": "trornwo9ocwkqjljx90h",
"authorization": "1213",
"method": "card",
"operation_type": "in",
"transaction_type": "charge",
"card": {
"type": "unknown",
"brand": "visa",
"address": {
"line1": "Street",
"line2": "House Number",
"line3": null,
"state": "State",
"city": "City",
"postal_code": "76000",
"country_code": "CL"
},
"card_number": "405188XXXXXX6623",
"holder_name": "Juan Vazquez Juarez",
"expiration_year": "20",
"expiration_month": "12",
"allows_charges": true,
"allows_payouts": false,
"bank_name": null,
"bank_code": "000"
},
"metadata": {
"reservation_number": "123456",
"transbank_buy_order": "kvnqhttcsw86tqqdqg1u",
"shares": "3",
"share_amount": "2000"
},
"status": "completed",
"conciliated": false,
"creation_date": "2016-05-02T16:20:44-05:00",
"operation_date": "2016-05-02T16:10:52-05:00",
"description": "B4JOW2 Origin-Destination 2016-04-01 32:34",
"error_message": null,
"order_id": "B4JOW2-20160401-1205",
"amount": 6000,
"currency": "CLP"
}
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. |
amount | numeric (required) Amount to charge. Must be an amount greater than zero, with up to two decimal digits. |
currency | String (required, length = 3) Currency to use. For Sky it can be either CLP or USD. |
provider | Object (required) Provider to use in order to charge the card. For direct payments, it must be a Direct charge provider object. |
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 successful transactions. |
customer | object (required) Information of the customer. |
gc_risk_assessment | Object (required) Information required to use Global Collect’s risk assessment. See Global Collect Risk Assessment object. |
metadata | list(key, value) (optional) Custom information about the transaction that can be stored. |
Response
Returns a transaction object with the charge information or with an error response.
Charges with Adyen
Response Example
{
"id": "trmddmg5v7byklp4ddgb",
"authorization": "73708",
"method": "card",
"operation_type": "in",
"transaction_type": "charge",
"card": {
"type": "debit",
"brand": "mastercard",
"address": {
"line1": "Hidalgo St.",
"line2": "120",
"line3": "apt. 23",
"state": "Queretaro",
"city": "Queretaro",
"postal_code": "76000",
"country_code": "GB"
},
"card_number": "555555XXXXXX4444",
"holder_name": "Eli Lopez",
"expiration_year": "18",
"expiration_month": "08",
"allows_charges": true,
"allows_payouts": false,
"bank_name": null,
"points_type": "santander",
"bank_code": "000",
"points_card": true
},
"status": "pending_confirmation",
"conciliated": false,
"creation_date": "2016-07-15T09:47:19-05:00",
"operation_date": "2016-07-15T09:47:23-05:00",
"description": "B4JOW6 ABC-DEF 2016-05-06 32:34",
"error_message": null,
"order_id": null,
"amount": 20,
"provider": {
"name": "adyen"
},
"currency": "USD",
"metadata": {
"reservation_number": "123456"
}
}
In case of using Adyen, the response for credit card payments will differ slightly.
For Adyen, charges will be created in status “pending_confirmation”. In these cases, you must wait for the webhook to confirm that the payment is done, and the user must be shown that their payment is still pending confirmation. Once the payment is confirmed, you will receive a “charge.succeeded” webhook event. If the payment fails, you will receive a “charge.failed” webhook event.
Webhook Example
{
"type": "charge.succeeded",
"event_date": "2016-07-15T09:48:30-05:00",
"transaction": {
"id": "trmddmg5v7byklp4ddgb",
"authorization": "73708",
"method": "card",
"operation_type": "in",
"transaction_type": "charge",
"card": {
"type": "debit",
"brand": "mastercard",
"address": {
"line1": "Hidalgo St.",
"line2": "120",
"line3": "apt. 23",
"state": "Queretaro",
"city": "Queretaro",
"postal_code": "76000",
"country_code": "GB"
},
"card_number": "555555XXXXXX4444",
"holder_name": "Eli Lopez",
"expiration_year": "18",
"expiration_month": "08",
"allows_charges": true,
"allows_payouts": false,
"bank_name": null,
"points_type": "santander",
"bank_code": "000",
"points_card": true
},
"status": "completed",
"conciliated": true,
"creation_date": "2016-07-15T09:47:19-05:00",
"operation_date": "2016-07-15T09:47:23-05:00",
"description": "B4JOW6 ABC-DEF 2016-05-06 32:34",
"error_message": null,
"order_id": null,
"amount": 20,
"provider": {
"name": "adyen"
},
"currency": "USD",
"metadata": {
"reservation_number": "123456"
}
}
}
Refunds in Adyen behave in a similar way. Once you request a refund, the transaction will be returned, with a “refund” field inside of it. The refund field contains the refund transaction, and in these cases it will have a status of “pending_confirmation”. Once the refund is completed, you will receive a “charge.refunded” webhook event. If the refund fails for some reason, you will get a “charge.refund.failed” event.
Refund example
{
"id": "trmddmg5v7byklp4ddgb",
"authorization": "73708",
"method": "card",
"operation_type": "in",
"transaction_type": "charge",
"card": {
"type": "debit",
"brand": "mastercard",
"address": {
"line1": "Hidalgo St.",
"line2": "120",
"line3": "apt. 23",
"state": "Queretaro",
"city": "Queretaro",
"postal_code": "76000",
"country_code": "GB"
},
"card_number": "555555XXXXXX4444",
"holder_name": "Eli Lopez",
"expiration_year": "18",
"expiration_month": "08",
"allows_charges": true,
"allows_payouts": false,
"bank_name": null,
"points_type": "santander",
"bank_code": "000",
"points_card": true
},
"status": "completed",
"refund": {
"id": "trwnq95h5kiaopqfqegt",
"authorization": "8814685940423203",
"method": "card",
"operation_type": "out",
"transaction_type": "refund",
"status": "pending_confirmation",
"conciliated": true,
"creation_date": "2016-07-15T09:52:09-05:00",
"operation_date": "2016-07-15T09:52:09-05:00",
"description": null,
"error_message": null,
"order_id": null,
"amount": 20,
"provider": {
"name": "adyen"
},
"currency": "USD"
},
"conciliated": true,
"creation_date": "2016-07-15T09:47:19-05:00",
"operation_date": "2016-07-15T09:47:23-05:00",
"description": "B4JOW6 ABC-DEF 2016-05-06 32:34",
"error_message": null,
"order_id": null,
"amount": 20,
"provider": {
"name": "adyen"
},
"currency": "USD",
"metadata": {
"reservation_number": "123456"
}
}
Refund webhook
{
"type": "charge.refunded",
"event_date": "2016-07-15T09:53:13-05:00",
"transaction": {
"id": "trmddmg5v7byklp4ddgb",
"authorization": "73708",
"method": "card",
"operation_type": "in",
"transaction_type": "charge",
"card": {
"type": "debit",
"brand": "mastercard",
"address": {
"line1": "Hidalgo St.",
"line2": "120",
"line3": "apt. 23",
"state": "Queretaro",
"city": "Queretaro",
"postal_code": "76000",
"country_code": "GB"
},
"card_number": "555555XXXXXX4444",
"holder_name": "Eli Lopez",
"expiration_year": "18",
"expiration_month": "08",
"allows_charges": true,
"allows_payouts": false,
"bank_name": null,
"points_type": "santander",
"bank_code": "000",
"points_card": true
},
"status": "completed",
"refund": {
"id": "trwnq95h5kiaopqfqegt",
"authorization": "8814685940423203",
"method": "card",
"operation_type": "out",
"transaction_type": "refund",
"card": {
"type": "debit",
"brand": "mastercard",
"address": {
"line1": "Hidalgo St.",
"line2": "120",
"line3": "apt. 23",
"state": "Queretaro",
"city": "Queretaro",
"postal_code": "76000",
"country_code": "GB"
},
"card_number": "555555XXXXXX4444",
"holder_name": "Eli Lopez",
"expiration_year": "18",
"expiration_month": "08",
"allows_charges": true,
"allows_payouts": false,
"bank_name": null,
"points_type": "santander",
"bank_code": "000",
"points_card": true
},
"status": "completed",
"conciliated": true,
"creation_date": "2016-07-15T09:52:09-05:00",
"operation_date": "2016-07-15T09:52:09-05:00",
"description": null,
"error_message": null,
"order_id": null,
"amount": 20,
"provider": {
"name": "adyen"
},
"currency": "USD"
},
"conciliated": true,
"creation_date": "2016-07-15T09:47:19-05:00",
"operation_date": "2016-07-15T09:47:23-05:00",
"description": "B4JOW6 ABC-DEF 2016-05-06 32:34",
"error_message": null,
"order_id": null,
"amount": 20,
"provider": {
"name": "adyen"
},
"currency": "USD",
"metadata": {
"reservation_number": "123456"
}
}
}
3D Secure / Fallback to Transbank Normal
3D Secure can be used if the transaction was rejected due to a risk assessment service (Error 3005). If this response is returned, you can send the same request but with the following additional parameters in the provider data:
Example Rejection by Risk Assessment
{
"category": "gateway",
"description": "The card was declined (k)",
"http_code": 402,
"error_code": 3005,
"request_id": "59898900-648a-42ba-8230-501eb40bece9"
}
Request
{
"source_id": "k570iqqwzrnxitxm4bkq",
"method": "card",
"amount": 20.00,
"currency": "USD",
"provider": {
"data": {
"point_of_sale": "web_retail",
"use_3d_secure" : true,
"url_success" : "http://www.openpay.mx",
"browser_info" : {
"accept_header" : "header",
"user_agent" : "agent"
}
}
},
"description": "B4JOW6 ABC-DEF 2016-05-06 32:34",
"customer": {
"name": "Eli",
"last_name": "Lopez",
"phone_number": "1234567890",
"email": "eli.lopez@openpay.mx"
},
"gc_risk_assessment": {
"website" : "http://www.openpay.mx",
"is_previous_customer" : false,
"customer_ip_address" : "189.204.92.250",
"airline_data": {
"airline_code": "123",
"airline_name": "Sky",
"passenger_name": "Juan Vazquez Juarez",
"pnr": "4FW1O2",
"flight_date": "2016-02-01",
"agency_number": 12345678,
"flight_legs": [
{
"carrier_code": "12",
"airline_class": "1",
"origin": "ABC",
"destination": "DEF",
"departure_date": "2015-01-01",
"departure_time": "12:55",
"flight_number": 123,
"fare": "FARE",
"fare_basis": "FAREBASIS",
"allow_stopover": true
}
],
"is_third_party": false,
"ticket_number": "1231212345678",
"ticket_issue_date": "2016-02-01",
"is_eticket": false,
"is_restricted_ticket": true,
"ticket_delivery_method": "eticket",
"airline_customer_id": "123456",
"is_registered_customer": false,
"airline_invoice_number": "123123"
}
},
"metadata": {
"reservation_number": "123456"
}
}
Response
{
"id": "trakm2jghxbhfjwzci7l",
"authorization": "000000086310000000830000100001",
"method": "card",
"operation_type": "in",
"transaction_type": "charge",
"card": {
"type": "credit",
"brand": "visa",
"address": {
"line1": "Hidalgo St.",
"line2": "120",
"line3": "apt. 23",
"state": "Queretaro",
"city": "Queretaro",
"postal_code": "76000",
"country_code": "MX"
},
"card_number": "400000XXXXXX0002",
"holder_name": "Eli Lopez",
"expiration_year": "18",
"expiration_month": "02",
"allows_charges": true,
"allows_payouts": false,
"bank_name": null,
"bank_code": "000"
},
"status": "charge_pending",
"conciliated": false,
"creation_date": "2016-07-07T13:17:56-05:00",
"operation_date": "2016-07-07T13:18:01-05:00",
"description": "B4JOW6 ABC-DEF 2016-05-06 32:34",
"error_message": null,
"order_id": null,
"amount": 20,
"currency": "USD",
"provider": {
"name": "global_collect"
},
"payment_method": {
"type": "redirect",
"url": "https://sandbox-api.openpay.mx/v1/mshqn9kihskcnz6d4k2c/charges/trakm2jghxbhfjwzci7l/redirect/"
},
"metadata": {
"reservation_number": "123456"
}
}
Property | Description |
---|---|
use_3d_secure | boolean (required) Indicates that the charge must be done using 3D secure (or Transbank Normal in case of Transbank) |
url_success | String (required, length = 255) The URL that the customer will be redirected to when the transaction is either accepted or rejected. A query string with the parameter “id” containing the Transaction ID will be added, and should be used to retrieve the transaction status from Openpay. |
browser_info | object (required) Contains information about the customer’s browser. |
browser_info > accept_header |
String (required) Accept header of the shopper’s web browser. E.g.: “text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8” |
browser_info > user_agent |
String (required) User Agent information of the shopper’s web browser. E.g.: “Mozilla/5.0 (X11; U; Linux i686; en-US; rv:1.9) Gecko/2008052912 Firefox/3.0” |
If the returned transaction has a status of charge_pending, it should be treated as a redirect transaction. If the request fails, this means that 3D secure is not available for this transaction.
Note that Maestro cards always require the use of 3D Secure.
Openpay payment webpage (Radixx)
Definition
POST /v1/{merchantId}/charges
For payments through the Radixx application, Openpay will provide a webpage where the customer can enter their card information in order to complete a payment.
Creating the charge
Request example
{
"confirm": "false",
"method": "card",
"amount": 15.00,
"currency": "USD",
"provider": {
"data": {
"point_of_sale": "web_retail",
"card_brand": "mastercard"
}
},
"order_id": "B4JOW6 Payment 1",
"description": "B4JOW6 ABC-DEF 2016-05-06 32:34",
"customer": {
"name": "Eli",
"last_name": "Lopez",
"phone_number": "1234567890",
"email": "eli.lopez@openpay.mx",
"address": {
"postal_code": "7600000",
"city": "City",
"line1": "Street",
"line2": "12",
"state": "State",
"country_code": "US"
}
},
"gc_risk_assessment": {
"website": "http://www.openpay.mx",
"is_previous_customer": false,
"airline_data": {
"airline_code": "123",
"airline_name": "Sky",
"passenger_name": "Juan Vazquez Juarez",
"pnr": "4FW1O2",
"flight_date": "2016-02-01",
"agency_number": 12345678,
"flight_legs": [
{
"carrier_code": "12",
"airline_class": "1",
"origin": "ABC",
"destination": "DEF",
"departure_date": "2015-01-01",
"departure_time": "12:55",
"flight_number": 123,
"fare": "FARE",
"fare_basis": "FAREBASIS",
"allow_stopover": true
}
],
"is_third_party": false,
"ticket_number": "1231212345678",
"ticket_issue_date": "2016-02-01",
"is_eticket": false,
"is_restricted_ticket": true,
"ticket_delivery_method": "eticket",
"airline_customer_id": "123456",
"is_registered_customer": false,
"airline_invoice_number": "123123"
}
},
"metadata": {
"reservation_number": "123456"
}
}
For this, Openpay will receive all the transaction information in a request, except for the card, and the parameter confirm set to false.
Note that, in this case, the customer billing address should be sent in the customer object.
Response example
{
"id": "trtrhonzuawsojmrovww",
"status": "charge_pending",
"method": "card",
"operation_type": "in",
"transaction_type": "charge",
"creation_date": "2016-06-01T09:48:38-05:00",
"description": "B4JOW6 ABC-DEF 2016-05-06 32:34",
"amount": 15,
"order_id": "B4JOW6 Payment 1",
"currency": "USD",
"payment_method": {
"type": "redirect",
"url": "https://dev-api.openpay.mx/v1/m71mp8sc0zih82p6jb7n/charges/trtrhonzuawsojmrovww/card_capture/"
},
"metadata": {
"reservation_number": "123456"
}
}
Openpay will return the created transaction and an URL pointing to the webpage to show to the user. This webpage will request the customer’s card information in order to complete payment.
Receiving the Webhook
Webhook example
{
"type": "charge.succeeded",
"event_date": "2016-06-01T09:49:43-05:00",
"transaction": {
"id": "trtrhonzuawsojmrovww",
"authorization": "OK2348",
"method": "card",
"operation_type": "in",
"transaction_type": "charge",
"card": {
"type": "unknown",
"brand": "mastercard",
"address": {
"postal_code": "7600000",
"city": "City",
"line1": "Street",
"line2": "12",
"state": "State",
"country_code": "US"
},
"card_number": "542418XXXXXX1732",
"holder_name": "Eli Lopez Rangel",
"expiration_year": "20",
"expiration_month": "12"
},
"status": "completed",
"conciliated": true,
"creation_date": "2016-06-01T09:48:38-05:00",
"operation_date": "2016-06-01T09:49:43-05:00",
"description": "B4JOW6 ABC-DEF 2016-05-06 32:34",
"order_id": "B4JOW6 Payment 1",
"amount": 15,
"provider": {
"name": "global_collect"
},
"currency": "USD"
},
"metadata": {
"reservation_number": "123456"
}
}
Once the payment is completed, Openpay will send a webhook to Radixx to confirm the payment. This webhook will be of type charge.succeeded if the transaction was successful, or charge.failed if the card was rejected.
Refunding a charge
Definition
POST https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/charges/{TRANSACTION_ID}/refund
Response
{
"id": "tro0b25fb39ay6kjv7dn",
"authorization": "123456",
"method": "card",
"operation_type": "in",
"transaction_type": "charge",
"card": {
"type": "credit",
"brand": "visa",
"address": {
"line1": "Hidalgo St.",
"line2": "120",
"line3": "apt. 23",
"state": "Queretaro",
"city": "Queretaro",
"postal_code": "76000",
"country_code": "MX"
},
"card_number": "426398XXXXXX9299",
"holder_name": "Eli Lopez",
"expiration_year": "18",
"expiration_month": "02",
"allows_charges": true,
"allows_payouts": false,
"bank_name": null,
"bank_code": "000"
},
"status": "completed",
"refund": {
"id": "trnyjl8e4s597lbyj9tg",
"authorization": "tro0b25fb39ay6kjv7dn",
"method": "card",
"operation_type": "out",
"transaction_type": "refund",
"status": "completed",
"conciliated": true,
"creation_date": "2016-07-07T11:39:20-05:00",
"operation_date": "2016-07-07T11:39:20-05:00",
"description": null,
"error_message": null,
"order_id": null,
"amount": 180,
"currency": "USD",
"provider": {
"name": "global_collect"
}
},
"conciliated": true,
"creation_date": "2016-07-07T11:37:49-05:00",
"operation_date": "2016-07-07T11:38:24-05:00",
"description": "B4JOW6 ABC-DEF 2016-05-06 32:34",
"error_message": null,
"order_id": null,
"amount": 180,
"currency": "USD",
"provider": {
"name": "global_collect"
},
"metadata": {
"reservation_number": "123456"
}
}
You can use this method if you want to refund a charge made with Transbank, GlobalCollect, or Adyen.
By default the amount to be returned will be the total charge, but you can specify a partial refund by sending an amount in the request. The amount must be in the same currency as the payment.
Note: You may need to wait for a day before the payment provider allows a partial refund. Payments that use Transbank installments can’t be partially refunded.
Request
Property | Description |
---|---|
description | string (optional, length = 250) Text to describe the refund reason. |
amount | decimal (optional) Amount to refund. Can’t be more than the transaction amount, and must be in the same currency. |
Response
Returns a transaction object with the refund information in the refund field, or an error response.
Redirect charge (Transbank “Transacción Normal”, Travel Club “Banco de Chile”, Khipu)
With this service a transaction will be returned, containing an URL to redirect the user to. This URL will then redirect the user to one of the above services.
Khipu Bank List
This endpoint is only required when using Khipu without redirect. It is required to retrieve the Bank ID to use in the charge.
GET /v1/{MERCHANT_ID}/providers/khipu/banks
Response
{
"banks" : [
{
"bank_id" : "Bawdf",
"name" : "DemoBank",
"min_amount" : 200.0
}
]
}
Response
Returns an object conainting a list of Khipu Banks with the list of allowed Khipu banks.
Khipu Bank object
Example Object
{
"bank_id" : "Bawdf",
"name" : "DemoBank"
}
Property | Description |
---|---|
bank_id | string Khipu Bank ID |
name | string Name of the bank to display to the user |
Creating charge
POST /v1/{MERCHANT_ID}/charges
Request
{
"method": "card",
"amount": 10000,
"currency": "CLP",
"description": "B4JOW2 Origin-Destination 2016-04-01 32:34",
"order_id": "B4JOW2-20160401-1400",
"customer": {
"name": "Eli",
"last_name": "Lopez",
"phone_number": "1234567890",
"email": "eli.lopez@openpay.mx"
},
"provider": {
"name": "transbank",
"data": {
"url_success": "http://www.skyairline.cl/payment/"
}
},
"metadata": {
"reservation_number": "123456"
}
}
Response
{
"id": "trczfzjweqvvzpoeya5d",
"method": "card",
"operation_type": "in",
"transaction_type": "charge",
"status": "charge_pending",
"creation_date": "2016-04-27T11:09:16-05:00",
"description": "B4JOW2 Origin-Destination 2016-04-01 32:34",
"due_date": "2016-04-27T11:09:21-05:00",
"order_id": "B4JOW2-20160401-1400",
"amount": 10000,
"currency": "CLP",
"provider": {
"name": "transbank"
},
"payment_method": {
"type": "redirect",
"url": "http://dev-api.openpay.mx/v1/m71mp8sc0zih82p6jb7n/charges/trczfzjweqvvzpoeya5d/redirect/"
},
"metadata": {
"reservation_number": "123456"
}
}
Request
Property | Description |
---|---|
method | string (required) 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. |
currency | String (required, length = 3) Currency to use. For Sky it can be either CLP or USD. |
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 successful transactions. |
customer | object (required) Information of the customer. |
provider | Object (required) Provider to use in order to charge the card. For redirect payments, it can be either a Transbank Provider object, a Travel Club Provider object, or a Khipu Provider object. |
metadata | list(key, value) (optional) Custom information about the transaction that can be stored. |
Note: This request does not need a source id since it doesn’t require a token.
Response
This method returns a transaction object in status “charge_pending”, containing the URL information to redirect to. Once the payment is made, this transaction will change to “completed” or “failed” and a webhook will be sent.
Redirect Payment Method
This object is returned in the field “payment_method” of the transaction when using a provider with redirect (Transbank “Transaccion Normal”, Travel Club, Khipu with redirect).
Object Example
{
"type" : "redirect",
"url" : "http://dev-api.openpay.mx/v1/m71mp8sc0zih82p6jb7n/charges/trczfzjweqvvzpoeya5d/redirect/",
"khipu_data" : {
"payment_id" : "uqqdrwodfptb",
"source_bank_name" : "Demo Bank",
"source_bank_url" : "https://www.bancodemo.com",
"destination_bank_name": "Banco Demo",
"destination_bank_url" : "https://www.bancodemo.com",
"account_identifier" : 1234567890,
"account_type" : "Cuenta corriente",
"account_holder_personal_identifier" : "76.187.287-7",
"account_holder_name" : "khipu dev a",
"account_holder_email" : "transferencias@khipu.com"
}
}
}
Property | Description |
---|---|
type | String Type of payment method. Always “redirect” in this case. |
url | String URL to redirect the user to with a GET request. |
khipu_data | object Khipu Data object containing information returned by Khipu when Khipu is the provider |
Khipu Data object
This object is returned when using Khipu as the provider.
Object Example
{
"payment_id" : "uqqdrwodfptb",
"allows_simplified" : false,
"source_bank_name" : "Demo Bank",
"source_bank_url" : "https://www.bancodemo.com",
"destination_bank_name": "Banco Demo",
"destination_bank_url" : "https://www.bancodemo.com",
"account_identifier" : 1234567890,
"account_type" : "Cuenta corriente",
"account_holder_personal_identifier" : "76.187.287-7",
"account_holder_name" : "khipu dev a",
"account_holder_email" : "transferencias@khipu.com"
}
Property | Description |
---|---|
payment_id | String Khipu payment Id for use with their browser extension. |
allows_simplified | boolean True if the payment allows simplified transaction without redirect. |
source_bank_name | String Name of the bank the user chose for payment. Only returned when request_bank_data = true. |
source_bank_url | String URL of the user’s bank’s webpage. Only returned when request_bank_data = true. |
destination_bank_name | String Name of the destination bank. Only returned when request_bank_data = true. |
destination_bank_url | String URL of the destination bank. Only returned when request_bank_data = true. |
account_identifier | String Account number that should receive the transfer. Only returned when request_bank_data = true. |
account_type | String Account type of the receiver account. Only returned when request_bank_data = true. |
account_holder_personal_identifier | String RUT of the receiver account. Only returned when request_bank_data = true. |
account_holder_name | String Name of the receiver account holder. Only returned when request_bank_data = true. |
account_holder_email | String Email of the receiver account holder. Only returned when request_bank_data = true. |
Khipu Email (Web & Radixx)
Definition
POST /v1/{merchantId}/charges
Khipu can also be used to accept a payment by sending the customer an email with an URL to a webpage where the customer can complete their payment.
Requesting payment
Request example
{
"method": "bank_account",
"amount": 1000,
"currency": "CLP",
"description": "Khipu email payment",
"order_id": "B4JOW2-20180401-1400",
"due_date" : "2016-06-01T11:23:29-05:00",
"customer": {
"name": "Eli",
"last_name": "Lopez",
"phone_number": "1234567890",
"email": "eli.lopez@openpay.mx"
},
"provider": {
"name": "khipu",
"data": {
"send_email" : true,
"url_success": "http://www.skyairline.cl/payment/"
}
},
"metadata": {
"reservation_number": "123456"
}
}
To use Khipu in this way, set the send_email field to true. The email will be sent to the one included in the request’s customer object.
You can optionally specify redirect URLs for the customer to be redirected to once they complete payment.
Response
{
"id": "trncmwqlsdtcgixq01ue",
"method": "card",
"operation_type": "in",
"transaction_type": "charge",
"status": "charge_pending",
"creation_date": "2016-06-01T10:53:29-05:00",
"description": "Khipu email payment",
"order_id": "B4JOW2-20180401-1400",
"due_date" : "2016-06-01T11:23:29-05:00",
"amount": 1000,
"currency": "CLP",
"provider": {
"name": "khipu"
},
"metadata": {
"reservation_number": "123456"
}
}
Once the transaction is created, Khipu will send an email to the customer requesting their payment through their website.
Verifying payment
Example webhook
{
"type": "charge.succeeded",
"event_date": "2016-06-01T17:46:48-05:00",
"transaction": {
"id": "trncmwqlsdtcgixq01ue",
"status": "completed",
"authorization": "80039",
"amount": 1000.00,
"currency": "CLP",
"method": "card",
"operation_type": "in",
"transaction_type": "charge",
"conciliated": true,
"creation_date": "2016-06-01T17:09:04-05:00",
"operation_date": "2016-06-01T17:26:10-05:00",
"description": "Khipu email payment",
"error_message": null,
"order_id": "L0WP34-1",
"due_date": "2016-06-01T18:46:10-05:00",
"provider": {
"name": "khipu"
},
"metadata": {
"reservation_number": "123456"
}
}
}
After the customer completes their payment and Khipu sends the confirmation to Openpay, Openpay will send a webhook of type charge.succeeded, indicating that the payment was completed.
When you receive the webhook, you must call the Openpay API to verify the status of the transaction using the Transaction ID.
Provider Objects
All provider objects contain two properties:
Property | Description |
---|---|
name | String The name of the provider to use. Can be “transbank”, “global_collect”, “travel_club”, or “khipu”. |
data | object Object with information specific to the provider. |
Direct charge provider object (GlobalCollect, Transbank Completa, Adyen)
Object Example
{
"data": {
"point_of_sale" : "web_retail",
"card_brand" : "visa",
"share_id": "1234",
"deferred_months" : 3
}
}
This provider object doesn’t require the provider name. The data element can contain the following properties:
Property | Description |
---|---|
point_of_sale | String (required) Point of sale of the transaction. Values allowed are “web_retail”, “web_empresas”, “web_agencias”, “call_center”, “ventas”, “kioskos”. |
card_brand | String (optional) Brand of the credit card. Can be “visa”, “american_express”, “mastercard”, “jcb” or “diners”.(Note: Will also allow “visa_debit”, “visa_electron”, “mastercard_debit”, and “maestro”). If not sent, Openpay will try to use the card number to identify it. |
share_id | String (optional, only with CLP and if the shares service returned installments) The Share ID of the number of installments selected by the customer when doing a direct payment. |
deferred_months | numeric (optional, only if share_id is specified and the installments allow deferred months) The number of months to defer payment selected by the customer. |
use_3d_secure | boolean (optional) Indicates that the charge must be done using 3D secure (or Transbank Normal in case of Transbank) |
url_success | String (required if use_3d_secure = true, length = 255) The URL that the customer will be redirected to when the transaction is accepted or rejected. A query string with the parameter “id” containing the Transaction ID will be added, and should be used to retrieve the transaction status from Openpay. |
browser_info | object (required if use_3d_secure = true) Contains information about the customer’s browser. |
browser_info > accept_header |
String (required if use_3d_secure = true) Accept header of the customer’s web browser. E.g.: “text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8” |
browser_info > user_agent |
String (required if use_3d_secure = true) User Agent information of the customer’s web browser. E.g.: “Mozilla/5.0 (X11; U; Linux i686; en-US; rv:1.9) Gecko/2008052912 Firefox/3.0” |
Transbank Provider object (Transacción Normal)
Object Example
{
"name": "transbank",
"data": {
"url_success": "http://www.skyairline.cl/reservation/success"
}
}
The data element can contain the following properties:
Property | Description |
---|---|
url_success | String (required, length = 255) The URL that the customer will be redirected to when the transaction is either successfull or rejected in a redirect payment. A query string with the parameter “id” containing the Transaction ID will be added, and should be used to retrieve the transaction status from Openpay. |
Travel Club Provider object
Object Example
{
"name": "travel_club",
"data": {
"url_success": "http://www.skyairline.cl/reservation/success"
"tax" : "2000"
}
}
The data element can contain the following properties:
Property | Description |
---|---|
url_success | String (required, length = 255) The URL that the customer will be redirected to when the transaction is done in a redirect payment, either successfuly or after a failure. A query string with the parameter “id” containing the Transaction ID will be added, and should be used to retrieve the transaction status from Openpay. |
tax | numeric (optional) The amount of taxes included in the total amount. |
Khipu Provider object
Object Example
{
"name": "khipu",
"data": {
"point_of_sale" : "web_retail",
"url_success": "http://www.skyairline.cl/reservation/success"
"body" : "Flight from ABC to DEF, 2 passengers",
"send_email" : false,
"bank_id" : "Bawdf",
"request_bank_data" : true,
"payer_personal_identifier" : "11.111.111-1"
}
}
The data element can contain the following properties:
Property | Description |
---|---|
point_of_sale | String (required) Point of sale of the transaction. Values allowed are “web_retail”, “web_empresas”, “web_agencias”, “call_center”, “ventas”, “kioskos”. |
url_success | String (required, length = 255) The URL that the customer will be redirected to when the transaction is done in a redirect payment, either successfuly or after a failure. A query string with the parameter “id” containing the Transaction ID will be added, and should be used to retrieve the transaction status from Openpay. |
body | String (optional) Detailed information to show in the payment page. |
send_email | boolean (optional) If true, Khipu will send an email to the customer. |
bank_id | String (see description) **Required when a redirect won’t be used. Bank for payment chosen by the customer. |
request_bank_data | boolean (optional) If true, the bank information needed for payment will be requested to Khipu for a Normal Transfer. False by default. |
payer_personal_identifier | String (see description) **Required when request_bank_data = true. Payer personal identifier, in this case, the RUT. |
Risk Assessment object
Object example
{
"website": "http://www.openpay.mx",
"is_previous_customer": false,
"customer_ip_address": "127.0.0.1",
"airline_data": {
"tickets": [
{
"number": "1233211223",
"passenger": {
"name": "Eli Lopez",
"email": "example@example.com",
"phone_number": "+521231231235",
"address": {
"city": "city",
"country_code": "GR",
"line1": "line 1",
"postal_code": "000000",
"state": "state"
}
}
}
],
"airline_code": "ABC",
"airline_name": "Test Airline",
"passenger_name": "Eli Lopez",
"pnr": "ABC123",
"flight_date": "2016-02-01",
"agency_number": 12345678,
"flight_legs": [
{
"trip_number": 1,
"carrier_code": "00",
"airline_class": "1",
"origin": "ABC",
"destination": "DEF",
"departure_date": "2017-12-01",
"departure_time": "12:55",
"departure_timezone": "-05:00",
"arrival_date": "2017-12-05",
"arrival_time": "12:55",
"arrival_timezone": "-05:00",
"flight_number": 123,
"fare": "FARE",
"fare_basis": "FAREBASIS",
"marketing_airline": "ABC",
"number_in_party": 3,
"allow_stopover": true
}
],
"is_third_party": false,
"ticket_number": "1231212345678",
"ticket_issue_date": "2017-10-01",
"is_eticket": false,
"is_restricted_ticket": true,
"ticket_delivery_method": "eticket",
"airline_customer_id": "123456",
"is_registered_customer": false,
"airline_invoice_number": "123123"
}
}
This element contains information required for some risk assessment integrations. Only the Airline Data is required.
Property | Description |
---|---|
airline_data | object (required) Airline Data object. Information related to the flight. |
is_previous_customer | boolean (optional) If the customer is a returning customer. Not required. |
order_timezone | String (optional, length = 2) Timezone in which the order was placed. Not required. |
website | String (optional, length = 60) URL of the website. Not required. |
customer_ip_address | String (optional, length = 15) IPv4 address of the customer who is making the purchase, when done in a web setting. |
Airline Data Object
Contains information related to the flight.
Object example
{
"tickets": [
{
"number": "1233211223",
"passenger": {
"name": "Eli Lopez",
"email": "example@example.com",
"phone_number": "+521231231235",
"address": {
"city": "city",
"country_code": "GR",
"line1": "line 1",
"postal_code": "000000",
"state": "state"
}
}
}
],
"airline_code": "ABC",
"airline_name": "Test Airline",
"passenger_name": "Eli Lopez",
"pnr": "ABC123",
"flight_date": "2016-02-01",
"agency_number": 12345678,
"flight_legs": [
{
"trip_number": 1,
"carrier_code": "00",
"airline_class": "1",
"origin": "ABC",
"destination": "DEF",
"departure_date": "2017-12-01",
"departure_time": "12:55",
"departure_timezone": "-05:00",
"arrival_date": "2017-12-05",
"arrival_time": "12:55",
"arrival_timezone": "-05:00",
"flight_number": 123,
"fare": "FARE",
"fare_basis": "FAREBASIS",
"marketing_airline": "ABC",
"number_in_party": 3,
"allow_stopover": true
}
],
"is_third_party": false,
"ticket_number": "1231212345678",
"ticket_issue_date": "2017-10-01",
"is_eticket": false,
"is_restricted_ticket": true,
"ticket_delivery_method": "eticket",
"airline_customer_id": "123456",
"is_registered_customer": false,
"airline_invoice_number": "123123"
}
Property | Description |
---|---|
tickets | Ticket objects (optional) Information about the tickets issued. |
airline_code | String (required, lenght = 3) Airline numeric code. |
airline_name | String (required, length = 20) Name of the airline. |
passenger_name | String (required, length = 49) Name of the passenger |
pnr | String (required, length = 127) Passenger Name Record |
flight_legs | array (required) Information about the flight legs. Must be in flight order. |
flight_date | String (optional) Departure date of the flight, in YYYY-MM-DD format. |
agency_number | String (optional, length = 8) Numeric code of the agent |
is_third_party | boolean (optional) true if the payer is not the ticket holder. |
ticket_number | String (optional, length = 13) The ticket number |
ticket_issue_date | String (optional) Ticket issue date in YYYY-MM-DD format. |
is_eticket | boolean (optional) true if the ticket is an E-Ticket. |
is_restricted_ticket | boolean (optional) true if the ticket is non-refundable. |
ticket_delivery_method | string (optional) One of the following: “eticket”, “city_ticket_office”,“airport_ticket_office”,“ticket_by_mail”,“ticket_on_departure” |
airline_customer_id | string (optional, length = 16) ID of the customer in the context of the airline data. |
is_registered_customer | boolean (optional) True if it is a known and registered customer |
airline_invoice_number | string (optional, length = 6) Airline tracing number |
Ticket Object
Contains information about the tickets issued
Object example
{
"number": "1233211223",
"passenger": {
"name": "Eli Lopez",
"email": "example@example.com",
"phone_number": "+521231231235",
"address": {
"city": "city",
"country_code": "GR",
"line1": "line 1",
"postal_code": "000000",
"state": "state"
}
}
}
Property | Description |
---|---|
number | String (optional) Ticket number |
passenger | Object (optional) Passenger information |
Ticket passenger object
Property | Description |
---|---|
id | String (optional) Passenger ID |
name | String (optional) Passenger name |
String (optional) Passenger Email |
|
phone_number | String (optional) Passenger Phone number |
address | Object (optional) Passenger Address object |
Ticket passenger address object
Property | Description |
---|---|
line1 | String (optional) Passenger address line 1, usually street |
line2 | String (optional) Passenger address line 2 |
state | String (optional) Passenger state |
city | String (optional) Passenger city |
postal_code | String (optional) Passenger postal code |
country_code | String (optional) Passenger country code, in 2 characters |
Flight Leg Object
Information about a single flight leg
Object example
{
"trip_number": 1,
"carrier_code": "00",
"airline_class": "1",
"origin": "ABC",
"destination": "DEF",
"departure_date": "2017-12-01",
"departure_time": "12:55",
"departure_timezone": "-05:00",
"arrival_date": "2017-12-05",
"arrival_time": "12:55",
"arrival_timezone": "-05:00",
"flight_number": 123,
"fare": "FARE",
"fare_basis": "FAREBASIS",
"marketing_airline": "ABC",
"number_in_party": 3,
"allow_stopover": true
}
Property | Description |
---|---|
trip_number | numeric (optional) If the payment covers more than one trip, each with multiple legs, this value must be the same for all legs of the same trip. |
carrier_code | string (required, length = 2) IATA carrier code |
airline_class | string (required, length = 2) Reservation Booking Designator |
origin | string (required, length = 3) Origin airport code |
destination | string (required, length = 3) Destination airport code |
departure_date | string (required) Departure date in format YYYY-MM-DD |
departure_time | string (required) Departure time in format HH:MM |
departure_timezone | string (optional) Timezone of the departue time, as a GMT offset or in tz database format (example: “America/Mexico_City”) |
arrival_date | string (optional) Arrival date in format YYYY-MM-DD |
arrival_time | string (optional) Arrival time in format HH:MM |
arrival_timezone | string (optional) Timezone of the arrival time, as a GMT offset or in tz database format (example: “America/Mexico_City”) |
flight_number | string (required, length = 53) The flight number assigned by the airline carrier |
fare | string (optional, length = 12) Fare of the leg |
fare_basis | string (required, length = 15) Fare basis |
marketing_airline | string (optional) Marketing Ariline code |
number_in_party | numeric (optional) Number of passengers in party |
Metadata
After a transaction is completed, it may contain a metadata field, with information related to each provider.
Example
{
"transbank_buy_order": "kvnqhttcsw86tqqdqg1u",
"shares": "3",
"share_amount": "2000"
}
The following values are currently being returned in the metadata field for Transbank:
Property | Description |
---|---|
transbank_buy_order | string (required) Buy order identifying the transaction in Transbank. Available for Transbank. |
shares | string (optional) Number of shares selected by the user. Available for Transbank if shares were selected. |
share_amount | string (optional) Amount per Transbank share. Available only for Transbank Complete if shares were selected. |
transbank_vci | string (optional) Transbank code returned if 3D Secure was used by the client in Transbank Normal. |
The following values are currently being returned in the metadata field for Travel Club / Banco de Chile:
Property | Description |
---|---|
travelclub_buy_order | string (required) External ID sent to Banco de Chile. |
dp_authorization | string (optional) Authorisation code for the Dolares Premium, if DP were used. (The authorization returned in the transaction also contains this number) |
dp_amount | string (optional) Amount of Dolares Premium used in this transaction, if used. |
exchange_rate | string (optional) Exchange rate per Dolar Premium returned by Banco de Chile, if DP were used. |
travelclub_buying_id | string (required) TravelClub charge identifier |
tc_authorization | string (optional) Authorization code for credit card charge, if a credit card was used. (The authorization returned in the transaction also contains this number) |
travelclub_discount | string (optional) Special discount applied to the transaction by Banco de Chile, if any. |