Payments

Payments are a core part of Orchestrate. On this page, we'll dive into the different payment endpoints you can use to manage payments. We'll look at how to query, create payments.

The payment model

The payment model provides comprehensive details about each payment, including the amount, currency, status, customer information, and important timestamps such as when the payment was created or completed.

Properties

Name
id
Type
string
Description
Unique identifier for the payment.
Name
amount
Type
number
Description
The amount for the payment.
Name
currency
Type
string
Description
The currency for the payment.
Name
status
Type
string
Description
The status of the payment. Can be pending, succeeded, failed, or expired.
Name
customer.id
Type
string
Description
The id of the customer for the payment.
Name
customer.email
Type
email
Description
The email of the customer for the payment.
Name
customer.name
Type
string
Description
The name of the customer for the payment. This is the name of the customer as it will be displayed to the customer.
Name
description
Type
string
Description
The description of the payment.
Name
metadata
Type
object
Description
The metadata for the payment. This can be used to store additional information about the payment useful for your system, e.g. an order id.
Name
success_url
Type
url
Description
The URL to redirect the customer to after the payment is completed e.g. a thank you page.
Name
next_action
Type
object
Description
Contains the next step required to complete the payment. Includes a url field that points to either the hosted checkout page or the 3DS authentication page, depending on whether payment method details were provided in the request.
Name
completed_at
Type
timestamp
Description
Timestamp of when the payment was completed. Defaults to null for pending payments.
Name
created_at
Type
timestamp
Description
Timestamp of when the payment was created.
Name
updated_at
Type
timestamp
Description
Timestamp of when the payment was last updated.
Name
expires_at
Type
timestamp
Description
Timestamp of when the payment link expires.

GET/api/v1/payments

List all payments

This endpoint allows you to retrieve a paginated list of all your payments. By default, a maximum of 10 payments are shown per page.

Optional attributes

Name
page
Type
positive integer
Description
The page number to retrieve (default: 1).
Name
per_page
Type
positive integer
Description
The number of payments to return per page (default: 10, max: 100).

Request

GET

/api/v1/payments

curl -G $ORCHESTRATE_BASE_URL/api/v1/payments \
  -H "Authorization: Bearer $ORCHESTRATE_API_KEY" \
  -d page=2 \
  -d per_page=10

Response

{
  "items": [
    {
      "id": "WAz8eIbvDR60rouK",
      // ... payment details
    },
    // ... more payments
  ],
  "pagination": {
    "page": 1,
    "per_page": 10,
    "total_pages": 3,
    "total_items": 24
  }
}

POST/api/v1/payments

Create a payment

This endpoint allows you to create a new payment and obtain a payment link.

Required attributes

Name
amount
Type
number
Description
The amount for the payment.
Name
currency
Type
string
Description
The currency for the payment (e.g. USD).
Name
customer.email
Type
email
Description
The email address of the customer.
Name
customer.name
Type
string
Description
The name of the customer.
Name
description
Type
string
Description
The description of the payment.
Name
expires_in
Type
integer
Description
The number of seconds until the payment link expires.
Name
metadata
Type
object
Description
The metadata for the payment. This can be used to store additional information about the payment useful for your system, e.g. an order id.
Name
success_url
Type
url
Description
The URL to redirect the customer to after the payment is completed e.g. a thank you page.
Name
cancel_url
Type
url
Description
The URL to redirect the customer to after the payment is cancelled.

Optional attributes

