Check Status API

Copy page

Copy page as Markdown for LLMs

Open in ChatGPT

Ask questions about this page

Open in Claude

Ask questions about this page

The check status operation allows you to verify the current state of any transaction processed through Amazon Payment Services. Use this API to check payment status, retrieve transaction details, verify authorized amounts, and get comprehensive transaction information for reporting and reconciliation purposes.

API Endpoints

https://sbpaymentservices.payfort.com/FortAPI/paymentApi

https://paymentservices.payfort.com/FortAPI/paymentApi

Request Format

• Method: POST
• Content-Type: application/json
• Submission: Server-to-server HTTPS POST

Request Parameters

Parameter
query_command   String Max: 50 Required Query operation command for status checking. Value: CHECK_STATUS Example. CHECK_STATUS
access_code   String Max: 20 Required Merchant access code obtained from Amazon Payment Services dashboard under Integration Settings. Example. s31bpM1ebfNnwqo8Kpg7
merchant_identifier   String Max: 20 Required Unique merchant identifier assigned by Amazon Payment Services during account setup. Example. FD1Ptq
merchant_reference   String Max: 40 Optional Your unique order reference used in the original transaction. Required if fort_id is not provided. Example. ORD-2024-001234
language   String Max: 2 Required Response language for messages and descriptions. Supported values: en (English) or ar (Arabic). Example. en
signature   String Max: 200 Required SHA-256 hash signature for request authentication and integrity validation. Example. 90f7092923c9eea8b0df6d509453a1791a36e2cd4a80eaef366e235b169a40e0
fort_id   Integer Max: 20 Optional Amazon Payment Services unique transaction reference. Required if merchant_reference is not provided. Example. 21722423333
maintenance_reference   String Max: 40 Optional Unique reference used in refund operations. When provided, allows checking the status of specific refund transactions without requiring fort_id or merchant_reference. Example. REF-REFUND-001
return_third_party_response_codes   String Max: 3 Optional Include third-party processor response codes in the response for enhanced debugging and reconciliation. Values: YES, NO Example. YES

You must provide either merchant_reference or fort_id (or both) to identify the transaction. The request will fail if neither is provided.

Check signature calculation section to learn how to calculate the signature.

Response Parameters

Parameter
query_command   String Max: 50 Query operation command from the request. Value: CHECK_STATUS Example. CHECK_STATUS
access_code   String Max: 20 Merchant access code used in the request. Example. s31bpM1ebfNnwqo8Kpg7
merchant_identifier   String Max: 20 Merchant identifier used in the request. Example. FD1Ptq
merchant_reference   String Max: 40 Unique order reference from the original transaction. Example. ORD-2024-001234
language   String Max: 2 Language used for the response messages. Example. en
signature   String Max: 200 Response signature for verification and security validation. Example. 90f7092923c9eea8b0df6d509453a1791a36e2cd4a80eaef366e235b169a40e0
fort_id   Integer Max: 20 Amazon Payment Services unique transaction reference. Example. 21722423333
response_message   String Max: 150 Human-readable response description in the requested language. Example. Success
response_code   String Max: 5 Five-digit response code indicating the query result. First 2 digits represent status, last 3 represent specific message. Example. 12000
status   String Max: 2 Two-digit status code indicating the current transaction state. Example. 20
transaction_status   String Max: 2 Status of the last operation performed on this specific transaction. Example. 20
transaction_code   String Max: 5 Response code for the last operation performed on this transaction. Example. 14000
transaction_message   String Max: 150 Message description for the last operation performed on this transaction. Example. Success
refunded_amount   Integer Max: 10 Total amount refunded for this transaction in smallest currency unit. Example. 5000
captured_amount   Integer Max: 10 Total amount captured for this transaction in smallest currency unit. Example. 10000
authorized_amount   Integer Max: 10 Total amount authorized for this transaction in smallest currency unit. Example. 10000
authorization_code   String Max: 100 Authorization code returned from the payment processor or issuing bank. Example. P1000000000000372136
processor_response_code   String Max: 100 Response code returned from the payment processor. Example. APPROVED
acquirer_response_code   String Max: 10 Response code returned from the acquiring bank. Example. 00

Check Status Sample Request

{
  "query_command": "CHECK_STATUS",
  "access_code": "s31bpM1ebfNnwqo8Kpg7",
  "merchant_identifier": "FD1Ptq",
  "merchant_reference": "ORD-2024-001234",
  "language": "en",
  "return_third_party_response_codes": "YES",
  "signature": "90f7092923c9eea8b0df6d509453a1791a36e2cd4a80eaef366e235b169a40e0"
}

import requests

status_data = {
    "query_command": "CHECK_STATUS",
    "access_code": "s31bpM1ebfNnwqo8Kpg7",
    "merchant_identifier": "FD1Ptq",
    "merchant_reference": "ORD-2024-001234",
    "language": "en",
    "return_third_party_response_codes": "YES",
    "signature": "90f7092923c9eea8b0df6d509453a1791a36e2cd4a80eaef366e235b169a40e0"
}

response = requests.post(
    "https://sbpaymentservices.payfort.com/FortAPI/paymentApi",
    json=status_data,
    headers={"Content-Type": "application/json"}
)

