Features Documentation
Start typing to search…

Authorize & Capture

Capturing/Releasing Amounts

Introduction

When a payment is made using a gateway that supports Authorization & Capture, you have the ability to capture (either partially or fully) the amount of the authorized payment or release it back to the customer.

  • Once the invoice is paid, it will appear in your MyFatoorah Portal and in the response of GET /v3/payments with the status "AUTHORIZE".
  • You can perform Capture or Release operations using the PUT /v3/payments/{paymentId} endpoint.
  • In the request body, set the "OperationType" parameter to either "CAPTURE" or "RELEASE" Depending on your intended action.
🚧

Approval Needed

Kindly contact your account manager to check the availability for enabling the Authorization Capture feature.

📘

Auto-Capture Option

You can choose between two flows:

  1. Authorize & Capture in two separate steps.
  2. Auto-Capture the payment directly in one step using "OperationType": "PAY" in your payment request.

How It Works

Step 1: Create a Payment with Authorization

When initiating the payment, send the "OperationType": "AUTHORIZE" parameter in the request.

{
    "PaymentMethod": "CARD",
    "Order": {
        "Amount": 10
    },
    "OperationType": "AUTHORIZE",
    "IntegrationUrls": {
       "Redirection": "https://your-website.com/payment-callback"
    }
}
{
    "PaymentMode": "COMPLETE_PAYMENT", 
    "Order": {
        "Amount": 30
    },
    "OperationType": "AUTHORIZE",
    "IntegrationUrls": {
        "Redirection": "https://your-website.com/payment-callback"
    }
}

Payment Response:

{
    "IsSuccess": true,
    "Message": "",
    "ValidationErrors": null,
    "Data": {
        "Invoice": {
            "Id": "6345277",
            "Status": "PENDING",
            "Reference": "2025001280",
            "CreationDate": "2025-12-06T18:29:12.2770000Z",
            "ExpirationDate": "2026-05-05T18:29:12.2770000Z",
            "ExternalIdentifier": null,
            "UserDefinedField": "",
            "MetaData": null
        },
        "Transaction": {
            "Id": "53059",
            "Status": "AUTHORIZE",
            "PaymentMethod": "VISA/MASTER",
            "PaymentId": "07076345277319592774",
            "ReferenceId": "534018053059",
            "TrackId": "06-12-2025_3195927",
            "AuthorizationId": "053059",
            "TransactionDate": "2025-12-06T18:29:17.0030000Z",
            "ECI": "02",
            "IP": {
                "Address": "197.32.110.20",
                "Country": "Egypt"
            },
            "Error": {
                "Code": "",
                "Message": ""
            },
            "Card": {
                "NameOnCard": "test test",
                "Number": "512345xxxxxx0008",
                "PanHash": "b888aa5f23a817883d4d12c74044bab1ae6ee65dc8d6e11515394aba452b273b",
                "ExpiryMonth": "01",
                "ExpiryYear": "39",
                "Brand": "Mastercard",
                "Issuer": "Test Bank",
                "IssuerCountry": "KWT",
                "FundingMethod": "credit"
            }
        },
        "Customer": {
            "Reference": "",
            "Name": "Anonymous",
            "Mobile": "+965",
            "Email": ""
        },
        "Amount": {
            "BaseCurrency": "KWD",
            "ValueInBaseCurrency": "23",
            "ServiceCharge": "0.003",
            "ServiceChargeVAT": "0",
            "ReceivableAmount": "22.997",
            "DisplayCurrency": "KWD",
            "ValueInDisplayCurrency": "23",
            "PayCurrency": "KWD",
            "ValueInPayCurrency": "23"
        },
        "Suppliers": []
    }
}
{
  "Event": {
    "Code": 1,
    "Name": "PAYMENT_STATUS_CHANGED",
    "CountryIsoCode": "KWT",
    "CreationDate": "2025-12-06T18:29:26.1300000Z",
    "Reference": "WH-595351"
  },
  "Data": {
    "Invoice": {
      "Id": "6345277",
      "Status": "PENDING",
      "Reference": "2025001280",
      "CreationDate": "2025-12-06T18:29:12.277Z",
      "ExpirationDate": "2026-05-05T18:29:12.277Z",
      "UserDefinedField": "",
      "ExternalIdentifier": null,
      "MetaData": null
    },
    "Transaction": {
      "Id": "53059",
      "Status": "AUTHORIZE",
      "PaymentMethod": "VISA/MASTER",
      "PaymentId": "07076345277319592774",
      "ReferenceId": "534018053059",
      "TrackId": "06-12-2025_3195927",
      "AuthorizationId": "053059",
      "TransactionDate": "2025-12-06T18:29:17.003Z",
      "ECI": "02",
      "IP": {
        "Address": "197.32.110.20",
        "Country": "Egypt"
      },
      "Error": {
        "Code": "",
        "Message": ""
      },
      "Card": {
        "NameOnCard": "test test",
        "Number": "512345xxxxxx0008",
        "PanHash": "b888aa5f23a817883d4d12c74044bab1ae6ee65dc8d6e11515394aba452b273b",
        "ExpiryMonth": "01",
        "ExpiryYear": "39",
        "Brand": "Mastercard",
        "Issuer": "Test Bank",
        "IssuerCountry": "KWT",
        "FundingMethod": "credit"
      }
    },
    "Customer": {
      "Name": "Anonymous",
      "Mobile": "+965",
      "Email": ""
    },
    "Amount": {
      "BaseCurrency": "KWD",
      "ValueInBaseCurrency": "23",
      "ServiceCharge": "0.003",
      "ServiceChargeVAT": "0",
      "ReceivableAmount": "22.997",
      "DisplayCurrency": "KWD",
      "ValueInDisplayCurrency": "23",
      "PayCurrency": "KWD",
      "ValueInPayCurrency": "23"
    },
    "Suppliers": []
  }
}

