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