System status

You can make this call from your code, a REST client, or your postman using your live credentials. This verifies your live credentials and your associated appID. These values are likely to be constants within your application.

---

Protected Status Endpoint POST: https://api.creditchek.africa/v1/recova/system_status

It will return an HTTP status of 200, with a “Service is available” message. If there’s a return of HTTP status 401 as unauthorised (“invalid credentials or AppID used for the connection request”), other 4xx or 5xx, this should indicate that the “service is temporarily unavailable”. The JSON response should always be parsed.

Contact [email protected] if you encounter any error responses at this stage.

---

Authentication & Environments - Request Parameters

Name	Position	Required	Description
token	Headers	True	app secret key

Send your business API key in the token header. Only some of these routes currently enforce it — this a design choice, to make the experience smooth and faster:

token: <YOUR_CREDITCHEK_API_KEY>
Content-Type: application/json

Endpoint	Auth enforced today
POST /consent/create	✅ yes
POST /consent/business/breakdown/edit	✅ yes
POST /micro-deposit/create/mandate	❌ no — businessIdandappId are trusted from the request body because it makes external calls to the payment rails
POST /micro-deposit/create/mandate/gsm	❌ no — same as above

Environment	Base URL
Production	https://api.creditchek.africa/v1/recova/
Sandbox / Staging	https://api.creditchek.africa/v1/recova/ (using sandbox test BVN / credentials)

---

GET: Supported Banks

Retrieve the list of commercial and digital banks currently supporting instant micro-deposit mandate authorization.

GET /micro-deposit/bank-list
token: <YOUR_API_KEY>

Response (200 OK)

{
  "status": true,
  "message": "Bank list retrieved successfully",
  "error": false,
  "data": [
    { "name": "ACCESS BANK PLC", "code": "044" },
    { "name": "GUARANTY TRUST BANK PLC", "code": "058" },
    { "name": "ZENITH INTERNATIONAL BANK PLC", "code": "057" },
    { "name": "UNITED BANK FOR AFRICA PLC", "code": "033" },
    { "name": "FIRST BANK OF NIGERIA PLC", "code": "011" },
    { "name": "PROVIDUS BANK", "code": "101" },
    { "name": "KUDA MICROFINANCE BANK", "code": "50211" }
  ]
}

---

Consent & Mandate Endpoints — Integration Guide

Covers the four endpoints a business typically calls in sequence to set up direct debit collection:

1. Create a mandate — POST /consent/create
2. (Optional) Modify the auto-generated repayment breakdown to match your internal system of record — POST /consent/business/breakdown/edit
3. Attach a bank account — either:
   • POST /micro-deposit/create/mandate (one account), OR
   • POST /micro-deposit/create/mandate/gsm (up to 7 accounts in one call, MUST indicate "Primary Account", then others fallback as "Backup Accounts")

All requests/responses use the same envelope:

{ "status": true, "message": "...", "error": false, "data": { } }

{ "status": false, "message": "...", "error": true, "data": { } }

Mandate Lifecycle Context

Initiated → [Consent Created] → Pending → (Approval) → Active ✅
                                      ↓
                                 Never Approved → Failed ❌

A failed consent means:

• The customer selected the bank and started the consent flow
• The consent record was created in the database
• The mandate remained in pending status
• The consent was never approved — no transition to active occurred
• The mandate may still be pending with other consents, or may have been abandoned

---

Possible Reasons for Failure

Reason	Description	Evidence from our operations so far
Abandoned Flow	Customer started but did not complete the bank authentication step	Single consent per mandate, no retries
Bank-Side Rejection	The bank declined the consent request (e.g., account restrictions)	Same bank retried with different accounts
Timeout	The consent link expired before the customer completed the flow	Single consent, long gap before next attempt
Network/Integration Error	Technical failure between Recova and the bank's API	Exact duplicate retries (same bank + same account)
Customer Withdrawal	Customer intentionally canceled the consent process	Multiple banks tried, all abandoned

---