Features Documentation
Start typing to search…

UpdatePaymentStatus

Endpoint

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 FieldTypeDescription
NameOnCardstringThe name of the cardholder entered by the payer.
NumberstringThe masked card number.
PanHashstringA unique identifier for the PAN.
ExpiryMonthstringExpiry month entered by the customer.
ExpiryYearstringExpiry year entered by the customer.
BrandstringVisa/Mastercard/Mada
IssuerstringName of the issuer bank
IssuerCountrystringThe issuer country of the card
FundingMethodstringThe 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;
}

Updated 21 days ago