Make Payment

To process a payment, there are two stages:

AUTH: Payment must be authorized by making a request with Action set to Auth. The vendor's request is validated, wallet funding is checked, and the biller's availability is confirmed. The account details of the specified member are returned for customer confirmation.

PAY: An authorized payment is then initiated with Action set to Pay. The vendor's wallet is debited and the product(s) or service(s) are provisioned.

warning

AUTH and PAY requests should be identical. Send the AUTH request prior to debiting the customer's payment method, to avoid having to refund them following an invalid request or incorrect member number.

info

In some cases, PAY may differ slightly from AUTH — e.g. if the customer's balance owing is returned during AUTH, the TotalAmount and each product's Price fields should be left blank in the PAY request.

Request

POST /api/payment/process

Payment Request Fields

Field	Type	Description	Required
Action	String	See Action values below	Required
BillerCode	String	Code identifying the biller	Required
Reference	String	Vendor's unique reference per transaction (same for AUTH and PAY)	Required
MemberNumber	String	The member number whose account/service/product will be credited	Required
Products	Array of PaymentProduct	The product(s) to be paid for	Required
TotalAmount	Decimal	Sum of product/service totals. Can be blank if AUTH returns balance/amount	Required
PayerDetails	PayerDetails	Details of vendor/customer payment. Required during PAY by some billers	Optional

Payment Product

Field	Type	Description	Required
Code	String	Unique identifier for the product	Required
Quantity	Integer	Defaults to 1 if not specified	Optional
Department	String	Mandatory if the product has a department	Sometimes
Price	Decimal	Leave blank if AUTH returns balance/amount. Required during PAY	Sometimes
RequiresForexPayment	Boolean	Required as acknowledgement of forex requirement	Sometimes
Metadata	Array of Key/Value Pairs	Any required metadata for the product	Sometimes

Payer Details

Only required by some billers, and when applicable only required during PAY (can be left blank during AUTH).

Field	Type	Description
BankAccountName	String	Source bank account name
BankAccountNumber	String	Source bank account number
BankName	String	Source bank name
BankBranch	String	Source bank branch
BankReference	String	Source bank reference, used for reconciliation
ContactNumber	String	Used by some billers to contact the payer
NationalId	String	Used by some billers to validate payer identity

Action

Action	Description
Auth	Authorize a payment before it can be initiated
Pay	Initiate an authorized payment
Retry	Retry a payment (in case of a retryable error or network interruption)
Status	Get the status of a payment

Sample Auth Request

// POST /api/payment/process
{
  "BillerCode": "COB",
  "MemberNumber": "ABC123",
  "Reference": "08be48c6-2624-4a06-95eb-be79ff5d6ef5",
  "TotalAmount": "100",
  "Products": [
    {
      "Code": "USD",
      "Quantity": "1",
      "Price": 100,
      "RequiresForexPayment": true
    }
  ],
  "Action": "AUTH"
}

Sample Pay Request

// POST /api/payment/process
{
  "BillerCode": "COB",
  "MemberNumber": "ABC123",
  "Reference": "08be48c6-2624-4a06-95eb-be79ff5d6ef5",
  "TotalAmount": "100",
  "Products": [
    {
      "Code": "USD",
      "Quantity": "1",
      "Price": 100,
      "RequiresForexPayment": true
    }
  ],
  "Action": "PAY"
}