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 pathContract
POST /api/v1/applicationsCreate 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/applicationsList 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}/logsRead application processing logs.
POST /api/v1/applications/{application}/cancelCancel an eligible unfinished application. Optional reason of up to 500 characters.
POST /api/v1/bank-statementsMultipart 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/customersLook up a borrower by customer_reference or bvn. Requires customers:read.
POST /api/v1/repaymentsRecord 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 pathContract
POST /customer/create-customerCreate 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 /banksRead the bank catalogue.
GET /banks/resolve/{account_number}/{bank_code}Resolve a bank account using its number and bank code.
GET /banks/direct-debit/supportedRead direct debit bank coverage.
POST /customer/{customer}/widget-sessionsCreate a hosted or embedded authorization session. See widget fields.
GET /widget-sessions/{session}Retrieve institution-side widget status and masked progress.
GET /settings/payment-methodsRead enabled collection methods where this API is enabled for your credentials.
PUT /settings/payment-methodsSet collection_methods to one or both of card and direct_debit.
POST /customer/card/{customer}/initializeInitialize 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-authorizedList card setup records.
POST /customer/direct-debit/{customer}/initializeInitialize a direct debit authorization.
GET /customer/direct-debit/{customer}/verification/{reference}Check a direct debit authorization by reference.
GET /customer/direct-debit/{customer}/get-authorizedList authorized direct debit sources.
GET /customer/direct-debit/{customer}/verify-all-linkedRefresh verification for linked direct debit sources.
POST /customer/bvn/lookup/fetchStart a BVN bank-account lookup.
POST /customer/bvn/lookup/refreshRefresh 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 pathContract
POST /clients/{customer}/collectionCreate 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}/instalmentList instalments.
POST /clients/collection/{collection}/instalmentAdd 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}/chargeRequest 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}/lifecycleRead remaining and collectible amounts and the next eligible debit.
POST /clients/collection/{collection}/lifecycle/eventsApply a loan lifecycle event.
POST /clients/misc/get-end-dateCalculate an end date from schedule inputs.
POST /clients/misc/generate-instalmentsGenerate a schedule preview.
GET /clients/misc/get-intervalsList interval types.
GET /clients/misc/get-tenuresList tenure types.
GET /clients/misc/get-payment-statusesList payment statuses.

Errors and retries#

SituationAction
Authentication or permission errorCheck the credential, environment, product access, and operation scope.
Validation errorInspect the returned field errors and correct the request.
Lifecycle conflict 409Check for a debit still processing, a conflicting event ID, or an incompatible collection state. Fetch the lifecycle snapshot before resubmitting.
Rate limit or quotaUse any returned retry hint and distinguish temporary throttling from exhausted quota.
Uncertain debit or bureau submissionVerify the original reference before attempting another operation.