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.

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.00, use 20000). Must be greater than or equal to 0.

currencystring

The currency code using an ISO 3 code, e.g. USD for US Dollar, EUR for Euro, 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

Attach a customer to this payment intent. Pass a customer id (cus_...) to attach an existing customer as-is, or pass an object and we reconcile it for you: send whatever customer data you have and we create or update the record on our end. Matching is keyed on your reference — reuse the same reference to update that customer, send a new (or no) reference to create one. It is a partial update: only the fields you include change; omitted fields are left untouched. The response returns the resulting cus_... id.

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.

webhooksoptional, array

Webhook endpoints to notify about this payment intent's events. Each endpoint is configured independently.

return_urloptional, string

The URL the customer is redirected to after the hosted payment flow finishes, whether it succeeded, failed, or timed out. Read the payment intent status on that page (via Get payment intent details) to determine the outcome and branch your UI. If omitted, the customer sees a generic result page.

POST /v202607/payment-intents

cURLNode.jsPython

import Orchestrapay, { ApiVersion } from '@orchestrapay/sdk';

const orchestrapay = new Orchestrapay('orch_sk_live_eu1_...', ApiVersion.v202607);

const paymentIntent = await orchestrapay.paymentIntents.create({
amount: 15000,
currency: 'usd',
idempotency_key: 'order_123',
webhooks: [
  {
    url: 'https://yoursite.com/webhooks/orchestrapay',
    secret: 'your_webhook_secret',
    events: ['payment.success', 'payment.canceled'],
  },
],
return_url: 'https://example.com/order/return',
});

// paymentIntent.payment_intent -> "pi_eu1_..."
// paymentIntent.url            -> hosted checkout page
// paymentIntent.status         -> "pending"

Response Parameters

payment_intentstring

The typed, region-coded identifier for the payment intent (e.g. pi_eu1_...).

statusstring

The payment intent status. Always pending on creation.

amountinteger

The amount, in cents, echoed back.

currencystring

The 3-letter ISO currency, echoed back.

urlstring

The Orchestrapay hosted payment page for this payment intent. Redirect the customer here to collect the payment without building your own checkout. (You can instead embed it with @orchestrapay/react using the pi_ id and your publishable key.)

expires_atstring

ISO 8601 timestamp after which the payment intent auto-cancels if not paid (created time + timeout).

customerstring

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

resource_createdboolean

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

RESPONSE

{
  "payment_intent": "pi_eu1_b8b5be0f481f42b4b7f5972118777c5f",
  "status": "pending",
  "amount": 15000,
  "currency": "usd",
  "url": "https://pay.orchestrapay.com/pay/pi_eu1_b8b5be0f481f42b4b7f5972118777c5f",
  "expires_at": "2026-07-07T13:30:00Z",
  "customer": "cus_eu1_2c1d7ef04db08d2e5e980f3f3bc70000",
  "resource_created": true
}

Query payment intents

Returns a list of payment intents, most recent first. Results are cursor-paginated and can be narrowed with a fixed set of filters.

Query Parameters

limitoptional, integer, default is 25

How many payment intents to return, 1 to 100.

starting_afteroptional, string

A cursor for pagination: a payment intent id (pi_...). Returns the page of results immediately after this object. Use the id of the last item from the previous page to fetch the next page.

ending_beforeoptional, string

A cursor for pagination: a payment intent id (pi_...). Returns the page of results immediately before this object.

statusoptional, string

Only return payment intents with this status: pending, success, or canceled.

createdoptional, object

Filter by creation time. Pass a Unix timestamp (or ISO 8601) for an exact match, or a range object.

customeroptional, string

Only return payment intents attached to this customer (cus_...).

currencyoptional, string

Only return payment intents in this 3-letter ISO currency.

Notes

• Results are ordered by creation time, most recent first.
• Pagination is cursor-based: pass the last item's pi_ id as starting_after to get the next page. There are no page numbers.