Name
mcc
Type
integer
Description
The Merchant Category Code (MCC) to identify the industry of this payment. Either mcc or account_id must be provided, but not both.
Name
account_id
Type
string
Description
The ID of the merchant account to be used for this payment. The account must be active and belong to the merchant. Either mcc or account_id must be provided, but not both.
Name
payment_method
Type
object
Description
PCI DSS Compliance Required: This field is only available for merchants who have completed PCI DSS certification and received explicit approval from our compliance team. Direct card processing requires enhanced security and compliance measures. Contact our support team to enable this feature.
Name
payment_method.type
Type
string
Description
The payment method type (e.g., "card").
Name
payment_method.card
Type
object
Description
Object containing the card details used for the transaction.
Name
payment_method.card.number
Type
string
Description
The customer's card number. Only allowed if PCI DSS compliance is approved.
Name
payment_method.card.expiry_month
Type
integer
Description
The expiry month of the card (1-12).
Name
payment_method.card.expiry_year
Type
integer
Description
The expiry year of the card in four digits.
Name
payment_method.card.cvc
Type
string
Description
The 3-4 digit card verification code (CVV/CVC).
Name
payment_method.billing_details
Type
object
Description
Object containing billing information associated with the payment method.
Name
payment_method.billing_details.name
Type
string
Description
The full billing name associated with the payment method.
Name
payment_method.billing_details.address
Type
object
Description
Object containing detailed billing address information.
Name
payment_method.billing_details.address.line1
Type
string
Description
Primary address line (e.g., street address, P.O. box, company name).
Name
payment_method.billing_details.address.line2
Type
string
Description
Secondary address line (optional), such as apartment, suite, or building name.
Name
payment_method.billing_details.address.city
Type
string
Description
City, town, or locality for the billing address.
Name
payment_method.billing_details.address.state
Type
string
Description
State, province, or region for the billing address.
Name
payment_method.billing_details.address.postal_code
Type
string
Description
ZIP or postal code of the billing address.
Name
payment_method.billing_details.address.country
Type
string
Description
Two-letter ISO 3166-1 country code (e.g., 'US', 'KE').

Understanding next_action: After creating a payment, the response includes a next_action object containing a url field. You should redirect your customer to this URL to complete the payment flow. Depending on whether you provided card details, this URL will either take the customer to a 3DS authentication page or to a hosted checkout page.

Request

POST

/v1/payments

curl -X POST $ORCHESTRATE_BASE_URL/api/v1/payments \
  -H "Authorization: Bearer $ORCHESTRATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100,
    "currency": "USD",
    "mcc": 6012,
    "account_id": "123e4567-e89b-12d3-a456-426614174000",
    "payment_method": {
      "type": "card",
      "card": {
        "number": "5123450000000008",
        "expiry_month": "01",
        "expiry_year": "2030",
        "cvc": "123"
      },
      "billing_details": {
        "name": "Jane Doe",
        "address": {
          "line1": "123 Main street",
          "line2": "Apartment 4B",
          "city": "New York",
          "state": "NY",
          "postal_code": "1001",
          "country": "US"
        }
      }
    },
    "customer": {
      "email": "john.doe@example.com",
      "name": "John Doe"
    },
    "description": "Payment for order 123",
    "expires_in": 3600,
    "metadata": {
      "order_id": "123"
    },
    "success_url": "https://example.com/success",
    "cancel_url": "https://example.com/cancel"
  }'

Response

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "amount": 100,
  "currency": "USD",
  "status": "pending",
  "customer": {
    "id": "987f6543-e21b-43d2-b654-123456789abc",
    "email": "john.doe@example.com",
    "name": "John Doe"
  },
  "description": "Payment for order 123",
  "metadata": {
    "order_id": "123"
  },
  "success_url": "https://example.com/success",
  "cancel_url": "https://example.com/cancel",
  "next_action": {
    "url": "https://sandbox.orchestrate.global/payments/123e4567-e89b-12d3-a456-426614174000"
  },
  "created_at": "2025-01-01T00:00:00Z",
  "updated_at": "2025-01-01T00:00:00Z",
  "expires_at": "2025-01-01T00:00:00Z"
}

GET/v1/payments/:id

Retrieve a payment

This endpoint allows you to retrieve a payment by providing its id. Refer to the payment model at the top of this page to see which properties are included with payment objects.

Request

GET

/v1/payments/:id

curl $ORCHESTRATE_BASE_URL/api/v1/payments/123e4567-e89b-12d3-a456-426614174000 \
  -H "Authorization: Bearer $ORCHESTRATE_API_KEY"

Response

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  // ... payment details
}