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
email 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.