Integration quick start
Overview
The Precium Debit Order API enables you to generate ad-hoc or recurring debit order payments and collections. This guide will help you make your first API call.
Prerequisites
Before you begin, you will need:
- API Credentials: Contact our sales team at support@precium.com to request your sandbox username and password
- Postman or HTTP Client: For testing API requests
- Understanding of South African debit orders: Familiarity with EFT and DebiCheck payment instruments
Step 1: Obtain Access Token
All API requests require a Bearer token. Generate one using OAuth 2.0 Client Credentials flow:
BASH
curl -X POST https://dev-payce.auth.eu-west-1.amazoncognito.com/oauth2/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-u "YOUR_USERNAME:YOUR_PASSWORD" \
-d "grant_type=client_credentials"
Response:
JSON
{
"access_token": "eyJraWQiOiJ...",
"expires_in": 86400,
"token_type": "Bearer"
}
Note: Access tokens expire every 24 hours.
Step 2: Get Your Merchant Profile
Retrieve your merchant profile to obtain the required configuration values:
BASH
curl -X GET https://dev.api.revio.co.za/v2/merchantprofile/ \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
Response:
JSON
[
{
"id": "24",
"profileCode": "TEST1",
"abbreviatedName": "TESTMERCH1",
"accountNumber": "12345678",
"branchCode": "051001",
"name": "TEST MERCHANT 1",
"instruments": ["EFTONEDAY", "EFTTWODAY", "EFTSAMEDAY", "DEBICHECK"],
"currency": "ZAR",
"entryClass": "21"
}
]
Store these values—you'll need them for subsequent API calls:
profileCodeabbreviatedNameaccountNumber(creditor account)branchCode(creditor branch)name(creditor name)
Step 3: Create Your First EFT Mandate
Create a mandate to authorise future collections from a customer:
BASH
curl -X POST https://dev.api.revio.co.za/v2/mandate/eft/ \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"defaultServiceType": "ONEDAY",
"profileCode": "TEST1",
"abbreviatedName": "TESTMERCH1",
"contractReference": "CONTRACT001",
"debtor": {
"accountNumber": "010553922",
"accountType": "CURRENT",
"bank": "ABSA",
"branchCode": "632005",
"firstName": "John",
"lastName": "Smith",
"identification": {
"emailAddress": "john@example.com",
"idNumber": "2001014800086",
"phoneNumber": "+27-123456789"
}
},
"creditor": {
"accountNumber": "12345678",
"accountType": "CURRENT",
"branchCode": "051001",
"name": "TEST MERCHANT 1",
"bank": "STANDARDBANK",
"phoneNumber": "+27-615333440",
"emailAddress": "merchant@test.com"
},
"frequency": "MONTHLY",
"collectionDay": 15,
"amountCents": 10000,
"currency": "ZAR",
"entryClass": "21"
}'
Response:
JSON
{
"id": "8f4a6b0f-fa9b-4f45-8e19-b75c1a70432a",
"status": "ACTIVE",
"contractReference": "CONTRACT001",
...
}
Step 4: Create a Collection
Use the mandate ID to create a collection:
BASH
curl -X POST https://dev.api.revio.co.za/v2/collection/eft/from_mandate/ \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"mandateId": "8f4a6b0f-fa9b-4f45-8e19-b75c1a70432a",
"collectionDate": "2024-02-15T00:00:00.000Z",
"amountCents": 10000,
"serviceType": "ONEDAY"
}'
Response:
JSON
{
"id": "63d94be3-1faf-428b-89f3-bc5271be8015",
"status": "PENDING",
...
}
Step 5: Check Collection Status
Monitor the collection status:
BASH
curl -X GET https://dev.api.revio.co.za/v2/collection/eft/63d94be3-1faf-428b-89f3-bc5271be8015/status/ \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
Quick Reference
Next Steps
- Authentication - Learn about token management
- EFT Debit Orders - Detailed EFT mandate and collection guide
- DebiCheck - Authenticated debit order collections
- Testing - Test scenarios and mock bank simulation
Resources
- Postman Collection: Available for download from the Precium technical reference documentation
