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 ParameterTypeDescription
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 floatThe 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
KeystringRefers to the Invoice ID, payment ID, or Customer Reference based on the key type
KeyTypestring"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 FieldTypeDescription
InvoiceId numberRepresents the invoice ID that was used in the inquiry call
InvoiceStatus string"Pending": The customer made the payment but no operations on it OR A release is made on the amount.
"Paid": A capture is made on the amount
InvoiceReference stringInvoice reference that MyFatoorah generates
CustomerReference stringThe customer reference data associated with the invoice
CreatedDate stringThe creation date of the invoice
ExpiryDate stringThe expiry date for the invoice
InvoiceValue numberThe value of Capture/Release
Comments stringComments that are associated with the invoice (mainly used portal use users)
CustomerName stringThe customer name that was save along with the invoice
CustomerMobile stringCustomer mobile number
CustomerEmail stringCustomer email address
UserDefinedField stringThe user-defined field that was stored during the invoice creation
InvoiceDisplayValue stringInvoice value that is displayed in case of a different currency from the base one
DueDepositnumberThe amount that will be deposited to the vendor
DepositStatusstringThe deposit status of the invoice, if it is "Deposited" or "Not Deposited".
InvoiceItems Array of InvoiceItemModel objects
InvoiceTransactions Array of InvoiceTransactionModel objects

InvoiceItemModel

Response FieldTypeDescription
ItemName stringInvoice item name that is stored with the invoice
Quantity integerItem quantity
UnitPrice numberItem unit price
Weight number100 >= Weight > 0
Weight in kg
Width number200 >= Width > 0
Width in cm
Height number160 >= Height > 0
Height in cm
Depth number200 >= Depth > 0
Depth in cm

InvoiceTransactionModel

Response FieldTypeDescription
TransactionDate stringThe date of the transaction related to the invoice
PaymentGateway stringThe gateway the transaction was processed through
ReferenceId stringThe reference that is generated by the payment gateway
TrackId stringThe track number that is used to track the transaction with the gateway
TransactionId stringThe transaction ID
PaymentId stringThe payment ID that is assigned to this transaction
AuthorizationId stringThe authorization ID that is assigned to this transaction
TransactionStatus stringThe 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 stringThe value of the transaction
CustomerServiceCharge stringThe service charges considered on the customer during the transaction
TotalServiceChargestringTotal service charge deducted from MyFatoorah side
DueValue stringThe amount value of this transaction
PaidCurrency stringThe currency that was used to pay the transaction
PaidCurrencyValue stringThe currency value that was used to pay the transaction
VatAmountstringThe value of the VAT amount for the transaction.
Currency stringTransaction currency
Error stringThe error message that might be associated with the transaction.
This error is from the acquirer bank/platform
ErrorCode stringThe MyFatoorah error code. Kindly, refer to the Error Codes table.

📘

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


Sample Message

Capture Request:

{
  "Operation": "capture",
  "Amount": 100,
  "Key": "2834690",
  "KeyType": "Invoiceid"
}
{
  "IsSuccess": true,
  "Message": "",
  "ValidationErrors": null,
  "Data": {
    "InvoiceId": 2834690,
    "InvoiceStatus": "Paid",
    "InvoiceReference": "2023018001",
    "CustomerReference": null,
    "CreatedDate": "2023-10-08T14:17:44.027",
    "ExpiryDate": "February 5, 2024",
    "ExpiryTime": "14:17:44.027",
    "InvoiceValue": 100,
    "Comments": null,
    "CustomerName": "Anonymous",
    "CustomerMobile": "+965",
    "CustomerEmail": null,
    "UserDefinedField": null,
    "InvoiceDisplayValue": "100.000 KD",
    "DueDeposit": 97.447,
    "DepositStatus": "Not Deposited",
    "InvoiceItems": [],
    "InvoiceTransactions": [
      {
        "TransactionDate": "2023-10-08T14:17:48.4466667",
        "PaymentGateway": "VISA/MASTER",
        "ReferenceId": "328111054824",
        "TrackId": "08-10-2023_1724719",
        "TransactionId": "54824",
        "PaymentId": "07072834690172471973",
        "AuthorizationId": "054824",
        "TransactionStatus": "Authorize",
        "TransationValue": "250.000",
        "CustomerServiceCharge": "0.000",
        "TotalServiceCharge": "5.550",
        "DueValue": "250.000",
        "PaidCurrency": "KD",
        "PaidCurrencyValue": "250.000",
        "VatAmount": "0.832",
        "IpAddress": "197.58.17.110",
        "Country": "Egypt",
        "Currency": "KD",
        "Error": null,
        "CardNumber": "450875xxxxxx1019",
        "ErrorCode": ""
      },
      {
        "TransactionDate": "2023-10-08T14:18:56.5033333",
        "PaymentGateway": "VISA/MASTER",
        "ReferenceId": "328111054824",
        "TrackId": "08-10-2023_1724720",
        "TransactionId": "63720",
        "PaymentId": "07072834690172472072",
        "AuthorizationId": "054824",
        "TransactionStatus": "Succss",
        "TransationValue": "100.000",
        "CustomerServiceCharge": "0.000",
        "TotalServiceCharge": "2.220",
        "DueValue": "100.000",
        "PaidCurrency": "KD",
        "PaidCurrencyValue": "100.000",
        "VatAmount": "0.333",
        "IpAddress": null,
        "Country": null,
        "Currency": "KD",
        "Error": null,
        "CardNumber": "450875xxxxxx1019",
        "ErrorCode": ""
      }
    ],
    "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": 250,
  "Key": "2834691",
  "KeyType": "Invoiceid"
}
{
  "IsSuccess": true,
  "Message": "",
  "ValidationErrors": null,
  "Data": {
    "InvoiceId": 2834691,
    "InvoiceStatus": "Pending",
    "InvoiceReference": "2023018002",
    "CustomerReference": null,
    "CreatedDate": "2023-10-08T14:19:43.77",
    "ExpiryDate": "February 5, 2024",
    "ExpiryTime": "14:19:43.770",
    "InvoiceValue": 250,
    "Comments": null,
    "CustomerName": "Anonymous",
    "CustomerMobile": "+965",
    "CustomerEmail": null,
    "UserDefinedField": null,
    "InvoiceDisplayValue": "250.000 KD",
    "DueDeposit": 0,
    "DepositStatus": "Not Deposited",
    "InvoiceItems": [],
    "InvoiceTransactions": [
      {
        "TransactionDate": "2023-10-08T14:19:48.3333333",
        "PaymentGateway": "VISA/MASTER",
        "ReferenceId": "328111059655",
        "TrackId": "08-10-2023_1724721",
        "TransactionId": "59655",
        "PaymentId": "07072834691172472172",
        "AuthorizationId": "059655",
        "TransactionStatus": "Authorize",
        "TransationValue": "250.000",
        "CustomerServiceCharge": "0.000",
        "TotalServiceCharge": "5.550",
        "DueValue": "250.000",
        "PaidCurrency": "KD",
        "PaidCurrencyValue": "250.000",
        "VatAmount": "0.832",
        "IpAddress": "197.58.17.110",
        "Country": "Egypt",
        "Currency": "KD",
        "Error": null,
        "CardNumber": "450875xxxxxx1019",
        "ErrorCode": ""
      },
      {
        "TransactionDate": "2023-10-08T14:20:20.8033333",
        "PaymentGateway": "VISA/MASTER",
        "ReferenceId": "07072834691172472273",
        "TrackId": "08-10-2023_1724722",
        "TransactionId": "07072834691172472273",
        "PaymentId": "07072834691172472273",
        "AuthorizationId": "07072834691172472273",
        "TransactionStatus": "Canceled",
        "TransationValue": "250.000",
        "CustomerServiceCharge": "0.000",
        "TotalServiceCharge": "5.550",
        "DueValue": "250.000",
        "PaidCurrency": "KD",
        "PaidCurrencyValue": "250.000",
        "VatAmount": "0.832",
        "IpAddress": null,
        "Country": null,
        "Currency": "KD",
        "Error": "Transaction Released",
        "CardNumber": null,
        "ErrorCode": ""
      }
    ],
    "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'      => '',
    /*
     * Country ISO Code (string)
     * Accepted value: KWT, SAU, ARE, QAT, BHR, OMN, JOD, or EGY. Check https://docs.myfatoorah.com/docs/iso-lookups
     */
    'countryCode' => '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;
}