Skip to main content
POST
/
collect
/
payment_sessions
curl --request POST \
  --url https://api.momentco.io/collect/payment_sessions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "amount": 200,
  "currency": "ZAR"
}
'
{
  "id": "ps_kfAWZgfQIoeG0q",
  "type": "one_time",
  "amount": 50,
  "currency": "ZAR",
  "status": "active",
  "payment_status": "unpaid",
  "checkout_session_id": "ckt802zEb2P2uS4Ql",
  "session_url": "https://moment.dev.momentpay.io/checkout/ckt802zEb2P2uS4Ql",
  "mode": "live",
  "created_at": "2025-03-18T14:06:51.149Z",
  "updated_at": "2025-03-18T14:06:51.149Z"
}

Authorizations

​
Authorization
string
header
required

Authentication using Bearer tokens. Include your API key in the Authorization header.

Key Types:

  • Test Keys: sk_test_* for development and testing
  • Live Keys: sk_* for production environments
  • Public Keys: pk_test_* or pk_* for client-side operations

📩 Need access? Contact Support to request your API keys.

Usage:

Authorization: Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc

Headers

​
Idempotency-Key
string<uuid>
required

A unique key to prevent duplicate operations. Use the same key for retries to ensure idempotent behavior.

Best Practices:

  • Use UUIDs or other cryptographically unique identifiers
  • Maintain keys for at least 24 hours for retry scenarios
  • Use different keys for different operations
  • Monitor Idempotent-Replayed header for cache hits
Required string length: 1 - 255

Body

application/json
​
amount
integer
required

The amount to be charged in the smallest currency unit. For example, 20.00 ZAR is represented as 2000 cents. Learn more about minor units.

Example:

1000

​
currency
string
required

The ISO 4217 currency code for the payment.

Example:

"ZAR"

​
type
enum<string>
default:one_time

The type of payment session (defaults to one_time):

  • one_time: A one-time payment where the customer is present in the flow and completes the payment. Optionally, the payment method can be saved for future use where the customer is present in the flow. For example, buying a product and optionally saving the card for later one-off purchases.
  • first_in_series: The first payment where the customer is present in the flow, representing the first payment in a series of future next_in_series payments where the payment method is saved for future use when the customer is not present in the flow. A mandate is recorded for compliance purposes. For example, setting up a subscription or installment plan for a product or service.
  • next_in_series: A subsequent payment where the customer is not present in the flow, representing the next payment in a series of payments, and is charged automatically using a saved payment method (payment_method_id) and the associated customer (customer_id). For example, the next payment on a subscription or installment plan for a product or service.
Available options:
one_time,
first_in_series,
next_in_series
​
options
One Time · object

Payment options specific to a one_time payment session.

​
metadata
object

Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. NEW Limitations:

  • Maximum 20 keys
  • Key names must be strings (max 40 characters)
  • Values must be strings (max 500 characters)
Example:
{
  "customer_id": "cust_123456",
  "order_id": "ord_789012"
}
​
external_reference
string

External reference for reconciliation or tracking purposes. Must be unique within your merchant account.

Maximum string length: 255
Example:

"INV-2024-001"

Response

Payment session created

​
id
string

The unique identifier for the payment session.

Example:

"ps_kfAWZgfQIoeG0q"

​
type
enum<string>

The type of payment session (defaults to one_time):

  • one_time: A one-time payment where the customer is present in the flow and completes the payment. Optionally, the payment method can be saved for future use where the customer is present in the flow. For example, buying a product and optionally saving the card for later one-off purchases.
  • first_in_series: The first payment where the customer is present in the flow, representing the first payment in a series of future next_in_series payments where the payment method is saved for future use when the customer is not present in the flow. A mandate is recorded for compliance purposes. For example, setting up a subscription or installment plan for a product or service.
  • next_in_series: A subsequent payment where the customer is not present in the flow, representing the next payment in a series of payments, and is charged automatically using a saved payment method (payment_method_id) and the associated customer (customer_id). For example, the next payment on a subscription or installment plan for a product or service.
Available options:
one_time,
first_in_series,
next_in_series
​
amount
integer

The amount to be charged in the smallest currency unit. For example, 20.00 ZAR is represented as 2000 cents. Learn more about minor units.

Example:

1000

​
currency
string

The ISO 4217 currency code for the payment.

Example:

"ZAR"

​
status
enum<string>

The current status of the payment session.

  • active: The session is in progress. The customer is interacting with the payment flow or the payment (via session_url), or the payment is being processed programmitcally using a saved payment method. Dependendent on the payment session type.
  • completed: The session completed successfully.
  • expired: The session expired due to inactivity or a timeout.
  • cancelled: The session was cancelled by the customer or merchant.
Available options:
active,
completed,
expired,
cancelled
​
payment_status
enum<string>

The status of the payment associated with the session:

  • paid: The payment succeeded.
  • unpaid: The payment failed or has not yet succeeded.
Available options:
paid,
unpaid
​
customer_id
string

The ID of the customer associated with the payment session.

​
payment_method_id
string

The ID of the saved payment method for a customer associated with this payment session.

​
checkout_session_id
null | string

The ID of the associated checkout session (for one_time or first_in_series types).

Example:

"chk_456789abc123def"

​
payment_id
string

Unique identifier for a payment

Example:

"p_xyz789abc123def456"

​
session_url
string<uri>

The URL where the customer is redirected to complete their payment in a secure payment flow. The customer can choose from a list of available payment methods, complete the payment, and is returned to the return_url once the session is complete.

  • Only returned for one_time and first_in_series types where where the customer is present in the flow and needs to complete the payment.
  • Not returned for subsequent payments where the customer is not present in the flow, and payment is completed automatically.
Example:

"https://moment.dev.momentpay.io/checkout/cktNnkWtk7p5GJd85"

​
return_url
string<uri>

The URL where the customer that is present in the payment flow is redirected to after completing the payment. Only applicable to one_time and first_in_series payment session types where the customer is present in the flow. The customer is typically redirected on success, cancellation or expiration.

Example:

"https://callback.merchant-shop.com"

​
last_payment_error
Last Payment Error · object

Details of last error that occurred during a payment attempt.

​
mode
enum<string>

Indicates whether the payment session is in live or test mode:

  • test: Used for testing and development. Payments are simulated, and no real transactions are processed. You can use test credit cards and accounts to ensure your integration works as expected before going live.
  • live: Used in production to process real payments. Real credit cards and accounts are used, and actual transactions occur. This mode is for accepting real money from customers.
Available options:
live,
test
​
external_reference
string

External reference for reconciliation or tracking purposes. Must be unique within your merchant account.

Maximum string length: 255
Example:

"INV-2024-001"

​
metadata
object

Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. NEW Limitations:

  • Maximum 20 keys
  • Key names must be strings (max 40 characters)
  • Values must be strings (max 500 characters)
Example:
{
  "customer_id": "cust_123456",
  "order_id": "ord_789012"
}
​
created_at
string<date-time>

ISO 8601 timestamp when the resource was created

Example:

"2025-06-16T10:30:00Z"

​
updated_at
string<date-time>

ISO 8601 timestamp when the resource was last updated

Example:

"2025-06-16T10:30:00Z"