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.