Request-To-Pay (TAN)

Overview

Request-To-Pay (RTP) collections utilize Timed Account Numbers (TAN) generated for the customer to finalize the payment through mobile money wallets or bank accounts using their digital channels. Unlike standard merchant account top-ups, these transactions represent direct bill payments, invoice settlements, or customer-initiated payment requests. OneKhusa notifies your system of these asynchronous push events via payrequest.success and payrequest.reversed.

Important: Do not trust any webhook notifications received, your system is required to verify prior to processing to avoid unauthorised notifications being processed.

Webhook Events

1. Successful RTP (`payrequest.success`)

The payrequest.success event is dispatched as soon as the end-user finalizes the payment request through their mobile banking or MNO application. This event confirms that the funds have been successfully debited from the customer’s account and credited to your merchant account.

HTTP Event Headers

POST your-callback-url HTTP/1.1
Host: onekhusa.com
Content-Type: application/json
X-OneKhusa-Webhook-Event: payrequest.success
X-OneKhusa-Webhook-Signature: e7b41920d39b821a9b71d2fe4a39281a8b329487c53d10a972c7247853b01938

Webhook JSON Payload

{
    "connectorId": 892353,
    "sourceAccountNumber": "74629183",
    "sourceAccountName": "OneKhusa Suppliers Ltd",
    "sourceInstitution": "National Bank of Malawi",
    "sourceReferenceNumber": "SRC4K8L2M9Q1Z",
    "beneficiaryAccountNumber": "102345678901",
    "transactionReferenceNumber": "250905SLFVXD",
    "transactionDescription": "Payment for invoice INV-2025-1010",
    "transactionAmount": 320500.75,
    "transactionFee": 1000.00,
    "transactionDate": "2025-10-10T14:50:00Z",
    "transactionStatusCode": "S",
    "transactionCode": "BAM",
    "responseCode": "S100",
    "metaData": {
        "timedAccountNumber": "11005533",
        "referenceNumber": "1020XDFS76GS777",
        "sourceDescription": "Samsung 85inch TV purchase"
    }
}

2. RTP Reversal (`payrequest.reversed`)

The payrequest.reversed event is emitted if an executed Request-To-Pay transaction is subsequently rolled back due to downstream network clearing issues, carrier settlement errors, or processed customer dispute claims. This event alerts your system to debit the corresponding account balance internally.

HTTP Event Headers

POST your-callback-url HTTP/1.1
Host: onekhusa.com
Content-Type: application/json
X-OneKhusa-Webhook-Event: payrequest.reversed
X-OneKhusa-Webhook-Signature: a8f3b019388d901f421f1e2989b71d2fe4a39281a8b329487c53d10a972c7247

Webhook JSON Payload

{
    "connectorId": 247482,
    "sourceAccountNumber": "74629183",
    "sourceAccountName": "OneKhusa Suppliers Ltd",
    "sourceInstitution": "Airtel Money",
    "sourceReferenceNumber": "SRC4K8L2M9Q1Z",
    "beneficiaryAccountNumber": "2659912345678",
    "transactionReferenceNumber": "251014SRTYXB",
    "transactionDescription": "Payment for invoice INV-2025-1010",
    "transactionAmount": 320500.75,
    "transactionFee": 1000.00,
    "transactionDate": "2025-10-10T14:50:00Z",
    "transactionStatusCode": "R",
    "transactionCode": "MWM",
    "responseCode": "S100",
    "metaData": {
        "timedAccountNumber": "11005533",
        "referenceNumber": "1020XDFS76GS777",
        "sourceDescription": "Samsung 85inch TV purchase"
    }
}

For detailed field descriptions, refer to the Field Descriptions section in the Collection Webhooks Overview.

Getting Started

Accept Payments

Disbursements

Bill Payments

Merchants

Disputes

Security

Supporting APIs

Overview

Webhook Events

1. Successful RTP (`payrequest.success`)

HTTP Event Headers

Webhook JSON Payload

2. RTP Reversal (`payrequest.reversed`)

HTTP Event Headers

Webhook JSON Payload

​Overview

​Webhook Events

​1. Successful RTP (payrequest.success)

​HTTP Event Headers

​Webhook JSON Payload

​2. RTP Reversal (payrequest.reversed)

​HTTP Event Headers

​Webhook JSON Payload

Overview

Webhook Events

1. Successful RTP (`payrequest.success`)

HTTP Event Headers

Webhook JSON Payload

2. RTP Reversal (`payrequest.reversed`)

HTTP Event Headers

Webhook JSON Payload