Step 2: Capture or Release the Payment

After the payment is authorized, you can either Capture the payment (fully or partially) or Release it back to the customer using the following endpoint:

Endpoint: PUT /v3/payments/{paymentId} (Update Payment)


{
    "OperationType": "CAPTURE",
    "Amount": 10
}
{
    "IsSuccess": true,
    "Message": "",
    "ValidationErrors": null,
    "Data": {
        "Invoice": {
            "Id": "6283869",
            "Status": "PAID",
            "Reference": "2025001139",
            "CreationDate": "2025-11-12T21:40:55.4400000Z",
            "ExpirationDate": "2026-04-11T21:40:55.4400000Z",
            "ExternalIdentifier": null,
            "UserDefinedField": "",
            "MetaData": null
        },
        "Transaction": {
            "Id": "189591",
            "Status": "SUCCESS",
            "PaymentMethod": "VISA/MASTER",
            "PaymentId": "07076283869314693674",
            "ReferenceId": "531621188501",
            "TrackId": "13-11-2025_3146936",
            "AuthorizationId": "188501",
            "TransactionDate": "2025-11-12T21:41:47.0156741Z",
            "ECI": "02",
            "IP": {
                "Address": "",
                "Country": ""
            },
            "Error": {
                "Code": "",
                "Message": ""
            },
            "Card": {
                "NameOnCard": "string",
                "Number": "512345xxxxxx0008",
                "PanHash": "b888aa5f23a817883d4d12c74044bab1ae6ee65dc8d6e11515394aba452b273b",
                "ExpiryMonth": "01",
                "ExpiryYear": "39",
                "Brand": "Mastercard",
                "Issuer": "Test Bank",
                "IssuerCountry": "KWT",
                "FundingMethod": "credit"
            }
        },
        "Customer": {
            "Reference": "",
            "Name": "Anonymous",
            "Mobile": "+965",
            "Email": ""
        },
        "Amount": {
            "BaseCurrency": "KWD",
            "ValueInBaseCurrency": "10",
            "ServiceCharge": "0.001",
            "ServiceChargeVAT": "0",
            "ReceivableAmount": "9.999",
            "DisplayCurrency": "KWD",
            "ValueInDisplayCurrency": "10",
            "PayCurrency": "KWD",
            "ValueInPayCurrency": "10"
        },
        "Suppliers": []
    }
}
🚧

Note: If the "Amount" in the capture request is less than the original amount in the first payment request, the response will be updated to the captured amount.

{
    "OperationType": "RELEASE",
}
{
    "IsSuccess": true,
    "Message": "",
    "ValidationErrors": null,
    "Data": {
        "Invoice": {
            "Id": "6283870",
            "Status": "PENDING",
            "Reference": "2025001140",
            "CreationDate": "2025-11-12T21:43:45.0970000Z",
            "ExpirationDate": "2026-04-11T21:43:45.0970000Z",
            "ExternalIdentifier": null,
            "UserDefinedField": "",
            "MetaData": null
        },
        "Transaction": {
            "Id": "07076283870314694073",
            "Status": "CANCELED",
            "PaymentMethod": "VISA/MASTER",
            "PaymentId": "07076283870314694073",
            "ReferenceId": "07076283870314694073",
            "TrackId": "13-11-2025_3146940",
            "AuthorizationId": "07076283870314694073",
            "TransactionDate": "2025-11-12T21:47:32.8772780Z",
            "ECI": "",
            "IP": {
                "Address": "",
                "Country": ""
            },
            "Error": {
                "Code": "",
                "Message": "Transaction Released"
            },
            "Card": {
                "NameOnCard": "string",
                "Number": "512345xxxxxx0008",
                "PanHash": "b888aa5f23a817883d4d12c74044bab1ae6ee65dc8d6e11515394aba452b273b",
                "ExpiryMonth": "01",
                "ExpiryYear": "39",
                "Brand": "Mastercard",
                "Issuer": "Test Bank",
                "IssuerCountry": "KWT",
                "FundingMethod": "credit"
            }
        },
        "Customer": {
            "Reference": "",
            "Name": "Anonymous",
            "Mobile": "+965",
            "Email": ""
        },
        "Amount": {
            "BaseCurrency": "KWD",
            "ValueInBaseCurrency": "10",
            "ServiceCharge": "0.001",
            "ServiceChargeVAT": "0",
            "ReceivableAmount": "9.999",
            "DisplayCurrency": "KWD",
            "ValueInDisplayCurrency": "10",
            "PayCurrency": "KWD",
            "ValueInPayCurrency": "10"
        },
        "Suppliers": []
    }
}
📘

Important Notes

  • You can perform only one Capture or Release operation per invoice.
  • Once captured or released, the payment cannot be modified again.
📘

Old Integration (V2)

In case you are using the integration for v2, you can find the documentation here:

Updated about 3 hours ago