Skip to main content

Payment Intents API

The Payment Intents API allows you to create, query, and manage payment intents. Payment intents represent individual payment attempts and contain all the necessary information for processing payments through various gateways.

Create a payment intent​

Creates a new payment intent that can be used to process a payment through a specific gateway.

Parameters​

gatewaystring

The name of the gateway that this payment intent is associated with. This needs to match the list of gateway names provided by Orchestrapay through the POST /checkout-intents endpoint.

checkout_intentoptional, string

The uuid that you received from creating a checkout intent (using the POST /checkout-intents endpoint). If a value is provided, you no longer need to provide any other field except `gateway`.

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.

checkout_intent_idempotency_keyoptional, string

An idempotency key provided by the merchant, 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, default is 1800

The SLA in seconds after which the payment intent is deemed cancelled. 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

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

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 the merchant receives. This is used 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.

POST /payment-intents
curl -X POST https://api.orchestrapay.com/payment-intents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "gateway": "mybnpl-stg",
    "checkout_intent": "7b8e759b-530a-4e34-8538-2d65c933f38d",
    "amount": 15000,
    "currency": "EGP",
    "checkout_intent_idempotency_key": "my_idempotency_key 123",
    "human_friendly_payment_intent_secret": "#1925",
    "payment_intent_timeout_seconds": 1800,
    "webhook_urls": ["https://excited-candied-measure.glitch.me/"],
    "webhook_secret": "My.Secret",
    "final_success_url": "https://example.com/?order_successful",
    "final_failure_url": "https://example.com/?order_canceled",
    "feature_flag": "filter6mo",
    "tenant": "myshop-1029x",
    "lg": "fr_MA",
    "line_items": [
      {
        "name": "Order 123",
        "quantity": 2,
        "price": 100,
        "image": "https://pay.orchestrapay.com/order123.svg",
        "category": "Mobile Phones",
        "slug": "random-slug",
        "url": "https://www.example.com"
      }
    ],
    "payload": {
      "some_data": "Unstructured JSON object with cart and customer data"
    }
  }'

Response Parameters​

payment_intentstring

Unique identifier for the payment intent

resource_createdboolean

Indicates if a new resource was created

target_urlstring

URL to redirect the customer to complete the payment intent

RESPONSE
{
  "payment_intent": "550e8400-e29b-41d4-a716-446655440000",
  "resource_created": true,
  "target_url": "https://api.orchestrapay.com/payment-intents/redirect?payment_intent=550e8400-e29b-41d4-a716-446655440000"
}

Query payment intents​

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

Query Parameters​

limitoptional, integer, default is 50

Number of entities per page (max 1000)

pageoptional, integer

Page number to query

sortByoptional, string

Sort by property:ASC|DESC (e.g., "amount:DESC"). Available columns: payment_intent_secret, amount_paid_by_customer, amount

filteroptional, object

Filter parameters for querying payment 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
GET /payment-intents
curl https://api.orchestrapay.com/payment-intents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d "limit=50" \
  -d "page=1" \
  -d "sortBy=amount:DESC" \
  -d "filter.currency=$eq:EGP" \
  -d "filter.status=$in:success,canceled"

Response Parameters​

data[]array

Array of payment intent objects

metaobject

Pagination metadata

linksobject

Pagination links

Notes​

  • The response follows JSON:API pagination specifications
  • You can sort by the following columns: payment_intent_secret, amount_paid_by_customer, amount
  • Filterable properties include: currency, created_at, updated_at, status, amount, checkout_intent, payment_intent_secret, checkout_intent_idempotency_key, gateway, gateway_transaction_id, gateway_transaction_human_readable, payment_intent
  • To fetch a single record by ID, use ?filter.payment_intent_secret=$eq:...
  • Status values in the response are simplified to their base form (e.g., pending_created becomes pending)
RESPONSE
{
  "data": [
    {
      "payment_intent_secret": 1234,
      "payment_intent": "550e8400-e29b-41d4-a716-446655440000",
      "amount": 1000,
      "currency": "EGP",
      "status": "success",
      "sub_status": "success",
      "created_at": "2023-07-01T12:00:00Z",
      "updated_at": "2023-07-01T12:00:00Z",
      "checkout_intent_idempotency_key": "order_123",
      "gateway": "paystack",
      "phone_number": "+201234567890",
      "step_number": 4,
      "last_reason": null
    }
  ],
  "meta": {
    "itemsPerPage": 50,
    "totalItems": 95,
    "currentPage": 2,
    "totalPages": 4,
    "sortBy": [["amount", "DESC"]]
  },
  "links": {
    "first": "https://api-staging.orchestrapay.com/payment-intents?page=1&limit=50&sortBy=amount:DESC",
    "previous": "https://api-staging.orchestrapay.com/payment-intents?page=1&limit=50&sortBy=amount:DESC",
    "current": "https://api-staging.orchestrapay.com/payment-intents?page=2&limit=50&sortBy=amount:DESC",
    "next": "https://api-staging.orchestrapay.com/payment-intents?page=3&limit=50&sortBy=amount:DESC",
    "last": "https://api-staging.orchestrapay.com/payment-intents?page=4&limit=50&sortBy=amount:DESC"
  }
}

