POST
/
checkout
/
sessions
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

Authorization
string
header
required

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

Body

application/json

A request to create a checkout session.

expires_in
integer
default:
3600

Defines when the checkout session will expire (in seconds). Defaults to an hour (3600 seconds).

Required range: 3600 <= x <= 86400
Example:

7200

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.

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

The airline addendum data which describes the airline booking associated with this transaction.

buyer
object

Provide buyer details for the transaction. No buyer resource will be created on Gr4vy when used.

Response

201
application/json
Returns the new Checkout Session.

A short-lived checkout session.

type
enum<string>

checkout-session.

Available options:
checkout-session
Example:

"checkout-session"

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

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.

payment_method
object | null

Details about the payment method for card type only.