Troubleshooting

Authentication Issues

Invalid or Expired Token

Symptom:401 Unauthorized response

‍

Causes:

• Access token has expired (tokens are valid for 24 hours)
• Token not included in Authorization header
• Malformed Authorization header

‍

Solutions:

1. Request a new access token:

‍

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_CLIENT_ID:YOUR_CLIENT_SECRET" \
  -d "grant_type=client_credentials"

‍

1. Ensure correct header format:

‍

Authorization: Bearer eyJraWQiOiJ...

‍

1. Implement token refresh logic before expiry

‍

Invalid Client Credentials

Symptom:invalid_client error from the authentication endpoint

‍

Causes:

• Incorrect client_id or client_secret
• Using sandbox credentials in production or vice versa
• Credentials not Base64 encoded correctly

‍

Solutions:

1. Verify credentials match environment (sandbox vs production)
2. Check for extra whitespace in credentials
3. Ensure Basic auth header is properly formatted:

‍

BASH

# Correct format
-u "client_id:client_secret"

# Or manually encode
echo -n "client_id:client_secret" | base64

‍

Mandate Creation Issues

Bank Account Verification Failure

Symptom:400 Bad Request with verification failure details

‍

Example Error:

JSON

{
  "Message": "Debtor account verification failure: details={\"AccountExists\":true,\"AccountIsOpen\":false,...}"
}

‍

Causes:

• Account is closed or dormant
• Incorrect account number or branch code
• Account type mismatch
• ID number doesn't match the account holder

‍

Solutions:

‍

Workaround: Set verifyAccount: false to skip verification (not recommended for production)

‍

Invalid Bank Name Format

Symptom:400 Bad Request mentioning the bank field

‍

Cause: Bank name not in the correct format

‍

Solution: Use uppercase, single-word format:

‍

‍

Duplicate External Reference

Symptom:409 Conflict error

‍

Cause: The externalReference value already exists

‍

Solutions:

1. Use unique references for each mandate/collection
2. Implement UUID generation:

‍

JSX

const externalReference = crypto.randomUUID();

‍

1. Include timestamp or sequence number:

‍

JSX

const externalReference = `MAN-${Date.now()}-${sequenceNumber}`;

‍

DebiCheck Authentication Timeout

Symptom: Mandate status remains PENDING_AUTHENTICATION then becomes AUTH_FAILURE

‍

Causes:

• Customer didn't respond within 120 seconds (TT1)
• The customer's phone is off or has no signal
• The bank couldn't deliver USSD/push notification

‍

Solutions:

1. Implement fallback authentication:

‍

JSON

{
  "authenticationType": "REALTIME",
  "fallbackAuthenticationType": "DELAYED_WITHOUT_AUTH"
}

‍

1. Use delayed authentication for after-hours:

‍

JSON

{
  "authenticationType": "DELAYED"
}

‍

1. Retry with batch processing:

‍

JSON

{
  "authenticationType": "BATCH"
}

‍

1. Follow up with the customer to ensure they're expecting the authentication request

‍

DebiCheck Mandate Rejected

Symptom: Status AUTH_FAILURE with rejection reason

‍

Causes:

• The customer actively rejected the mandate
• Mandate details don't match customer expectations
• The customer doesn't recognise the merchant

‍

Solutions:

1. Verify contract details with the customer before submitting
2. Ensure the abbreviated name is recognisable to the customer
3. Confirm collection amount and frequency
4. Re-submit with corrected details after customer confirmation

‍

Collection Issues

Collection Returned Unpaid

Symptom: Collection status UNPAID

‍

Common Causes and Solutions:

‍

PASA Rules:

• Cannot resubmit until the next mandated date
• After 2 "Not provided for" returns, a new mandate is required
• "Account Closed" or "Payment Stopped" cannot be resubmitted

‍

Collection Disputed

Symptom: Collection status DISPUTED

‍

Causes:

• Customer claims no valid mandate exists
• Collection violates the mandate terms
• The customer cancelled the mandate

‍

Solutions:

1. Retrieve and review the original mandate
2. Verify collection was within mandate parameters:

• Correct amount (within max limits)
• Correct collection day
• The mandate was active

1. Respond to the bank within 30 days with the mandate evidence
2. For DebiCheck: Disputes are less likely if the collection matches the authenticated terms

‍

Collection Submitted After Cut-off

