Payment Methods API

Build your own payment-method picker without embedding @orchestrapay/react.

List payment methods for the default form

GET /v202607/payment-methods resolves the tenant's default payment form using the same rules as embedded checkout.

Parameters

This endpoint has no path or query parameters.

GET /v202607/payment-methods

cURLNode.jsPython

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

const orchestrapay = new Orchestrapay('orch_sk_live_eu1_...', ApiVersion.v202607);
const methods = await orchestrapay.paymentMethods.list();

Response Parameters

payment_formstring | null

The resolved payment form (pf_...). Null when the methods were derived directly from connectors.

payment_methodsarray

The configured payment methods in display order.

RESPONSE

{
"payment_form": "pf_eu1_...",
"payment_methods": [
  {
    "name": "souhoola",
    "title": "Souhoola",
    "category": "Buy Now Pay Later",
    "logo_url": "https://static.orchestrapay.com/payment-gateways/souhoola-logo.png",
    "favicon_url": "https://static.orchestrapay.com/payment-gateways/souhoola-favicon.png"
  }
]
}

List payment methods for a specific form

GET /v202607/payment-methods/{payment_form} resolves the methods configured on the supplied pf_... form. The form must belong to the API key's tenant.

Path Parameters

payment_formstring

The payment form reference (pf_...) whose methods should be returned.

GET /v202607/payment-methods/{payment_form}

cURLNode.jsPython

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

const orchestrapay = new Orchestrapay('orch_sk_live_eu1_...', ApiVersion.v202607);
const methods = await orchestrapay.paymentMethods.list('pf_eu1_...');

Response Parameters

The response parameters are the same as the default-form endpoint above.

RESPONSE

{
"payment_form": "pf_eu1_...",
"payment_methods": [
  {
    "name": "souhoola",
    "title": "Souhoola",
    "category": "Buy Now Pay Later",
    "logo_url": "https://static.orchestrapay.com/payment-gateways/souhoola-logo.png",
    "favicon_url": "https://static.orchestrapay.com/payment-gateways/souhoola-favicon.png"
  }
]
}

Charge a saved card (MIT)

POST /cards/mit charges a saved card off-session (a Merchant-Initiated Transaction), with the customer not present. Use it for recurring, installment, or unscheduled "card on file" charges after the customer has completed at least one successful customer-present payment (CIT) that saved their card.

The charge amount and currency come from a payment intent you create first, so a full MIT is two calls:

1. Create a payment intent for the amount you want to charge (see Payment Intents).
2. POST /cards/mit referencing that intent and the saved card.

This endpoint is authenticated with a secret API key whose claims include cards.mit, and is scoped to the tenant that owns both the payment intent and the saved card. It is version-neutral (no /v202xxx prefix).

Parameters

Parameter	Type	Description
payment_intent_secret	string, required	The payment intent / transaction to charge (carries amount + currency).
payment_method_uuid	string, required	The saved card's payment-method id, from a previous successful CIT.
agreement_id	string, required	A stable id linking this MIT to the original customer agreement (CIT).
agreement_type	string, required	One of RECURRING, INSTALLMENT, or UNSCHEDULED.

curl https://api-{region}.orchestrapay.com/cards/mit \
  -H "Authorization: Bearer orch_sk_live_eu1_..." \
  -H "Content-Type: application/json" \
  -d '{
    "payment_intent_secret": "pi_eu1_...",
    "payment_method_uuid": "...",
    "agreement_id": "agr_...",
    "agreement_type": "UNSCHEDULED"
  }'

Response

{ "code": "ok", "transaction_uuid": "ti_eu1_..." }

A saved card must already carry a gateway token from a prior successful CIT, otherwise the charge is rejected (NO_GATEWAY_TOKENS). If the issuer requires Strong Customer Authentication, the response surfaces a recoverable REQUIRES_ACTION with a 3DS URL rather than a hard decline.

To charge the same saved card for different amounts, create a new payment intent per amount and call POST /cards/mit again with the same payment_method_uuid.