> ## Documentation Index
> Fetch the complete documentation index at: https://docs.momentco.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Create a Payment Session
> Create a payment session.
## OpenAPI
````yaml POST /collect/payment_sessions
openapi: 3.1.0
info:
version: 1.0.0
title: Payment Sessions API
description: Payment Sessions API
contact:
name: Moment
url: https://momentco.net
email: support@momentco.net
servers:
- url: https://api.momentpay.net
security: []
tags:
- name: Event Model
x-displayName: Event Model
description: |
- name: Payment Sessions
x-displayName: Payment Sessions
description: >-
A `Payment Session` represents a single interaction for initiating and
managing a payment, tracking its status, outcome, and associated metadata.
- name: Payment Session Model
x-displayName: Payment Session Model
description: |
- name: Problem Detail Model
x-displayName: Problem Detail Model
description: |
externalDocs:
description: Read the full API documentation
url: https://momentco.net/docs
paths:
/collect/payment_sessions:
post:
tags:
- Payment Sessions
summary: Create a payment session
description: |
Create a payment session.
operationId: create_payment_session
parameters:
- $ref: '#/components/parameters/idempotency_key'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
amount:
$ref: '#/components/schemas/amount'
description: >
The amount to charge for this session, in the smallest
currency unit. For `first_in_series` sessions, if
`mandate_options.amount` is not explicitly set, this value
is also used as the consent ceiling for all subsequent
`next_in_series` payments under the mandate.
currency:
$ref: '#/components/schemas/currency'
type:
$ref: '#/components/schemas/type'
default: one_time
options:
$ref: '#/components/schemas/options'
payment_allocation:
$ref: '#/components/schemas/payment_allocation'
metadata:
$ref: '#/components/schemas/metadata_fields'
external_reference:
$ref: '#/components/schemas/external_reference'
required:
- amount
- currency
if:
properties:
amount:
const: 0
type:
const: first_in_series
required:
- amount
- type
then:
properties:
options:
properties:
mandate_options:
properties:
amount: {}
required:
- amount
required:
- mandate_options
required:
- options
examples:
One time minimal request:
$ref: '#/components/examples/one_time_minimal'
One time detailed request:
$ref: '#/components/examples/one_time_detailed_request'
First in series minimal request:
$ref: '#/components/examples/first_in_series_minimal'
Next in series request:
$ref: '#/components/examples/next_in_series_request'
First in series on_demand mandates request:
$ref: '#/components/examples/first_in_series_on_demand_mandates'
First in series scheduled mandates request:
$ref: '#/components/examples/first_in_series_scheduled_mandates'
responses:
'201':
description: Payment session created
content:
application/json:
schema:
$ref: '#/components/schemas/payment_session'
examples:
One time minimal request:
$ref: '#/components/examples/one_time_session_created_response'
One time detailed request:
$ref: >-
#/components/examples/one_time_detailed_session_created_response
First in series minimal request:
$ref: >-
#/components/examples/first_in_series_session_created_response
Next in series request:
$ref: >-
#/components/examples/next_in_series_session_created_response
First in series on_demand mandates request:
$ref: >-
#/components/examples/first_in_series_on_demand_mandates_created_response
First in series scheduled mandates request:
$ref: >-
#/components/examples/first_in_series_scheduled_mandates_created_response
headers:
Request-Id:
$ref: '#/components/headers/request_id'
'400':
$ref: '#/components/responses/bad_request'
'401':
$ref: '#/components/responses/unauthorized'
'409':
$ref: '#/components/responses/conflict'
'500':
$ref: '#/components/responses/internal_server_error'
security:
- bearer_auth: []
components:
parameters:
idempotency_key:
name: Idempotency-Key
in: header
required: true
description: >
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
schema:
type: string
format: uuid
minLength: 1
maxLength: 255
pattern: ^[a-zA-Z0-9-]+$
example: 550e8400-e29b-41d4-a716-446655440000
schemas:
amount:
title: Amount
type: integer
description: >
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](/api-reference/basics/monetary_amounts#minor-units-explained).
example: 1000
currency:
title: Currency
type: string
description: The ISO 4217 currency code for the payment.
example: ZAR
type:
title: Session Type
type: string
enum:
- one_time
- first_in_series
- next_in_series
description: >
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.
options:
title: Options
description: >-
The options used to setup the payment initiated and managed by the
payment session.
anyOf:
- $ref: '#/components/schemas/one_time'
- $ref: '#/components/schemas/first_in_series'
- $ref: '#/components/schemas/next_in_series'
payment_allocation:
title: Payment Allocation
type: object
description: >
The purpose and target of the payment. Immutable once the session is
created. See [Payment
Allocation](/documentation/collect/payment-sessions/payment-allocation)
for details.
properties:
purpose:
type: string
enum:
- purchase
- wallet_funding
- gaming_deposit
- settlement
- invoice_payment
- merchant_defined
description: >
The reason the payment is being made. See [Payment
Allocation](/documentation/collect/payment-sessions/payment-allocation)
for details.
applies_to:
oneOf:
- $ref: '#/components/schemas/allocation_target_customer'
- $ref: '#/components/schemas/allocation_target_account'
- $ref: '#/components/schemas/allocation_target_bill'
- $ref: '#/components/schemas/allocation_target_payment_request'
- $ref: '#/components/schemas/allocation_target_wallet'
- $ref: '#/components/schemas/allocation_target_merchant_wallet'
- $ref: '#/components/schemas/allocation_target_merchant_gaming_account'
- $ref: '#/components/schemas/allocation_target_merchant_invoice'
- $ref: '#/components/schemas/allocation_target_merchant_defined'
- $ref: '#/components/schemas/allocation_target_unstructured'
required:
- purpose
additionalProperties: false
metadata_fields:
type: object
description: >
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)
additionalProperties:
type: string
example:
customer_id: cust_123456
order_id: ord_789012
external_reference:
type: string
description: |
External reference for reconciliation or tracking purposes.
Must be unique within your merchant account.
maxLength: 255
pattern: ^[a-zA-Z0-9_-]+$
example: INV-2024-001
payment_session:
title: Payment Session Object
type: object
properties:
id:
type: string
description: The unique identifier for the payment session.
example: ps_kfAWZgfQIoeG0q
type:
$ref: '#/components/schemas/type'
amount:
$ref: '#/components/schemas/amount'
currency:
$ref: '#/components/schemas/currency'
status:
type: string
enum:
- active
- completed
- expired
- cancelled
description: |
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.
payment_status:
type: string
enum:
- paid
- unpaid
- pending
deprecated: true
description: >
Deprecated. Use `payment_outcome` instead.
The status of the payment associated with the session:
- `paid`: The payment succeeded.
- `unpaid`: The payment failed or has not yet succeeded.
- `pending`: The payment is still being processed and has not
succeeded yet.
payment_outcome:
$ref: '#/components/schemas/payment_outcome'
customer_id:
$ref: '#/components/schemas/customer_id'
payment_method_id:
$ref: '#/components/schemas/payment_method_id'
checkout_session_id:
type:
- 'null'
- string
example: chk_456789abc123def
description: >
The ID of the associated checkout session (for `one_time` or
`first_in_series` types).
payment_id:
$ref: '#/components/schemas/payment_id'
session_url:
type: string
format: uri
example: https://moment.dev.momentpay.io/checkout/cktNnkWtk7p5GJd85
description: >
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.
return_url:
$ref: '#/components/schemas/return_url'
last_payment_error:
$ref: '#/components/schemas/last_payment_error'
mode:
type: string
enum:
- live
- test
description: >
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.
external_reference:
$ref: '#/components/schemas/external_reference'
payment_allocation:
allOf:
- $ref: '#/components/schemas/payment_allocation'
description: >-
🚧 **Coming Soon.** Restricts collections to specific days of
the week or month.
metadata:
$ref: '#/components/schemas/metadata_fields'
created_at:
$ref: '#/components/schemas/created_at'
updated_at:
$ref: '#/components/schemas/updated_at'
additionalProperties: false
one_time:
title: One Time
type: object
description: |
Payment options specific to a `one_time` payment session.
properties:
customer:
anyOf:
- $ref: '#/components/schemas/customer_id'
- $ref: '#/components/schemas/customer'
save_payment_method:
$ref: '#/components/schemas/save_payment_method'
deprecated: true
description: Deprecated — use `checkout_options.save_payment_method` instead.
return_url:
$ref: '#/components/schemas/return_url'
deprecated: true
description: Deprecated — use `checkout_options.return_url` instead.
checkout_options:
$ref: '#/components/schemas/checkout_options_one_time'
payment_options:
$ref: '#/components/schemas/payment_options'
payment_method_options:
$ref: '#/components/schemas/payment_method_options'
additionalProperties: false
first_in_series:
title: First In Series
type: object
description: |
Payment options specific to a `first_in_series` payment session.
properties:
customer:
anyOf:
- $ref: '#/components/schemas/customer_id'
- $ref: '#/components/schemas/customer'
return_url:
$ref: '#/components/schemas/return_url'
deprecated: true
description: Deprecated — use `checkout_options.return_url` instead.
checkout_options:
$ref: '#/components/schemas/checkout_options_first_in_series'
payment_options:
$ref: '#/components/schemas/payment_options'
payment_method_options:
$ref: '#/components/schemas/payment_method_options'
mandate_options:
allOf:
- $ref: '#/components/schemas/mandate_options'
description: |
Defaults to `type: on_demand`
subscription_options:
allOf:
- $ref: '#/components/schemas/subscription_options'
description: Configuration options for creating a platform-managed subscription.
additionalProperties: false
required:
- customer
next_in_series:
title: Next In Series
type: object
description: |
Payment options specific to a `next_in_series` payment session.
properties:
customer:
$ref: '#/components/schemas/customer_id'
payment_method:
$ref: '#/components/schemas/payment_method_id'
payment_options:
$ref: '#/components/schemas/payment_options'
payment_method_options:
$ref: '#/components/schemas/payment_method_options'
additionalProperties: false
required:
- customer
- payment_method
allocation_target_customer:
title: Customer
type: object
description: >
Applied to a Moment-managed customer. Moment resolves which bills or
payment requests to settle. See [Payment
Allocation](/documentation/collect/payment-sessions/payment-allocation)
for details.
required:
- type
- id
properties:
type:
type: string
enum:
- customer
description: |
A Moment-managed customer. `id` must be a Moment customer object ID.
id:
type: string
description: Moment customer object ID, prefixed with `cust_`.
description:
type: string
description: Human-readable description of the target.
attributes:
type: object
additionalProperties:
type: string
description: >
Free-form key-value pairs stamped onto the customer record at
settlement time. Not evaluated by Moment for compliance. Maximum 20
keys. Key names must be strings (max 40 characters). Values must be
strings (max 500 characters).
additionalProperties: false
allocation_target_account:
title: Account
type: object
description: >
Applied to a Moment-managed account. Moment resolves which bills or
payment requests to settle. See [Payment
Allocation](/documentation/collect/payment-sessions/payment-allocation)
for details.
required:
- type
- id
properties:
type:
type: string
enum:
- account
description: |
A Moment-managed account. `id` must be a Moment account object ID.
id:
type: string
description: Moment account object ID, prefixed with `acc_`.
description:
type: string
description: Human-readable description of the target.
attributes:
type: object
additionalProperties:
type: string
description: >
Free-form key-value pairs stamped onto the account record at
settlement time. Not evaluated by Moment for compliance. Maximum 20
keys. Key names must be strings (max 40 characters). Values must be
strings (max 500 characters).
additionalProperties: false
allocation_target_bill:
title: Bill
type: object
description: >
Applied to a Moment-managed bill. See [Payment
Allocation](/documentation/collect/payment-sessions/payment-allocation)
for details.
required:
- type
- id
properties:
type:
type: string
enum:
- bill
description: >
A Moment-managed bill. `id` must be a Moment bill ID with the
`bill_` prefix.
id:
type: string
description: Moment bill ID, prefixed with `bill_`.
description:
type: string
description: Human-readable description of the target.
attributes:
type: object
additionalProperties:
type: string
description: >
Free-form key-value pairs stamped onto the bill record at settlement
time. Not evaluated by Moment for compliance. Maximum 20 keys. Key
names must be strings (max 40 characters). Values must be strings
(max 500 characters).
additionalProperties: false
allocation_target_payment_request:
title: Payment Request
type: object
description: >
Applied to a Moment-managed payment request. See [Payment
Allocation](/documentation/collect/payment-sessions/payment-allocation)
for details.
required:
- type
- id
properties:
type:
type: string
enum:
- payment_request
description: >
A Moment-managed payment request. `id` must be a Moment payment
request ID with the `pr_` prefix.
id:
type: string
description: Moment payment request ID, prefixed with `pr_`.
description:
type: string
description: Human-readable description of the target.
attributes:
type: object
additionalProperties:
type: string
description: >
Free-form key-value pairs stamped onto the payment request record at
settlement time. Not evaluated by Moment for compliance. Maximum 20
keys. Key names must be strings (max 40 characters). Values must be
strings (max 500 characters).
additionalProperties: false
allocation_target_wallet:
title: Wallet
type: object
description: >
Applied to a Moment-managed wallet. No compliance attributes required.
See [Payment
Allocation](/documentation/collect/payment-sessions/payment-allocation)
for details.
required:
- type
- id
properties:
type:
type: string
enum:
- wallet
description: |
A Moment-managed wallet. `id` must be a Moment wallet object ID.
id:
type: string
description: Moment wallet object ID.
description:
type: string
description: Human-readable description of the target.
attributes:
type: object
additionalProperties:
type: string
description: >
Free-form key-value pairs stamped onto the wallet funding record at
transaction time. Not evaluated by Moment for compliance. Maximum 20
keys. Key names must be strings (max 40 characters). Values must be
strings (max 500 characters).
additionalProperties: false
allocation_target_merchant_wallet:
title: Merchant Wallet
type: object
description: >
Applied to a wallet in the merchant system or an external platform.
Compliance attributes required for AML and sanctions screening. See
[Payment
Allocation](/documentation/collect/payment-sessions/payment-allocation)
for details.
required:
- type
- id
- attributes
properties:
type:
type: string
enum:
- merchant_wallet
description: >
A wallet held in the merchant system or an external platform. `id`
is the merchant-defined identifier.
id:
type: string
description: Merchant-defined wallet identifier.
description:
type: string
description: Human-readable description of the target.
attributes:
type: object
required:
- recipient
- jurisdiction
additionalProperties: false
properties:
recipient:
$ref: '#/components/schemas/attributes_recipient'
jurisdiction:
type: string
description: >
Regulatory jurisdiction of the wallet scheme. Typically an ISO
3166-1 alpha-2 country code (for example `ZA`), but may be a
sub-national region or other regulatory zone where the licensing
authority is not at country level. May differ from
`recipient.country`.
account:
$ref: '#/components/schemas/attributes_account'
additionalProperties: false
allocation_target_merchant_gaming_account:
title: Merchant Gaming Account
type: object
description: >
Applied to a gaming or gambling account in the merchant system.
Compliance attributes required. Payments blocked for self-excluded
players. See [Payment
Allocation](/documentation/collect/payment-sessions/payment-allocation)
for details.
required:
- type
- id
- attributes
properties:
type:
type: string
enum:
- merchant_gaming_account
description: >
A gaming or gambling account in the merchant system. `id` is the
merchant-defined identifier.
id:
type: string
description: Merchant-defined player or account identifier.
description:
type: string
description: Human-readable description of the target.
attributes:
type: object
required:
- recipient
- jurisdiction
- gaming
additionalProperties: false
properties:
recipient:
$ref: '#/components/schemas/attributes_recipient'
gaming:
$ref: '#/components/schemas/attributes_gaming'
jurisdiction:
type: string
description: >
Regulatory jurisdiction of the gaming operator. Typically an ISO
3166-1 alpha-2 country code (for example `ZA` or `CW`), but may
be a sub-national region or other regulatory zone where the
licensing authority is not at country level. Drives regulatory
rule selection. May differ from `recipient.country` when a
player in one country uses a platform licensed in another.
account:
$ref: '#/components/schemas/attributes_account'
additionalProperties: false
allocation_target_merchant_invoice:
title: Merchant Invoice
type: object
description: >
Applied to an invoice in the merchant system or an external platform.
See [Payment
Allocation](/documentation/collect/payment-sessions/payment-allocation)
for details.
required:
- type
- id
properties:
type:
type: string
enum:
- merchant_invoice
description: >
An invoice in the merchant system or an external platform. `id` is
the merchant-defined identifier.
id:
type: string
description: Merchant-defined invoice identifier.
description:
type: string
description: Human-readable description of the target.
attributes:
type: object
properties:
invoice_number:
type: string
description: Invoice reference in the merchant system.
purchase_order:
type: string
description: Purchase order number if applicable.
additionalProperties: false
additionalProperties: false
allocation_target_merchant_defined:
title: Merchant Defined
type: object
description: >
Applied to a custom target defined by the merchant. See [Payment
Allocation](/documentation/collect/payment-sessions/payment-allocation)
for details.
required:
- type
- id
properties:
type:
type: string
enum:
- merchant_defined
description: |
A custom target type defined by the merchant.
id:
type: string
description: Merchant-defined identifier for the target.
description:
type: string
description: Human-readable description of the target.
attributes:
type: object
additionalProperties:
type: string
description: >
Free-form key-value pairs for merchant-defined compliance or
operational data. Maximum 20 keys. Key names must be strings (max 40
characters). Values must be strings (max 500 characters).
additionalProperties: false
allocation_target_unstructured:
title: Unstructured
type: object
description: >
Applied to a target with no structured identifier. Requires at least one
of `description` or `attributes`. See [Payment
Allocation](/documentation/collect/payment-sessions/payment-allocation)
for details.
required:
- type
properties:
type:
type: string
enum:
- unstructured
description: >
An unstructured target with no identifier. Use `description` or
`attributes` to describe the target.
description:
type: string
description: Human-readable description of the target.
attributes:
type: object
additionalProperties:
type: string
description: >
Free-form key-value pairs for merchant-defined data about the
target. Maximum 20 keys. Key names must be strings (max 40
characters). Values must be strings (max 500 characters).
additionalProperties: false
payment_outcome:
title: Payment Outcome
type: string
enum:
- not_started
- pending
- paid
- unpaid
- reserved
- payment_method_verified
description: >
The outcome of the payment associated with the session:
- `not_started`: Payment has not been initiated. A draft payment object
may exist but nothing is awaiting an outcome.
- `pending`: Payment has been initiated and is awaiting a final outcome.
May be waiting on customer action (for example, authentication,
redirect, voucher) or provider confirmation (for example, bank, network,
async settlement).
- `paid`: Payment succeeded. Terminal.
- `unpaid`: Payment failed, expired, or was cancelled. Terminal.
- `reserved`: Funds were authorised successfully and are reserved on the
payment method. Applies to `capture_method: manual` flows. The session
outcome remains `reserved` even after subsequent capture or void
operations, which are tracked on the underlying payment resource.
- `payment_method_verified`: No payment was taken. Payment method was
verified and vaulted via a supported `amount: 0` `one_time` or
`first_in_series` session. Terminal. Only applicable when `amount: 0` on
those supported session types.
customer_id:
title: Customer ID
type: string
description: The ID of the customer associated with the payment session.
payment_method_id:
title: Payment Method ID
type: string
description: >-
The ID of the saved payment method for a customer associated with this
payment session.
payment_id:
type: string
description: Unique identifier for a payment
example: p_xyz789abc123def456
return_url:
title: Return URL
type: string
format: uri
example: https://callback.merchant-shop.com
description: >
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.
last_payment_error:
title: Last Payment Error
type: object
description: Details of last error that occurred during a payment attempt.
properties:
error_code:
type: string
description: A short code representing the type of error (e.g. `card_declined`).
decline_code:
type: string
description: >
A code that explains why a card transaction was declined, typically
provided by the issuing bank, payment processor, or credit card
network. (e.g. `insufficient_funds`)
message:
type: string
description: A human-readable message describing the error.
example: General Error
timestamp:
type: string
format: date-time
description: The timestamp of when the error occurred.
additionalProperties: false
created_at:
type: string
format: date-time
description: ISO 8601 timestamp when the resource was created
example: '2025-06-16T10:30:00Z'
updated_at:
type: string
format: date-time
description: ISO 8601 timestamp when the resource was last updated
example: '2025-06-16T10:30:00Z'
problem_detail:
title: Problem Detail Object
type: object
properties:
type:
type: string
description: >
A URI reference that identifies the problem type. This URI should
provide human-readable documentation for the problem type.
title:
type: string
description: |
A short, human-readable summary of the problem type.
status:
type: integer
description: |
The HTTP status code applicable to this problem.
detail:
type: string
description: >
A human-readable explanation specific to this occurrence of the
problem.
instance:
type: string
description: >
A URI reference that identifies the specific occurrence of the
problem.
code:
type: string
description: A machine-readable code that describes the specific error condition
enum:
- bad_request
- conflict
- unauthorized
- missing_authorization
- operation_not_allowed
- resource_not_found
- resource_already_exists
- bill_already_voided
- internal_server_error
- payment_not_found
example: bad_request
required:
- type
- title
- status
description: |
A standardized format for problem details, following RFC 9457.
customer:
title: Customer Object
type: object
description: |
The customer associated with the payment session.
properties:
name:
type: string
description: The customers full name or business name.
email:
type: string
description: The customers email address.
phone:
type: string
description: The customers phone number.
description:
type: string
description: >-
An arbitrary value to provide an additional description for the
customer.
external_reference:
$ref: '#/components/schemas/external_reference'
metadata:
$ref: '#/components/schemas/metadata_fields'
additionalProperties: false
save_payment_method:
title: Save Payment Method
type: string
enum:
- always
- never
- prompt
description: >
Determines whether the payment method should be saved for future use
when the customer is present in the flow.
- `always`: Save the payment method automatically to the customer
specified.
- `never`: Do not save the payment method.
- `prompt`: Prompt to save the payment method to the customer specified.
Only applicable for `one_time` payments and if a customer has been
provided in the `customer_id` field. Defaults to `never`.
When `amount: 0` is set on a `one_time` session for payment method
verification, this field is implicitly `always` and does not need to be
supplied. If supplied, only `always` is accepted; other values are
rejected.
default: never
checkout_options_one_time:
title: Checkout Options
type: object
description: >-
Customisable options for the checkout page, including UI elements and
description text.
allOf:
- $ref: '#/components/schemas/checkout_options'
- type: object
properties:
save_payment_method:
$ref: '#/components/schemas/save_payment_method'
return_url:
$ref: '#/components/schemas/return_url'
additionalProperties: false
payment_options:
title: Payment Options
type: object
description: >
Payment specific options. These options are applied on the underlying
payment.
properties:
max_attempts:
type: integer
minimum: 1
description: >
Maximum number of payment attempts permitted for this payment. If
omitted or null, attempts are not limited (infinite). If set, the
platform will prevent new attempts once the limit is reached.
metadata:
$ref: '#/components/schemas/metadata_fields'
description: Key-value pairs for storing additional custom data on the payment.
additionalProperties: false
payment_method_options:
title: Payment Method Options
type: object
description: >
Payment-method specific options. These are best-effort and only apply if
the relevant payment method is used during the payment. For supported
`amount: 0` payment-method verification flows, any supplied
`card.capture_method` is ignored because the zero amount already signals
verification intent.
properties:
card:
type: object
description: |
Card specific options.
properties:
capture_method:
type: string
enum:
- automatic
- manual
default: automatic
description: >
Best-effort. Applies only when the payment method is card.
- `automatic`: capture immediately (sale/purchase behaviour)
- `manual`: authorise now and capture later via POST /collect/payments/{id}/captures
Available on card-backed `one_time`, `first_in_series`, and
`next_in_series` payments.
Ignored for supported `amount: 0` payment-method verification
flows.
example: manual
additionalProperties: false
example:
card:
capture_method: manual
additionalProperties: false
checkout_options_first_in_series:
title: Checkout Options
type: object
description: >-
Customisable options for the checkout page, including UI elements and
description text.
allOf:
- $ref: '#/components/schemas/checkout_options'
- type: object
properties:
return_url:
$ref: '#/components/schemas/return_url'
additionalProperties: false
mandate_options:
title: Mandate Options
description: >
Mandate specific options that define the customer's consent boundaries
and any additional constraints for future `next_in_series` payments.
Technical retries are handled internally. Business retries happen by
creating a new `next_in_series` at a later time and may be governed by
`retry_policy`. All fields are optional. Omitting `mandate_options`
entirely creates an unconstrained mandate with no declared type: valid
indefinitely, for any amount, with no consent boundaries recorded. This
is equivalent in effect to `type: on_demand` with no other fields set,
but without the explicit intent declaration. Setting `type` is
recommended to record the merchant's intent. Use `scheduled` for
recurring payments on a defined cadence, `on_demand` for
merchant-initiated collections with no fixed schedule.
oneOf:
- $ref: '#/components/schemas/mandate_options_on_demand'
- $ref: '#/components/schemas/mandate_options_scheduled'
- $ref: '#/components/schemas/mandate_options_installment'
subscription_options:
title: Subscription Options
type: object
description: >
Configuration options for creating a platform-managed subscription. When
provided, the platform will automatically schedule and execute future
`next_in_series` payments on the cadence defined by
`mandate_options.recurrence`. If omitted, no subscription is created and
the merchant must initiate each `next_in_series` payment manually. A
subscription always operates within the bounds of the associated
`mandate_options`. The mandate defines what the customer has authorised;
the subscription defines how the merchant schedules payments within that
authorisation.
properties:
active_period:
type: object
description: >
Defines the date range within which the subscription is active.
Payments will only be created within this window. If omitted, the
subscription inherits its window from
`mandate_options.validity_period`. If
`mandate_options.validity_period` is also not set, the subscription
starts immediately and has no defined end date. The active period
must fall within `mandate_options.validity_period`. The mandate
remains the authorisation ceiling and cannot be exceeded.
properties:
start_date:
type: string
description: >-
The date from which the subscription begins scheduling payments.
If omitted, defaults to the mandate's `start_date` or
immediately if no mandate start date is set.
format: date
end_date:
type: string
description: >-
The date after which no further payments are scheduled. If
omitted, defaults to the mandate's `end_date` or runs
indefinitely if no mandate end date is set.
format: date
additionalProperties: false
scheduled_time:
type: string
pattern: ^([01][0-9]|2[0-3]):[0-5][0-9]$
default: '00:00'
description: >
Time of day (HH:MM, 24-hour) at which scheduled collections are
executed. Evaluated in the timezone specified by
`mandate_options.timezone`. Defaults to 00:00 if not specified.
example: '09:00'
amount:
type: integer
minimum: 1
description: >
The fixed amount in the smallest currency unit that will be
collected in future payments.
If not specified, the amount is inferred from:
- mandate_options.amount (if a fixed amount is provided)
- session amount (if > 0)
For example, *20.00 ZAR* is represented as *2000 cents*.
Learn more about [minor
units](/api-reference/basics/monetary_amounts#minor-units-explained).
metadata:
$ref: '#/components/schemas/metadata_fields'
additionalProperties: false
attributes_recipient:
title: Recipient
description: >-
Identity of the payment recipient. Used for AML, PEP, and sanctions
screening.
type: object
additionalProperties: false
required:
- name
- country
properties:
name:
type: string
description: Full legal name of the recipient.
first_name:
type: string
description: >-
First name. Optional complement to `name` for providers that require
split name fields.
middle_name:
type: string
description: >-
Middle name. Used for identity disambiguation where first and last
name collisions are common.
last_name:
type: string
description: >-
Last name. Optional complement to `name` for providers that require
split name fields.
country:
$ref: '#/components/schemas/country_code'
description: Country of residence of the recipient.
date_of_birth:
type: string
format: date
description: >-
Date of birth in `yyyy-mm-dd` format. Required by some regulators
for age verification.
identification:
$ref: '#/components/schemas/attributes_identification'
address:
$ref: '#/components/schemas/address'
attributes_account:
title: Account
description: Wallet or account metadata for risk classification and program routing.
type: object
additionalProperties: false
properties:
type:
type: string
description: >-
Type of wallet or account (for example `savings`, `current`,
`ewallet`).
program:
type: string
description: Program or scheme identifier for the wallet or account.
attributes_gaming:
title: Gaming Compliance
description: >-
Responsible gambling and regulatory compliance attributes for gaming
deposits.
type: object
additionalProperties: false
required:
- kyc_status
- player_status
- deposit_limit_applied
properties:
kyc_status:
type: string
enum:
- verified
- pending
- unverified
description: KYC verification status of the player.
player_status:
type: string
enum:
- active
- suspended
- self_excluded
description: Account status of the player.
deposit_limit_applied:
type: boolean
description: >-
Whether deposit limits have been checked and applied for this
player.
tier:
type: string
description: Player classification or VIP tier.
checkout_options:
title: Checkout Options
type: object
description: >-
Customisable options for the checkout page, including UI elements and
description text.
properties:
description:
type: string
description: Additional text describing the payment.
example: Invoice Payment
metadata:
$ref: '#/components/schemas/metadata_fields'
description: Key-value pairs for storing additional custom data on the payment.
visible_payment_methods:
type: array
description: >
Controls which payment methods appear on the hosted checkout. For
full details and integration patterns, see [Integrate Specific
Payment
Methods](/api-reference/collect/payment_sessions/quickstart-control-payment-methods).
items:
type: string
description: The payment method identifier.
example: cards
selected_payment_method:
type: string
description: >
Pre-selects a payment method when the checkout loads. Accepts the
same formats as `visible_payment_methods`: a category (for example
`cards`), a type (for example `card`), or a category-qualified type
(for example `cards.card`). For full details, see [Integrate
Specific Payment
Methods](/api-reference/collect/payment_sessions/quickstart-control-payment-methods).
example: cards.card
display_fields:
type: array
description: >
Additional structured information displayed on the checkout page,
for example account number, invoice number, due date, etc.
items:
type: object
properties:
title:
type: string
description: The field identifier
example: Invoice number
description:
type: string
description: The field value
example: INV-20250101
example:
- title: Invoice number
description: INV-20250101
- title: Account number
description: ACC-001
- title: Due date
description: '2025-01-01'
presentation_mode:
allOf:
- $ref: '#/components/schemas/presentation_mode'
description: The presentation mode for the checkout session.
mandate_options_on_demand:
title: On-demand Mandate Options
description: >
Mandate options for on-demand collections where recurrence is not a
required part of the customer's consent. Use this type for
merchant-initiated payments such as variable recurring payments (VRP),
wallet top-ups, and usage-based billing. `recurrence` is optional:
include it if the merchant intends to collect on a consistent cadence
and wants providers to derive the implicit period window from it.
`subscription_options` may also be provided to automate scheduling.
type: object
required:
- type
properties:
type:
type: string
enum:
- on_demand
description: >
Identifies this as an on-demand mandate. The customer consents to
merchant-initiated collections within the defined constraints.
Recurrence is not required as part of the consent declaration.
amount:
$ref: '#/components/schemas/mandate_amount'
validity_period:
$ref: '#/components/schemas/mandate_validity_period'
max_occurrences:
type: integer
minimum: 1
description: >
Maximum number of future successful occurrences allowed under the
mandate. If not specified, occurrences are unlimited.
timezone:
allOf:
- $ref: '#/components/schemas/timezone'
description: >-
🚧 **Coming Soon.** The timezone used when evaluating allowed days
and period limits.
allowed_days:
allOf:
- $ref: '#/components/schemas/day_pattern'
description: >-
🚧 **Coming Soon.** Restricts collections to specific days of the
week or month.
spacing:
allOf:
- $ref: '#/components/schemas/mandate_spacing'
description: >-
🚧 **Coming Soon.** Enforces a minimum gap between consecutive
collections.
period_limits:
allOf:
- $ref: '#/components/schemas/mandate_period_limits'
description: >-
🚧 **Coming Soon.** Caps the number or total amount of collections
within a rolling or calendar period.
retry_policy:
allOf:
- $ref: '#/components/schemas/mandate_retry_policy'
description: >-
🚧 **Coming Soon.** Controls how failed collection attempts are
retried.
metadata:
$ref: '#/components/schemas/metadata_fields'
additionalProperties: false
mandate_options_scheduled:
title: Scheduled Mandate Options
description: >
Mandate options for scheduled recurring payments. The customer consents
to payments on an explicit cadence defined by `recurrence`. Use
`subscription_options` alongside this type to have the platform schedule
payments automatically.
type: object
required:
- type
- recurrence
properties:
type:
type: string
enum:
- scheduled
description: >
Identifies this as a scheduled mandate. The customer has consented
to payments on the cadence defined by `recurrence`.
amount:
$ref: '#/components/schemas/mandate_amount'
recurrence:
$ref: '#/components/schemas/recurrence'
description: >
The consented payment cadence. Defines how frequently the customer
has agreed to be charged. When `subscription_options` is provided,
the subscription uses this recurrence to schedule payments
automatically. Providers that do not support explicit period limits
derive the implicit period window from this interval combined with
the consented amount.
validity_period:
$ref: '#/components/schemas/mandate_validity_period'
max_occurrences:
type: integer
minimum: 1
description: >
Maximum number of future successful occurrences allowed under the
mandate. If not specified, occurrences are unlimited.
timezone:
allOf:
- $ref: '#/components/schemas/timezone'
description: 🚧 **Coming Soon.** The timezone used when evaluating period limits.
period_limits:
allOf:
- $ref: '#/components/schemas/mandate_period_limits'
description: >-
🚧 **Coming Soon.** Caps the number or total amount of collections
within a rolling or calendar period.
retry_policy:
allOf:
- $ref: '#/components/schemas/mandate_retry_policy'
description: >-
🚧 **Coming Soon.** Controls how failed collection attempts are
retried.
metadata:
$ref: '#/components/schemas/metadata_fields'
additionalProperties: false
mandate_options_installment:
title: Installment Mandate Options
description: >
🚧 **Coming Soon.** Mandate options for installment payment plans. The
customer consents to a defined number of payments totalling
`total_amount`, structured according to `terms`. Use `terms.type:
periodic` for equal payments on a regular cadence, or `terms.type:
fixed` for an explicit schedule with specific amounts and dates.
type: object
required:
- type
- total_amount
- terms
properties:
type:
type: string
enum:
- installment
description: >
Identifies this as an installment mandate. The customer consents to
a fixed payment plan totalling `total_amount`, structured by
`terms`.
total_amount:
type: integer
minimum: 1
description: >
The total amount the customer consents to across all installments,
in the smallest currency unit. For `terms.type: fixed`, this must
equal the sum of all `terms.items[*].amount` values. For
`terms.type: periodic` where `terms.amount` is omitted,
`total_amount` must be evenly divisible by `terms.max_occurrences`.
example: 100000
terms:
$ref: '#/components/schemas/installment_terms'
description: >
The payment structure for this installment plan. Defines how the
total amount is split and when each installment is due.
validity_period:
$ref: '#/components/schemas/mandate_validity_period'
timezone:
$ref: '#/components/schemas/timezone'
retry_policy:
$ref: '#/components/schemas/mandate_retry_policy'
metadata:
$ref: '#/components/schemas/metadata_fields'
additionalProperties: false
country_code:
title: Country Code
type: string
description: ISO 3166-1 alpha-2 country code.
pattern: ^[A-Z]{2}$
example: ZA
attributes_identification:
title: Identification
description: Identity document details for the recipient.
type: object
additionalProperties: false
properties:
type:
$ref: '#/components/schemas/identity_document_type'
description: Type of identity document.
number:
type: string
description: Identity document number.
issuing_country:
$ref: '#/components/schemas/country_code'
description: >-
Country that issued the identity document. May differ from `country`
for foreign nationals.
address:
title: Address
type: object
description: Postal address.
properties:
line1:
type: string
description: First line of the address (street, PO Box, etc.)
maxLength: 200
example: 123 Main Street
line2:
type: string
description: Second line of the address (apartment, suite, floor, etc.)
maxLength: 200
city:
type: string
description: City or locality.
maxLength: 100
state:
type: string
description: State, province, or region.
maxLength: 100
postal_code:
type: string
description: Postal code or ZIP code.
maxLength: 20
pin:
type: string
description: 'Deprecated: use `postal_code` instead.'
deprecated: true
maxLength: 20
country:
$ref: '#/components/schemas/country_code'
description: Country of the address.
additionalProperties: false
presentation_mode:
title: Presentation Mode
description: |
Controls how the checkout UI is presented.
oneOf:
- $ref: '#/components/schemas/presentation_mode_redirect'
- $ref: '#/components/schemas/presentation_mode_embedded_modal'
- $ref: '#/components/schemas/presentation_mode_embedded_inline'
mandate_amount:
title: Mandate Amount
description: >
The per-payment amount constraint the customer consents to. Either a
fixed amount or a variable range with a minimum and/or maximum.
oneOf:
- type: integer
minimum: 1
description: >
The fixed amount in the smallest currency unit that may be collected
in future payments. If not specified, the `amount` from the
originating `first_in_series` session is used as the consent ceiling
and applies to all subsequent `next_in_series` payments under this
mandate. This fallback does not apply when the originating session
has `amount: 0` (payment method verification): in that case
`mandate_options.amount` must be provided explicitly, otherwise the
consent ceiling would be 0 and no future payment could be collected.
example: 1000
- type: object
description: >
A variable-amount mandate. Specifies the minimum and/or maximum that
may be collected in future payments, in the smallest currency unit.
At least one of `min` or `max` must be provided, and `min` must not
exceed `max`.
properties:
min:
type: integer
minimum: 1
description: >-
Minimum allowed amount in minor units. Must not exceed `max` if
both are provided.
max:
type: integer
minimum: 1
description: >-
Maximum allowed amount in minor units. Must not be less than
`min` if both are provided.
additionalProperties: false
mandate_validity_period:
title: Mandate Validity Period
description: The date range during which the mandate is considered active.
type: object
properties:
start_date:
type: string
format: date
description: >
Mandate validity start date (inclusive). If not specified, the
mandate is active immediately from the date of creation. When
`period_limits` is also set, align `start_date` with your period
boundary to ensure the first window is a full period and the mandate
active date and window start are in sync.
end_date:
type: string
format: date
description: >-
Mandate validity end date (inclusive). If not specified, the mandate
does not expire.
additionalProperties: false
example:
start_date: '2026-01-01'
end_date: '2026-12-31'
timezone:
title: Timezone
type: string
description: >
IANA timezone identifier used when evaluating date and time boundaries.
Defaults to UTC if not specified.
example: Africa/Johannesburg
day_pattern:
title: Day Pattern
description: >
Specifies one or more days within a time interval a payment applies to.
Used as an execution constraint in `mandate_options.allowed_days` to
restrict which days charges may fall on.
oneOf:
- $ref: '#/components/schemas/day_of_month'
- $ref: '#/components/schemas/day_of_week'
- $ref: '#/components/schemas/day_of_year'
- $ref: '#/components/schemas/nth_day_of_month'
mandate_spacing:
title: Mandate Spacing
description: >
Optional spacing constraints between successful payments under the
mandate. Controls the minimum and maximum number of calendar days
allowed between collections.
type: object
properties:
min_interval_days:
type: integer
minimum: 1
description: >
Minimum spacing, in whole calendar days, between successful
payments. If not specified, no minimum spacing is enforced.
max_interval_days:
type: integer
minimum: 1
description: >
Maximum spacing, in whole calendar days, between successful
payments. If not specified, no maximum spacing is enforced.
additionalProperties: false
example:
min_interval_days: 7
max_interval_days: 31
mandate_period_limits:
title: Mandate Period Limits
description: >
Optional limits applied to successful payments within a defined period
window. Limits are enforced in addition to per-payment amount
constraints. All mandate constraints are cumulative (AND logic). When
using period limits, align `validity_period.start_date` with the period
boundary to ensure the first window is a full period. If they are
misaligned, the first window may be partial and charges could occur
closer together than expected across the boundary.
type: object
required:
- period
properties:
period:
type: string
enum:
- day
- week
- month
- year
description: The calendar unit that defines each limit window.
period_length:
type: integer
minimum: 1
default: 1
description: >
Multiplier for `period`. For example, `period: month, period_length:
3` defines a 3-month window. Defaults to 1.
max_count:
type: integer
minimum: 1
description: >
Maximum number of successful payments allowed within the period
window. If not specified, no count limit is applied.
max_amount:
type: integer
minimum: 1
description: >
Maximum total amount, in minor units, across successful payments
within the period window. If not specified, no amount limit is
applied. When both `max_amount` and a per-payment `amount.max` are
set, `max_amount` must be greater than or equal to `amount.max`,
since it represents a cumulative ceiling across multiple payments
within the window. When set, providers receive `max_amount` as the
collection ceiling for the period. When not set, some providers
derive the ceiling from `amount` (fixed) or `amount.max` (variable),
with the `recurrence` interval defining the implicit period window.
window:
$ref: '#/components/schemas/period_limit_window'
additionalProperties: false
example:
period: month
max_count: 2
max_amount: 50000
window:
mode: cycle
anchor:
type: day_of_month
day: 1
mandate_retry_policy:
title: Mandate Retry Policy
description: >
Optional business retry policy for failed collections. Retries are
expressed as additional `next_in_series` payments initiated later, not
automatic re-attempts within a single payment.
type: object
properties:
max_retries:
type: integer
minimum: 0
description: >
Maximum number of additional retry attempts allowed after a failed
collection. If not specified, retries are unlimited.
min_days_between_retries:
type: integer
minimum: 1
description: >
Minimum number of calendar days required between consecutive retry
attempts. If not specified, no minimum gap is enforced.
max_days_since_failure:
type: integer
minimum: 1
description: >
Maximum number of calendar days after the original failed collection
during which retries may occur. If not specified, retries may occur
indefinitely.
additionalProperties: false
example:
max_retries: 3
min_days_between_retries: 3
max_days_since_failure: 30
recurrence:
title: Recurrence
description: >
Defines how frequently payments are created while the subscription is
active. Each type bundles the interval with its valid scheduling
options, preventing invalid combinations.
oneOf:
- $ref: '#/components/schemas/recurrence_daily'
- $ref: '#/components/schemas/recurrence_weekly'
- $ref: '#/components/schemas/recurrence_monthly'
- $ref: '#/components/schemas/recurrence_yearly'
installment_terms:
title: Installment Terms
description: >
Defines the payment structure for an installment mandate. Use `periodic`
for equal payments on a regular cadence, or `fixed` for an explicit
schedule with specific amounts and dates per installment.
oneOf:
- $ref: '#/components/schemas/installment_terms_periodic'
- $ref: '#/components/schemas/installment_terms_fixed'
identity_document_type:
title: Identity Document Type
type: string
description: Type of identity document used for KYC and AML verification.
enum:
- national_id
- passport
- drivers_license
- asylum_seeker_permit
- other
presentation_mode_redirect:
title: Redirect Mode
description: >-
Customer is redirected to a separate checkout page hosted by Moment to
complete the payment.
type: object
required:
- mode
properties:
mode:
type: string
enum:
- redirect
additionalProperties: false
example:
mode: redirect
presentation_mode_embedded_modal:
title: Embedded Modal Mode
description: Checkout is rendered within the merchant's website as a modal overlay.
type: object
required:
- mode
- variant
properties:
mode:
type: string
enum:
- embedded
variant:
type: string
enum:
- modal
additionalProperties: false
example:
mode: embedded
variant: modal
presentation_mode_embedded_inline:
title: Embedded Inline Mode
description: >-
Checkout is rendered inline within the merchant's website. Supports
additional presentation options.
type: object
required:
- mode
- variant
properties:
mode:
type: string
enum:
- embedded
variant:
type: string
enum:
- inline
options:
type: object
description: Additional presentation controls for inline embedded checkout.
additionalProperties: false
properties:
display_pay_button:
type: boolean
default: true
description: >-
Controls visibility of the Pay button inside the checkout UI.
Defaults to true.
additionalProperties: false
example:
mode: embedded
variant: inline
options:
display_pay_button: false
day_of_month:
title: Day of Month
description: >
Targets specific calendar days within each month. For example, `days:
[1, 15]` targets the 1st and 15th of each month.
type: object
required:
- type
- days
properties:
type:
type: string
enum:
- day_of_month
days:
type: array
minItems: 1
uniqueItems: true
description: >
Target days within each month. Integer values are capped at 28 to
avoid ambiguity in shorter months; use "last" for end-of-month.
items:
oneOf:
- type: integer
minimum: 1
maximum: 28
- type: string
enum:
- last
adjustment:
$ref: '#/components/schemas/weekday_adjustment'
default: none
additionalProperties: false
example:
type: day_of_month
days:
- 1
- 15
adjustment: none
day_of_week:
title: Day of Week
description: >
Targets specific days of the week. For example, `days: [mon, wed]`
targets Mondays and Wednesdays.
type: object
required:
- type
- days
properties:
type:
type: string
enum:
- day_of_week
days:
type: array
minItems: 1
uniqueItems: true
description: Target days of the week.
items:
$ref: '#/components/schemas/day_name'
additionalProperties: false
example:
type: day_of_week
days:
- mon
- wed
- fri
day_of_year:
title: Day of Year
description: >
Targets one or more specific calendar dates within each year. For
example, `dates: [{month: 1, day: 15}, {month: 7, day: 1}]` targets
January 15th and July 1st each year.
type: object
required:
- type
- dates
properties:
type:
type: string
enum:
- day_of_year
dates:
type: array
minItems: 1
uniqueItems: true
description: Target dates within each year.
items:
type: object
required:
- month
- day
properties:
month:
type: integer
minimum: 1
maximum: 12
description: The month of the year (1–12).
day:
oneOf:
- type: integer
minimum: 1
maximum: 28
- type: string
enum:
- last
description: >-
The day of the month (1–28). Capped at 28 to avoid ambiguity
in shorter months; use "last" for end-of-month.
additionalProperties: false
adjustment:
$ref: '#/components/schemas/weekday_adjustment'
default: none
additionalProperties: false
example:
type: day_of_year
dates:
- month: 1
day: 15
- month: 7
day: 1
nth_day_of_month:
title: Nth Day of Month
description: >
Targets a specific day occurrence within each month. For example, `day:
mon, occurrence: 2` targets the second Monday of each month.
type: object
required:
- type
- day
- occurrence
properties:
type:
type: string
enum:
- nth_day_of_month
day:
$ref: '#/components/schemas/day_name'
occurrence:
oneOf:
- type: integer
minimum: 1
maximum: 5
- type: string
enum:
- last
description: >-
Which occurrence of the day within the month. 1–5 for first through
fifth, or "last" for the last.
additionalProperties: false
example:
type: nth_day_of_month
day: mon
occurrence: 2
period_limit_window:
title: Period Limit Window
description: >
Controls how the period limit window is aligned in time. Use `calendar`
(default) to align to standard calendar boundaries. Use `cycle` to align
to an explicit anchor date. If not specified, defaults to `calendar`
mode.
oneOf:
- $ref: '#/components/schemas/period_limit_window_calendar'
- $ref: '#/components/schemas/period_limit_window_cycle'
recurrence_daily:
title: Daily Recurrence
description: Schedules payments every N days.
type: object
required:
- type
- interval_count
properties:
type:
type: string
enum:
- daily
interval_count:
type: integer
minimum: 1
description: Number of days between payments.
additionalProperties: false
example:
type: daily
interval_count: 1
recurrence_weekly:
title: Weekly Recurrence
description: >-
Schedules payments every N weeks, optionally on specific days of the
week.
type: object
required:
- type
- interval_count
properties:
type:
type: string
enum:
- weekly
interval_count:
type: integer
minimum: 1
description: Number of weeks between payment cycles.
'on':
type: object
description: >
Targets specific days of the week within each cycle. If omitted,
payments are scheduled on the day of the week the subscription
starts.
properties:
days:
type: array
minItems: 1
uniqueItems: true
description: >
Days of the week on which payments are scheduled. Each specified
day produces a separate payment within the cycle.
items:
$ref: '#/components/schemas/day_name'
required:
- days
additionalProperties: false
additionalProperties: false
example:
type: weekly
interval_count: 1
'on':
days:
- mon
- fri
recurrence_monthly:
title: Monthly Recurrence
description: >-
Schedules payments every N months, optionally on a specific day or
occurrence within the month.
type: object
required:
- type
- interval_count
properties:
type:
type: string
enum:
- monthly
interval_count:
type: integer
minimum: 1
description: Number of months between payment cycles.
'on':
description: >
Specifies which day(s) within each month payments are scheduled on.
If omitted, payments are scheduled on the same calendar day the
subscription starts.
oneOf:
- $ref: '#/components/schemas/day_of_month'
- $ref: '#/components/schemas/nth_day_of_month'
additionalProperties: false
example:
type: monthly
interval_count: 1
'on':
type: day_of_month
days:
- 1
- 15
adjustment: nearest_weekday
recurrence_yearly:
title: Yearly Recurrence
description: >-
Schedules payments every N years, optionally on specific date(s) within
the year.
type: object
required:
- type
- interval_count
properties:
type:
type: string
enum:
- yearly
interval_count:
type: integer
minimum: 1
description: Number of years between payment cycles.
'on':
$ref: '#/components/schemas/day_of_year'
description: >
Specifies which date(s) within each year payments are scheduled on.
If omitted, payments are scheduled on the anniversary of the
subscription start date.
additionalProperties: false
example:
type: yearly
interval_count: 1
'on':
type: day_of_year
dates:
- month: 1
day: 15
installment_terms_periodic:
title: Periodic Installment Terms
description: >
Installment terms for equal payments on a regular cadence. The cadence
is defined by `recurrence` and the exact number of installments by
`max_occurrences`. The schema enforces both as required, ensuring the
full payment schedule is unambiguous at consent time.
type: object
required:
- type
- recurrence
- max_occurrences
properties:
type:
type: string
enum:
- periodic
description: Identifies these as periodic installment terms.
recurrence:
$ref: '#/components/schemas/recurrence'
description: >
The payment cadence. Defines how frequently installments are
collected. Reuses the same recurrence types as `scheduled` mandates.
max_occurrences:
type: integer
minimum: 2
description: >
The exact number of installments in the plan. Required for periodic
terms. Together with `recurrence`, fully defines the payment
schedule. Must be at least 2 — a single payment is not an
installment plan.
amount:
type: integer
minimum: 1
description: >
The amount collected per installment, in the smallest currency unit.
If not specified, the per-installment amount is derived from
`total_amount / max_occurrences`. When omitted, `total_amount` must
be evenly divisible by `max_occurrences`.
example: 25000
additionalProperties: false
example:
type: periodic
recurrence:
type: monthly
interval_count: 1
'on':
type: day_of_month
days:
- 1
adjustment: nearest_weekday
max_occurrences: 4
amount: 25000
installment_terms_fixed:
title: Fixed Installment Terms
description: >
Installment terms for an explicit schedule with specific amounts and due
dates per installment. Use when the payment plan is irregular or amounts
vary across installments. The sum of all `items[*].amount` values must
equal `mandate_options.total_amount`.
type: object
required:
- type
- items
properties:
type:
type: string
enum:
- fixed
description: Identifies these as fixed installment terms.
adjustment:
$ref: '#/components/schemas/weekday_adjustment'
description: >
Adjustment applied when a due date falls on a weekend. Applies
uniformly to all installment items. Defaults to `none`.
recurrence:
type: object
description: >
Optional provider cadence hint. Required when using payment
providers that need a declared collection interval for mandate
registration (such as Capitec VRP). Has no scheduling role: payment
dates are defined by `items`. The platform derives `amount.max` for
provider registration from the maximum of `items[*].amount`.
required:
- type
- interval_count
properties:
type:
type: string
enum:
- daily
- weekly
- monthly
- yearly
description: The cadence unit for the installment plan.
interval_count:
type: integer
minimum: 1
description: Number of units between installments.
additionalProperties: false
items:
type: array
minItems: 2
description: >
The explicit installment schedule. Each entry defines the amount and
due date for one installment. Must contain at least 2 items. The sum
of all `amount` values must equal `mandate_options.total_amount`.
items:
$ref: '#/components/schemas/installment_item'
additionalProperties: false
example:
type: fixed
adjustment: none
items:
- amount: 30000
due_date: '2026-04-01'
- amount: 30000
due_date: '2026-05-01'
- amount: 40000
due_date: '2026-06-01'
weekday_adjustment:
title: Weekday Adjustment
type: string
enum:
- none
- nearest_weekday
- previous_weekday
- next_weekday
description: >
Adjustment applied when a scheduled day falls on a weekend. Defaults to
`none` if not specified. Weekday means Monday through Friday. Bank
holidays are not considered.
day_name:
title: Day Name
type: string
enum:
- mon
- tue
- wed
- thu
- fri
- sat
- sun
description: ISO day of week abbreviation, covering all seven days.
period_limit_window_calendar:
title: Calendar Window
description: >
Aligns the period limit window to standard calendar boundaries. For
example, a monthly window resets on the 1st of each month.
type: object
required:
- mode
properties:
mode:
type: string
enum:
- calendar
additionalProperties: false
example:
mode: calendar
period_limit_window_cycle:
title: Cycle Window
description: >
Aligns the period limit window to an explicit anchor date. For example,
a monthly window anchored to the 15th resets on the 15th of each month,
regardless of when the mandate was created. Timezone evaluation is
governed by the `timezone` field on `mandate_options`.
type: object
required:
- mode
- anchor
properties:
mode:
type: string
enum:
- cycle
anchor:
$ref: '#/components/schemas/mandate_anchor'
additionalProperties: false
example:
mode: cycle
anchor:
type: day_of_month
day: 15
installment_item:
title: Installment Item
description: >
A single installment in a fixed payment schedule, defining the amount
and due date.
type: object
required:
- amount
- due_date
properties:
amount:
type: integer
minimum: 1
description: >
The amount to collect for this installment, in the smallest currency
unit.
example: 30000
due_date:
type: string
format: date
description: >
The date on which this installment is due. Subject to the
`adjustment` defined on the parent `terms` object if the date falls
on a weekend.
example: '2026-04-01'
additionalProperties: false
mandate_anchor:
title: Mandate Anchor
description: >-
The anchor date for the cycle window. Only relevant when `mode` is
`cycle`.
oneOf:
- $ref: '#/components/schemas/mandate_anchor_day_of_month'
- $ref: '#/components/schemas/mandate_anchor_day_of_year'
mandate_anchor_day_of_month:
title: Day of Month Anchor
type: object
required:
- type
- day
description: >
Anchors the cycle window to a specific day of each month. Common use
cases include monthly subscriptions billed on the 1st, mid-month billing
cycles on the 15th, or end-of-month charges using `"last"`. If the
anchor falls on a weekend, the `adjustment` field controls how it is
shifted.
example:
type: day_of_month
day: 15
adjustment: none
properties:
type:
type: string
enum:
- day_of_month
day:
oneOf:
- type: integer
minimum: 1
maximum: 28
- type: string
enum:
- last
description: Day of the month, 1–28, or "last" for the final calendar day.
adjustment:
$ref: '#/components/schemas/weekday_adjustment'
default: none
additionalProperties: false
mandate_anchor_day_of_year:
title: Day of Year Anchor
type: object
required:
- type
- month
- day
description: >
Anchors the cycle window to a specific day of a given month each year.
Common use cases include annual subscriptions renewing on January 1st,
fiscal-year billing aligned to April 1st, or policy renewals on a fixed
calendar date. Use `"last"` to anchor to the final calendar day of the
specified month. The `adjustment` field controls shifting when the
anchor falls on a weekend.
example:
type: day_of_year
month: 4
day: 1
adjustment: none
properties:
type:
type: string
enum:
- day_of_year
month:
type: integer
minimum: 1
maximum: 12
day:
oneOf:
- type: integer
minimum: 1
maximum: 28
- type: string
enum:
- last
description: >-
Day of the month, 1–28, or "last" for the final calendar day of the
specified month.
adjustment:
$ref: '#/components/schemas/weekday_adjustment'
default: none
additionalProperties: false
examples:
one_time_minimal:
value:
amount: 200
currency: ZAR
one_time_detailed_request:
value:
amount: 100
currency: ZAR
type: one_time
options:
customer:
name: Lara
email: lara@gmail.com
phone: '+97121123331'
external_reference: merchant_customer_id_1
checkout_options:
return_url: https://callback.merchant-shop.com
external_reference: merchant_order_id_1234
metadata:
card_id: card_123
session_id: session123
customer_id: mercahant_customer_id
first_in_series_minimal:
value:
amount: 50
currency: ZAR
type: first_in_series
options:
customer:
name: Alex
next_in_series_request:
value:
amount: 300
currency: ZAR
type: next_in_series
options:
customer: cus_eFsFeDWsLiDkvt
payment_method: pmt_izWG6Vcvy4VYiU
first_in_series_on_demand_mandates:
value:
amount: 2000
currency: ZAR
type: first_in_series
external_reference: order_12345
options:
customer:
name: John Doe
mandate_options:
type: on_demand
amount:
min: 1000
max: 30000
validity_period:
start_date: '2026-04-29'
end_date: '2027-04-29'
first_in_series_scheduled_mandates:
value:
amount: 30000
currency: ZAR
type: first_in_series
external_reference: order_12345
options:
customer:
name: John Doe
mandate_options:
type: scheduled
recurrence:
type: weekly
interval_count: 1
amount:
min: 1000
max: 30000
validity_period:
start_date: '2026-04-29'
end_date: '2027-04-29'
one_time_session_created_response:
description: One-time Payment session created
summary: Example of a created one-time payment session
value:
id: ps_kfAWZgfQIoeG0q
type: one_time
amount: 50
currency: ZAR
status: active
payment_status: unpaid
payment_outcome: not_started
checkout_session_id: ckt802zEb2P2uS4Ql
session_url: https://moment.momentpay.io/checkout/ckt802zEb2P2uS4Ql
mode: live
created_at: '2025-03-18T14:06:51.149Z'
updated_at: '2025-03-18T14:06:51.149Z'
one_time_detailed_session_created_response:
description: One-time Payment session created
summary: Example of a created one-time payment session
value:
id: ps_6UL2mRuMtDnxC9
type: one_time
amount: 100
currency: ZAR
status: active
payment_status: unpaid
payment_outcome: not_started
customer_id: cus_P4Nl9MKdh7RhT
checkout_session_id: cktNnkWtk7p5GJd85
session_url: https://moment.momentpay.io/checkout/cktNnkWtk7p5GJd85
return_url: https://callback.merchant-shop.com
mode: live
external_reference: merchant_order_id_1234
metadata:
card_id: card_123
session_id: session123
customer_id: mercahant_customer_id
created_at: '2025-03-19T08:24:56.501Z'
updated_at: '2025-03-19T08:24:56.501Z'
first_in_series_session_created_response:
summary: Example of a created first_in_series payment session
value:
id: ps_eLtQXMBUErQF5i
type: first_in_series
amount: 50
currency: ZAR
status: active
payment_status: unpaid
payment_outcome: not_started
customer_id: cus_J17pnG25nuvKu
checkout_session_id: cktaoPzVYDN0rI7FH
session_url: https://moment.momentpay.io/checkout/cktaoPzVYDN0rI7FH
mode: live
created_at: '2025-03-18T14:13:51.379Z'
updated_at: '2025-03-18T14:13:51.379Z'
next_in_series_session_created_response:
summary: Example of a created next_in_series payment session
description: Next In Series Payment session created
value:
id: ps_aWICss5eVG0IWZ
type: next_in_series
amount: 100
currency: ZAR
status: active
payment_status: unpaid
payment_outcome: not_started
customer_id: cus_eFsFeDWsLiDkvt
payment_id: pay_a499a1377caf6a04d29bd3248a0d182c
mode: live
created_at: '2025-03-19T07:18:22.986Z'
updated_at: '2025-03-19T07:18:22.986Z'
first_in_series_on_demand_mandates_created_response:
summary: Example of a created first_in_series payment session
value:
id: ps_hjVjP18RKxsCEJ
type: first_in_series
amount: 2000
currency: ZAR
status: active
payment_status: unpaid
payment_outcome: not_started
customer_id: cus_L1j0MRPl4CaZuyskysd2
checkout_session_id: ckt4MtgnWtU28xxz
session_url: https://moment.momentpay.io/checkout/ckt4MtgnWtU28xxz
mode: live
external_reference: order_12345
created_at: '2026-04-28T14:41:15.424Z'
updated_at: '2026-04-28T14:41:15.424Z'
first_in_series_scheduled_mandates_created_response:
summary: Example of a created first_in_series payment session
value:
id: ps_hjVjP18RKxsCEJ
type: first_in_series
amount: 30000
currency: ZAR
status: active
payment_status: unpaid
payment_outcome: not_started
customer_id: cus_L1j0MRPl4CaZuysky5V8q
checkout_session_id: ckt4MtgnWtUY4mZun
session_url: https://moment.momentpay.io/checkout/ckt4MtgnWtUY4mZun
mode: live
external_reference: order_12345
created_at: '2026-04-28T14:41:15.424Z'
updated_at: '2026-04-28T14:41:15.424Z'
headers:
request_id:
description: >
A unique identifier for the request, used for tracing and debugging
purposes.
This `Request-Id` is included in every response to enable request
tracing across multiple services or systems.
It helps correlate logs and track the flow of requests through
distributed systems.
The value is typically a universally unique identifier (UUID) to ensure
uniqueness across requests.
schema:
type: string
examples:
- 63efe730-f599-40a5-afb7-9dda5fc31773
responses:
bad_request:
description: Invalid input or parameters
content:
application/json:
schema:
$ref: '#/components/schemas/problem_detail'
example:
type: https://docs.momentco.io/errors/bad_request
title: Invalid Request
status: 400
detail: The currency field must be a valid ISO 4217 currency code.
instance: /payment_sessions
headers:
Request-Id:
$ref: '#/components/headers/request_id'
unauthorized:
description: Authentication required
content:
application/json:
schema:
$ref: '#/components/schemas/problem_detail'
example:
type: https://docs.momentco.io/errors/unauthorized
title: Unauthorized
status: 401
detail: The API key provided is invalid.
instance: /payment_sessions
headers:
Request-Id:
$ref: '#/components/headers/request_id'
conflict:
description: Conflict in the request
content:
application/json:
schema:
$ref: '#/components/schemas/problem_detail'
example:
type: https://docs.momentco.io/errors/conflict
title: Conflict
status: 409
detail: A payment session with the same idempotency key already exists.
instance: /payment_sessions
headers:
Request-Id:
$ref: '#/components/headers/request_id'
internal_server_error:
description: Unexpected server error
content:
application/json:
schema:
$ref: '#/components/schemas/problem_detail'
example:
type: https://docs.momentco.io/errors/internal_server_error
title: Internal Server Error
status: 500
detail: An unexpected error occurred. Please try again later.
instance: /payment_sessions
headers:
Request-Id:
$ref: '#/components/headers/request_id'
securitySchemes:
bearer_auth:
type: http
scheme: bearer
bearerFormat: JWT
description: >
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](/documentation/support) to
request your API keys.
**Usage:**
```http
Authorization: Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc
```
````