Step 1: Initialize mandate

Step 1: Initialize e-mandate with the payer

POST: https://api.creditchek.africa/v1/recova/consent/create

Creates an e-mandate agreement record for the payer. At this stage, the mandate is in a pending state awaiting bank account attachment and payer authorization.

POST /v1/recova/consent/create
Content-Type: application/json
token: <YOUR_API_KEY>

Sample Payload for Dev or Staging integration testing

Sandbox-safe values that skip real DB writes / Payment Rails calls entirely, useful for exercising each endpoint's request-shape and validation rules without live data:

Value	Where	Effect
bvn: "12345678901" or "09876543212"	POST /consent/create	Returns a canned mandate (_id: "77192739b3cf770000000000"), nothing persisted.
mandateId: "77192739b3cf770000000000"	POST /consent/business/breakdown/edit	Runs the real date-range + exact-amount validation against a fixed demo window (startDate 2024-07-07, endDate 2024-10-31, totalAmountDue 15000) and returns the built breakdown — no DB read/write.
mandateId: "77192739b3cf770000000000"	POST /micro-deposit/create/mandate/gsm	Skips the business/mandate/wallet lookups and Payment Rails calls for every account in the request; still enforces the real request-shape checks (max 7 accounts, no duplicate account numbers, at most one primary). Returns a canned results array, demo: true per entry.
accountNumber: "1234567890" or "0987654321"	POST /micro-deposit/create/mandate and .../gsm	Skips Payment Rails for that specific account only (still requires a real mandate unless combined with the demo mandateId above).
mandateId: "77192739b3cf770000000000"	POST /consent/business/pause-mandate, /resume-mandate, /cancel-mandate	Skips the real Mandate lookup, returns a canned success response, and fires the matching Webhook event below — no DB read/write.

The demo bvn path (/consent/create) does not chain into the demo mandateId above — it never persists a real Mandate, so its returned id on the backend only works against endpoints that explicitly special-case it (as listed on record), not against real Mandate lookups.

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

Request Parameters

Field	Type	Required?	Description
productId	string	Yes	Your product ID created on the CreditChek Portal.
bvn	string	Yes	11-digit Bank Verification Number of the payer.
startDate	string	Yes	Start date of collection (YYYY-MM-DD). Schedule at least 72 hours out.
endDate	string	Yes	Expiration date of the direct debit mandate (YYYY-MM-DD).
totalAmountDue	number	Yes	Total amount to be collected (₦250 to ₦200,000,000).
collectionMode	string	Yes	"auto" (scheduler-driven) or "manual" (merchant-triggered).
debitType	string	Conditional	"recurring" or "oneTime". Required if collectionMode is "auto".
frequency	string	Conditional	"daily", "weekly", or "monthly". Required for recurring debits.
mandateType	string	Yes	"fixed" (equal installments) or "variable" (flexible schedule).
firstRepaymentPercentage	number	Optional	For variable mandates: percentage (10 to 90) charged in installment #1.
balanceEnquiry	boolean	Yes	Set true to enable pre-debit balance checks.
corporateAccount	boolean	Yes	Set true if debiting a registered business/corporate account.
rcNumber	string	Conditional	CAC registration number (required when corporateAccount is true).
businessName	string	Conditional	Registered corporate name (required when corporateAccount is true).
businessEmail	string	Conditional	Corporate billing email (required when corporateAccount is true).
businessPhone	string	Conditional	Corporate phone contact (required when corporateAccount is true).
externalReference	string	Optional	Your platform’s unique reference identifier for this loan or order.

Sample Request (Individual Payer)

{
  "productId": "768fc9999999999999999999",
  "bvn": "12345678901",
  "frequency": "monthly",
  "startDate": "2026-10-01",
  "endDate": "2026-12-31",
  "totalAmountDue": 60000,
  "collectionMode": "auto",
  "debitType": "recurring",
  "mandateType": "variable",
  "firstRepaymentPercentage": 20,
  "balanceEnquiry": false,
  "corporateAccount": false,
  "externalReference": "LN-TEST-001"
}

Sample Request (Corporate Account)

{
  "productId": "768fc9999999999999999999",
  "bvn": "12345678901",
  "frequency": "monthly",
  "startDate": "2026-10-01",
  "endDate": "2027-04-01",
  "totalAmountDue": 1500000,
  "collectionMode": "auto",
  "debitType": "recurring",
  "mandateType": "fixed",
  "balanceEnquiry": true,
  "corporateAccount": true,
  "rcNumber": "RC1829910",
  "businessName": "ACME LOGISTICS LIMITED",
  "businessEmail": "[email protected]",
  "businessPhone": "08012345678"
}

Sample Response (201 Created)

{
  "status": true,
  "message": "consent created successfully",
  "error": false,
  "data": {
    "_id": "77192739b3cf770000000000",
    "businessId": "730c8be89121212121212121",
    "appId": "730c8be89131cd1111111111",
    "reference": "563315af-f0a4-420f-8e5e-df9b1c28973b",
    "productId": "768fc9999999999999999999",
    "bvn": "12345678901",
    "startDate": "2026-10-01",
    "endDate": "2026-12-31",
    "frequency": "monthly",
    "totalAmountDue": 60000,
    "outstandingBalance": 60000,
    "collectedAmount": 0,
    "collectionMode": "auto",
    "debitType": "recurring",
    "mandateType": "variable",
    "status": "pending",
    "consents": [],
    "acceptedTerms": true
  }
}

[!TIP] Keep the returned _id (mandateId). You will provide it in subsequent steps to attach bank accounts, check status, or modify schedules.

---

Step 1b: Preview & Edit Repayment Breakdown

Before attaching a bank account, you can preview the generated breakdown or customize the installment dates and amounts.

Preview Variable Breakdown

Test how different dates and initial percentages shape installment amounts without creating a mandate.

POST /v1/recova/consent/breakdown/variable
Content-Type: application/json

{
  "startDate": "2026-10-01",
  "endDate": "2026-12-31",
  "frequency": "monthly",
  "amount": 60000,
  "firstRepaymentPercentage": 20
}

Modify Auto-generated Mandate Breakdown (Optional)

If your financing plan requires custom payment days or uneven payments, you can submit an explicit breakdown before attaching a bank account:

POST /v1/recova/consent/business/breakdown/edit
Content-Type: application/json
token: <YOUR_API_KEY>

{
  "mandateId": "66f1b8c4d29a430018a99101",
  "breakdown": [
    { "dueDate": "2026-10-15", "totalAmount": 20000 },
    { "dueDate": "2026-11-15", "totalAmount": 20000 },
    { "dueDate": "2026-12-15", "totalAmount": 20000 }
  ]
}

[!NOTE] Breakdown Requirements

• The sum of all installment totalAmount values must match totalAmountDue exactly.
• Every dueDate must fall within [startDate, endDate].
• The schedule can only be modified while the mandate is pending and before any bank account has been successfully attached(submitted for approval).

---

Step 2: Set Mandate (Attach Bank Account)

Attach the payer’s verified bank account to the initialized mandate. RecovaPRO provides two single-account authorization pathways:

[!TIP] Looking for Multi-Bank Mandates (GSM)? To enroll multiple bank accounts (1 primary + up to 6 secondary backup accounts) discovered via CreditChek Radar BVN lookup for automated cascading recovery, see Section 4: Multi-Bank Mandates (GSM).

---