- Documentation
- Cloud Vault
- API Reference
- GitHub
Transactions
Buyers
Checkout Sessions
Payment options
Refunds
Sessions
Card schemes
Digital wallets
Gift cards
Payment methods
Payment method definitions
Account updater
Network tokens
Payment service tokens
Vault Forwarding
All services
Payment service definitions
Payment services
Digital wallets
Anti-fraud services
Gift-card services
Flow
Merchant accounts
Reports
Report executions
Payments
Instruments
Vault
Connections
Dashboard
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 '{
"cart_items": [
{
"name": "GoPro HERO9 Camcorder",
"quantity": 1,
"unit_amount": 37999,
"discount_amount": 49999999,
"tax_amount": 49999999,
"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"
}
}'{
"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": 49999999,
"tax_amount": 49999999,
"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"
},
"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
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.
The quantity of this item in the cart. This value cannot be negative or zero.
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.
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.
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.
An external identifier for the cart item. This can be set to any value and is not sent to the payment service.
The SKU for the item.
The product URL for the item.
The URL for the image of the item.
A 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.
Response
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.
The quantity of this item in the cart. This value cannot be negative or zero.
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.
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.
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.
An external identifier for the cart item. This can be set to any value and is not sent to the payment service.
The SKU for the item.
The product URL for the item.
The URL for the image of the item.
A 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.
Details 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.
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 '{
"cart_items": [
{
"name": "GoPro HERO9 Camcorder",
"quantity": 1,
"unit_amount": 37999,
"discount_amount": 49999999,
"tax_amount": 49999999,
"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"
}
}'{
"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": 49999999,
"tax_amount": 49999999,
"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"
},
"fingerprint": "20eb353620155d2b5fc864cc46a73ea77cb92c725238650839da1813fa987a17"
}
}