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 review 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) Use this field to send the Billing Address' Street. |
line2 | string (required) Use this field to send the Billing Address' House number. |
line3 | string (optional) This field is optional and can be used for any extra address information. |
Retrieve Transbank “Shares” (Installments)
This is used to allow the customer to pay using installments. The customer should choose how many installments they would like (from 2 to 48), and Openpay will send back the information with the monthly cost.
These installments may or may not generate interest, depending on the transaction.
This step is optional, and should only be called when using Transbank.
Definition
Using token POST /v1/{merchantId}/tokens/{tokenId}/shares
Using stored card POST /v1/{merchantId}/cards/{cardId}/shares
Request example
{ "provider": "transbank", "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" } ] }
Request
Property | Description |
---|---|
provider | string (required) Contains the provider that will be used to make the charge. Only “transbank” is allowed. |
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.
Charge a card
Definition
Merchant: POST https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/charges
Customer: POST https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/customers/{CUSTOMER_ID}/charges
Request example
{ "source_id": "kvnqhttcsw86tqqdqg1u", "method": "card", "amount": 6000, "currency": "CLP", "provider": { "name": "transbank", "data": { "share_id": "1234" } }, "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" } } }
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" }, "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", "fee": { "amount": 176.5, "tax": 28.24 } }
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 can be either a Transbank Provider object or a GlobalCollect 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) Customer information who is charged. You can use the same parameters used in the creation of a customer but an account for the customer will not be created. Note: This parameter can be used only by creating the charge at the merchant level To create a customer and keep a record of their charges history refer to create a customer and do the charge at the customer level. |
gc_risk_assessment | Object (required) Information required to use Global Collect’s risk assessment. See Global Collect Risk Assessment object. |
Response
Returns a transaction object with the charge information or with an error response.
Redirect card 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.
Merchant: POST https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/charges
Customer: POST https://sandbox-api.openpay.mx/v1/{MERCHANT_ID}/customers/{CUSTOMER_ID}/charges
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/reservation/success", "url_failure": "http://www.skyairline.cl/reservation/failed" } } }
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/" } }
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. |
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. |
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) Customer information who is charged. You can use the same parameters used in the creation of a customer but an account for the customer will not be created. Note: This parameter can be used only by creating the charge at the merchant level To create a customer and keep a record of their charges history refer to create a customer and do the charge at the customer level. |
Note: This request does not need a source id since it doesn’t require a token.
Response
This method returns a transaction 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.
Common Objects
Shares object
Object 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" } ] }
Property | Description |
---|---|
amount | numeric The total transaction amount. |
currency | numeric The currency of the payment to make. |
available | array of Share objects Information of the available installments. |
share_amount | numeric The amount that the customer will pay each month according to Transbank. |
Share object
Object Example
{ "share_id": "1234", "shares" : "3", "share_amount": "2000" }
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. |
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. |
Transbank Provider object
Object Example
{ "name": "transbank", "data": { "share_id": "1234", "shares" : "3", "share_amount" : "2000", "url_success": "http://www.skyairline.cl/reservation/success", "url_failure": "http://www.skyairline.cl/reservation/failed" } }
The data element can contain the following properties:
Property | Description |
---|---|
share_id | String (optional) The Share ID of the number of installments selected by the customer when doing a direct payment. |
url_success | String (required, length = 255) The URL that the customer will be redirected to when the transaction is successfull in a redirect payment. A query string with the parameter “id” containing the Transaction ID will be added. |
url_failure | String (required, length = 255) The URL that the customer will be redirected to when the transaction is rejected in a redirect payment. A query string with the parameter “id” containing the Transaction ID will be added. Can be the same as url_success. |
Travel Club Provider object
Object Example
{ "name": "travel_club", "data": { "url_success": "http://www.skyairline.cl/reservation/success", "url_failure": "http://www.skyairline.cl/reservation/failed", "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 successfull in a redirect payment. A query string with the parameter “id” containing the Transaction ID will be added. |
url_failure | String (required, length = 255) The URL that the customer will be redirected to when the transaction is rejected in a redirect payment. A query string with the parameter “id” containing the Transaction ID will be added. Can be the same as url_success. |
tax | numeric (optional) The amount of taxes included in the total amount. |
Global Collect Provider object
Object Example
{ "name": "global_collect" }
This provider does not need a data element.
Global Collect Risk Assessment object
Object example
{ "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" } }
This element contains information required for the Global Collect Risk Assessment API. Only the Airline Data is required.
Property | Description |
---|---|
airline_data | object (required) Airline Data object. Information related to the flight. |
is_previous_customer | String (optional) If the customer is a returning customer. Not required. |
order_timezone | String (optional) Timezone in which the order was placed. Not required. |
website | String (optional) URL of the website. Not required. |
Airline Data Object
Contains information related to the flight.
Object example
{ "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" }
Property | Description |
---|---|
airline_code | String (required, lenght = 3) Airline numeric code. |
airline_name | String (required) Name of the airline. |
passenger_name | String (required) Name of the passenger |
pnr | String (required) 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) Numeric code of the agent |
is_third_party | boolean (optional) true if the payer is not the ticket holder. |
ticket_number | String (optional) 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) 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) Airline tracing number |
Flight Leg Object
Information about a single flight leg
Object example
{ "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 }
Property | Description |
---|---|
carrier_code | string (required) IATA carrier code |
airline_class | string (required) Reservation Booking Designator |
origin | string (required) Origin airport code |
destination | string (required) Destination airport code |
departure_date | string (required) Departure date in format YYYY-MM-DD |
departure_time | string (required) Departure time in format HH:MM |
flight_number | string (required) The flight number assigned by the airline carrier |
fare | string (optional) Fare of the leg |
fare_basis | string (required) Fare basis |
allow_stopover | string (required) true if stopovers are permitted. |