Technical reference documentation
About this reference
The endpoint reference for the Precium Direct Debit (Mandates) API. Interactive documentation and a Postman collection are linked below; the tables on this page are the quick reference.
| Resource | Link |
|---|---|
| Interactive reference — production | api.revio.co.za/swagger |
| Interactive reference — sandbox | dev.api.revio.co.za/swagger |
| Postman collection | Debit Order API |
Environments
| 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 |
Unlike the card APIs, sandbox and production are separate hosts. Credentials are issued per environment and are not interchangeable.
API version
Two versions are served. Build against v2 — 88 operations against v1's 50, and the only version carrying account verification, bulk CSV, DebiCheck amend, poll and reset, settlement and statement data, mandate audit and reporting. v1 remains available for existing integrations and is not being extended.
The version is part of the path, so the two are parallel trees that share no endpoints. Every path below is v2 and is relative to the base URL.
Authentication
OAuth 2.0 client credentials. POST to the token endpoint with HTTP Basic authentication, then send the returned JWT as a bearer token.
curl -X POST https://prod-payce.auth.eu-west-1.amazoncognito.com/oauth2/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-u "$CLIENT_ID:$CLIENT_SECRET" \
-d "grant_type=client_credentials"Authorization: Bearer <access_token>Tokens are valid for 24 hours (expires_in: 86400). Cache and reuse one rather than requesting per call, and refresh on 401.
Mandates
A mandate is the payer's authority to collect. Create one before collecting.
| Method | Path | Purpose |
|---|---|---|
| GET, POST | /v2/mandate/debicheck | List or create DebiCheck mandates |
| GET, PUT, PATCH | /v2/mandate/debicheck/{mandateId} | Retrieve or update a mandate |
| POST | /v2/mandate/debicheck/{mandateId}/auth | Authenticate the mandate with the payer |
| POST | /v2/mandate/debicheck/{mandateId}/amend | Amend an authenticated mandate |
| POST | /v2/mandate/debicheck/{mandateId}/poll | Poll the bank for an authentication result |
| POST | /v2/mandate/debicheck/{mandateId}/reset | Reset to the previous valid state |
| GET | /v2/mandate/debicheck/{mandateId}/status | Latest status |
| GET, POST | /v2/mandate/eft | List or create EFT mandates |
| GET, PUT, PATCH, DELETE | /v2/mandate/eft/{mandateId} | Retrieve, update or delete |
| GET | /v2/mandate/eft/{mandateId}/status | Latest status |
| GET, POST | /v2/mandateresult | Mandate results |
| GET, POST | /v2/mandateaudit | Mandate audit trail |
| GET, DELETE | /v2/mandateaudit/{id} | A specific audit record |
amend sets requiresAuth internally — do not set it yourself.
Collections
A collection debits a payer under an existing mandate.
| Method | Path | Purpose |
|---|---|---|
| GET, POST | /v2/collection/debicheck | List or create DebiCheck collections |
| POST | /v2/collection/debicheck/from_mandate | Create from an existing mandate |
| GET, DELETE | /v2/collection/debicheck/{collectionId} | Retrieve or cancel |
| GET | /v2/collection/debicheck/{collectionId}/status | Latest status |
| POST | /v2/collection/debicheck/{collectionId}/recreate_as_eft | Recreate a failed DebiCheck collection as EFT |
| GET, POST | /v2/collection/eft | List or create EFT collections |
| POST | /v2/collection/eft/from_mandate | Create from an existing mandate |
| GET, DELETE | /v2/collection/eft/{collectionId} | Retrieve or cancel |
| GET | /v2/collection/eft/{collectionId}/status | Latest status |
| GET, POST | /v2/collectionresult | Collection results |
Payments
Outbound EFT credits to a bank account.
| Method | Path | Purpose |
|---|---|---|
| GET, POST | /v2/payment/eft | List or create EFT payments |
| GET, DELETE | /v2/payment/eft/{paymentId} | Retrieve or cancel |
| GET | /v2/payment/eft/{paymentId}/status | Latest status |
Bulk operations by CSV
Mandates, collections and payments can all be created in bulk. The pattern is identical for each: generate a template, upload it, then download the processed results.
| Method | Path pattern | Purpose |
|---|---|---|
| GET | /v2/{mandate|collection|payment}/{type}/upload/csv/generate_template | Download the correct CSV template |
| POST | /v2/{mandate|collection|payment}/{type}/upload/csv | Submit a populated CSV; returns a bulkUploadId |
| GET | /v2/{mandate|collection|payment}/{type}/download/csv/{bulkUploadId} | Download the processed results |
Always generate the template rather than constructing a CSV by hand — column order and headers are validated on upload.
Account verification
| Method | Path | Purpose |
|---|---|---|
| POST | /v2/accountverification/validate | Validate a bank account's structure |
| POST | /v2/accountverification/verify | Verify the account exists and matches the holder |
Verify before creating a mandate. An unverifiable account produces a mandate that will fail at collection.
Profiles
| Method | Path | Purpose |
|---|---|---|
| GET | /v2/merchantprofile | List merchant profiles |
| GET | /v2/merchantprofile/{id} | A specific merchant profile |
| GET | /v2/clientprofile | List client profiles |
| GET | /v2/clientprofile/{id} | A specific client profile |
GET /v2/merchantprofile is the simplest call to confirm a token works.
Callbacks
Register the URL you want events delivered to, then use the test endpoints to confirm your handler before going live.
| Method | Path | Purpose |
|---|---|---|
| GET, POST | /v2/clientcallbackurl | List or register your callback URL |
| GET, PUT, DELETE | /v2/clientcallbackurl/{id} | Retrieve, update or remove a registration |
| POST | /v2/callback/test/mandate/debicheck/{mandateId} | Trigger a test mandate callback |
| POST | /v2/callback/test/collection/debicheck/{collectionId} | Trigger a test DebiCheck collection callback |
| POST | /v2/callback/test/collection/eft/{collectionId} | Trigger a test EFT collection callback |
| POST | /v2/callback/test/payment/eft/{paymentId} | Trigger a test EFT payment callback |
| POST | /v2/callback/test/settlement/{settlementId} | Trigger a test settlement callback |
This API does not sign its callbacks. There is no signature header and no public key, so a callback cannot be authenticated from its content alone. Treat every callback as an untrusted notification: use it as a prompt to re-read the authoritative state from the relevant /status endpoint, and never act on the payload's values directly. This differs from the card APIs, which do sign callbacks — do not carry that assumption across.
Events
Polling alternatives to callbacks, each ordered by time so you can resume from where you left off.
| Method | Path | Purpose |
|---|---|---|
| GET | /v2/event/mandate | Mandate events |
| GET | /v2/event/collection | Collection events |
| GET | /v2/event/payment | Payment events |
| GET | /v2/event/profile | Profile events |
Because callbacks are unsigned, the event endpoints are the more trustworthy basis for reconciliation.
Settlement and reporting
| Method | Path | Purpose |
|---|---|---|
| GET | /v2/reporting | Reports per profile |
| GET | /v2/transactionfile | List transaction files |
| GET | /v2/transactionfile/{id} | A specific transaction file |
| GET | /v2/bankaccountstatement/{bankAccountNumber} | Statements for an account |
| GET | /v2/bankaccountstatement/{bankAccountNumber}/{id} | A specific statement |
| GET | /v2/bankaccountmarkoff | Mark-off details |
| GET | /v2/bankaccountsettlement/config/{configId}/execute | Settlement executions for a configuration |
Conventions
| Topic | Behaviour |
|---|---|
| Authentication | Bearer JWT from Cognito; 24-hour validity; refresh on 401 |
| Environments | Separate hosts and separate credentials for sandbox and production |
| Version | In the path. Build against /v2/ |
| Status | Every object type exposes a /status endpoint — the authoritative source |
| Callbacks | Unsigned. Use as a prompt to re-read state, not as a source of truth |
| Bulk | Generate template → upload → download results, keyed by bulkUploadId |
Status codes
| Code | Meaning |
|---|---|
200 / 201 | Success / created |
400 | Validation error — check the response body for the failing field |
401 | Token missing, malformed or expired. Request a new one |
403 | Token valid but not permitted for this profile |
404 | Not found, or the wrong API version in the path |
500 | Server error. Safe to retry reads |
Response codes specific to mandates and collections are in Response codes; diagnostics are in Troubleshooting.
