Introduction
Documentation for specific gateways can be found here.
Direct Card Charges
Endpoint
POST /v1/{MERCHANT_ID}/charges
Sample request
{
"method": "card",
"source_id": "kyeayujmaizcsjm0ir0p",
"amount": "12000",
"currency": "EUR",
"description": "Card charge test",
"order_id": "PNR123-ExampleOrderID",
"customer": {
"name": "Eli",
"last_name": "Lopez",
"phone_number": "1234567890",
"email": "example@example.com",
"address": {
"line1": "Line 1 Required",
"line2": "Optional",
"line3": "Optional",
"state": "Required",
"city": "Required",
"postal_code": "required",
"country_code": "GR"
}
},
"affiliation": {
"name": "AFFILIATION_NAME"
},
"provider": {
"data": {
"point_of_sale": "web_retail",
"card_brand": "mastercard"
}
},
"gc_risk_assessment": {
"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"
}
}
}
Sample response
{
"id": "trakah1ugqj208xj8meu",
"authorization": "988808",
"operation_type": "in",
"method": "card",
"transaction_type": "charge",
"card": {
"type": "unknown",
"brand": "mastercard",
"address": {
"line1": "Line 1",
"line2": "Line 2",
"line3": "Line 3",
"state": "Queretaro",
"city": "Queretaro",
"postal_code": "76000",
"country_code": "MX"
},
"card_number": "541333XXXXXX0000",
"holder_name": "Eli Lopez",
"expiration_year": "19",
"expiration_month": "01",
"allows_charges": true,
"allows_payouts": false,
"bank_name": null,
"bank_code": "000"
},
"status": "completed",
"conciliated": false,
"creation_date": "2018-08-07T18:46:40-05:00",
"operation_date": "2018-08-07T18:46:43-05:00",
"description": "Card charge test",
"error_message": null,
"order_id": "PNR123-ExampleOrderID",
"amount": 12000,
"currency": "EUR",
"customer": {
"name": "Eli",
"last_name": "Lopez",
"email": "example@example.com",
"phone_number": "1234567890",
"address": {
"line1": "Line 1 Required",
"line2": "Optional",
"line3": "Optional",
"state": "Required",
"city": "Required",
"postal_code": "required",
"country_code": "GR"
},
"creation_date": "2018-08-07T18:46:40-05:00",
"external_id": null,
"clabe": null
},
"fee": {
"amount": 0.02,
"tax": 0,
"currency": "USD"
}
}
In a direct card charge, the card information is sent first to Openpay directly from the user’s browser, using the Openpay JS Library, generating a token as a response. This token is then sent to the back end and attached to the charge request sent to Openpay.
It is recommented to read the documentation for Card charges to understand the basic fields.
For these integrations, the following additional fields should be added:
Affiliation object
Property | Description |
---|---|
name | string Arbitrary name for the gateway account to use. Must be agreed upon between Openpay and the merchant |
An Affiliation name is used to decide what gateway or account should be used for a Merchant that has multiple gateways or accounts available. It can also be used to identify the origin of the transaction (Call Center, Web, etc.). Commonly used affiliation names are “WEB” or “CALL_CENTER”.
Provider Object
Property | Description |
---|---|
data | object Object with information specific to the provider. |
Object Example
{
"data": {
"point_of_sale" : "web_retail",
"card_brand" : "visa"
}
}
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”, “diners”, “visa_debit”, “visa_electron”, “mastercard_debit”, and “maestro”. |
Values for provider.data.card_brand
General values allowed are:
Values allowed |
---|
visa |
visa_debit |
visa_electron |
american_express |
mastercard |
mastercard_debit |
maestro |
jcb |
diners |
Other values may be available depending on the gateway to be used.
Risk Assessment object
Object example
{
"website": "http://www.openpay.mx",
"is_previous_customer": false,
"customer_ip_address": "127.0.0.1",
"airline_data": {
"tickets": [
{
"number": "1233211223",
"passenger": {
"name": "Eli Lopez",
"email": "example@example.com",
"phone_number": "+521231231235",
"address": {
"city": "city",
"country_code": "GR",
"line1": "line 1",
"postal_code": "000000",
"state": "state"
}
}
}
],
"airline_code": "ABC",
"airline_name": "Test Airline",
"passenger_name": "Eli Lopez",
"pnr": "ABC123",
"flight_date": "2016-02-01",
"agency_number": 12345678,
"flight_legs": [
{
"trip_number": 1,
"carrier_code": "00",
"airline_class": "1",
"origin": "ABC",
"destination": "DEF",
"departure_date": "2017-12-01",
"departure_time": "12:55",
"departure_timezone": "-05:00",
"arrival_date": "2017-12-05",
"arrival_time": "12:55",
"arrival_timezone": "-05:00",
"flight_number": 123,
"fare": "FARE",
"fare_basis": "FAREBASIS",
"marketing_airline": "ABC",
"number_in_party": 3,
"allow_stopover": true
}
],
"is_third_party": false,
"ticket_number": "1231212345678",
"ticket_issue_date": "2017-10-01",
"is_eticket": false,
"is_restricted_ticket": true,
"ticket_delivery_method": "eticket",
"airline_customer_id": "123456",
"is_registered_customer": false,
"airline_invoice_number": "123123"
}
}
This element contains information required for some risk assessment integrations. Only the Airline Data is required.
Property | Description |
---|---|
airline_data | object (required) Airline Data object. Information related to the flight. |
is_previous_customer | boolean (optional) If the customer is a returning customer. Not required. |
order_timezone | String (optional, length = 2) Timezone in which the order was placed. Not required. |
website | String (optional, length = 60) URL of the website. Not required. |
customer_ip_address | String (optional, length = 15) IPv4 address of the customer who is making the purchase, when done in a web setting. |
Airline Data Object
Contains information related to the flight.
Object example
{
"tickets": [
{
"number": "1233211223",
"passenger": {
"name": "Eli Lopez",
"email": "example@example.com",
"phone_number": "+521231231235",
"address": {
"city": "city",
"country_code": "GR",
"line1": "line 1",
"postal_code": "000000",
"state": "state"
}
}
}
],
"airline_code": "ABC",
"airline_name": "Test Airline",
"passenger_name": "Eli Lopez",
"pnr": "ABC123",
"flight_date": "2016-02-01",
"agency_number": 12345678,
"flight_legs": [
{
"trip_number": 1,
"carrier_code": "00",
"airline_class": "1",
"origin": "ABC",
"destination": "DEF",
"departure_date": "2017-12-01",
"departure_time": "12:55",
"departure_timezone": "-05:00",
"arrival_date": "2017-12-05",
"arrival_time": "12:55",
"arrival_timezone": "-05:00",
"flight_number": 123,
"fare": "FARE",
"fare_basis": "FAREBASIS",
"marketing_airline": "ABC",
"number_in_party": 3,
"allow_stopover": true
}
],
"is_third_party": false,
"ticket_number": "1231212345678",
"ticket_issue_date": "2017-10-01",
"is_eticket": false,
"is_restricted_ticket": true,
"ticket_delivery_method": "eticket",
"airline_customer_id": "123456",
"is_registered_customer": false,
"airline_invoice_number": "123123"
}
Property | Description |
---|---|
tickets | Ticket objects (optional) Information about the tickets issued. |
airline_code | String (required, lenght = 3) Airline numeric code. |
airline_name | String (required, length = 20) Name of the airline. |
passenger_name | String (required, length = 49) Name of the passenger |
pnr | String (required, length = 127) Passenger Name Record |
flight_legs | array (required) Information about the flight legs. Must be in flight order. |
flight_date | String (optional) Departure date of the flight, in YYYY-MM-DD format. |
agency_number | String (optional, length = 8) Numeric code of the agent |
is_third_party | boolean (optional) true if the payer is not the ticket holder. |
ticket_number | String (optional, length = 13) The ticket number |
ticket_issue_date | String (optional) Ticket issue date in YYYY-MM-DD format. |
is_eticket | boolean (optional) true if the ticket is an E-Ticket. |
is_restricted_ticket | boolean (optional) true if the ticket is non-refundable. |
ticket_delivery_method | string (optional) One of the following: “eticket”, “city_ticket_office”,“airport_ticket_office”,“ticket_by_mail”,“ticket_on_departure” |
airline_customer_id | string (optional, length = 16) ID of the customer in the context of the airline data. |
is_registered_customer | boolean (optional) True if it is a known and registered customer |
airline_invoice_number | string (optional, length = 6) Airline tracing number |
Ticket Object
Contains information about the tickets issued
Object example
{
"number": "1233211223",
"passenger": {
"name": "Eli Lopez",
"email": "example@example.com",
"phone_number": "+521231231235",
"address": {
"city": "city",
"country_code": "GR",
"line1": "line 1",
"postal_code": "000000",
"state": "state"
}
}
}
Property | Description |
---|---|
number | String (optional) Ticket number |
passenger | Object (optional) Passenger information |
Ticket passenger object
Property | Description |
---|---|
id | String (optional) Passenger ID |
name | String (optional) Passenger name |
String (optional) Passenger Email |
|
phone_number | String (optional) Passenger Phone number |
address | Object (optional) Passenger Address object |
Ticket passenger address object
Property | Description |
---|---|
line1 | String (optional) Passenger address line 1, usually street |
line2 | String (optional) Passenger address line 2 |
state | String (optional) Passenger state |
city | String (optional) Passenger city |
postal_code | String (optional) Passenger postal code |
country_code | String (optional) Passenger country code, in 2 characters |
Flight Leg Object
Information about a single flight leg
Object example
{
"trip_number": 1,
"carrier_code": "00",
"airline_class": "1",
"origin": "ABC",
"destination": "DEF",
"departure_date": "2017-12-01",
"departure_time": "12:55",
"departure_timezone": "-05:00",
"arrival_date": "2017-12-05",
"arrival_time": "12:55",
"arrival_timezone": "-05:00",
"flight_number": 123,
"fare": "FARE",
"fare_basis": "FAREBASIS",
"marketing_airline": "ABC",
"number_in_party": 3,
"allow_stopover": true
}
Property | Description |
---|---|
trip_number | numeric (optional) If the payment covers more than one trip, each with multiple legs, this value must be the same for all legs of the same trip. |
carrier_code | string (required, length = 2) IATA carrier code |
airline_class | string (required, length = 2) Reservation Booking Designator |
origin | string (required, length = 3) Origin airport code |
destination | string (required, length = 3) Destination airport code |
departure_date | string (required) Departure date in format YYYY-MM-DD |
departure_time | string (required) Departure time in format HH:MM |
departure_timezone | string (optional) Timezone of the departue time, as a GMT offset or in tz database format (example: “America/Mexico_City”) |
arrival_date | string (optional) Arrival date in format YYYY-MM-DD |
arrival_time | string (optional) Arrival time in format HH:MM |
arrival_timezone | string (optional) Timezone of the arrival time, as a GMT offset or in tz database format (example: “America/Mexico_City”) |
flight_number | string (required, length = 53) The flight number assigned by the airline carrier |
fare | string (optional, length = 12) Fare of the leg |
fare_basis | string (required, length = 15) Fare basis |
marketing_airline | string (optional) Marketing Ariline code |
number_in_party | numeric (optional) Number of passengers in party |