Symptom: Collection not processed on the expected date

‍

Cause: Submitted after bank processing cut-off time

‍

Cut-off Times:

‍

Solutions:

1. Submit collections well before cut-off times
2. Account for your system processing time
3. For time-sensitive collections, use same-day service with early submission

‍

Payment Issues

Payment Exceeds Limits

Symptom: Payment rejected with "exceeds industry-imposed limits"

‍

Cause: Payment amount ≥ R5,000,000

‍

Solution: Route high-value payments through a real-time line (contact Precium support)

‍

Payment to an Invalid Account

Symptom: Payment status FAILED

‍

Causes:

• Invalid account number
• Incorrect branch code
• Account doesn't accept credits

‍

Solutions:

1. Verify recipient account details
2. Consider implementing account verification before payment
3. Confirm the branch code matches the account's bank

‍

Webhook Issues

Not Receiving Webhooks

Symptom: No callbacks received at registered URL

‍

Causes:

• Callback URL not registered
• URL not publicly accessible
• HTTPS certificate issues
• Firewall blocking requests

‍

Solutions:

1. Verify the callback URL is registered:

‍

BASH

# Register callback URL
curl -X POST https://dev.api.revio.co.za/v2/clientcallbackurl/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "clientId": YOUR_CLIENT_ID,
    "url": "https://your-server.com/webhook",
    "callbackType": "EFT_COLLECTION",
    "callbackVersion": "V2"
  }'

‍

1. Test with webhook.site first:

‍

JSON

{
  "url": "https://webhook.site/your-unique-id"
}

‍

1. Ensure your server:

• Is publicly accessible
• Has valid SSL certificate
• Responds within 5 seconds
• Returns HTTP 200

‍

Webhook Timeout Errors

Symptom: Callbacks received but marked as failed

‍

Cause: Webhook handler takes too long to respond

‍

Solution: Return 200 immediately, process asynchronously:

‍

JSX

app.post('/webhook', (req, res) => {
  // Respond immediately
  res.status(200).send('OK');

  // Process in background
  processWebhookAsync(req.body);
});

‍

API Request Issues

400 Bad Request

Symptom: Request rejected with validation error

‍

Common Causes:

1. Missing required fields

• Check all required fields are present
• Verify field names match API specification (case-sensitive)

1. Invalid date format

• Use ISO 8601 format: 2024-01-15T10:00:00.000Z

1. Invalid phone number format

• Use format: +27-XXXXXXXXX

1. Invalid amount

• Amount must be in cents (integer)
• 10000 = R100.00

1. Invalid enum values

• Check accepted values for fields like accountType, serviceType, frequency

‍

404 Not Found

Symptom: Resource not found error

‍

Causes:

• Invalid resource ID
• Resource was deleted
• Wrong endpoint URL

‍

Solutions:

1. Verify the ID exists and is correctly formatted (UUID)
2. Check endpoint URL matches documentation
3. Ensure you're using the correct API version (/v2/)

‍

500 Internal Server Error

Symptom: Server error response

‍

Actions:

1. Note the timestamp and request details
2. Check for x-request-id in response headers
3. Retry with exponential backoff
4. If persistent, contact Precium support with:

• Request endpoint
• Request payload (redact sensitive data)
• Timestamp
• Request ID (if available)

‍

Environment Issues

Using the Wrong Environment

Symptom: Unexpected behaviour, missing data, or authentication failures

‍

Cause: Mixing sandbox and production credentials/endpoints

‍

Environment Reference:

‍

Solution: Use environment variables to manage configuration:

‍

JSX

const config = {
  authUrl: process.env.REVIO_AUTH_URL,
  apiUrl: process.env.REVIO_API_URL,
  clientId: process.env.REVIO_CLIENT_ID,
  clientSecret: process.env.REVIO_CLIENT_SECRET
};

‍

Getting Help

If you cannot resolve an issue:

1. Check documentation: Review the relevant section of this documentation
2. Review Swagger: https://dev.api.revio.co.za/swagger/index.html
3. Test in sandbox: Reproduce the issue in the sandbox environment
4. Contact support: Email support@precium.com with:

• Description of the issue
• Steps to reproduce
• Request/response examples (redact sensitive data)
• Environment (sandbox/production)
• Timestamp of failed requests

‍

© 2026 Precium. All rights reserved.