South Africa

The 54Pay Collections API enables merchants to accept payments in South Africa. After initiating a collection, the API returns a payment URL (redirectionUrl) which you redirect the customer to, where they complete payment via the hosted gateway.

Authentication

All API requests require authentication using your merchant credentials.

Headers

Header	Type	Description
X-module	string	Base64(amount+transactionReference+customerNumber)
X-business	string	Base64-encoded Merchant Public Key: {Base64(Merchant Public Key)}
Content-Type	string	Must be application/json
x-app	string	Must be api

Initiate Collection

Creates a payment collection request.

POST https://subsidiary.dev.mypaygate.co/collection/v1/payin

Request

curl --location 'https://subsidiary.dev.mypaygate.co/collection/v1/payin' --header 'Accept: application/json' --header 'X-module: {Base64(amount+transactionReference+customerNumber)}' --header 'X-business: {Base64(Merchant Public Key)}' --header 'Content-Type: application/json' --header 'X-app: api' --data-raw '{
  "requestHeader": {
      "clientId": "",
      "requestType": "Collections"
  },
  "customerName": "Thandiwe Mthethwa",
  "customerEmail": "a@a.com",
  "customerNumber": "27820000000",
  "transactionReference": "TXN10273646",
  "transactionDescription": "Test",
  "transactionAmount": 5,
  "transactionCurrency": "ZAF",
  "transactionCountry": "ZM",
  "successUrl": "https://54pay.co",
  "errorUrl": "https://54pay.co",
  "cancelUrl": "",
  "operatorCode": "ZAPYL",
  "webhookUrl": ""
}'
'

Response:

{
  "responseDetails": {
      "responseCode": "09",
      "responseMessage": "PENDING"
  },
  "transactionReference": "TXN10273646",
  "otpIsRequired": false,
  "lengthOfOtp": 0,
  "paymentCompletionRequired": false,
  "redirectionRequired": true,
  "redirectionUrl": "https://payments.pay-label.com/pay/hosted?payment_key=3ad19a39...&payment_type=eft"
}

Payment Completion:

Redirect the customer to the redirectionUrl to complete payment.

Flow: API Request → Receive Payment Link → Customer Completes Payment → Redirect to Success or Error URL

Webhooks

Payment Status Webhook

The API sends POST requests to your webhookUrl when payment status changes.

Sample Webhook

{
"transaction_reference": "176414160871313",
"transaction_status": "Funds Received",
"transaction_fee": 0,
"amount_received": 5,
"initiated_date": "2025-11-26 08:20:08",
"current_status_date": "2025-11-26 08:29:21",
"received_from": {},
"merchant_reference": "TXN10273646",
"status": "COMPLETED",
"channel": "MOBILE_MONEY",
"currency_code": "ZAR"
}

Webhook Status Values

Status	Description
COMPLETED	Payment successfully received
FAILED	Payment failed or expired

Webhook Implementation

Your webhook endpoint must:

1. Accept POST requests: Listen for incoming webhook notifications
2. Validate payload: Verify merchant_reference matches your records
3. Return 200 OK
4. Process asynchronously: Handle business logic after responding
5. Handle duplicates: Implement idempotency using transaction_reference

Webhook Security

• Verify requests originate from 54Pay IP addresses
• Validate the merchant_reference exists in your system
• Store webhook payloads for audit trail