Documentation/API/Bulk Payments

Bulk Payments Service

Process multiple payment transactions with single OTP verification

VERTEX ENGINE

00

Table of Contents

  1. Initiate Bulk Payment
  2. Verify Bulk Payment OTP
  3. Get Bulk Payment Status
  4. Cancel Bulk Payment

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
}

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
}

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
}

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
}

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.

Previous: PaymentsNext: Cards