> ## 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.

# Capture Payment

> Captures an authorised payment, settling the funds.

This endpoint is only applicable for payments created with `capture_method: manual`. The payment must be in the `succeeded` status (authorised) and the authorisation must not have expired.

You can perform a partial capture by specifying an `amount` less than the remaining authorised amount. Omitting the `amount` captures the full remaining authorised amount.




## OpenAPI

````yaml POST /collect/payments/{id}/captures
openapi: 3.1.0
info:
  version: 1.0.0
  title: Payments API
  description: Payments API
  contact:
    name: Moment
    url: https://momentco.net
    email: support@momentco.net
servers:
  - url: https://api.momentpay.net
security: []
tags:
  - name: Payment Events
    x-displayName: Payment Events
    description: Webhook events emitted during the payment lifecycle.
  - name: Payment
    x-displayName: Payment
    description: >
      A Payment represents a financial transaction. For payments with
      capture_method manual, authorisation and settlement are separate steps.
  - name: Payment Model
    x-displayName: Payment Model
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/payment" />
  - name: Payment Event Model
    x-displayName: Payment Event Model
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/payment_event" />
  - name: Problem Detail Model
    x-displayName: Problem Detail Model
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/problem_detail" />
externalDocs:
  description: Read the full API documentation
  url: https://momentco.net/docs