Get payment intent details​

Retrieves public data for a specific payment intent. This endpoint is safe to use in frontend applications.

Parameters​

payment_intentstring

The payment intent UUID to retrieve

GET /payment-intents/{payment_intent}
curl https://api.orchestrapay.com/payment-intents/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Parameters​

amountinteger

Payment intent amount in cents

currencystring

Three-letter ISO currency code

payment_intentstring

Payment intent UUID

human_friendly_payment_intent_secretstring

Human-readable payment intent ID

gatewaystring

Payment gateway used

payment_intent_timeout_secondsinteger

Timeout duration in seconds

final_failure_urlstring

URL to redirect on failure

final_success_urlstring

URL to redirect on success

statusstring

Payment intent status

initial_dataobject

Gateway-specific initial data

payment_intent_datestring

Payment intent creation date

feature_flagstring

Feature flag identifier

tenantobject

Tenant information

tenant_initial_user_dataobject

User data associated with payment intent

lgstring

Language code

x_token_idstring

Token identifier

step_numberinteger

Current step in payment intent flow

last_reasonstring

Last status reason

RESPONSE
{
  "amount": 1000,
  "currency": "EGP",
  "payment_intent": "550e8400-e29b-41d4-a716-446655440000",
  "human_friendly_payment_intent_secret": "PI123",
  "gateway": "paystack",
  "payment_intent_timeout_seconds": 3600,
  "final_failure_url": "https://example.com/failure",
  "final_success_url": "https://example.com/success",
  "status": "pending",
  "initial_data": {
    "checkout_url": "https://checkout.paystack.com/123"
  },
  "payment_intent_date": "2023-07-01T12:00:00Z",
  "feature_flag": "new_ui",
  "tenant": {
    "logo": "https://example.com/logo.png",
    "favicon": "https://example.com/favicon.ico"
  },
  "tenant_initial_user_data": {
    "phone_number": "+201234567890",
    "email": "customer@example.com",
    "payment_intent_channel": "web",
    "redirect_to": "https://example.com"
  },
  "lg": "en",
  "x_token_id": "token_123",
  "step_number": 1,
  "last_reason": "Waiting for customer action"
}

Cancel payment intent​

Cancels a payment intent that is still in a mutable state.

Parameters​

payment_intentstring

The payment intent UUID to cancel

Status Codes​

  • 200 OK: Payment intent was successfully canceled
  • 404 Not Found: No payment intent with the given UUID exists
  • 409 Conflict: Payment intent is not mutable (already completed or canceled)
PUT /payment-intents/{payment_intent}/cancel
curl -X PUT https://api.orchestrapay.com/payment-intents/550e8400-e29b-41d4-a716-446655440000/cancel \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Parameters​

amountinteger

Payment intent amount in cents

currencystring

Three-letter ISO currency code

payment_intentstring

Payment intent UUID

human_friendly_payment_intent_secretstring

Human-readable payment intent ID

gatewaystring

Payment gateway used

payment_intent_timeout_secondsinteger

Timeout duration in seconds

final_failure_urlstring

URL to redirect on failure

final_success_urlstring

URL to redirect on success

statusstring

Payment intent status (canceled)

initial_dataobject

Gateway-specific initial data

payment_intent_datestring

Payment intent creation date

feature_flagstring

Feature flag identifier

tenantobject

Tenant information

tenant_initial_user_dataobject

User data associated with payment intent

lgstring

Language code

x_token_idstring

Token identifier

step_numberinteger

The last successful step before the transaction failed.

last_reasonstring

Last status reason

RESPONSE
{
  "amount": 1000,
  "currency": "EGP",
  "payment_intent": "550e8400-e29b-41d4-a716-446655440000",
  "human_friendly_payment_intent_secret": "PI123",
  "gateway": "paystack",
  "payment_intent_timeout_seconds": 3600,
  "final_failure_url": "https://example.com/failure",
  "final_success_url": "https://example.com/success",
  "status": "canceled",
  "initial_data": {
    "checkout_url": "https://checkout.paystack.com/123"
  },
  "payment_intent_date": "2023-07-01T12:00:00Z",
  "feature_flag": "new_ui",
  "tenant": {
    "logo": "https://example.com/logo.png",
    "favicon": "https://example.com/favicon.ico"
  },
  "tenant_initial_user_data": {
    "phone_number": "+201234567890",
    "email": "customer@example.com",
    "payment_intent_channel": "web",
    "redirect_to": "https://example.com"
  },
  "lg": "en",
  "x_token_id": "token_123",
  "step_number": 4,
  "last_reason": null
}