UpdatePaymentStatus

Overview

The "UpdatePaymentStatus" endpoint is a POST request. It is used to either capture fully/partially the invoice amount or release the amount back into the customer's account. Detailed functionality of how to use this endpoint is explained below.

The endpoint on Swagger is: Payment_UpdatePaymentStatus.

Now, we are going to declare the endpoint and its models along with each accepted parameter and possible value.

🚧
Number of Processes
Please notice that you can make only one Capture/Release operation on each invoice.

Request Model

The request is a POST request with the following parameters:

Input Parameter	Type	Description
Operation	string	"Capture": Refers to capturing fully or partially the invoice value. "Release": Refers to releasing fully the invoice value to the customer's account.
Amount	float	The amount to be captured/released. Capture: The amount has to be less than or equal to the invoice value. Mandatory Release: The amount has to be equal to the invoice value. _Optional*_
Key	string	Refers to the Invoice ID, payment ID, or Customer Reference based on the key type
KeyType	string	"InvoiceId": Refers to the invoice number that MyFatoorah generates "PaymentId": The value is returned upon having any update on the invoice payment "CustomerReference": The reference used to link your orders in the store

👍
PaymentId
We strongly recommend to use the value PaymentId (which is returned in the CallBackURL ) to update the payment status, this will get you full information about the invoice that you can use within your application. As long as there is not payment or transactions done for a certain invoice, you can inquire using InvoiceId.

Response Model

After viewing the Response Model that you will get as a result of your request, here, you will find complete details about the Data Model of this API endpoint. Let's check it and its contents.

Response Field	Type	Description
InvoiceId	number	Represents the invoice ID that was used in the inquiry call
InvoiceStatus	string	"Pending": The customer made the payment but no operations on it ORA release is made on the amount. "Paid": A capture is made on the amount
InvoiceReference	string	Invoice reference that MyFatoorah generates
CustomerReference	string	The customer reference data associated with the invoice
CreatedDate	string	The creation date of the invoice
ExpiryDate	string	The expiry date for the invoice
InvoiceValue	number	The value of Capture/Release
Comments	string	Comments that are associated with the invoice (mainly used by portal users)
CustomerName	string	The customer name that was save along with the invoice
CustomerMobile	string	Customer mobile number
CustomerEmail	string	Customer email address
UserDefinedField	string	The user-defined field that was stored during the invoice creation
InvoiceDisplayValue	string	Invoice value that is displayed in case of a different currency from the base one
DueDeposit	number	The amount that will be deposited to the vendor
DepositStatus	string	The deposit status of the invoice, if it is "Deposited" or "Not Deposited".
InvoiceItems	Array of InvoiceItemModel objects
InvoiceTransactions	Array of InvoiceTransactionModel objects

InvoiceItemModel

Response Field	Type	Description
ItemName	string	Invoice item name that is stored with the invoice
Quantity	integer	Item Quantity
UnitPrice	number	Item unit price
Weight	number	100 >= Weight > 0 Weight in kg
Width	number	200 >= Width > 0 Width in cm
Height	number	160 >= Height > 0 Height in cm
Depth	number	200 >= Depth > 0 Depth in cm

InvoiceTransactionModel

Response Field	Type	Description
TransactionDate	string	The date of the transaction related to the invoice
PaymentGateway	string	The gateway the transaction was processed through
ReferenceId	string	The reference that is generated by the payment gateway
TrackId	string	The track number that is used to track the transaction with the gateway
TransactionId	string	The transaction ID
PaymentId	string	The payment ID that is assigned to this transaction
AuthorizationId	string	The authorization ID that is assigned to this transaction
TransactionStatus	string	The status of the transaction could be any of: InProgress_: The payment attempt is not completed Succss_: The capture was successful Failed_: A transaction attempt failed Authorize_: The client makes the payment Canceled_: The amount is released
TransationValue	string	The value of the transaction
CustomerServiceCharge	string	The service charges considered on the customer during the transaction
TotalServiceCharge	string	Total service charge deducted from MyFatoorah side
DueValue	string	The amount value of this transaction
PaidCurrency	string	The currency that was used to pay the transaction
PaidCurrencyValue	string	The currency value that was used to pay the transaction
VatAmount	string	The value of the VAT amount for the transaction.
Currency	string	Transaction currency
Error	string	The error message that might be associated with the transaction. This error is from the acquirer bank/platform
ErrorCode	string	The MyFatoorah error code. Kindly, refer to the Error Codes table.
ECI	string	The ECI record of the transaction.
Card	object	Contains details about the card used for payment.

📘
Transactions
Transactions information are totally related to the gateway response that came from the acquirer bank / platform. Not necessarily to have information to all the fields, and this was designed only to provide you information about all transactions that happened for a certain invoice

Card Model