paths:
  /collect/payments/{id}/captures:
    parameters:
      - name: id
        in: path
        description: The unique identifier for the payment.
        required: true
        schema:
          type: string
    post:
      tags:
        - Payment
      summary: Capture Payment
      description: >
        Captures an authorised payment, settling the funds.


        This endpoint is only applicable for payments created with
        `capture_method: manual`. The payment must be in the `succeeded` status
        (authorised) and the authorisation must not have expired.


        You can perform a partial capture by specifying an `amount` less than
        the remaining authorised amount. Omitting the `amount` captures the full
        remaining authorised amount.
      operationId: capture_payment
      parameters:
        - $ref: '#/components/parameters/idempotency_key'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/capture_payment_request'
            examples:
              Full Capture:
                summary: Full capture
                description: >-
                  Omit the amount to capture the full remaining authorised
                  amount.
                value: {}
              Partial Capture:
                summary: Partial capture
                description: >-
                  Specify an amount to capture less than the remaining
                  authorised amount.
                value:
                  amount: 50000
              Capture With Metadata:
                summary: Capture with metadata
                description: Attach metadata to the capture operation.
                value:
                  amount: 50000
                  metadata:
                    reference: order_123
      responses:
        '200':
          $ref: '#/components/responses/payment_captured'
        '400':
          $ref: '#/components/responses/bad_request'
        '401':
          $ref: '#/components/responses/unauthorized'
        '404':
          $ref: '#/components/responses/not_found'
        '409':
          $ref: '#/components/responses/capture_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:
    capture_payment_request:
      title: Capture Payment Request
      type: object
      description: >
        Request body for capturing an authorised payment. All fields are
        optional.

        Omitting the `amount` field will capture the full remaining authorised
        amount.
      properties:
        amount:
          type: integer
          description: |
            The amount to capture, in the smallest currency unit (e.g. cents).
            Must be less than or equal to the remaining authorised amount.
            Omit to capture the full remaining authorised amount.
          example: 50000
        metadata:
          $ref: '#/components/schemas/metadata_fields'
      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)
      example:
        customer_id: cust_123456
        order_id: ord_789012
    payment:
      title: Payment Object
      type: object
      description: Contains detailed information about the payment.
      properties:
        id:
          $ref: '#/components/schemas/payment_id'
        reconciliation_reference:
          $ref: '#/components/schemas/reconciliation_reference'
        status:
          $ref: '#/components/schemas/payment_status'
        amount:
          $ref: '#/components/schemas/amount'
        currency:
          $ref: '#/components/schemas/currency'
        capture_method:
          $ref: '#/components/schemas/capture_method'
        intent:
          $ref: '#/components/schemas/intent'
        authorised_amount:
          $ref: '#/components/schemas/authorised_amount'
        paid_amount:
          $ref: '#/components/schemas/paid_amount'
        voided_amount:
          $ref: '#/components/schemas/voided_amount'
        country:
          $ref: '#/components/schemas/country'
        payment_method_details:
          $ref: '#/components/schemas/payment_method_details'
        external_reference:
          $ref: '#/components/schemas/external_reference'
        last_payment_error:
          $ref: '#/components/schemas/last_payment_error'
        mode:
          $ref: '#/components/schemas/mode'
        metadata:
          $ref: '#/components/schemas/metadata_fields'
        created_at:
          $ref: '#/components/schemas/created_at'
        updated_at:
          $ref: '#/components/schemas/updated_at'
      additionalProperties: false
    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_id:
      type: string
      description: Unique identifier for a payment
      example: p_xyz789abc123def456
    reconciliation_reference:
      title: Reconciliation Reference
      type: string
      description: Reference ID used for reconciling the payment.
      example: 67612dd5d8efe547cb887d0d
    payment_status:
      title: Payment Status
      type: string
      enum:
        - draft
        - initiating
        - pending_action
        - processing
        - succeeded
        - failed
        - cancelled
        - expired
      description: >
        The current status of the payment:

        - `draft`: The payment has been created but not yet started.

        - `initiating`: The payment is being initiated and awaiting further
        steps.

        - `pending_action`: The payment requires an action from the customer or
        external system before it can proceed.

        - `processing`: The payment is actively being processed.

        - `succeeded`: The payment was completed successfully.

        - `failed`: The payment is failed.

        - `cancelled`: The payment was cancelled before completion.

        - `expired`: The payment has expired and can no longer be completed.
      example: succeeded
    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
    capture_method:
      title: Capture Method
      type: string
      enum:
        - automatic
        - manual
      description: >
        Controls how the payment is captured after authorisation:

        - `automatic`: The payment is captured immediately upon successful
        authorisation (default). This is equivalent to a standard sale
        transaction.

        - `manual`: The payment is authorised only. Funds are reserved on the
        customer's payment method, but not yet captured. The merchant must
        explicitly capture or void the payment using the capture or void
        endpoints.
      default: automatic
      example: manual
    intent:
      title: Payment Intent
      type: string
      enum:
        - payment
        - payment_method_verification
      description: >
        The intent of the payment as determined by the platform at creation
        time:

        - `payment`: a monetary payment or authorisation was intended. Funds
        were reserved or settled.

        - `payment_method_verification`: the payment method was verified without
        reserving or moving funds. Set when `amount: 0` on a supported session
        type (`one_time` with `save_payment_method: always`, or
        `first_in_series`).
      example: payment
    authorised_amount:
      title: Authorised Amount
      type: integer
      description: >
        The total amount authorised on the customer's payment method, in the
        smallest currency unit (e.g. cents).

        Set when an authorisation succeeds for a payment method that supports
        authorisation. For payments that authorise and settle in one flow, this
        reflects the amount that was authorised and immediately settled.

        For manual-capture payments, this remains the original authorised total.
        Subsequent capture and void operations update `paid_amount` and
        `voided_amount` instead.

        Present only when the payment method supports authorisation.
      example: 100001
    paid_amount:
      title: Paid Amount
      type: integer
      description: >
        The total amount that has been settled for this payment, in the smallest
        currency unit (e.g. cents).

        For payments that settle immediately, this typically matches the full
        payment amount once the payment succeeds.

        For manual-capture payments, this reflects the portion captured so far,
        increases with each capture, and does not decrease when any remaining
        amount is voided.
      example: 100001
    voided_amount:
      title: Voided Amount
      type: integer
      description: >
        The total amount released from the original authorisation by successful
        void operations, in the smallest currency unit (e.g. cents).

        Incremented each time authorised funds are released. For manual-capture
        payments, this reflects the total amount no longer available to capture
        because it has been voided.

        Present only when the payment method supports authorisation.
      example: 50001
    country:
      title: Country
      type: string
      description: >-
        The country where the payment was initiated, represented in ISO 3166-1
        alpha-2 format.
      example: ZA
    payment_method_details:
      type: object
      description: Details of the payment method used for the payment.
      required:
        - type
      discriminator:
        propertyName: type
      oneOf:
        - title: Card
          type: object
          required:
            - type
            - card
          properties:
            type:
              type: string
              enum:
                - card
            card:
              type: object
              description: Card-specific details for the payment method.
              properties:
                type:
                  type: string
                  description: Card type (e.g. credit, debit).
                scheme:
                  type: string
                  description: Card network.
                bin:
                  type: string
                  description: Bank identification number for the card.
                last4:
                  type: string
                  description: Last 4 digits of the card.
              additionalProperties: true
          additionalProperties: false
        - title: Capitec pay
          type: object
          required:
            - type
            - capitec_pay
          properties:
            type:
              type: string
              enum:
                - capitec_pay
            capitec_pay:
              type: object
              description: Capitec pay details for the payment method.
              properties:
                bank:
                  type: string
                  description: Name of the bank (capitec).
                phone_number:
                  type: string
                  description: Phone number associated with the Capitec pay.
              additionalProperties: true
          additionalProperties: false
        - title: Instant EFT
          type: object
          required:
            - type
            - instant_eft
          properties:
            type:
              type: string
              enum:
                - instant_eft
            instant_eft:
              type: object
              description: Instant EFT details for the payment method.
              properties:
                bank:
                  type: string
                  description: Name of the destination bank.
              additionalProperties: true
          additionalProperties: false
        - title: Zapper
          type: object
          required:
            - type
          properties:
            type:
              type: string
              enum:
                - zapper
          additionalProperties: false
        - title: MTN momo
          type: object
          required:
            - type
            - mtn_momo
          properties:
            type:
              type: string
              enum:
                - mtn_momo
            mtn_momo:
              type: object
              description: MTN momo details for the payment method.
              properties:
                phone_number:
                  type: string
                  description: Phone number associated with the MTN momo.
              additionalProperties: true
          additionalProperties: false
    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
    last_payment_error:
      title: Last Payment Error
      type: object
      description: Details of the last error that occurred during a payment attempt.
      properties:
        error_code:
          $ref: '#/components/schemas/error_code'
        decline_code:
          $ref: '#/components/schemas/decline_code'
        message:
          $ref: '#/components/schemas/error_message'
        timestamp:
          $ref: '#/components/schemas/error_timestamp'
      additionalProperties: false
    mode:
      title: Mode
      type: string
      enum:
        - live
        - test
      description: |
        Indicates whether the payment is in live or test mode:
          - `test`: Used for testing and development. Payments are simulated, and no real transactions are processed.
          - `live`: Used in production to process real payments. Real credit cards and accounts are used, and actual transactions occur.
    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'
    error_code:
      title: Error Code
      type: string
      description: A short code representing the type of error (e.g. `card_declined`).
      example: card_declined
    decline_code:
      title: 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`).
      example: insufficient_funds
    error_message:
      title: Error Message
      type: string
      description: A human readable message describing the error.
      example: General Error
    error_timestamp:
      title: Error Timestamp
      type: string
      format: date-time
      description: The timestamp of when the error occurred.
      example: '2026-02-12T09:01:05.000Z'
  responses:
    payment_captured:
      description: Payment captured successfully
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/payment'
          examples:
            Full Capture:
              summary: Full capture of authorised payment
              description: Payment after capturing the full authorised amount
              value:
                id: pay_rOaZNqKZMFxsRb2NBL1cj
                status: succeeded
                amount: 100001
                currency: ZAR
                capture_method: manual
                authorised_amount: 100001
                paid_amount: 100001
                voided_amount: 0
                country: ZA
                payment_method_details:
                  type: card
                  card:
                    type: CREDIT
                    scheme: MASTERCARD
                    bin: '527346'
                    last4: '3333'
                external_reference: '12345'
                mode: live
                metadata:
                  customer_id: cust_123456
                  order_id: ord_789012
                created_at: '2026-02-12T09:00:44.224Z'
                updated_at: '2026-02-12T09:05:12.531Z'
            Partial Capture:
              summary: Partial capture of authorised payment
              description: Payment after capturing a portion of the authorised amount
              value:
                id: pay_rOaZNqKZMFxsRb2NBL1cj
                status: succeeded
                amount: 100001
                currency: ZAR
                capture_method: manual
                authorised_amount: 100001
                paid_amount: 50000
                voided_amount: 0
                country: ZA
                payment_method_details:
                  type: card
                  card:
                    type: CREDIT
                    scheme: MASTERCARD
                    bin: '527346'
                    last4: '3333'
                external_reference: '12345'
                mode: live
                metadata:
                  customer_id: cust_123456
                  order_id: ord_789012
                created_at: '2026-02-12T09:00:44.224Z'
                updated_at: '2026-02-12T09:05:12.531Z'
            Capture With Metadata:
              summary: Capture with metadata
              description: >-
                Payment after capturing a portion of the authorised amount with
                metadata
              value:
                id: pay_rOaZNqKZMFxsRb2NBL1cj
                status: succeeded
                amount: 100001
                currency: ZAR
                capture_method: manual
                authorised_amount: 100001
                paid_amount: 50000
                voided_amount: 0
                country: ZA
                payment_method_details:
                  type: card
                  card:
                    type: CREDIT
                    scheme: MASTERCARD
                    bin: '527346'
                    last4: '3333'
                external_reference: '12345'
                mode: live
                metadata:
                  customer_id: cust_123456
                  order_id: ord_789012
                  reference: order_123
                created_at: '2026-02-12T09:00:44.224Z'
                updated_at: '2026-02-12T09:05:12.531Z'
      headers:
        Request-Id:
          $ref: '#/components/headers/request_id'
        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
    bad_request:
      description: Bad Request - Invalid request parameters or malformed request
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/problem_detail'
          examples:
            Invalid Amount:
              summary: Invalid capture/void 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/payments/pay_rOaZNqKZMFxsRb2NBL1cj/captures
                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:
            Invalid API Key:
              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/payments/pay_rOaZNqKZMFxsRb2NBL1cj/captures
                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/payments/pay_rOaZNqKZMFxsRb2NBL1cj/captures
                code: missing_authorization
      headers:
        Request-Id:
          $ref: '#/components/headers/request_id'
    not_found:
      description: Resource not Found - The requested payment does not exist
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/problem_detail'
          examples:
            Payment Not Found:
              summary: Payment not found
              value:
                type: https://docs.momentco.io/errors/not-found
                title: Resource Not Found
                status: 404
                detail: The requested payment does not exist.
                instance: /collect/payments/pay_nonexistent123
                code: resource_not_found
      headers:
        Request-Id:
          $ref: '#/components/headers/request_id'
    capture_conflict:
      description: Conflict - The payment cannot be captured in its current state
      headers:
        Request-Id:
          $ref: '#/components/headers/request_id'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/problem_detail'
          examples:
            Payment Not Authorised:
              summary: Payment is not in an authorised state
              value:
                type: https://docs.momentco.io/errors/conflict
                title: Conflict
                status: 409
                detail: >-
                  The payment is not in an authorised state and cannot be
                  captured.
                instance: /collect/payments/pay_rOaZNqKZMFxsRb2NBL1cj/captures
                code: conflict
            Amount Exceeds Authorised:
              summary: Capture amount exceeds remaining authorised amount
              value:
                type: https://docs.momentco.io/errors/conflict
                title: Conflict
                status: 409
                detail: The capture amount exceeds the remaining authorised amount.
                instance: /collect/payments/pay_rOaZNqKZMFxsRb2NBL1cj/captures
                code: conflict
            Authorisation Expired:
              summary: Authorisation has expired
              value:
                type: https://docs.momentco.io/errors/conflict
                title: Conflict
                status: 409
                detail: The authorisation has expired and can no longer be captured.
                instance: /collect/payments/pay_rOaZNqKZMFxsRb2NBL1cj/captures
                code: conflict
    internal_server_error:
      description: Unexpected server error
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/problem_detail'
          examples:
            Internal Server Error:
              summary: Unexpected 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/payments/pay_rOaZNqKZMFxsRb2NBL1cj/captures
                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
  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

        ```

````