Card Charge Guide for Sky Integration
This is a guide for Card Charges using Transbank and Global Collect, sending the card information to Openpay through the Openpay.js library.
1. Requesting Card Data
This section shows in summary how to use the library Openpay.js to send the card information to Openpay directly from the customer's web browser. You can see a more detailed explanation here.
After the user has decided to pay using his card information, a page with an HTML form should be shown. This form must contain fields for the Card Information, as well as for the Billing Address.
The information Openpay needs is:
- Card
- Holder Name
- Number
- Expiration Year
- Expiration Month
- CVV
- Billing Address
- Street
- House Number
- City
- State
- Postal Code
- Country Code (in ISO 3166-1 alpha-2)
The card information SHOULD NOT be sent to the Ezy servers. Instead, this information should be sent from the customer's web browser directly to Openpay. Note that this is the only service in this guide that is not meant to be called from the server side.
In order to send the information to Openpay directly from the browser, the Openpay.js Javascript Library is used.
<script type="text/javascript" src="https://openpay.s3.amazonaws.com/openpay.v1.min.js"></script>
To configure the library, the following code should be executed after the webpage has loaded:
OpenPay.setId('MERCHANT_ID'); // Your API Merchant ID
OpenPay.setApiKey('PUBLIC_API_KEY'); // The value of your Public API Key.
OpenPay.setSandboxMode(true); // Use the Sandbox environment, set to false in production
Once the Openpay.js library is configured and the user enters their information, you can send the information to Openpay using the method OpenPay.token.create:
OpenPay.token.create({
"card_number": cardNumber,
"holder_name": holderName,
"expiration_year": expirationYear,
"expiration_month": expirationMonth,
"cvv2":" cvv,
"address":{
"line1": street, // Use Line1 for the Street Number
"line2": houseNumber, // Use line2 for the House Number
"line3": apartmentNumber, // Use line3 for any additional address information, such as apartmentNumber
"city": city,
"state": state,
"postal_code": postalCode,
"country_code": countryCode
}
},
function(successResponse){ // Success Callback
var token = successResponse.data.id;
// Token received
},
function(errorResponse){ // Error Callback
var errorMessage = errorResponse.message;
// Handle error
});
2. Requesting Installments (Optional, available only for Transbank)
After registering the card, you can retrieve the cost of installments available.
For this, you need to send the following information to the Shares service of the token.
- Provider: The provider that will be used for the charge. In this case, only "transbank" will return available information.
- Amount: The amount that will be charged to the card.
- Currency: The currency of the amount.
- Shares: An array containing the installments we are interested in.
The service will return a list of available installments among those sent in the array, each with their monthly cost.
This step can be repeated until the customer finds a number of installments that suits them.
Example:
These are not meant as complete HTTP Requests, and are only intended to show the information sent and returned.
POST /v1/{merchantId}/tokens/{tokenId}/shares HTTP/1.1
{ "provider": "transbank", "amount": 6000, "currency" : "CLP" "shares": [3, 6, 13] }
Response:
{
"amount" : "6000",
"currency" : "CLP",
"available" : [
{
"share_id": "1234",
"shares" : "3",
"share_amount": "2000"
},
{
"share_id": "5678",
"shares" : "6",
"share_amount": "1000"
}
]
}
Note that in this case there is no available option for 13 installments for this transaction. If a provider other than "transbank" is used, the list of available installments will be empty.
3. Completing the charge
Once you have the card token, and optionally the share_id from the selected number of installments, you can complete the charge using the API. For this you need to send the following information:
- Method: This should always be "card"
- Source ID: This is the card token obtained using the Openpay.js library
- Amount: The amount to charge the customer. If installments were requested, the amounts must match.
- Currency: The currency of the transaction. If installments were requested, the currencies must match.
- Description: A description of the transaction
- Order ID: An unique identifier for the charge. This cannot be repeated among all successful transactions. Can be used to search for transactions and to prevent duplicate charges.
- Customer: The information of the customer who is making the payment.
- Name: First Name of the customer
- Last Name: Last name or family name of the customer
- Email: Email of the customer
- Phone Number: The customer's phone number. Optional.
- Address: Customer address. Optional.
- Provider
- Name: The name of the provider to use. This can be either "transbank" or "global_collect".
- Share ID: The share_id property of the chosen installment. This is optional, and only used for Transbank.
- Global Collect Risk Assessment data: Click here for a complete list of the fields required in this object.
After being called, if successful, the API will return the transaction information. Otherwise, an error will be returned.
The following are some important fields of the returned transaction:
- ID: Unique Transaction ID within Openpay, which is used to retrieve the information or to issue refunds.
- Status: The status of the transaction. A status of "completed" means the transaction was successful and the card was charged.
- Authorization: The authorization number issued by the provider.
- Operation Date: Contains the date when the card was charged.
- Card
- Card number: This contains a masked version of the card number, with only the first 6 and last 4 digits visible.
- Holder name: The name entered as the Holder name in the form.
Example:
POST /v1/{merchantId}/charges HTTP/1.1
{ "method": "card", "source_id": "kvnqhttcsw86tqqdqg1u", "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": "Airline Name", "passenger_name": "Juan Vazquez Juarez", "pnr": "B4JOW2", "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_basis": "FAREBASIS", "allow_stopover": false } ] } } }
Response:
{
"id": "trornwo9ocwkqjljx90h",
"authorization": "193573",
"method": "card",
"transaction_type": "charge",
"card": {
"type": "credit",
"brand": "visa",
"address": {
"line1": "Street",
"line2": "135",
"line3": "12",
"state": "State",
"city": "City",
"postal_code": "8720000",
"country_code": "CL"
},
"card_number": "405188XXXXXX6623",
"holder_name": "Juan Vazquez Juarez",
"expiration_year": "20",
"expiration_month": "12"
},
"status": "completed",
"operation_date": "2016-05-02T16:10:52-05:00",
"description": "B4JOW2 Origin-Destination 2016-04-01 32:34",
"order_id": "B4JOW2-20160401-1205",
"amount": 6000,
"currency": "CLP",
"provider" : {
"name" : "transbank"
}
}
Note: A few fields from the response have been omitted.