result = response.json()
print(result)

<?php
$statusData = [
    "query_command" => "CHECK_STATUS",
    "access_code" => "s31bpM1ebfNnwqo8Kpg7",
    "merchant_identifier" => "FD1Ptq",
    "merchant_reference" => "ORD-2024-001234",
    "language" => "en",
    "return_third_party_response_codes" => "YES",
    "signature" => "90f7092923c9eea8b0df6d509453a1791a36e2cd4a80eaef366e235b169a40e0"
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://sbpaymentservices.payfort.com/FortAPI/paymentApi");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($statusData));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Content-Type: application/json"
]);

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
print_r($result);
?>

const statusData = {
    query_command: "CHECK_STATUS",
    access_code: "s31bpM1ebfNnwqo8Kpg7",
    merchant_identifier: "FD1Ptq",
    merchant_reference: "ORD-2024-001234",
    language: "en",
    return_third_party_response_codes: "YES",
    signature: "90f7092923c9eea8b0df6d509453a1791a36e2cd4a80eaef366e235b169a40e0"
};

const response = await fetch("https://sbpaymentservices.payfort.com/FortAPI/paymentApi", {
    method: "POST",
    headers: {
        "Content-Type": "application/json"
    },
    body: JSON.stringify(statusData)
});

const result = await response.json();
console.log(result);

curl -X POST https://sbpaymentservices.payfort.com/FortAPI/paymentApi \
  -H "Content-Type: application/json" \
  -d '{
    "query_command": "CHECK_STATUS",
    "access_code": "s31bpM1ebfNnwqo8Kpg7",
    "merchant_identifier": "FD1Ptq",
    "merchant_reference": "ORD-2024-001234",
    "language": "en",
    "return_third_party_response_codes": "YES",
    "signature": "90f7092923c9eea8b0df6d509453a1791a36e2cd4a80eaef366e235b169a40e0"
  }'

Sample Response

{
  "query_command": "CHECK_STATUS",
  "access_code": "s31bpM1ebfNnwqo8Kpg7",
  "merchant_identifier": "FD1Ptq",
  "merchant_reference": "ORD-2024-001234",
  "language": "en",
  "signature": "90f7092923c9eea8b0df6d509453a1791a36e2cd4a80eaef366e235b169a40e0",
  "fort_id": "21722423333",
  "response_message": "Success",
    "response_code": "12000",
  "status": "20",
  "transaction_status": "20",
    "transaction_code": "14000",
  "transaction_message": "Success",
  "authorized_amount": "10000",
  "captured_amount": "10000",
  "refunded_amount": "0",
  "authorization_code": "P1000000000000372136",
  "processor_response_code": "APPROVED",
  "acquirer_response_code": "00"
}

Response Parameters

Parameter
query_command   String Max: 50 Query operation command from the request. Value: CHECK_STATUS Example. CHECK_STATUS
access_code   String Max: 20 Merchant access code used in the request. Example. s31bpM1ebfNnwqo8Kpg7
merchant_identifier   String Max: 20 Merchant identifier used in the request. Example. FD1Ptq
merchant_reference   String Max: 40 Unique order reference from the original transaction. Example. ORD-2024-001234
language   String Max: 2 Language used for the response messages. Example. en
signature   String Max: 200 Response signature for verification and security validation. Example. 90f7092923c9eea8b0df6d509453a1791a36e2cd4a80eaef366e235b169a40e0
fort_id   Integer Max: 20 Amazon Payment Services unique transaction reference. Example. 21722423333
response_message   String Max: 150 Human-readable response description in the requested language. Example. Success
response_code   String Max: 5 Five-digit response code indicating the query result. First 2 digits represent status, last 3 represent specific message. Example. 12000
status   String Max: 2 Two-digit status code indicating the current transaction state. Example. 20
transaction_status   String Max: 2 Status of the last operation performed on this specific transaction. Example. 20
transaction_code   String Max: 5 Response code for the last operation performed on this transaction. Example. 14000
transaction_message   String Max: 150 Message description for the last operation performed on this transaction. Example. Success
refunded_amount   Integer Max: 10 Total amount refunded for this transaction in smallest currency unit. Example. 5000
captured_amount   Integer Max: 10 Total amount captured for this transaction in smallest currency unit. Example. 10000
authorized_amount   Integer Max: 10 Total amount authorized for this transaction in smallest currency unit. Example. 10000
authorization_code   String Max: 100 Authorization code returned from the payment processor or issuing bank. Example. P1000000000000372136
processor_response_code   String Max: 100 Response code returned from the payment processor. Example. APPROVED
acquirer_response_code   String Max: 10 Response code returned from the acquiring bank. Example. 00

You can perform a check status API for refunds by passing only the maintenance_reference used in the refund API request, without needing to include the fort_id or merchant_reference. In this scenario, the CHECK_STATUS response will return the refunded amount linked to the specific maintenance_reference, rather than the total refunded amount, which is especially useful when handling multiple partial refunds under the same transaction.

Response Codes

For a complete list of response codes and their descriptions, please refer to our Error Codes Documentation.