# Testing (/docs/direct-debit/testing)

The Revio sandbox environment provides a mock-bank infrastructure for comprehensive testing.

## Overview [#overview]

The sandbox allows you to:

- Test mandate creation, collections, and payments
- Simulate bank processing and status changes
- Test error scenarios and edge cases
- Verify webhook integrations

## Getting Started [#getting-started]

### Request Test Credentials [#request-test-credentials]

Contact Precium at support@precium.com to request sandbox credentials:

- `client_id` (username)
- `client_secret` (password)

### Test Resources [#test-resources]

| Resource | Location |
|---|---|
| Postman Collection | [Download](https://revio-direct-debit-order-api.readme.io/) |
| Swagger Documentation | `https://dev.api.revio.co.za/swagger/index.html` |
| Sandbox API | `https://dev.api.revio.co.za/` |
| Production API | `https://api.revio.co.za/` — do not test against this |

## Test Merchant Profile [#test-merchant-profile]

Use this pre-configured profile for sandbox testing:

| Field | Value |
|---|---|
| `id` | `24` |
| `profileCode` | `TEST1` |
| `abbreviatedName` | `TESTMERCH1` |
| `accountNumber` | `12345678` |
| `branchCode` | `051001` |
| `name` | `TEST MERCHANT 1` |
| `instruments` | `EFTONEDAY`, `EFTTWODAY`, `EFTSAMEDAY`, `DEBICHECK` |
| `currency` | `ZAR` |
| `entryClass` | `21` |
| `createdByClient` | `109` |

## Mock Bank Simulation [#mock-bank-simulation]

The mock bank simulates real bank processing, including:

- Status changes (PENDING → COMPLETED/UNPAID)
- Business rules enforcement
- Response file generation

### Simulation Scenarios [#simulation-scenarios]

| Instrument | Available Tests |
|---|---|
| EFT Debit Order | Create mandate, amend mandate, create collection |
| DebiCheck | Create mandate (TT1/TT2), amend mandate, cancel/suspend, create collection |
| EFT Payments | Create payment, delete payment |

## EFT Collection Test Scenarios [#eft-collection-test-scenarios]

Use specific account numbers to simulate different outcomes:

### Account Number Scenarios [#account-number-scenarios]

| Account Number | Scenario | Description |
|---|---|---|
| `910000001` | Full reject | Receive full rejection response |
| `910000002` | Batch rejection | Receive batch rejection response |
| `210000001` | Dispute | Dispute file 40 seconds after response |
| `110000001` | Accepted | Accepted file 40 seconds after pending |
| `110000002` | Unpaid | Unpaid file 40 seconds after pending |
| `110000003` | Accepted (3 days) | Accepted with settlement 3 days out |
| `110000004` | Unpaid (3 days) | Unpaid with settlement 3 days out |
| `110000005` | Accepted (5 days) | Accepted with settlement 5 days out |
| `110000006` | Unpaid (5 days) | Unpaid with settlement 5 days out |
| Any other | Success | Accepted response |

### Example: Test Unpaid Collection [#example-test-unpaid-collection]

```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 '{
    "debtor": {
      "accountNumber": "110000002",
      ...
    },
    ...
  }'
```

## DebiCheck Mandate Test Scenarios [#debicheck-mandate-test-scenarios]

Use specific contract references to simulate authentication outcomes:

### Contract Reference Scenarios [#contract-reference-scenarios]

| Contract Reference | Scenario | Description |
|---|---|---|
| `NORESPONSE` | No response | Customer doesn't respond within 120 seconds |
| `FAILINIT` | Init failure | Unexpected bank error during authentication |
| `REJECT` | Rejected | Customer rejects the mandate |
| `TIMEOUT` | Timeout | Authentication times out waiting for bank |
| Any other | Success | Mandate authenticated successfully |

### Example: Test Rejected Mandate [#example-test-rejected-mandate]

```bash
curl -X POST https://dev.api.revio.co.za/v2/mandate/debicheck/ \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "contractReference": "REJECT",
    "authenticationType": "REALTIME",
    ...
  }'
```

### Example: Test No Response [#example-test-no-response]

```bash
curl -X POST https://dev.api.revio.co.za/v2/mandate/debicheck/ \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "contractReference": "NORESPONSE",
    "authenticationType": "REALTIME",
    "fallbackAuthenticationType": "DELAYED_WITHOUT_AUTH",
    ...
  }'
```

## Webhook Testing [#webhook-testing]

### Simulate Status Changes [#simulate-status-changes]

Test callback handling by simulating status changes:

```bash
curl -X POST https://dev.api.revio.co.za/v2/callback/test/collection/eft/{collectionId}/ \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "collectionStatus": "UNPAID",
    "callbackVersion": "V2"
  }
```

### Test with Override URL [#test-with-override-url]

Send callbacks to a test endpoint:

```bash
curl -X POST https://dev.api.revio.co.za/v2/callback/test/collection/eft/{collectionId}/ \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "overrideUrl": "https://webhook.site/your-test-id",
    "collectionStatus": "COMPLETED",
    "callbackVersion": "V2"
  }'
```

## Testing Checklist [#testing-checklist]

### Mandate Management [#mandate-management]

- Create EFT mandate
- Create DebiCheck mandate (REALTIME)
- Create DebiCheck mandate (DELAYED)
- Get mandate status
- Amend mandate
- Test authentication failure scenarios

### Collections [#collections]

- Create EFT collection from the mandate
- Create a DebiCheck collection from the mandate
- Get collection status
- Test unpaid scenarios
- Test dispute scenarios

### Payments [#payments]

- Create a same-day EFT payment
- Create a one-day EFT payment
- Create a two-day EFT payment
- Get payment status

### Webhooks [#webhooks]

- Register callback URL
- Receive collection status callback
- Receive mandate status callback
- Handle all status types

### Error Handling [#error-handling]

- Invalid authentication
- Missing required fields
- Invalid account numbers
- Duplicate references

## DebiCheck Implementation Tips [#debicheck-implementation-tips]

When implementing DebiCheck, consider:

### Client References [#client-references]

Ensure each mandate has a unique contract reference (max 14 characters). This appears on customer bank statements alongside your abbreviated name.

### Timing [#timing]

Plan for authentication outside business hours:

- DebiCheck mandates can only be obtained 06:00-20:00 weekdays
- Consider switching to TT2 (batch) for after-hours onboarding

### Managing Failures [#managing-failures]

- Implement retry logic with `realtimeAuthRetries`
- Use `fallbackAuthenticationType` for automatic failover
- Follow up with customers who ignore authentication requests

### Mandate Rules [#mandate-rules]

| Consideration | Guidance |
|---|---|
| Value Type | Choose `FIXED`, `VARIABLE`, or `USAGEBASED` based on billing model |
| Amount Adjustments | Use `adjustmentRate` OR `adjustmentAmountCents`, not both |
| Max Amount | Set `maxAmountCents` to accommodate your maximum expected collection |
| Collection Day | Present collections for the authenticated day only |
| Tracking | Allocate enough tracking days (max 10) for your retry strategy |

### Collection Timing [#collection-timing]

- Submit collections at least 2 calendar days before the collection day
- Do not adjust for public holidays or weekends (or use `allowDateAdjustment`)
- Only collect on authenticated mandates

### Mandate Management [#mandate-management-1]

Consider creating new mandates rather than amending existing ones to avoid complexity in re-authentication scenarios.

## Test Data [#test-data]

### Valid Test ID Numbers [#valid-test-id-numbers]

Use a valid South African ID number format:

- `0001010000006`
- `8501015800089`
- `0001010000089`

### Test Phone Numbers [#test-phone-numbers]

Use format `+27-XXXXXXXXX`:

- `+27-123456789`
- `+27-615333440`
- `+27-987654321`

### Test Bank Details [#test-bank-details]

| Bank | Branch Code |
|---|---|
| ABSA | `632005`, `632500` |
| Standard Bank | `051001` |
| FNB | `250655` |
| Nedbank | `198765` |
| Capitec | `470010` |

## Moving to Production [#moving-to-production]

Once testing is complete:

1. Review the Going Live checklist
2. Contact your Revio account manager for production credentials
3. Update your application configuration
4. Perform smoke tests in production

<Callout type="info">
Important: Never use production credentials in sandbox or vice versa.
</Callout>