Response Field	Type	Description
NameOnCard	string	The name of the cardholder entered by the payer.
Number	string	The masked card number.
PanHash	string	A unique identifier for the PAN.
ExpiryMonth	string	Expiry month entered by the customer.
ExpiryYear	string	Expiry year entered by the customer.
Brand	string	Visa/Mastercard/Mada
Issuer	string	Name of the issuer bank
IssuerCountry	string	The issuer country of the card
FundingMethod	string	The funding method of the card (e.g.: debit, credit, prepaid)

Sample Message

Capture Request:

{
  "Operation": "capture",
  "Amount": 2,
  "Key": "5822983",
  "KeyType": "Invoiceid"
}

{
    "IsSuccess": true,
    "Message": "",
    "ValidationErrors": null,
    "Data": {
        "InvoiceId": 5822983,
        "InvoiceStatus": "Paid",
        "InvoiceReference": "2025051962",
        "CustomerReference": "3MmGr8oXAtTnLciEoUAQp6ZZPdEZJ4",
        "CreatedDate": "2025-06-11T11:49:35.507",
        "ExpiryDate": "November 8, 2025",
        "ExpiryTime": "11:49:35.507",
        "InvoiceValue": 2.000,
        "Comments": null,
        "CustomerName": "Anonymous",
        "CustomerMobile": "+965",
        "CustomerEmail": null,
        "UserDefinedField": null,
        "InvoiceDisplayValue": "2.000 KD",
        "DueDeposit": 1.955,
        "DepositStatus": "Not Deposited",
        "InvoiceItems": [],
        "InvoiceTransactions": [
            {
                "TransactionDate": "2025-06-11T11:49:37.4666667",
                "PaymentGateway": "VISA/MASTER",
                "ReferenceId": "516208132783",
                "TrackId": "11-06-2025_2785331",
                "TransactionId": "132783",
                "PaymentId": "07075822983278533173",
                "AuthorizationId": "630070",
                "TransactionStatus": "Authorize",
                "TransationValue": "40.000",
                "CustomerServiceCharge": "0.000",
                "TotalServiceCharge": "0.780",
                "DueValue": "40.000",
                "PaidCurrency": "KD",
                "PaidCurrencyValue": "40.000",
                "VatAmount": "0.117",
                "IpAddress": "102.43.239.185",
                "Country": "Egypt",
                "Currency": "KD",
                "Error": null,
                "CardNumber": "545454xxxxxx5454",
                "ErrorCode": "",
                "ECI": "02",
                "Card": {
                    "NameOnCard": "test",
                    "Number": "545454xxxxxx5454",
                    "PanHash": "3cc8217a6aad545082e07e563edeec444ce961a2468fa1a5eddf238969095735",
                    "ExpiryMonth": "12",
                    "ExpiryYear": "34",
                    "Brand": "Mastercard",
                    "Issuer": "Test Bank",
                    "IssuerCountry": "KWT",
                    "FundingMethod": "credit"
                }
            },
            {
                "TransactionDate": "2025-06-11T11:50:21.8333333",
                "PaymentGateway": "VISA/MASTER",
                "ReferenceId": "516208132783",
                "TrackId": "11-06-2025_2785333",
                "TransactionId": "133803",
                "PaymentId": "07075822983278533374",
                "AuthorizationId": "630070",
                "TransactionStatus": "Succss",
                "TransationValue": "2.000",
                "CustomerServiceCharge": "0.000",
                "TotalServiceCharge": "0.039",
                "DueValue": "2.000",
                "PaidCurrency": "KD",
                "PaidCurrencyValue": "2.000",
                "VatAmount": "0.006",
                "IpAddress": null,
                "Country": null,
                "Currency": "KD",
                "Error": null,
                "CardNumber": "545454xxxxxx5454",
                "ErrorCode": "",
                "ECI": "02",
                "Card": {
                    "NameOnCard": "",
                    "Number": "545454xxxxxx5454",
                    "PanHash": "",
                    "ExpiryMonth": "",
                    "ExpiryYear": "",
                    "Brand": "",
                    "Issuer": "",
                    "IssuerCountry": "",
                    "FundingMethod": ""
                }
            }
        ],
        "Suppliers": []
    }
}

Kindly note that if the "amount" in the capture request is less than the primary "InvoiceValue", the "InvoiceValue" in the response will change to the amount entered in the request.

Release Request:

{
  "Operation": "release",
  "Amount": 40,
  "Key": "5822987",
  "KeyType": "Invoiceid"
}

