Introduction
Debit Order API Documentation
Welcome to the Precium Debit Order API documentation. This API enables you to process debit order collections and EFT payments in South Africa.
Our Debit Order API is built on a comprehensive platform that handles the full complexity of South African payment processing. While you interact with our REST API endpoints, these backend services work together to ensure reliable, compliant, and automated debit order processing at scale.
Platform Services
| Service | Features & Capabilities |
|---|---|
| Authentication service | Secure OAuth2 implementation using bearer tokens for API authentication accross merchant profiles. |
| Scheduling service | Provides automated cut-off management for both internal and external timelines, with intelligent acquirer submission window management to ensure timely processing. |
| Mandate management service | Handles complete mandate lifecycle automation including mandate amendment processing and re-authentication workflows to maintain compliance and accuracy. |
| Batching service | Enables flexible user set management with support for multi-profile batch submission, allowing batching by account, userset, and abbreviated name. |
| Cut-off management service | Manages acquirer submission windows automatically, handles service type cutoff scheduling, and accounts for non-processing days to prevent failed submissions. |
| Submission service | Executes automated schedule processing with built-in recovery on processing failures. Handles bank response irregularities and ensures robustness on submissions and resubmissions within cutoff windows, with submission idempotency guarantees. |
| Results mapping service | Performs timeous mapping of result sets and manages result and dispute files. Tracks authentication results for both realtime and batch transactions with optimized large dataset management. |
| Reconciliation service | Provides automated mapping and reconciliation between reported results and bank statement results, with discrepancy detection and resolution capabilities. |
| Monitoring service | Offers real-time uptime monitoring with proactive fault detection and exception reporting and alerting across all system services. |
| Webhook service | Delivers real-time callback alerting for transaction status updates and mandate lifecycle notifications through configurable webhook endpoints per client system. |
| Multi-merchant capability | Supports management of multiple merchant profiles with abbreviated name separation, account-level separation of concerns, and independent configuration per merchant. |
| Multi-acquirer integration layer | Provides seamless integration with all South African acquirers, supporting different SFTP protocols and authentication standards. Handles file pattern normalisation across acquirers and standardises transaction and authentication results. |
What This Means for You
✓ Simplified Integration - You only need to integrate with our single, unified API
✓ Automatic Compliance - Cut-offs, windows, and banking rules are handled automatically
✓ Reliability - Built-in retry logic, error handling, and reconciliation
✓ Scale - Designed to handle high volumes with batch processing and large dataset support
✓ Multi-Bank - One API works with all major South African banks
✓ Real-Time Updates - Webhook integration keeps your systems synchronised
✓ White-Label Ready - Platforms can easily build their own branded debit order acquiring services on top of our infrastructure, with multi-merchant and multi-profile support enabling complete service separation
Documentation Structure
| Document | Description |
|---|---|
| Quickstart | Get up and running quickly |
| Authentication | API access and token management |
| Merchant Profiles | Managing merchant configurations |
| EFT Debit Orders | EFT mandate and collection management |
| DebiCheck | DebiCheck mandate and collection management |
| EFT Payments | Outbound EFT credit payments |
| Webhooks | Event notifications and callbacks |
| Testing | Sandbox environment and test scenarios |
| Going Live | Production readiness checklist |
| Response Codes | API status codes and error handling |
| Risk management | PASA rules, glossary, and additional information |
| Troubleshooting | Common issues and solutions |
| Glossary | Key terms |
API Base URLs
| Environment | URL |
|---|---|
| Sandbox | https://dev.api.revio.co.za/ |
| Production | https://api.revio.co.za/ |
API version
Two versions are served in production. Build against v2. It is a superset — 88 operations against v1's 50 — and carries account verification, bulk CSV upload and download, DebiCheck mandate amend, poll and reset, settlement and bank-account statements, mandate audit and reporting. v1 remains available for existing integrations and is not being extended.
The version sits in the path, so the two are parallel trees rather than successive revisions: /v1/… and /v2/… share no endpoints. Every example in this documentation uses v2.
| Environment | Base URL | Token endpoint |
|---|---|---|
| Sandbox | https://dev.api.revio.co.za/ | https://dev-payce.auth.eu-west-1.amazoncognito.com/oauth2/token |
| Production | https://api.revio.co.za/ | https://prod-payce.auth.eu-west-1.amazoncognito.com/oauth2/token |
Interactive reference: api.revio.co.za/swagger (production) and dev.api.revio.co.za/swagger (sandbox).
Key Features
- EFT Debit Orders: Collect recurring payments via standard EFT debit orders
- DebiCheck: Authenticated debit orders with reduced disputability
- EFT Payments: Same-day, one-day, and two-day outbound payments
- Bank Account Verification: Validate customer bank details before collection
- Webhooks: Real-time notifications for transaction status changes
- Automated Reconciliation: Match collections to bank statements automatically
Support
For technical support or to request API credentials, contact:
- Email: support@precium.com
Version
Current API Version: v2
