API References

Bulk Payments Service

Process multiple payment transactions with single OTP verification

1. Initiate Bulk Payment

Initiates a bulk payment request containing multiple payment transactions.

Subject: svc.account.<entity_id>.bulk_payment.initiate

Request

{
  "bulk_payment_id": "string",     // Required: unique identifier for this bulk payment batch
  "total_amount": 0,               // Required: total amount in cents for all transactions
  "payment_count": 0,              // Required: number of payments in this batch
  "description": "string",         // Required: description of the bulk payment batch
  "payments": [                    // Required: array of payment objects
    {
      "payment_id": "string",      // Required: unique identifier for this payment
      "amount": 0,                 // Required: amount in cents (ie. 1000 == ZAR 10.00)
      "ref": "string",             // Required: reference for the recipient (2-25 chars)
      "real_time": boolean,        // Required: pay and clear now option
      "own_ref": "string",         // Required: your reference (2-50 chars)
      "account_number": "string",  // Required: recipient account number
      "branch_code": "string",     // Required: bank branch code
      "name": "string",            // Required: recipient name
      "notification_email": "string" // Optional: must be valid email if provided
    }
  ],
  "callback_url": "string"         // Optional: webhook URL for status updates
}
FieldTypeRequiredDescription
bulk_payment_idstringrequiredUnique identifier for this bulk payment batch
total_amountnumberrequiredTotal amount in cents for all transactions
payment_countnumberrequiredNumber of payments in this batch
descriptionstringrequiredDescription of the bulk payment batch
paymentsarrayrequiredArray of payment objects, one per transfer (see fields below)
callback_urlstringoptionalWebhook URL for status updates

Payment object fields

Each item in the payments array must contain the following fields.

FieldTypeRequiredDescription
payment_idstringrequiredUnique identifier for this payment
amountnumberrequiredAmount in cents (ie. 1000 == ZAR 10.00)
refstringrequiredReference for the recipient (2-25 chars)
real_timebooleanrequiredPay and clear now option
own_refstringrequiredYour reference (2-50 chars)
account_numberstringrequiredRecipient account number
branch_codestringrequiredBank branch code
namestringrequiredRecipient name
notification_emailstringoptionalMust be valid email if provided

Key Features

  • Process up to 1000 payments in a single batch
  • Single OTP verification for entire batch
  • Mixed payment types supported (EFT and RTC)
  • Atomic processing (all succeed or all fail)
  • Real-time status tracking for each payment

Response

{
  "bulk_payment_id": "string",
  "status": "pending_otp",
  "otp_reference": "string",
  "expires_at": "2024-01-01T00:00:00Z",
  "total_amount": "string",
  "payment_count": 0
}

Possible Errors

  • 400 Bad Request: Invalid request data | Exceeds batch limit | Insufficient total funds
  • 401 Unauthorized: Authentication failed
  • 409 Conflict: Duplicate bulk_payment_id
  • 500 Internal Server Error: Server-side error occurred

2. Verify Bulk Payment OTP

Verifies the OTP and processes the bulk payment batch.

Subject: svc.account.<entity_id>.bulk_payment.verify

Request

{
  "bulk_payment_id": "string",  // Required: the bulk payment identifier
  "otp": "string"               // Required: the OTP code received
}
FieldTypeRequiredDescription
bulk_payment_idstringrequiredThe bulk payment identifier
otpstringrequiredThe OTP code received

Response

{
  "bulk_payment_id": "string",
  "status": "processing",
  "processed_count": 0,
  "total_count": 0,
  "payments": [
    {
      "payment_id": "string",
      "status": "processing",
      "tx_id": null
    }
  ]
}

Processing Notes

After OTP verification, payments are processed asynchronously. Use the status endpoint or webhook callbacks to track individual payment completion.

Possible Errors

  • 400 Bad Request: Invalid OTP | OTP expired
  • 404 Not Found: Bulk payment not found
  • 429 Too Many Requests: Too many OTP attempts

3. Get Bulk Payment Status

Retrieves the current status of a bulk payment batch and all individual payments.

Subject: svc.account.<entity_id>.bulk_payment.status

Request

{
  "bulk_payment_id": "string"  // Required: the bulk payment identifier
}
FieldTypeRequiredDescription
bulk_payment_idstringrequiredThe bulk payment identifier

Response

{
  "bulk_payment_id": "string",
  "status": "completed",        // pending_otp | processing | completed | failed | cancelled
  "created_at": "2024-01-01T00:00:00Z",
  "completed_at": "2024-01-01T00:00:00Z",
  "total_amount": "string",
  "successful_amount": "string",
  "failed_amount": "string",
  "payment_count": 0,
  "successful_count": 0,
  "failed_count": 0,
  "payments": [
    {
      "payment_id": "string",
      "status": "success",      // pending | processing | success | failed
      "tx_id": "string",
      "amount": "string",
      "recipient_name": "string",
      "error_message": null,
      "processed_at": "2024-01-01T00:00:00Z"
    }
  ]
}

Status Values

  • pending_otp: Awaiting OTP verification
  • processing: Payments are being processed
  • completed: All payments have been processed
  • failed: Batch processing failed
  • cancelled: Batch was cancelled

4. Cancel Bulk Payment

Cancels a pending bulk payment batch (only available before OTP verification).

Subject: svc.account.<entity_id>.bulk_payment.cancel

Request

{
  "bulk_payment_id": "string",  // Required: the bulk payment identifier
  "reason": "string"            // Optional: cancellation reason
}
FieldTypeRequiredDescription
bulk_payment_idstringrequiredThe bulk payment identifier
reasonstringoptionalCancellation reason

Response

{
  "bulk_payment_id": "string",
  "status": "cancelled",
  "cancelled_at": "2024-01-01T00:00:00Z",
  "reason": "string"
}

Possible Errors

  • 400 Bad Request: Cannot cancel: already processing
  • 404 Not Found: Bulk payment not found

Implementation Notes

Best Practices

  • Always validate total amounts before submission
  • Implement retry logic for failed individual payments
  • Use webhooks for real-time status updates
  • Store bulk_payment_id for reconciliation
  • Implement proper error handling for partial failures

Limits

  • Maximum 1000 payments per batch
  • OTP expires after 5 minutes
  • Maximum 3 OTP attempts per batch
  • Bulk payments cannot be modified after creation

Webhook Events

If a callback_url is provided, the following events will be sent:

  • bulk_payment.verified: OTP verified successfully
  • bulk_payment.completed: All payments processed
  • payment.success: Individual payment succeeded
  • payment.failed: Individual payment failed

For more information on webhook implementation, see the Notifications "Webhook" Service.