Checkout Intents API

The Checkout Intents API allows you to create and query checkout intent objects, which are essential for initiating payment sessions and managing payment intents.

Create a checkout intent

Creates a checkout intent object that can be used to generate payment intents. The checkout intent object contains necessary secrets and returns a list of available payment gateways and BNPLs.

Parameters

amountinteger

The amount for the payment intent in cents (e.g. for 200 EGP, use 20000). Must be greater than or equal to 0.

currencystring

The currency code using an ISO 3 code, e.g. EGP for Egyptian Pound, USD for US Dollar, etc.

final_success_urloptional, string

The final URL where the customer will be redirected once the payment intent is successful. If no value is provided, the customer will be shown a generic success message (we strongly advise to provide a value).

final_failure_urloptional, string

The final URL where the customer will be redirected if the payment intent is canceled, fails or times out past its SLA. If no value is provided, the customer will be shown a generic failure message (we strongly advise to provide a value).

checkout_intent_idempotency_keyoptional, string

An idempotency key provided by Orchestrapay, this is a free-form optional string that, if provided, will restrain from two similar resources being created.

human_friendly_payment_intent_secretoptional, string

An optional free-form value that will be displayed to the customer on the front-end as a reference. This is typically the Order Name that the customer can see on the merchant website and will be used for troubleshooting with the CX team of the merchant.

payment_intent_timeout_secondsoptional, integer

The SLA in seconds after which the payment intent is deemed cancelled. Defaults to 1800. We start counting the SLA only after the payment intent is created, if you create a checkout intent at T0 and a payment intent at T1, the SLA time expiry is calculated from T1.

webhook_urlsoptional, array

A list of URLs that will be subscribed to all new events for this payment intent (or payment intents associated with this checkout intents). Each will receive the same payload at the same time.

webhook_secretoptional, string

An optional webhook secret that is sent over as a header in every webhook that we send, under the header name Orchestrapay-Webhook-Secret.

feature_flagoptional, string

A feature flag to be executed for the payment intent. Feature flags allow you to display a certain behaviour to certain customers.

tenantoptional, string

Name of the tenant (you can have multiple tenants for the same integration).

lgoptional, string

Any locale that you want to use for the payment intent. You can also specify a locale when redirecting the user by appending the ?lg= property to the querystring.

line_itemsoptional, array

A cart object containing the items being purchased

payloadoptional, object

The payload that Orchestrapay receives from the merchant. Orchestrapay uses this to run pre-credit checks with the BNPLs and to speed up the checkout process, this is also returned to you through the webhook so it could be useful to store any metadata you need.

Status Codes

201 Created: A new checkout intent was successfully created
200 OK: An existing checkout intent was found (when using idempotency_key)

POST /checkout-intents

curl -X POST https://api-staging.orchestrapay.com/checkout-intents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1000,
    "currency": "USD",
    "payment_method": "card",
    "customer": {
      "email": "customer@example.com"
    },
    "tenant": "your-tenant-id",
    "checkout_intent_idempotency_key": "550e8400-e29b-41d4-a716-446655440000",
    "line_items": [
      {
        "name": "Product Name",
        "price": 1000,
        "quantity": 1,
        "image": "https://example.com/image.jpg",
        "category": "Electronics",
        "slug": "product-slug",
        "url": "https://example.com/product"
      }
    ]
  }'

Response Parameters

checkout_intentstring

UUID that can be safely used in frontend to create payment intents

checkout_intent_secretinteger

Unique identifier for the checkout intent

resource_createdboolean

Indicates if a new resource was created

gateways[]array

List of available payment gateways and BNPLs

RESPONSE

{
  "checkout_intent": "550e8400-e29b-41d4-a716-446655440000",
  "checkout_intent_secret": 123,
  "resource_created": true,
  "gateways": [
    {
      "id": "stripe",
      "name": "Stripe",
      "type": "card",
      "enabled": true
    },
    {
      "id": "klarna",
      "name": "Klarna",
      "type": "bnpl",
      "enabled": true
    }
  ]
}

Query checkout intents

Retrieves a paginated list of checkout intents that match your query criteria.

Query Parameters

limitoptional, integer, default is 10

This specifies a limit on the number of objects to return, ranging between 1 and 1000.

pageoptional, integer

Page number to query.

sortByoptional, string

Sort by property:ASC|DESC (e.g., "amount:DESC").

filteroptional, object

Filter parameters for querying checkout intents

Filter Operators

$eqEqual to

$notNot equal to

$nullIs null

$inIn array

$gtGreater than

$gteGreater than or equal to

$ltLess than

$lteLess than or equal to

$btwBetween

$ilikeCase-insensitive like

$swStarts with

$containsContains

Status Codes

200 OK: The request was successful

GET /checkout-intents

curl https://api.orchestrapay.com/checkout-intents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d "filter.currency=$eq:EGP" \
  -d "filter.amount=$gt:3000" \
  -d "filter.created_at=$btw:2023-07-01T00:00:00,2023-07-31T23:59:59.59"

Response Parameters

data[]array

Array of checkout intent objects

metaobject

Pagination metadata

linksobject

Pagination links

Notes

The response follows JSON:API pagination specifications
You can sort by multiple columns
Filterable properties include: currency, created_at, updated_at, amount, checkout_intent_secret, checkout_intent, checkout_intent_idempotency_key
To fetch a single record, use ?filter.checkout_intent_secret=$eq:...
The payload field is excluded from the response for security reasons
The webhook_secret field is excluded from the response for security reasons
The payment_id field is excluded from the response for security reasons
The updated_at and deleted_at fields are excluded from the response

RESPONSE

{
  "data": [
    {
      "checkout_intent": "550e8400-e29b-41d4-a716-446655440000",
      "checkout_intent_secret": 1234,
      "amount": 5000,
      "currency": "EGP",
      "final_success_url": "https://example.com/success",
      "final_failure_url": "https://example.com/failure",
      "payment_intent_timeout_seconds": 1800,
      "checkout_intent_idempotency_key": "order_123",
      "human_friendly_payment_intent_secret": "#1940284",
      "webhook_urls": ["https://example.com/webhook"],
      "feature_flag": "filter6mo",
      "locale": "en",
      "created_at": "2023-07-15T12:00:00Z",
      "line_items": [
        {
          "name": "Product Name",
          "quantity": 2,
          "price": 2500,
          "image": "https://example.com/image.jpg",
          "category": "Financial Services",
          "slug": "payment",
          "url": "https://example.com"
        }
      ]
    }
  ],
  "meta": {
    "itemsPerPage": 10,
    "totalItems": 1,
    "currentPage": 1,
    "totalPages": 1,
    "sortBy": []
  },
  "links": {
    "first": "https://api.orchestrapay.com/checkout-intents?page=1&limit=10",
    "previous": null,
    "current": "https://api.orchestrapay.com/checkout-intents?page=1&limit=10",
    "next": null,
    "last": "https://api.orchestrapay.com/checkout-intents?page=1&limit=10"
  }
}

Create a checkout intent​

Parameters​

Status Codes​

Response Parameters​

Query checkout intents​

Query Parameters​

Filter Operators​

Status Codes​

Response Parameters​

Notes​

Create a checkout intent

Parameters

Status Codes

Response Parameters

Query checkout intents

Query Parameters

Filter Operators

Status Codes

Response Parameters

Notes