Payments
- Transactions
- Buyers
- Checkout Sessions
- Payment links
- Payment options
- Payouts
- Refunds
- Sessions
- Settlement records
Instruments
- Card schemes
- Digital wallets
- Gift cards
- Payment methods
- Payment method definitions
Vault
- Account updater
- Network tokens
- Payment service tokens
- Vault Forward
- Vault Forward endpoints
- Vault Forward authentication
Connections
- All services
- Payment services
- Digital wallets
- Anti-fraud services
Dashboard
- Flow
- Reports
- Report executions
New checkout session
Creates a new Checkout Session.
curl --request POST \
--url https://api.{gr4vy_id}.gr4vy.app/checkout/sessions \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"expires_in": 7200,
"cart_items": [
{
"name": "GoPro HERO9 Camcorder",
"quantity": 1,
"unit_amount": 37999,
"discount_amount": 0,
"tax_amount": 0,
"external_identifier": "item-789123",
"sku": "sku-789123",
"product_url": "https://example.com/items/gopro",
"image_url": "https://example.com/images/items/gopro.png",
"categories": [
"<string>"
],
"product_type": "physical"
}
],
"metadata": {
"key": "value"
},
"airline": {
"passenger_name_record": "JOHN L",
"booking_code": "X36Q9C",
"ticket_number": "123-1234-151555",
"ticket_delivery_method": "other",
"issued_at": "2013-07-16T19:23:00.000+00:00",
"issued_address": "123 Broadway, New York",
"travel_agency_code": "12345",
"travel_agency_name": "Agency name",
"travel_agency_invoice_number": "EG15555155",
"travel_agency_plan_name": "B733",
"restricted_ticket": false,
"issuing_carrier_code": "A3",
"reservation_system": "Amadeus",
"passengers": [
{
"title": "Mr.",
"first_name": "John",
"last_name": "Lunn",
"email_address": "john@example.com",
"phone_number": "+1234567890",
"passport_number": "7700225",
"ticket_number": "LH1236699999",
"frequent_flyer_number": "15885566",
"date_of_birth": "2013-07-16",
"age_group": "adult"
}
],
"legs": [
{
"carrier_code": "LY",
"flight_number": "BA98",
"departure_at": "2013-07-16T19:23:00.000+00:00",
"departure_country": "UK",
"departure_city": "London",
"departure_airport": "LHR",
"arrival_at": "2013-07-16T19:23:00.000+00:00",
"arrival_country": "UK",
"arrival_city": "London",
"arrival_airport": "LHR",
"fare_basis_code": "WH7LNR",
"flight_class": "E",
"stop_over": false,
"route_type": "round_trip",
"coupon_number": "15885566",
"fare_amount": 100,
"fee_amount": 100,
"tax_amount": 100,
"departure_tax_amount": 100
}
]
},
"buyer": {
"external_identifier": "user-789123",
"display_name": "John L.",
"billing_details": {
"first_name": "John",
"last_name": "Lunn",
"email_address": "john@example.com",
"phone_number": "+1234567890",
"address": {
"city": "London",
"country": "GB",
"postal_code": "789123",
"state": "Greater London",
"state_code": "GB-LND",
"house_number_or_name": "10",
"line1": "10 Oxford Street",
"line2": "New Oxford Court",
"organization": "Gr4vy"
},
"tax_id": {
"value": "12345678931",
"kind": "gb.vat"
}
},
"shipping_details": {
"type": "shipping-details",
"id": "8724fd24-5489-4a5d-90fd-0604df7d3b83",
"buyer_id": "8724fd24-5489-4a5d-90fd-0604df7d3b83",
"first_name": "John",
"last_name": "Lunn",
"email_address": "john@example.com",
"phone_number": "+1234567890",
"address": {
"city": "London",
"country": "GB",
"postal_code": "789123",
"state": "Greater London",
"state_code": "GB-LND",
"house_number_or_name": "10",
"line1": "10 Oxford Street",
"line2": "New Oxford Court",
"organization": "Gr4vy"
}
},
"account_number": "1234567"
}
}'{
"type": "checkout-session",
"id": "8d3fe99b-1422-42e6-bbb3-932d95ae5f79",
"expires_at": "2022-01-01T00:00:00+00:00",
"cart_items": [
{
"name": "GoPro HERO9 Camcorder",
"quantity": 1,
"unit_amount": 37999,
"discount_amount": 0,
"tax_amount": 0,
"external_identifier": "item-789123",
"sku": "sku-789123",
"product_url": "https://example.com/items/gopro",
"image_url": "https://example.com/images/items/gopro.png",
"categories": [
"<string>"
],
"product_type": "physical"
}
],
"metadata": {
"key": "value"
},
"airline": {
"passenger_name_record": "JOHN L",
"booking_code": "X36Q9C",
"ticket_number": "123-1234-151555",
"ticket_delivery_method": "other",
"issued_at": "2013-07-16T19:23:00.000+00:00",
"issued_address": "123 Broadway, New York",
"travel_agency_code": "12345",
"travel_agency_name": "Agency name",
"travel_agency_invoice_number": "EG15555155",
"travel_agency_plan_name": "B733",
"restricted_ticket": false,
"issuing_carrier_code": "A3",
"reservation_system": "Amadeus",
"passengers": [
{
"title": "Mr.",
"first_name": "John",
"last_name": "Lunn",
"email_address": "john@example.com",
"phone_number": "+1234567890",
"passport_number": "7700225",
"ticket_number": "LH1236699999",
"frequent_flyer_number": "15885566",
"date_of_birth": "2013-07-16",
"age_group": "adult"
}
],
"legs": [
{
"carrier_code": "LY",
"flight_number": "BA98",
"departure_at": "2013-07-16T19:23:00.000+00:00",
"departure_country": "UK",
"departure_city": "London",
"departure_airport": "LHR",
"arrival_at": "2013-07-16T19:23:00.000+00:00",
"arrival_country": "UK",
"arrival_city": "London",
"arrival_airport": "LHR",
"fare_basis_code": "WH7LNR",
"flight_class": "E",
"stop_over": false,
"route_type": "round_trip",
"coupon_number": "15885566",
"fare_amount": 100,
"fee_amount": 100,
"tax_amount": 100,
"departure_tax_amount": 100
}
]
},
"payment_method": {
"type": "payment_method",
"id": "<string>",
"method": "card",
"scheme": "visa",
"label": "4242",
"details": {
"bin": "411111",
"card_type": "credit",
"card_country": "US",
"card_issuer_name": "Bank"
},
"fingerprint": "20eb353620155d2b5fc864cc46a73ea77cb92c725238650839da1813fa987a17"
}
}This endpoint requires the checkout-sessions.write scope.
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Body
A request to create a checkout session.
Defines when the checkout session will expire (in seconds). Defaults to an hour (3600 seconds).
3600 < x < 86400An array of cart items that represents the line items of a transaction.
The name of the cart item. The value you set for this property may be truncated if the maximum length accepted by a payment service provider is less than 255 characters.
255The quantity of this item in the cart. This value cannot be negative or zero.
1 < x < 99999999The amount for an individual item represented as a monetary amount
in the smallest currency unit for the given currency, for example
1299 USD cents represents $12.99.
The amount sent through to the payment processor as unitary amount
will be calculated to include the discount and tax values sent
as part of this cart item.
0 < x < 99999999The amount discounted for this item represented as a monetary amount
in the smallest currency unit for the given currency, for example 1299
USD cents represents $12.99.
Please note that this amount is for the total of the cart item and not for an individual item. For example, if the quantity is 5, this value should be the total discount amount for 5 of the cart item.
You might see unexpected failed transactions if the discount_amount can
not be equally divided by the quantity value. This is due to the fact
that some payment services require this amount to be specified per unit.
In this situation we recommend splitting this item into separate items, each with their own specific discount.
0 < x < 99999999The tax amount for this item represented as a monetary amount
in the smallest currency unit for the given currency, for example 1299
USD cents represents $12.99.
Please not that this amount is for the total of the cart item and not for an individual item. For example, if the quantity is 5, this value should be the total tax amount for 5 of the cart item.
You might see unexpected failed transactions if the tax_amount can
not be equally divided by the quantity value. This is due to the fact
that some payment services require this amount to be specified per unit.
In this situation we recommend splitting this item into separate items, each with their own specific tax amount.
0 < x < 99999999An external identifier for the cart item. This can be set to any value and is not sent to the payment service.
200The SKU for the item.
200The product URL for the item.
2083The URL for the image of the item.
2083A list of strings containing product categories for the item. Max length per item: 50.
The product type of the cart item.
physical, discount, shipping_fee, sales_tax, digital, gift_card, store_credit, surcharge Any additional information about the transaction that you would like to store as key-value pairs. This data is passed to payment service providers that support it.
The airline addendum data which describes the airline booking associated with this transaction.
The Passenger Name Record (PNR) in the airline reservation system.
1 - 50The unique identifier of the reservation in the global distribution system.
1 - 50The airline's unique ticket number.
1 - 50The delivery method of the ticket.
electronic, other The date that the ticket was last issued in the airline reservation system.
The address of the place/agency that issued the ticket.
1 - 255The IATA travel agency code.
1 - 50The name of the travel agency.
1 - 200The reference number of the invoice that was issued by the travel agency.
1 - 50The name of the travel agency plan.
1 - 200Indicates whether the ticket is restricted (refundable).
For airline aggregators, two-character IATA code of the airline issuing the ticket.
2The name of the reservation system.
1 - 200An array of the travelling passengers.
Title of the passenger.
1 - 50The first name(s) or given name of the passenger.
1 - 255The last name, or family name, of the passenger.
1 - 255The email address of the passenger.
1 - 320The phone number of the passenger. This number is formatted according to the E164 number standard.
1 - 50The passenger's unique passport number.
1 - 50The ticket number for a flight.
1 - 50The passenger's frequent flyer number.
5 - 50The passenger's date of birth.
adult, infant An array of separate trip segments. Each leg contains detailed itinerary information.
2 character airline code as set by IATA.
2Unique identifier of the flight number.
3 - 6The date and time of travel in local time at the departure airport.
Departure country code in ISO 3166 format.
2Departure city name.
1 - 100Departure airport code of leg. 3-letter ISO code according to IATA official directory.
3The date and time of travel in local time at the arrival airport.
Arrival country code in ISO 3166 format.
2Arrival city name.
1 - 100Arrival airport code of leg. 3-letter ISO code according to IATA official directory.
3The alphanumeric code for the "booking class" of a ticket.
1 - 8Indicates service class (first class, business class, etc.).
1 - 5Indicates whether a stopover is allowed on this ticket.
The route type of the flight.
round_trip, one_way Coupon number associated with the leg.
1 - 50Amount of the ticket, for current leg of the trip, excluding taxes and fees.
0 < x < 99999999Fee amount for current leg of the trip.
0 < x < 99999999Amount of the taxes for current leg of the trip.
0 < x < 99999999Departure tax amount charged by a country when a person is leaving the country.
0 < x < 99999999Provide buyer details for the transaction. No buyer resource will be created on Gr4vy when used.
An external identifier that can be used to match the buyer against your own records. This value needs to be unique for all buyers.
1 - 200A unique name for this buyer which is used in the Gr4vy admin panel to give a buyer a human readable name.
1 - 200The optional billing details for the a buyer.
The first name(s) or given name for the buyer.
1 - 255The last name, or family name, of the buyer.
1 - 255The email address for the buyer.
1 - 320The phone number for the buyer which should be formatted according to the E164 number standard.
1 - 50The billing address for the buyer.
The city for the address.
1 - 100The country for the address in ISO 3166 format.
2The postal code or zip code for the address.
1 - 50The state, county, or province for the address.
1 - 255The first line of the address.
1 - 255The code of state, county, or province for the address in ISO 3166-2 format.
4 - 6The house number or name for the address. Not all payment services use this field but some do.
1 - 255The second line of the address.
1 - 255The optional name of the company or organisation to add to the address.
1 - 255The tax ID information associated with the billing details.
The tax ID for the buyer.
1 - 50The kind of tax ID.
ae.trn, au.abn, ar.dni, ar.cuil, ar.cuit, br.cnpj, br.cpf, ca.bn, ca.gst_hst, ca.pst_bc, ca.pst_mb, ca.pst_sk, ca.qst, ch.vat, cl.tin, es.cif, eu.vat, gb.vat, hk.br, id.nik, id.npwp, in.gst, jp.cn, jp.rn, kr.brn, li.uid, mx.curp, my.frp, my.itn, my.nric, my.sst, no.vat, nz.gst, ph.tin, ru.inn, ru.kpp, sa.vat, sg.gst, sg.uen, th.id, th.vat, tw.vat, us.ein, za.vat The optional shipping details for the buyer.
The type of this resource. Is always shipping-details.
shipping-details The unique ID for a buyer's shipping detail.
The unique ID for a buyer.
The first name(s) or given name of the buyer.
1 - 255The last name, or family name, of the buyer.
1 - 255The email address of the buyer.
1 - 320The phone number of the buyer. This number is formatted according to the E164 number standard.
1 - 50The physical shipping address associated to this buyer.
The city for the address.
1 - 100The country for the address in ISO 3166 format.
2The postal code or zip code for the address.
1 - 50The state, county, or province for the address.
1 - 255The code of state, county, or province for the address in ISO 3166-2 format.
4 - 6The house number or name for the address. Not all payment services use this field but some do.
1 - 255The first line of the address.
1 - 255The second line of the address.
1 - 255The optional name of the company or organisation to add to the address.
1 - 255The source account number to perform an account funding transaction.
1 - 255Response
A short-lived checkout session.
checkout-session.
checkout-session The ID of the Checkout Session.
The date and time when the Checkout Session will expire. By default this will be set to 1 hour from the date of creation.
An array of cart items that represents the line items of a transaction.
The name of the cart item. The value you set for this property may be truncated if the maximum length accepted by a payment service provider is less than 255 characters.
255The quantity of this item in the cart. This value cannot be negative or zero.
1 < x < 99999999The amount for an individual item represented as a monetary amount
in the smallest currency unit for the given currency, for example
1299 USD cents represents $12.99.
The amount sent through to the payment processor as unitary amount
will be calculated to include the discount and tax values sent
as part of this cart item.
0 < x < 99999999The amount discounted for this item represented as a monetary amount
in the smallest currency unit for the given currency, for example 1299
USD cents represents $12.99.
Please note that this amount is for the total of the cart item and not for an individual item. For example, if the quantity is 5, this value should be the total discount amount for 5 of the cart item.
You might see unexpected failed transactions if the discount_amount can
not be equally divided by the quantity value. This is due to the fact
that some payment services require this amount to be specified per unit.
In this situation we recommend splitting this item into separate items, each with their own specific discount.
0 < x < 99999999The tax amount for this item represented as a monetary amount
in the smallest currency unit for the given currency, for example 1299
USD cents represents $12.99.
Please not that this amount is for the total of the cart item and not for an individual item. For example, if the quantity is 5, this value should be the total tax amount for 5 of the cart item.
You might see unexpected failed transactions if the tax_amount can
not be equally divided by the quantity value. This is due to the fact
that some payment services require this amount to be specified per unit.
In this situation we recommend splitting this item into separate items, each with their own specific tax amount.
0 < x < 99999999An external identifier for the cart item. This can be set to any value and is not sent to the payment service.
200The SKU for the item.
200The product URL for the item.
2083The URL for the image of the item.
2083A list of strings containing product categories for the item. Max length per item: 50.
The product type of the cart item.
physical, discount, shipping_fee, sales_tax, digital, gift_card, store_credit, surcharge Any additional information about the transaction that you would like to store as key-value pairs. This data is passed to payment service providers that support it.
Contains information about an airline travel, if applicable.
The Passenger Name Record (PNR) in the airline reservation system.
1 - 50The unique identifier of the reservation in the global distribution system.
1 - 50The airline's unique ticket number.
1 - 50The delivery method of the ticket.
electronic, other The date that the ticket was last issued in the airline reservation system.
The address of the place/agency that issued the ticket.
1 - 255The IATA travel agency code.
1 - 50The name of the travel agency.
1 - 200The reference number of the invoice that was issued by the travel agency.
1 - 50The name of the travel agency plan.
1 - 200Indicates whether the ticket is restricted (refundable).
For airline aggregators, two-character IATA code of the airline issuing the ticket.
2The name of the reservation system.
1 - 200An array of the travelling passengers.
Title of the passenger.
1 - 50The first name(s) or given name of the passenger.
1 - 255The last name, or family name, of the passenger.
1 - 255The email address of the passenger.
1 - 320The phone number of the passenger. This number is formatted according to the E164 number standard.
1 - 50The passenger's unique passport number.
1 - 50The ticket number for a flight.
1 - 50The passenger's frequent flyer number.
5 - 50The passenger's date of birth.
adult, infant An array of separate trip segments. Each leg contains detailed itinerary information.
2 character airline code as set by IATA.
2Unique identifier of the flight number.
3 - 6The date and time of travel in local time at the departure airport.
Departure country code in ISO 3166 format.
2Departure city name.
1 - 100Departure airport code of leg. 3-letter ISO code according to IATA official directory.
3The date and time of travel in local time at the arrival airport.
Arrival country code in ISO 3166 format.
2Arrival city name.
1 - 100Arrival airport code of leg. 3-letter ISO code according to IATA official directory.
3The alphanumeric code for the "booking class" of a ticket.
1 - 8Indicates service class (first class, business class, etc.).
1 - 5Indicates whether a stopover is allowed on this ticket.
The route type of the flight.
round_trip, one_way Coupon number associated with the leg.
1 - 50Amount of the ticket, for current leg of the trip, excluding taxes and fees.
0 < x < 99999999Fee amount for current leg of the trip.
0 < x < 99999999Amount of the taxes for current leg of the trip.
0 < x < 99999999Departure tax amount charged by a country when a person is leaving the country.
0 < x < 99999999Details about the payment method for card type only.
Unique ID for the payment method.
Payment method type.
card The scheme/brand of the card.
accel, amex, bancontact, carte-bancaire, cirrus, culiance, dankort, diners-club, discover, eftpos-australia, elo, hipercard, jcb, maestro, mastercard, mir, nyce, other, pulse, rupay, star, uatp, unionpay, visa Last four digits of PAN.
First six digits of PAN.
credit, debit, prepaid ISO 3166 two letter country code.
2The name of the card issuer.
The unique hash derived from the payment method identifier (e.g. card number).
Was this page helpful?
curl --request POST \
--url https://api.{gr4vy_id}.gr4vy.app/checkout/sessions \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"expires_in": 7200,
"cart_items": [
{
"name": "GoPro HERO9 Camcorder",
"quantity": 1,
"unit_amount": 37999,
"discount_amount": 0,
"tax_amount": 0,
"external_identifier": "item-789123",
"sku": "sku-789123",
"product_url": "https://example.com/items/gopro",
"image_url": "https://example.com/images/items/gopro.png",
"categories": [
"<string>"
],
"product_type": "physical"
}
],
"metadata": {
"key": "value"
},
"airline": {
"passenger_name_record": "JOHN L",
"booking_code": "X36Q9C",
"ticket_number": "123-1234-151555",
"ticket_delivery_method": "other",
"issued_at": "2013-07-16T19:23:00.000+00:00",
"issued_address": "123 Broadway, New York",
"travel_agency_code": "12345",
"travel_agency_name": "Agency name",
"travel_agency_invoice_number": "EG15555155",
"travel_agency_plan_name": "B733",
"restricted_ticket": false,
"issuing_carrier_code": "A3",
"reservation_system": "Amadeus",
"passengers": [
{
"title": "Mr.",
"first_name": "John",
"last_name": "Lunn",
"email_address": "john@example.com",
"phone_number": "+1234567890",
"passport_number": "7700225",
"ticket_number": "LH1236699999",
"frequent_flyer_number": "15885566",
"date_of_birth": "2013-07-16",
"age_group": "adult"
}
],
"legs": [
{
"carrier_code": "LY",
"flight_number": "BA98",
"departure_at": "2013-07-16T19:23:00.000+00:00",
"departure_country": "UK",
"departure_city": "London",
"departure_airport": "LHR",
"arrival_at": "2013-07-16T19:23:00.000+00:00",
"arrival_country": "UK",
"arrival_city": "London",
"arrival_airport": "LHR",
"fare_basis_code": "WH7LNR",
"flight_class": "E",
"stop_over": false,
"route_type": "round_trip",
"coupon_number": "15885566",
"fare_amount": 100,
"fee_amount": 100,
"tax_amount": 100,
"departure_tax_amount": 100
}
]
},
"buyer": {
"external_identifier": "user-789123",
"display_name": "John L.",
"billing_details": {
"first_name": "John",
"last_name": "Lunn",
"email_address": "john@example.com",
"phone_number": "+1234567890",
"address": {
"city": "London",
"country": "GB",
"postal_code": "789123",
"state": "Greater London",
"state_code": "GB-LND",
"house_number_or_name": "10",
"line1": "10 Oxford Street",
"line2": "New Oxford Court",
"organization": "Gr4vy"
},
"tax_id": {
"value": "12345678931",
"kind": "gb.vat"
}
},
"shipping_details": {
"type": "shipping-details",
"id": "8724fd24-5489-4a5d-90fd-0604df7d3b83",
"buyer_id": "8724fd24-5489-4a5d-90fd-0604df7d3b83",
"first_name": "John",
"last_name": "Lunn",
"email_address": "john@example.com",
"phone_number": "+1234567890",
"address": {
"city": "London",
"country": "GB",
"postal_code": "789123",
"state": "Greater London",
"state_code": "GB-LND",
"house_number_or_name": "10",
"line1": "10 Oxford Street",
"line2": "New Oxford Court",
"organization": "Gr4vy"
}
},
"account_number": "1234567"
}
}'{
"type": "checkout-session",
"id": "8d3fe99b-1422-42e6-bbb3-932d95ae5f79",
"expires_at": "2022-01-01T00:00:00+00:00",
"cart_items": [
{
"name": "GoPro HERO9 Camcorder",
"quantity": 1,
"unit_amount": 37999,
"discount_amount": 0,
"tax_amount": 0,
"external_identifier": "item-789123",
"sku": "sku-789123",
"product_url": "https://example.com/items/gopro",
"image_url": "https://example.com/images/items/gopro.png",
"categories": [
"<string>"
],
"product_type": "physical"
}
],
"metadata": {
"key": "value"
},
"airline": {
"passenger_name_record": "JOHN L",
"booking_code": "X36Q9C",
"ticket_number": "123-1234-151555",
"ticket_delivery_method": "other",
"issued_at": "2013-07-16T19:23:00.000+00:00",
"issued_address": "123 Broadway, New York",
"travel_agency_code": "12345",
"travel_agency_name": "Agency name",
"travel_agency_invoice_number": "EG15555155",
"travel_agency_plan_name": "B733",
"restricted_ticket": false,
"issuing_carrier_code": "A3",
"reservation_system": "Amadeus",
"passengers": [
{
"title": "Mr.",
"first_name": "John",
"last_name": "Lunn",
"email_address": "john@example.com",
"phone_number": "+1234567890",
"passport_number": "7700225",
"ticket_number": "LH1236699999",
"frequent_flyer_number": "15885566",
"date_of_birth": "2013-07-16",
"age_group": "adult"
}
],
"legs": [
{
"carrier_code": "LY",
"flight_number": "BA98",
"departure_at": "2013-07-16T19:23:00.000+00:00",
"departure_country": "UK",
"departure_city": "London",
"departure_airport": "LHR",
"arrival_at": "2013-07-16T19:23:00.000+00:00",
"arrival_country": "UK",
"arrival_city": "London",
"arrival_airport": "LHR",
"fare_basis_code": "WH7LNR",
"flight_class": "E",
"stop_over": false,
"route_type": "round_trip",
"coupon_number": "15885566",
"fare_amount": 100,
"fee_amount": 100,
"tax_amount": 100,
"departure_tax_amount": 100
}
]
},
"payment_method": {
"type": "payment_method",
"id": "<string>",
"method": "card",
"scheme": "visa",
"label": "4242",
"details": {
"bin": "411111",
"card_type": "credit",
"card_country": "US",
"card_issuer_name": "Bank"
},
"fingerprint": "20eb353620155d2b5fc864cc46a73ea77cb92c725238650839da1813fa987a17"
}
}