Features Documentation

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": "7323804",
            "Status": "PENDING",
            "Reference": "2026008311",
            "CreationDate": "2026-10-29T20:12:36.9570000Z",
            "ExpirationDate": "2027-03-28T20:12:36.9570000Z",
            "ExternalIdentifier": "testExternal",
            "UserDefinedField": "",
            "MetaData": null
        },
        "Transaction": {
            "Id": "167196",
            "Status": "AUTHORIZE",
            "PaymentMethod": "VISA/MASTER",
            "PaymentId": "07077323804392274272",
            "ReferenceId": "630220167196",
            "TrackId": "29-10-2026_3922742",
            "AuthorizationId": "167196",
            "TransactionDate": "2026-10-29T20:12:36.9730000Z",
            "ECI": "",
            "NetworkTransactionId": "777123456789",
            "AgreementId": "",
            "IP": {
                "Address": "",
                "Country": ""
            },
            "Error": {
                "Code": "",
                "Message": "",
                "ResponseCode": "00",
                "MerchantAdviceCode": ""
            },
            "Card": {
                "NameOnCard": "JOHN DOE",
                "Number": "222300xxxxxx0007",
                "Token": "TKN-2556b5b7-e6aa-4765-be53-e81f3ad861c5",
                "PanHash": "c546530474ccebec86da0df2b3983a599c3348f497ab599548f206f73d4b736b",
                "ExpiryMonth": "01",
                "ExpiryYear": "39",
                "Brand": "Mastercard",
                "Issuer": "",
                "IssuerCountry": "",
                "FundingMethod": ""
            }
        },
        "Customer": {
            "Name": "Anonymous",
            "Mobile": "+965",
            "Email": ""
        },
        "Amount": {
            "BaseCurrency": "KWD",
            "ValueInBaseCurrency": "10",
            "ServiceCharge": "0.1",
            "ServiceChargeVAT": "0.015",
            "ReceivableAmount": "9.885",
            "DisplayCurrency": "KWD",
            "ValueInDisplayCurrency": "10",
            "PayCurrency": "KWD",
            "ValueInPayCurrency": "10"
        },
        "Suppliers": []
    }
}
{
  "Event": {
    "Code": 1,
    "Name": "PAYMENT_STATUS_CHANGED",
    "CountryIsoCode": "KWT",
    "CreationDate": "2026-10-29T20:12:37.8970000Z",
    "Reference": "WH-1137283"
  },
  "Data": {
    "Invoice": {
      "Id": "7323804",
      "Status": "PENDING",
      "Reference": "2026008311",
      "CreationDate": "2026-10-29T20:12:36.9574853Z",
      "ExpirationDate": "2027-03-28T20:12:36.9574853Z",
      "UserDefinedField": "",
      "ExternalIdentifier": "testExternal",
      "MetaData": null
    },
    "Transaction": {
      "Id": "167196",
      "Status": "AUTHORIZE",
      "PaymentMethod": "VISA/MASTER",
      "PaymentId": "07077323804392274272",
      "ReferenceId": "630220167196",
      "TrackId": "29-10-2026_3922742",
      "AuthorizationId": "167196",
      "TransactionDate": "2026-10-29T20:12:36.973Z",
      "ECI": "",
      "NetworkTransactionId": "777123456789",
      "AgreementId": "",
      "IP": {
        "Address": "",
        "Country": ""
      },
      "Error": {
        "Code": "",
        "Message": "",
        "ResponseCode": "00",
        "MerchantAdviceCode": ""
      },
      "Card": {
        "NameOnCard": "JOHN DOE",
        "Number": "222300xxxxxx0007",
        "Token": "TKN-2556b5b7-e6aa-4765-be53-e81f3ad861c5",
        "PanHash": "c546530474ccebec86da0df2b3983a599c3348f497ab599548f206f73d4b736b",
        "ExpiryMonth": "01",
        "ExpiryYear": "39",
        "Brand": "Mastercard",
        "Issuer": "",
        "IssuerCountry": "",
        "FundingMethod": ""
      }
    },
    "Customer": {
      "Name": "Anonymous",
      "Mobile": "+965",
      "Email": ""
    },
    "Amount": {
      "BaseCurrency": "KWD",
      "ValueInBaseCurrency": "10",
      "ServiceCharge": "0.1",
      "ServiceChargeVAT": "0.015",
      "ReceivableAmount": "9.885",
      "DisplayCurrency": "KWD",
      "ValueInDisplayCurrency": "10",
      "PayCurrency": "KWD",
      "ValueInPayCurrency": "10"
    },
    "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": "7323804",
            "Status": "PAID",
            "Reference": "2026008311",
            "CreationDate": "2026-10-29T20:12:36.9570000Z",
            "ExpirationDate": "2027-03-28T20:12:36.9570000Z",
            "ExternalIdentifier": "testExternal",
            "UserDefinedField": "",
            "MetaData": null
        },
        "Transaction": {
            "Id": "168276",
            "Status": "SUCCESS",
            "PaymentMethod": "VISA/MASTER",
            "PaymentId": "07077323804392274573",
            "ReferenceId": "630220167196",
            "TrackId": "29-10-2026_3922745",
            "AuthorizationId": "167196",
            "TransactionDate": "2026-10-29T20:15:51.0915886Z",
            "ECI": "",
            "NetworkTransactionId": "777123456789",
            "AgreementId": "",
            "IP": {
                "Address": "",
                "Country": ""
            },
            "Error": {
                "Code": "",
                "Message": "",
                "ResponseCode": "00",
                "MerchantAdviceCode": ""
            },
            "Card": {
                "NameOnCard": "JOHN DOE",
                "Number": "222300xxxxxx0007",
                "Token": "TKN-2556b5b7-e6aa-4765-be53-e81f3ad861c5",
                "PanHash": "c546530474ccebec86da0df2b3983a599c3348f497ab599548f206f73d4b736b",
                "ExpiryMonth": "01",
                "ExpiryYear": "39",
                "Brand": "Mastercard",
                "Issuer": "",
                "IssuerCountry": "",
                "FundingMethod": ""
            }
        },
        "Customer": {
            "Name": "Anonymous",
            "Mobile": "+965",
            "Email": ""
        },
        "Amount": {
            "BaseCurrency": "KWD",
            "ValueInBaseCurrency": "10",
            "ServiceCharge": "0.1",
            "ServiceChargeVAT": "0.015",
            "ReceivableAmount": "9.885",
            "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": "7323809",
            "Status": "PENDING",
            "Reference": "2026008312",
            "CreationDate": "2026-10-29T20:16:33.1970000Z",
            "ExpirationDate": "2027-03-28T20:16:33.1970000Z",
            "ExternalIdentifier": "testExternal",
            "UserDefinedField": "",
            "MetaData": null
        },
        "Transaction": {
            "Id": "07077323809392274773",
            "Status": "CANCELED",
            "PaymentMethod": "VISA/MASTER",
            "PaymentId": "07077323809392274773",
            "ReferenceId": "07077323809392274773",
            "TrackId": "29-10-2026_3922747",
            "AuthorizationId": "07077323809392274773",
            "TransactionDate": "2026-10-29T20:16:51.6115248Z",
            "ECI": "",
            "NetworkTransactionId": "777123456789",
            "AgreementId": "",
            "IP": {
                "Address": "",
                "Country": ""
            },
            "Error": {
                "Code": "",
                "Message": "",
                "ResponseCode": "",
                "MerchantAdviceCode": ""
            },
            "Card": {
                "NameOnCard": "JOHN DOE",
                "Number": "222300xxxxxx0007",
                "Token": "TKN-2556b5b7-e6aa-4765-be53-e81f3ad861c5",
                "PanHash": "c546530474ccebec86da0df2b3983a599c3348f497ab599548f206f73d4b736b",
                "ExpiryMonth": "01",
                "ExpiryYear": "39",
                "Brand": "Mastercard",
                "Issuer": "",
                "IssuerCountry": "",
                "FundingMethod": ""
            }
        },
        "Customer": {
            "Name": "Anonymous",
            "Mobile": "+965",
            "Email": ""
        },
        "Amount": {
            "BaseCurrency": "KWD",
            "ValueInBaseCurrency": "10",
            "ServiceCharge": "0.1",
            "ServiceChargeVAT": "0.015",
            "ReceivableAmount": "9.885",
            "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 16 days ago

Did this page help you?