> ## 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 Request > Creates a new Payment Request for collecting payments from customers. ## OpenAPI ````yaml POST /collect/payment_requests openapi: 3.1.0 info: version: 1.0.0 title: Payment Requests API description: > # Payment Requests API The Payment Requests API enables merchants to create, manage, and track Payment Requests for collecting payments from customers. contact: name: Moment url: https://momentco.net email: support@momentco.net servers: - url: https://api.momentpay.net description: Production server security: - BearerAuth: [] tags: - name: Payment Requests description: > Payment Requests allow you to collect payments from customers by sharing a URL that directs them to a secure payment page. - name: Webhooks description: > Webhook events that notify your application of changes to Payment Requests in real-time. Configure webhook endpoints in your merchant dashboard to receive these notifications. externalDocs: description: API documentation url: https://docs.momentco.io paths: /collect/payment_requests: post: tags: - Payment Requests summary: Create Payment Request description: | Creates a new Payment Request for collecting payments from customers. operationId: create_payment_request parameters: - $ref: '#/components/parameters/idempotency_key' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/create_payment_request' examples: Minimal Link Request: summary: Minimal link request (type defaults to link) description: Required fields only; `expires_at` will default to 24h. value: amount: 10000 currency: ZAR Detailed Link Request: summary: Link request with metadata and explicit expiry description: Includes optional fields; overrides default 24h expiry. value: amount: 10000 currency: ZAR external_reference: INV-20240617-XYZ description: Payment for invoice INV-20240617-XYZ expires_at: '2025-07-17T23:59:59Z' metadata: customer_name: John Doe order_type: Subscription sales_agent: AGT-9283 Push Request: summary: Push request via Capitec banking app description: > Customer approves in Capitec app; `expires_at` will default to 2 minutes if omitted. value: amount: 15000 type: push currency: ZAR description: Phone order (push) push: provider: capitec capitec: phone_number: '+27823778084' metadata: customer_id: cust_654321 order_id: ord_210987 responses: '201': $ref: '#/components/responses/payment_request_created' '400': $ref: '#/components/responses/bad_request' '401': $ref: '#/components/responses/unauthorized' '409': $ref: '#/components/responses/conflict' '500': $ref: '#/components/responses/internal_server_error' 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: create_payment_request: type: object description: | Request payload for creating a new Payment Request. If `type` is omitted, it defaults to `link`. - Link: `expires_at` defaults to 24h (see ExpiresAt). - Push: `expires_at` defaults to 2 minutes (see ExpiresAt). oneOf: - title: Link Request type: object properties: type: type: string enum: - link default: link amount: $ref: '#/components/schemas/amount' currency: $ref: '#/components/schemas/currency' external_reference: $ref: '#/components/schemas/external_reference' description: $ref: '#/components/schemas/description' expires_at: $ref: '#/components/schemas/expires_at' metadata: $ref: '#/components/schemas/metadata_fields' required: - amount - currency additionalProperties: false - title: Push Request type: object properties: type: type: string enum: - push amount: $ref: '#/components/schemas/amount' currency: $ref: '#/components/schemas/currency' external_reference: $ref: '#/components/schemas/external_reference' description: $ref: '#/components/schemas/description' expires_at: $ref: '#/components/schemas/expires_at' metadata: $ref: '#/components/schemas/metadata_fields' push: $ref: '#/components/schemas/payment_request_push_details' required: - type - amount - currency - push additionalProperties: false 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 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 description: type: string description: Human-readable description of what the payment is for maxLength: 500 example: Product purchase expires_at: type: string format: date-time description: | ISO 8601 timestamp indicating when the Payment Request expires. **Defaults (if not provided):** - **Link (`type=link` or omitted):** 24 hours from `created_at` - **Push (`type=push`):** 2 minutes from `created_at` Must be in the future when creating or updating. example: '2025-06-17T10:30:00Z' x-default-link-ttl: PT24H x-default-push-ttl: PT2M 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 payment_request_push_details: type: object description: > Details for push (bank) payment requests. Uses a provider-specific sub-object. **Beta — only Capitec is supported.** properties: provider: type: string description: Payment push provider. enum: - capitec example: capitec capitec: type: object description: >- Fields required by the Capitec provider. This is dependent on the provider name. properties: phone_number: type: string description: Customer phone number in E.164 format. pattern: ^\+[1-9]\d{1,14}$ example: '+27823778084' required: - phone_number additionalProperties: false required: - provider - capitec additionalProperties: false payment_request: type: object description: > A Payment Request represents a request for payment that can be shared via a link or sent to a banking app for authorization and Payment. properties: id: $ref: '#/components/schemas/payment_request_id' type: type: string description: Delivery mode of the payment request. enum: - link - push default: link status: $ref: '#/components/schemas/payment_request_status' enum: - active - paid - expired - failed payment_id: $ref: '#/components/schemas/payment_id' description: Associated payment ID when the request has been paid. amount: $ref: '#/components/schemas/amount' currency: $ref: '#/components/schemas/currency' external_reference: $ref: '#/components/schemas/external_reference' expires_at: $ref: '#/components/schemas/expires_at' description: $ref: '#/components/schemas/description' link: $ref: '#/components/schemas/payment_request_link_details' push: $ref: '#/components/schemas/payment_request_push_details' metadata: $ref: '#/components/schemas/metadata_fields' created_at: $ref: '#/components/schemas/created_at' updated_at: $ref: '#/components/schemas/updated_at' required: - id - type - status - amount - currency - created_at - updated_at additionalProperties: false example: id: pr_6phg74i4jG9wbzZbFDUQB status: active payment_id: p_xyz789abc123def456 type: link amount: 1000 currency: ZAR external_reference: INV-2024-001 expires_at: '2025-06-17T10:30:00Z' description: Product purchase link: checkout_session_id: chk_456789abc123def url: https://links.momentpay.io/zZbFDUQB metadata: customer_id: cust_123456 order_id: ord_789012 created_at: '2025-06-16T10:30:00Z' updated_at: '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. payment_request_id: type: string description: Unique identifier for the Payment Request. example: pr_6phg74i4jG9wbzZbFDUQB payment_request_status: type: string description: | Current status of the Payment Request. - **Link:** `active`, `paid`, `expired` - **Push:** `active`, `paid`, `expired`, `failed` enum: - active - paid - expired - failed example: active payment_id: type: string description: Unique identifier for a payment example: p_xyz789abc123def456 payment_request_link_details: type: object description: Details for link-based payment requests. properties: checkout_session_id: type: string description: Checkout session token for processing. example: chk_456789abc123def url: type: string format: uri description: The URL where customers can complete the payment. pattern: ^https://links\.momentpay\.io/[a-zA-Z0-9]+$ example: https://links.momentpay.io/zZbFDUQB 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' responses: payment_request_created: description: Payment Request created successfully content: application/json: schema: $ref: '#/components/schemas/payment_request' examples: Minimal Link Request: summary: Payment Request that is link-based description: Example of a freshly created link-based Payment Request value: id: pr_6phg74i4jG9wbzZbFDUQB type: link status: active amount: 10000 currency: ZAR external_reference: INV-2024-001 description: Product purchase expires_at: '2025-06-17T10:30:00Z' link: checkout_session_id: chk_G9wbzZbFDUQBFAE url: https://links.momentpay.io/G9wbzZbFDUQBFAE metadata: customer_id: cust_123456 order_id: ord_789012 created_at: '2025-06-16T10:30:00Z' updated_at: '2025-06-16T10:30:00Z' Detailed Link Request: summary: Payment Request that is link-based description: Example of a freshly created link-based Payment Request value: id: pr_6phg74i4jG9wbzZbFDUQB type: link status: active amount: 10000 currency: ZAR external_reference: INV-2024-001 description: Product purchase expires_at: '2025-06-17T10:30:00Z' link: checkout_session_id: chk_G9wbzZbFDUQBFAE url: https://links.momentpay.io/G9wbzZbFDUQBFAE metadata: customer_id: cust_123456 order_id: ord_789012 created_at: '2025-06-16T10:30:00Z' updated_at: '2025-06-16T10:30:00Z' Push Request: summary: Payment Request that is push-based description: >- Example of a freshly created push-based Payment Request via Capitec value: id: pr_9jkL01mNoPqRsTuVwXyZ status: active amount: 10000 type: push currency: ZAR external_reference: INV-2024-002 description: Phone order push: provider: capitec capitec: phone_number: '+27823778084' metadata: customer_id: cust_654321 order_id: ord_210987 created_at: '2025-06-16T11:00:00Z' updated_at: '2025-06-16T11:00:00Z' headers: Request-Id: $ref: '#/components/headers/request_id' Idempotent-Replayed: $ref: '#/components/headers/idempotent_replayed' bad_request: description: Bad Request - Invalid request parameters or malformed request content: application/problem+json: schema: $ref: '#/components/schemas/problem_detail' examples: Invalid Currency: summary: Invalid currency code value: type: https://docs.momentco.io/errors/bad-request title: Bad Request status: 400 detail: The currency field must be a valid ISO 4217 currency code. instance: /collect/payment_request code: bad_request Invalid Amount: summary: Invalid amount value: type: https://docs.momentco.io/errors/bad-request title: Bad Request status: 400 detail: The amount field must be a positive integer. instance: /collect/payment_request code: bad_request headers: Request-Id: $ref: '#/components/headers/request_id' unauthorized: description: Unauthorized - Invalid or missing authentication credentials content: application/problem+json: schema: $ref: '#/components/schemas/problem_detail' examples: unauthorized: summary: Invalid API key value: type: https://docs.momentco.io/errors/unauthorized title: Unauthorized status: 401 detail: The API key provided is invalid. instance: /collect/payment_request code: unauthorized missing_authorization: summary: Missing authorization header value: type: https://docs.momentco.io/errors/unauthorized title: Unauthorized status: 401 detail: Authorization header is required. instance: /collect/payment_request code: missing_authorization headers: Request-Id: $ref: '#/components/headers/request_id' conflict: description: Conflict - Resource state conflict or duplicate resource content: application/problem+json: schema: $ref: '#/components/schemas/problem_detail' examples: Duplicate Idempotency key: summary: Duplicate Idempotency key value: type: https://docs.momentco.io/errors/conflict title: Conflict status: 409 detail: >- A Payment Request with the same idempotency key already exists. instance: /collect/payment_request code: conflict headers: Request-Id: $ref: '#/components/headers/request_id' internal_server_error: description: Internal Server Error - An unexpected error occurred content: application/problem+json: schema: $ref: '#/components/schemas/problem_detail' examples: Internal Server Error: summary: Internal server error value: 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: /collect/payment_request code: internal_server_error headers: Request-Id: $ref: '#/components/headers/request_id' 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 idempotent_replayed: description: > Indicates whether this response is a replay of a previous request due to idempotency. When `true`, the response is being returned from cache based on the Idempotency-Key provided in the request. schema: type: boolean example: false securitySchemes: BearerAuth: 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 ``` ````