GET /v202607/payment-intents

cURLNode.jsPython

const params = new URLSearchParams({
limit: '25',
status: 'success',
currency: 'usd',
'created[gte]': '1704067200',
starting_after: 'pi_eu1_b8b5be0f481f42b4b7f5972118777c5f'
});
const response = await fetch(
'https://api-{region}.orchestrapay.com/v202607/payment-intents?' + params,
{ headers: { 'Authorization': 'Bearer orch_sk_live_eu1_...' } }
);

Response Parameters

dataarray

The list of payment intents, most recent first.

has_moreboolean

true if there are more results after this page. Fetch them with starting_after set to the last item's id.

RESPONSE

{
  "data": [
    {
      "payment_intent": "pi_eu1_b8b5be0f481f42b4b7f5972118777c5f",
      "status": "success",
      "amount": 15000,
      "currency": "USD",
      "customer": "cus_eu1_2c1d7ef04db08d2e5e980f3f3bc70000",
      "created_at": "2026-07-01T12:00:00Z"
    }
  ],
  "has_more": true
}

Get payment intent details

Retrieves a payment intent. Returns the same shape as when you create one, plus its current status.

Parameters

payment_intentstring

The payment intent reference to retrieve (pi_...).

GET /v202607/payment-intents/{payment_intent}

cURLNode.jsPython

const response = await fetch('https://api-{region}.orchestrapay.com/v202607/payment-intents/pi_eu1_b8b5be0f481f42b4b7f5972118777c5f', {
  headers: { 'Authorization': 'Bearer orch_sk_live_eu1_...' }
});

Response Parameters

payment_intentstring

The payment intent reference (pi_...).

statusstring

pending, success, or canceled.

amountinteger

Amount in cents.

currencystring

Three-letter ISO currency code.

urlstring

The Orchestrapay hosted payment page for this payment intent.

expires_atstring

ISO 8601 timestamp after which the payment intent auto-cancels if not paid.

customerstring

The attached customer (cus_...), if any.

created_atstring

ISO 8601 creation timestamp.

RESPONSE

{
  "payment_intent": "pi_eu1_b8b5be0f481f42b4b7f5972118777c5f",
  "status": "success",
  "amount": 15000,
  "currency": "USD",
  "url": "https://pay.orchestrapay.com/pay/pi_eu1_b8b5be0f481f42b4b7f5972118777c5f",
  "expires_at": "2026-07-07T13:30:00Z",
  "customer": "cus_eu1_2c1d7ef04db08d2e5e980f3f3bc70000",
  "created_at": "2026-07-01T12:00:00Z"
}

Cancel payment intent

Cancels a payment intent that is still in a mutable (pending) state. Returns the canceled payment intent.

Parameters

payment_intentstring

The payment intent reference to cancel (pi_...).

Status Codes

• 200 OK: Payment intent was canceled
• 404 Not Found: No payment intent with the given reference exists
• 409 Conflict: Payment intent is not mutable (already succeeded or canceled)

POST /v202607/payment-intents/{payment_intent}/cancel

cURLNode.jsPython

const response = await fetch('https://api-{region}.orchestrapay.com/v202607/payment-intents/pi_eu1_b8b5be0f481f42b4b7f5972118777c5f/cancel', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer orch_sk_live_eu1_...' }
});

Response Parameters

Returns the payment intent object (same shape as Get payment intent details) with status set to canceled.

RESPONSE

{
  "payment_intent": "pi_eu1_b8b5be0f481f42b4b7f5972118777c5f",
  "status": "canceled",
  "amount": 15000,
  "currency": "USD",
  "url": "https://pay.orchestrapay.com/pay/pi_eu1_b8b5be0f481f42b4b7f5972118777c5f",
  "expires_at": "2026-07-07T13:30:00Z",
  "customer": "cus_eu1_2c1d7ef04db08d2e5e980f3f3bc70000",
  "created_at": "2026-07-01T12:00:00Z"
}