On this page
API Reference
Use the environment origin and product credential from your onboarding. All paths in these tables include the version where applicable. Use JSON for request bodies unless the endpoint specifies multipart. Check the HTTP status and response body before updating local state.
Vector#
| Method and path | Contract |
|---|---|
POST /api/v1/applications | Create an underwriting application. Required inputs and examples are in Applications and decisions and Bank statements. Returns 201 and the application. |
GET /api/v1/applications/{application} | Read application status and available decision data. |
GET /api/v1/applications | List applications for a borrower. Supply a customer_reference or bvn. Optional filters include status, from_date, and to_date. Use page and per_page for pagination, with up to 100 records per page. Returns applications and pagination with total, perPage, currentPage, and lastPage. |
GET /api/v1/applications/{application}/logs | Read application processing logs. |
POST /api/v1/applications/{application}/cancel | Cancel an eligible unfinished application. Optional reason of up to 500 characters. |
POST /api/v1/bank-statements | Multipart parser request with applicationId, file, and optional PDF password. Returns 202 with id and status. |
GET /api/v1/bank-statements/{id} | Read parsing state and any failureReason. |
GET /api/v1/customers | Look up a borrower by customer_reference or bvn. Requires customers:read. |
POST /api/v1/repayments | Record a repayment event for an approved application. |
Application creation, individual status, cancellation, statement operations, and repayments use the decisions:create scope in the public route definitions. Listing applications and reading logs use applications:read.
Collections customers and setup#
Paths below are relative to /api/v1/collections.
| Method and path | Contract |
|---|---|
POST /customer/create-customer | Create a customer. Requires email and an 11-digit bvn. |
GET /customer/get-customer/{customerId} | Retrieve a customer by Yana ID. |
GET /customer/get-customer-by-identifier/{identifier} | Retrieve a customer by email or BVN. URL-encode the identifier. |
GET /banks | Read the bank catalogue. |
GET /banks/resolve/{account_number}/{bank_code} | Resolve a bank account using its number and bank code. |
GET /banks/direct-debit/supported | Read direct debit bank coverage. |
POST /customer/{customer}/widget-sessions | Create a hosted or embedded authorization session. See widget fields. |
GET /widget-sessions/{session} | Retrieve institution-side widget status and masked progress. |
GET /settings/payment-methods | Read enabled collection methods where this API is enabled for your credentials. |
PUT /settings/payment-methods | Set collection_methods to one or both of card and direct_debit. |
POST /customer/card/{customer}/initialize | Initialize hosted card setup. Send consent: true and use callback_url for your return handler. |
GET /customer/card/{customer}/verification/{reference} | Check a card setup transaction. |
GET /customer/card/{customer}/get-authorized | List card setup records. |
POST /customer/direct-debit/{customer}/initialize | Initialize a direct debit authorization. |
GET /customer/direct-debit/{customer}/verification/{reference} | Check a direct debit authorization by reference. |
GET /customer/direct-debit/{customer}/get-authorized | List authorized direct debit sources. |
GET /customer/direct-debit/{customer}/verify-all-linked | Refresh verification for linked direct debit sources. |
POST /customer/bvn/lookup/fetch | Start a BVN bank-account lookup. |
POST /customer/bvn/lookup/refresh | Refresh the BVN lookup flow. |
POST /customer/bvn/lookup/verify/{sessionId} | Verify a BVN lookup session. |
POST /customer/bvn/lookup/details/{sessionId} | Retrieve details for a BVN lookup session. |
Collections schedules, debits, and lifecycle#
Paths below are relative to /api/v1/collections.
| Method and path | Contract |
|---|---|
POST /clients/{customer}/collection | Create a collection and schedule. See Repayments and charges. |
GET /clients/{customer}/collection/{collection} | Read a collection by its ID. |
GET /customer/{customer}/collections/{filter} | List a customer's collections using a supported filter. |
GET /clients/collection/{collection}/instalment | List instalments. |
POST /clients/collection/{collection}/instalment | Add an instalment. |
GET /clients/collection/{collection}/instalment/{instalment} | Read an instalment. |
PATCH /clients/collection/{collection}/instalment/{instalment} | Update an instalment, including its amount or future charge window. |
DELETE /clients/collection/{collection}/instalment/{instalment} | Delete an instalment where permitted by its state. |
GET /clients/instalments/{instalment}/charge | Request a debit attempt. |
GET /clients/instalments/get-transaction-status/{customer}/{reference} | Verify a transaction by reference. |
GET /clients/instalments/get-collection-by-extenral-reference/{customer}/{reference} | Look up a collection by external reference. Use the path spelling shown. |
GET /clients/collection/{collection}/lifecycle | Read remaining and collectible amounts and the next eligible debit. |
POST /clients/collection/{collection}/lifecycle/events | Apply a loan lifecycle event. |
POST /clients/misc/get-end-date | Calculate an end date from schedule inputs. |
POST /clients/misc/generate-instalments | Generate a schedule preview. |
GET /clients/misc/get-intervals | List interval types. |
GET /clients/misc/get-tenures | List tenure types. |
GET /clients/misc/get-payment-statuses | List payment statuses. |
Errors and retries#
| Situation | Action |
|---|---|
| Authentication or permission error | Check the credential, environment, product access, and operation scope. |
| Validation error | Inspect the returned field errors and correct the request. |
Lifecycle conflict 409 | Check for a debit still processing, a conflicting event ID, or an incompatible collection state. Fetch the lifecycle snapshot before resubmitting. |
| Rate limit or quota | Use any returned retry hint and distinguish temporary throttling from exhausted quota. |
| Uncertain debit or bureau submission | Verify the original reference before attempting another operation. |