Skip to main content

Payment Forms API

List the payment forms configured for your tenant or retrieve one form. Form records include their pf_... ID, title, lifecycle status, and whether they are the default. The detail response also includes the saved form configuration.

List payment forms​

GET /v202607/payment-forms returns forms newest first. Pagination is cursor-based: pass the last form's ID as starting_after to fetch the next page. You can also filter by status (draft, production, or archived).

Query Parameters​

limitoptional, integer, default is 25

How many payment forms to return, from 1 to 100.

starting_afteroptional, string

Return the page immediately after this payment form (pf_...).

ending_beforeoptional, string

Return the page immediately before this payment form (pf_...).

statusoptional, string

Only return forms with this status: draft, production, or archived.

Notes​

  • Results are ordered by creation time, most recent first.
  • Pagination is cursor-based; there are no page numbers.
GET /v202607/payment-forms
import Orchestrapay, { ApiVersion } from '@orchestrapay/sdk';

const orchestrapay = new Orchestrapay('orch_sk_live_eu1_...', ApiVersion.v202607);
const forms = await orchestrapay.paymentForms.list({
limit: 25,
status: 'production',
});

Response Parameters​

dataarray

The payment forms, most recent first.

has_moreboolean

true when another page of results is available.

RESPONSE
{
"data": [
  {
    "payment_form": "pf_eu1_...",
    "title": "Main checkout",
    "description": null,
    "status": "production",
    "is_default": true,
    "created_at": "2026-07-11T12:00:00.000Z",
    "updated_at": "2026-07-11T12:00:00.000Z"
  }
],
"has_more": false
}

Retrieve a payment form​

GET /v202607/payment-forms/{payment_form} returns one tenant-scoped form and its config.

Path Parameters​

payment_formstring

The payment form reference (pf_...) to retrieve.

GET /v202607/payment-forms/{payment_form}
import Orchestrapay, { ApiVersion } from '@orchestrapay/sdk';

const orchestrapay = new Orchestrapay('orch_sk_live_eu1_...', ApiVersion.v202607);
const form = await orchestrapay.paymentForms.retrieve('pf_eu1_...');

Response Parameters​

payment_formstring

The payment form reference (pf_...).

titlestring | null

The payment form title.

descriptionstring | null

The payment form description.

statusstring

draft, production, or archived.

is_defaultboolean

Whether this is the tenant default form.

created_atstring

ISO 8601 creation timestamp.

updated_atstring

ISO 8601 update timestamp.

configobject

The saved payment-form configuration, including its groups and gateways.

RESPONSE
{
"payment_form": "pf_eu1_...",
"title": "Main checkout",
"description": "Primary customer checkout form",
"status": "production",
"is_default": true,
"created_at": "2026-07-11T12:00:00.000Z",
"updated_at": "2026-07-11T12:00:00.000Z",
"config": {
  "groups": [
    {
      "id": "8f398e56-8c28-4f05-b8bb-df00481082bc",
      "gateways": [
        {
          "id": "bf637dde-08ed-48d3-a7aa-b07d915660cc",
          "gatewayName": "souhoola"
        }
      ]
    }
  ]
}
}