Get checkout session

GET

checkout

sessions

{checkout_session_id}

curl --request GET \
  --url https://api.mattildapayments.com/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"
  },
  "payment_method": {
    "type": "payment_method",
    "id": "<string>",
    "method": "card",
    "scheme": "visa",
    "label": "4242",
    "details": {
      "bin": "411111",
      "card_type": "credit",
      "card_country": "US"
    }
  }
}

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

requireddeprecated

The amount for an individual item represented as a monetary amount in the smallest currency unit for the given currency, for example 1299 MXN 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:0

The amount discounted for this item represented as a monetary amount in the smallest currency unit for the given currency, for example 1299 MXN 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:0

The tax amount for this item represented as a monetary amount in the smallest currency unit for the given currency, for example 1299 MXN 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" }

payment_method

object | null

Details about the payment method for card type only.

Was this page helpful?

Suggest edits

New checkout session Update checkout session

curl --request GET \
  --url https://api.mattildapayments.com/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"
  },
  "payment_method": {
    "type": "payment_method",
    "id": "<string>",
    "method": "card",
    "scheme": "visa",
    "label": "4242",
    "details": {
      "bin": "411111",
      "card_type": "credit",
      "card_country": "US"
    }
  }
}

Payments

Instruments

Vault

Dashboard

Errors

Authorizations

Path Parameters

Response