Get checkout session

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
Gift-card services

Dashboard

Flow
Merchant accounts
Reports
Report executions

Errors

GET

checkout

sessions

{checkout_session_id}

curl --request GET \
  --url https://api.{gr4vy_id}.gr4vy.app/checkout/sessions/{checkout_session_id} \
  --header 'Authorization: Bearer <token>'

{
  "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.read scope.

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

checkout_session_id

string

required

The unique ID for a Checkout Session.

Example:

"8724fd24-5489-4a5d-90fd-0604df7d3b83"

Response

200

application/json

Returns details about a current Checkout Session.

A short-lived checkout session.

type

enum<string>

checkout-session.

Available options:

checkout-session

Example:

"checkout-session"

string

The ID of the Checkout Session.

Example:

"8d3fe99b-1422-42e6-bbb3-932d95ae5f79"

expires_at

string

The date and time when the Checkout Session will expire. By default this will be set to 1 hour from the date of creation.

Example:

"2022-01-01T00:00:00+00:00"

cart_items

object[] | null

An array of cart items that represents the line items of a transaction.

A cart item that represents a single cart line item for a transaction. Note that some optional properties are required for certain payment service providers. If no value is set for these properties, we will use their default value.

If the total due to be paid for the item is required by the payment service provider, generally referred to as the "total amount", the formula below will usually be used to calculate this amount:

(unit_amount * quantity) - discount_amount + tax_amount

It's highly recommended that the total amount to pay for all items should match the transaction's amount to reduce the risk of the transaction being declined by the payment service provider.

cart_items.name

string

required

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.

Maximum length: 255

Example:

"GoPro HERO9 Camcorder"

cart_items.quantity

integer

required

The quantity of this item in the cart. This value cannot be negative or zero.

Required range: 1 <= x <= 99999999

Example:

1

cart_items.unit_amount

integer

required

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

Required range: 0 <= x <= 99999999

Example:

37999

cart_items.discount_amount

integer | null

default:

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

Required range: 0 <= x <= 99999999

Example:

0

cart_items.tax_amount

integer | null

default:

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

Required range: 0 <= x <= 99999999

Example:

0

cart_items.external_identifier

string | null

An external identifier for the cart item. This can be set to any value and is not sent to the payment service.

Maximum length: 200

Example:

"item-789123"

cart_items.sku

string | null

The SKU for the item.

Maximum length: 200

Example:

"sku-789123"

cart_items.product_url

string | null

The product URL for the item.

Maximum length: 2083

Example:

"https://example.com/items/gopro"

cart_items.image_url

string | null

The URL for the image of the item.

Maximum length: 2083

Example:

"https://example.com/images/items/gopro.png"

cart_items.categories

string[] | null

A list of strings containing product categories for the item. Max length per item: 50.

cart_items.product_type

enum<string> | null

The product type of the cart item.

Available options:

physical,

discount,

shipping_fee,

sales_tax,

digital,

gift_card,

store_credit,

surcharge

Example:

"physical"

metadata

object | null

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.

Example:

{ "key": "value" }

airline

object

Contains information about an airline travel, if applicable.

airline.passenger_name_record

string | null

The Passenger Name Record (PNR) in the airline reservation system.

Required string length: 1 - 50

Example:

"JOHN L"

airline.booking_code

string | null

The unique identifier of the reservation in the global distribution system.

Required string length: 1 - 50

Example:

"X36Q9C"

airline.ticket_number

string | null

The airline's unique ticket number.

Required string length: 1 - 50

Example:

"123-1234-151555"

airline.ticket_delivery_method

enum<string> | null

default:

electronic

The delivery method of the ticket.

Available options:

electronic,

other

Example:

"other"

airline.issued_at

string | null

The date that the ticket was last issued in the airline reservation system.

Example:

"2013-07-16T19:23:00.000+00:00"

airline.issued_address

string | null

The address of the place/agency that issued the ticket.

Required string length: 1 - 255

Example:

"123 Broadway, New York"

airline.travel_agency_code

string | null

The IATA travel agency code.

Required string length: 1 - 50

Example:

"12345"

airline.travel_agency_name

string | null

The name of the travel agency.

Required string length: 1 - 200

Example:

"Agency name"

airline.travel_agency_invoice_number

string | null

The reference number of the invoice that was issued by the travel agency.

Required string length: 1 - 50

Example:

"EG15555155"

airline.travel_agency_plan_name

string | null

The name of the travel agency plan.

Required string length: 1 - 200

Example:

"B733"

airline.restricted_ticket

boolean | null

Indicates whether the ticket is restricted (refundable).

Example:

false

airline.issuing_carrier_code

string | null

For airline aggregators, two-character IATA code of the airline issuing the ticket.

Required string length: 2

Example:

"A3"

airline.reservation_system

string | null

The name of the reservation system.

Required string length: 1 - 200

Example:

"Amadeus"

airline.passengers

object[] | null

An array of the travelling passengers.

Information of the travelling passenger.

airline.legs

object[] | null

An array of separate trip segments. Each leg contains detailed itinerary information.

Each of the separate trip segment, contains detailed itinerary information.

airline.legs.carrier_code

string | null

2 character airline code as set by IATA.

Required string length: 2

Example:

"LY"

airline.legs.flight_number

string | null

Unique identifier of the flight number.

Required string length: 3 - 6

Example:

"BA98"

airline.legs.departure_at

string | null

The date and time of travel in local time at the departure airport.

Example:

"2013-07-16T19:23:00.000+00:00"

airline.legs.departure_country

string | null

Departure country code in ISO 3166 format.

Required string length: 2

Example:

"UK"

airline.legs.departure_city

string | null

Departure city name.

Required string length: 1 - 100

Example:

"London"

airline.legs.departure_airport

string | null

Departure airport code of leg. 3-letter ISO code according to IATA official directory.

Required string length: 3

Example:

"LHR"

airline.legs.arrival_at

string | null

The date and time of travel in local time at the arrival airport.

Example:

"2013-07-16T19:23:00.000+00:00"

airline.legs.arrival_country

string | null

Arrival country code in ISO 3166 format.

Required string length: 2

Example:

"UK"

airline.legs.arrival_city

string | null

Arrival city name.

Required string length: 1 - 100

Example:

"London"

airline.legs.arrival_airport

string | null

Arrival airport code of leg. 3-letter ISO code according to IATA official directory.

Required string length: 3

Example:

"LHR"

airline.legs.fare_basis_code

string | null

The alphanumeric code for the "booking class" of a ticket.

Required string length: 1 - 8

Example:

"WH7LNR"

airline.legs.flight_class

string | null

Indicates service class (first class, business class, etc.).

Required string length: 1 - 5

Example:

"E"

airline.legs.stop_over

boolean | null

Indicates whether a stopover is allowed on this ticket.

Example:

false

airline.legs.route_type

enum<string>

The route type of the flight.

Available options:

round_trip,

one_way

Example:

"round_trip"

airline.legs.coupon_number

string | null

Coupon number associated with the leg.

Required string length: 1 - 50

Example:

"15885566"

airline.legs.fare_amount

integer | null

Amount of the ticket, for current leg of the trip, excluding taxes and fees.

Required range: 0 <= x <= 99999999

Example:

100

airline.legs.fee_amount

integer | null

Fee amount for current leg of the trip.

Required range: 0 <= x <= 99999999

Example:

100

airline.legs.tax_amount

integer | null

Amount of the taxes for current leg of the trip.

Required range: 0 <= x <= 99999999

Example:

100

airline.legs.departure_tax_amount

integer | null

Departure tax amount charged by a country when a person is leaving the country.

Required range: 0 <= x <= 99999999

Example:

100

payment_method

object | null

Details about the payment method for card type only.

Was this page helpful?

New checkout session Update checkout session

curl --request GET \
  --url https://api.{gr4vy_id}.gr4vy.app/checkout/sessions/{checkout_session_id} \
  --header 'Authorization: Bearer <token>'

{
  "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"
  }
}