Payment Intents API

The Payment Intents API lets you create, query, and manage payment intents. A payment intent represents a single payment. Create it on your server with an amount and a currency, then collect it on the hosted page or the embedded form.

Region-specific host

The API is region-specific. In the examples below, swap {region} in api-{region}.orchestrapay.com for your account's region host (for example api-europe; see Environments). The @orchestrapay/sdk picks it automatically from your key.

Create a payment intent

Creates a payment intent. It covers every gateway you have connected, so you do not pick a gateway here. All you need is an amount and a currency.

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.

idempotency_keyoptional, string

A unique, free-form key. Sending the same request with the same idempotency key returns the existing payment intent instead of creating a duplicate.

customeroptional, string | object

Either an existing customer reference (cus_...), or an object with any of merchant_id, first_name, last_name, phone_number, email to create or update a customer.

metadataoptional, object

A set of string key-value pairs you can attach to the payment intent. Returned to you on webhooks, handy for storing your own order references.

timeoutoptional, integer, default is 1800

Seconds after which the payment intent is canceled if it has not succeeded. Counted from the moment the payment intent is created.

webhook_urlsoptional, array

A list of URLs that will be subscribed to all events for this payment intent. Each URL receives 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).

POST /v202606/payment-intents

curl -X POST https://api-{region}.orchestrapay.com/v202606/payment-intents \
  -H "Authorization: Bearer orch_sk_live_eu1_..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 15000,
    "currency": "egp",
    "idempotency_key": "order_123",
    "webhook_urls": ["https://yoursite.com/webhooks/orchestrapay"],
    "webhook_secret": "your_webhook_secret",
    "final_success_url": "https://example.com/?order_successful",
    "final_failure_url": "https://example.com/?order_canceled"
  }'

Response Parameters

payment_intentstring

Unique identifier for the payment intent (e.g. pi_eu1_...)

payment_intent_createdboolean

true if a new payment intent was created, false if an existing one was returned via idempotency key.

customerstring

The customer reference (cus_...), returned only when a customer was created or matched.

RESPONSE

{
  "payment_intent": "pi_eu1_b8b5be0f481f42b4b7f5972118777c5f",
  "payment_intent_created": true
}

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-{region}.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, payment_intent_secret, idempotency_key, gateway, 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-{region}.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-{region}.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
}

Create a payment intent​

Parameters​

Response Parameters​

Query payment intents​

Query Parameters​

Filter Operators​

Response Parameters​

Notes​

Get payment intent details​

Parameters​

Response Parameters​

Cancel payment intent​

Parameters​

Status Codes​

Response Parameters​

Create a payment intent

Parameters

Response Parameters

Query payment intents

Query Parameters

Filter Operators

Response Parameters

Notes

Get payment intent details

Parameters

Response Parameters

Cancel payment intent

Parameters

Status Codes

Response Parameters