Confirming a Transaction

This section explains how you can confirm the status of a completed payment process.

There are two endpoints available to confirm the status of a completed payment process; whichever one you decide to utilize is up to you based on your application's needs.

Ensure to set the correct mode in your request header (sandbox or live)

Always pay attention to the status field, as it accurately reflects the transaction outcome. The ResponseDescription provides the reason behind that outcome.

1. /payment_process/confirmation/{AIRGATE_TRANSACTION_REF}

Use the above endpoint to confirm a transaction using the airgate generated transaction reference Below are sample responses if you're using the above endpoint

Successful transaction sample response

{
    "success": true,
    "response": {
        "Amount": 1000,
        "CardNumber": "",
        "MerchantReference": "b4f1c959-f19e-4b3a-a081-627964827b6d",
        "PaymentReference": "GTB|API|MX21696|06-03-2025|474796270|565639",
        "RetrievalReferenceNumber": "000106923853",
        "Stan": "000008",
        "Channel": "API",
        "TerminalId": "3PXM0001",
        "SplitAccounts": [],
        "TransactionDate": "2025-03-06T11:18:16",
        "ResponseCode": "00",
        "ResponseDescription": "Approved by Financial Institution",
        "BankCode": "058",
        "PaymentId": 474796270,
        "RemittanceAmount": 0
    },
    "status_code": 200,
    "merchant": {
        "first_name": "victor",
        "last_name": "olorunfemi",
        "email": "[e-mail]",
        "phone_number": "8135681176",
        "is_compliance_verified": 1
    },
    "customer_transaction_ref": "b4f1c959-f19e-4b3a-a081-627964827b6d",
    "status": "Successful"
}

Failed transaction sample response

{
    "success": false,
    "response": {
        "Amount": 1000,
        "CardNumber": "",
        "MerchantReference": "2c3f50f7-cb3b-4657-bd59-e05d98366da5",
        "PaymentReference": "KYB|API|MX21696|06-03-2025|474796279|511246",
        "RetrievalReferenceNumber": "000106923853",
        "Stan": "000008",
        "Channel": "API",
        "TerminalId": "3PXM0001",
        "SplitAccounts": [],
        "TransactionDate": "2025-03-06T11:22:03",
        "ResponseCode": "Z1",
        "ResponseDescription": "Transaction Error",
        "BankCode": "KYB",
        "PaymentId": 474796279,
        "RemittanceAmount": 0
    },
    "status_code": 200,
    "merchant": {
        "first_name": "victor",
        "last_name": "olorunfemi",
        "email": "[e-mail]",
        "phone_number": "8135681176",
        "is_compliance_verified": 1
    },
    "customer_transaction_ref": "2c3f50f7-cb3b-4657-bd59-e05d98366da5",
    "status": "Unsuccessful"
}

1. /payment_process/confirmation_by_cutomer_ref/{CUSTOMER_TRANSACTION_REF}

If you choose to use this endpoint, keep in mind that txn_list will always be an array of objects. The most recent entry is always at index 0, so refer to txn_list[0] to access the latest transaction record.

Use the above endpoint to confirm a transaction using your unique customer transaction reference

Below are sample responses if you're using the above endpoint

Failed transaction sample response

{
    "success": true,
    "txn_count": 1,
    "txn_list": [
        {
            "success": false,
            "response": {
                "Amount": 1000,
                "CardNumber": "",
                "MerchantReference": "92635775-b459-4f6e-ba76-d77997d05d7f",
                "PaymentReference": "FBN|API|MX21696|06-03-2025|474796300|440510",
                "RetrievalReferenceNumber": "000106923853",
                "Stan": "000008",
                "Channel": "API",
                "TerminalId": "3PXM0001",
                "SplitAccounts": [],
                "TransactionDate": "2025-03-06T11:56:14",
                "ResponseCode": "51",
                "ResponseDescription": "Insufficient Funds",
                "BankCode": "011",
                "PaymentId": 474796300,
                "RemittanceAmount": 0
            },
            "status_code": 200,
            "merchant": {
                "first_name": "victor",
                "last_name": "olorunfemi",
                "email": "[e-mail]",
                "phone_number": "8135681176",
                "is_compliance_verified": 1
            },
            "customer_transaction_ref": "AIR12987",
            "status": "Unsuccessful",
            "internal_transaction_ref": "92635775-b459-4f6e-ba76-d77997d05d7f"
        }
    ]
}

Successful transaction sample response

{
    "success": true,
    "txn_count": 1,
    "txn_list": [
        {
            "success": true,
            "response": {
                "Amount": 1000,
                "CardNumber": "",
                "MerchantReference": "b4f1c959-f19e-4b3a-a081-627964827b6d",
                "PaymentReference": "GTB|API|MX21696|06-03-2025|474796270|565639",
                "RetrievalReferenceNumber": "000106923853",
                "Stan": "000008",
                "Channel": "API",
                "TerminalId": "3PXM0001",
                "SplitAccounts": [],
                "TransactionDate": "2025-03-06T11:18:16",
                "ResponseCode": "00",
                "ResponseDescription": "Approved by Financial Institution",
                "BankCode": "058",
                "PaymentId": 474796270,
                "RemittanceAmount": 0
            },
            "status_code": 200,
            "merchant": {
                "first_name": "Victor",
                "last_name": "Olorunfemi",
                "email": "[e-mail]",
                "phone_number": "8135681176",
                "is_compliance_verified": 1
            },
            "customer_transaction_ref": "b4f1c959-f19e-4b3a-a081-627964827b6d",
            "status": "Successful"
        }
    ]
}