Capture Payment

This guide explains how to capture a pre-authorized payment using the appropriate API endpoint. This action is typically performed after a payment has been pre-authorized but before funds are captured.

Quick Reference

• Capture Payment: Moves funds from the customer's account to the merchant after a successful pre-authorization.
  • Endpoint: POST v1/payments/{paymentId}/capture
  • Scope: merchant
  • Key Fields: amount, metadata
• When to Use:
  • Capture: When you want to finalize a pre-authorized payment and collect funds.
• Error Codes: See Capture Payment Error Codes

Overview

• Capture is used to finalize a pre-authorized payment, moving the held funds to the merchant. This must be done within the authorization window (typically 7 days).
• Only AUTHORIZED payments can be captured. This action is irreversible; if merchants want to reverse, a refund must be initiated.

Capture Pre-Authorized Payment

To capture a pre-authorized payment, use the following payload:

Sample Request

Sample Request – Capture Payment

{
  "amount": 1,
  "metadata": {
    "property1": "string",
    "property2": "string"
  }
}

Typical Capture Workflow

1. Pre-authorize a payment (status: AUTHORIZED).
2. When ready to collect funds, call the capture endpoint with the amount (can be full or partial).
3. The payment status transitions to COMPLETED if successful.
4. If the capture fails, the status will be FAILED and an error will be returned.

Capture Statuses

Status	Description
AUTHORIZED	The pre-authorization hold is placed successfully
COMPLETED	The payment has been captured
FAILED	The capture operation failed

Metadata Handling

• Only 20 metadata key-value pairs are allowed in total for a payment.
• When capturing a payment, the metadata pairs provided in the capture request will be appended to the existing payment metadata.
• If the payment already has 19 metadata pairs, only 1 additional pair can be passed in the capture request.
• If a metadata key already exists in the payment, the value will be overridden with the value provided in the capture request.

Error Handling

• If you attempt to capture a payment that is not in the AUTHORIZED state, an error will be returned.
• See Capture Payment Error Codes for details on error codes and troubleshooting.

Best Practices

• Always check the payment status before attempting to capture.
• Capture the payment as soon as the goods/services are delivered to avoid authorization expiry.
• Log and monitor all capture attempts and responses for audit and support.