{
    "IsSuccess": true,
    "Message": "",
    "ValidationErrors": null,
    "Data": {
        "InvoiceId": 5822987,
        "InvoiceStatus": "Pending",
        "InvoiceReference": "2025051963",
        "CustomerReference": "1P1seSwCdMTdUTjCKme6KKaMrbpf",
        "CreatedDate": "2025-06-11T11:51:23.727",
        "ExpiryDate": "November 8, 2025",
        "ExpiryTime": "11:51:23.727",
        "InvoiceValue": 40.000,
        "Comments": null,
        "CustomerName": "Anonymous",
        "CustomerMobile": "+965",
        "CustomerEmail": null,
        "UserDefinedField": null,
        "InvoiceDisplayValue": "40.000 KD",
        "DueDeposit": 0.000,
        "DepositStatus": "Not Deposited",
        "InvoiceItems": [],
        "InvoiceTransactions": [
            {
                "TransactionDate": "2025-06-11T11:51:25.1133333",
                "PaymentGateway": "VISA/MASTER",
                "ReferenceId": "516208135873",
                "TrackId": "11-06-2025_2785335",
                "TransactionId": "135873",
                "PaymentId": "07075822987278533574",
                "AuthorizationId": "538820",
                "TransactionStatus": "Authorize",
                "TransationValue": "40.000",
                "CustomerServiceCharge": "0.000",
                "TotalServiceCharge": "0.780",
                "DueValue": "40.000",
                "PaidCurrency": "KD",
                "PaidCurrencyValue": "40.000",
                "VatAmount": "0.117",
                "IpAddress": "102.43.239.185",
                "Country": "Egypt",
                "Currency": "KD",
                "Error": null,
                "CardNumber": "545454xxxxxx5454",
                "ErrorCode": "",
                "ECI": "02",
                "Card": {
                    "NameOnCard": "test",
                    "Number": "545454xxxxxx5454",
                    "PanHash": "3cc8217a6aad545082e07e563edeec444ce961a2468fa1a5eddf238969095735",
                    "ExpiryMonth": "12",
                    "ExpiryYear": "34",
                    "Brand": "Mastercard",
                    "Issuer": "Test Bank",
                    "IssuerCountry": "KWT",
                    "FundingMethod": "credit"
                }
            },
            {
                "TransactionDate": "2025-06-11T11:52:04.64",
                "PaymentGateway": "VISA/MASTER",
                "ReferenceId": "07075822987278533674",
                "TrackId": "11-06-2025_2785336",
                "TransactionId": "07075822987278533674",
                "PaymentId": "07075822987278533674",
                "AuthorizationId": "07075822987278533674",
                "TransactionStatus": "Canceled",
                "TransationValue": "40.000",
                "CustomerServiceCharge": "0.000",
                "TotalServiceCharge": "0.780",
                "DueValue": "40.000",
                "PaidCurrency": "KD",
                "PaidCurrencyValue": "40.000",
                "VatAmount": "0.117",
                "IpAddress": null,
                "Country": null,
                "Currency": "KD",
                "Error": "Transaction Released",
                "CardNumber": null,
                "ErrorCode": "",
                "ECI": null,
                "Card": {
                    "NameOnCard": "",
                    "Number": "",
                    "PanHash": "",
                    "ExpiryMonth": "",
                    "ExpiryYear": "",
                    "Brand": "",
                    "Issuer": "",
                    "IssuerCountry": "",
                    "FundingMethod": ""
                }
            }
        ],
        "Suppliers": []
    }
}

Sample Code

<?php

/* For simplicity check our PHP SDK library here https://myfatoorah.readme.io/php-library */

//PHP Notice:  To enable MyFatoorah auto-update, kindly give the write/read permissions to the library folder
//use zip file
include 'myfatoorah-library-2.2/MyfatoorahLoader.php';
include 'myfatoorah-library-2.2/MyfatoorahLibrary.php';

//use composer
//require 'vendor/autoload.php';
//use MyFatoorah\Library\MyFatoorah;

/* --------------------------- Configurations ------------------------------- */
//Test
$mfConfig = [
    /**
     * API Token Key (string)
     * Accepted value:
     * Live Token: https://myfatoorah.readme.io/docs/live-token
     * Test Token: https://myfatoorah.readme.io/docs/test-token
     */
    'apiKey' => '',
    /*
     * Vendor Country ISO Code (string)
     * Accepted value: KWT, SAU, ARE, QAT, BHR, OMN, JOD, or EGY. Check https://docs.myfatoorah.com/docs/iso-lookups
     */
    'vcCode' => 'KWT',
    /**
     * Test Mode (boolean)
     * Accepted value: true for the test mode or false for the live mode
     */
    'isTest' => true,
];

/* --------------------------- UpdatePaymentStatus Endpoint ----------------- */

//------------- Post Fields -------------------------
//Check https://docs.myfatoorah.com/docs/updatepaymentstatus#request-model
$postFields = [
    'Operation' => 'capture', //or 'release'
    'Amount'    => 1,
    'Key'       => '2834690',
    'KeyType'   => 'Invoiceid', //'PaymentId', or 'CustomerReference'
];

//------------- Call the Endpoint -------------------------
try {
    $mfObj  = new MyFatoorah($mfConfig);
    $apiURL = $mfObj->getApiUrl();
    $obj    = $mfObj->callAPI("$apiURL/v2/UpdatePaymentStatus", $postFields);

    //Display the result to your customer
    echo '<h3><u>UpdatePaymentStatus Response Object:</u></h3><pre>';
    print_r($obj);
    echo '</pre>';
} catch (Exception $ex) {
    echo $ex->getMessage();
    die;
}