EFT Debit orders

EFT debit orders (standard debit orders) enable merchants to collect funds from customer bank accounts with written, electronic, or voice-recorded authorisation.

‍

Overview

EFT debit orders are cost-efficient payment instruments for collecting recurring revenue. The process involves:

1. Create a Mandate: Obtain and store customer authorisation
2. Create Collections: Submit collection instructions against the mandate
3. Monitor Status: Track collection results and handle failures

‍

Service Types

‍

Mandates

A mandate represents the customer's authorisation to debit their account.

‍

Create EFT Mandate

Endpoint

POST /v2/mandate/eft/

‍

Request

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": "0001010000006",
        "phoneNumber": "+27-123456789",
        "passportNumber": ""
      }
    },
    "creditor": {
      "accountNumber": "12345678",
      "accountType": "CURRENT",
      "branchCode": "051001",
      "name": "TEST MERCHANT 1",
      "bank": "STANDARDBANK",
      "phoneNumber": "+27-615333440",
      "emailAddress": "merchant@test.com"
    },
    "releaseDate": "2024-12-31T00:00:00.000Z",
    "frequency": "MONTHLY",
    "collectionDay": 15,
    "amountCents": 10000,
    "currency": "ZAR",
    "entryClass": "21",
    "verifyAccount": false
  }'

‍

Request Fields

‍

Debtor Object

‍

Creditor Object

‍

Frequency Values

‍

Bank Names

Use uppercase, single-word format:

• ABSA
• STANDARDBANK
• FNB
• NEDBANK
• CAPITEC
• INVESTEC
• BIDVEST

‍

Response

JSON

{
  "id": "8f4a6b0f-fa9b-4f45-8e19-b75c1a70432a",
  "status": "ACTIVE",
  "defaultServiceType": "ONEDAY",
  "profileCode": "TEST1",
  "abbreviatedName": "TESTMERCH1",
  "contractReference": "CONTRACT001",
  "debtor": { ... },
  "creditor": { ... },
  "frequency": "MONTHLY",
  "collectionDay": 15,
  "amountCents": 10000,
  "createdAt": "2024-01-15T10:30:00.000Z"
}

‍

Bank Account Verification

Set verifyAccount: true to verify the debtor's bank account before creating the mandate:

‍

JSON

{
  "verifyAccount": true
}

‍

The verification checks:

• Account exists
• Account is open
• Account type matches
• Account accepts debits
• ID number matches the account holder

‍

If verification fails, the mandate will not be created. See Bank Account Verification for details.

‍

Ultimate Creditor (Split Payments)

For split payment scenarios, include the ultimateCreditor object:

‍

JSON

{
  "ultimateCreditor": {
    "accountNumber": "010553983",
    "accountType": "CURRENT",
    "branchCode": "051001",
    "name": "PARTNER COMPANY",
    "bank": "STANDARDBANK",
    "phoneNumber": "+27-615333440",
    "emailAddress": "partner@test.com",
    "idNumber": "0001010000089"
  }
}

‍

Collections

Collections are individual debit instructions processed against a mandate.

‍

Create EFT Collection

Endpoint

POST /v2/collection/eft/from_mandate/

‍

Request

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"
  }'

‍

Request Fields

‍

Response

JSON

{
  "id": "63d94be3-1faf-428b-89f3-bc5271be8015",
  "mandateId": "8f4a6b0f-fa9b-4f45-8e19-b75c1a70432a",
  "status": "PENDING",
  "collectionDate": "2024-02-15T00:00:00.000Z",
  "amountCents": 10000,
  "serviceType": "ONEDAY"
}

‍

Get Collection Status

Endpoint

GET /v2/collection/eft/{collectionId}/status/

‍

Request

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"

‍

Response

JSON

{
  "id": "63d94be3-1faf-428b-89f3-bc5271be8015",
  "status": "COMPLETED",
  "statementId": "stmt_12345"
}

‍

Collection Statuses

‍

Bank Account Verification

Verify customer bank details before creating mandates.

‍

Verification Checks

‍

Failure Response

JSON

{
  "value": {
    "Message": "Debtor account verification failure: details={\"AccountExists\":true,\"AccountIsOpen\":false,\"AccountTypeMatches\":null,\"IdNumberMatches\":null,\"AccountAcceptsDebits\":null}"
  },
  "statusCode": 400
}

‍

Cut-off Times

Submit collections before these cut-off times:

‍

‍

Reconciliation

Revio automatically reconciles collection results to bank statements. Successfully reconciled collections include a statementId field:

‍

JSON

{
  "id": "63d94be3-1faf-428b-89f3-bc5271be8015",
  "status": "COMPLETED",
  "statementId": "stmt_12345"
}

‍

Contact your Revio account manager to enable automatic reconciliation.

‍

Error Handling

Common Errors

‍

Unpaid Collections

When a collection returns unpaid:

• Do not resubmit until the next mandated date
• After 2 consecutive "Not provided for" failures, obtain a new mandate
• "Account Closed" or "Payment Stopped" requires customer contact

‍

Best Practices

1. Store mandate IDs: Keep track of mandate IDs for future collections
2. Use external references: Add your own references for easier reconciliation
3. Handle failures gracefully: Implement retry logic respecting PASA rules
4. Verify accounts: Use verifyAccount: true to reduce failed collections
5. Submit early: Submit collections well before cut-off times