API reference
Wallets
Your own wallets and your customers’ wallets, each with a real bank account number, and payouts from them.
Create a customer wallet
Opens a wallet with its own bank account number for one of your customers. Transfers into that account number credit the wallet, and Lint posts business.customer.wallet.deposit to your webhook endpoints.
Body
- business_customer_idstring (uuid)required
The customer's
idfrom POST /customers/create. Must be one of your customers.Example:
"550e8400-e29b-41d4-a716-446655440000" - currencystringrequired
Wallet currency code
Example:
"NGN"
Responses
- 201Wallet created
- 401Missing, invalid or expired access token.
unauthenticated - 422A field failed validation.
validation_failed - 502An upstream bank, biller or identity provider failed. Safe to retry; send the same Idempotency-Key where the endpoint supports one.
provider_error
curl -X POST https://staging.lint.finance/api/partner/v1/wallets/create \
-H "Authorization: Bearer $LINT_ACCESS_TOKEN" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
"business_customer_id": "550e8400-e29b-41d4-a716-446655440000",
"currency": "NGN"
}'{
"data": {
"id": "209bc13c-70ce-450d-8f2e-7a870362912a",
"customer_wallet": true,
"balance": 2500000,
"available_balance": 2500000,
"currency": "NGN",
"country_code": "NG",
"account_details": {
"bank": "SafeHaven Microfinance Bank",
"account_number": "6010172152",
"account_name": "Ada Obi",
"bank_code": "999240"
},
"created_at": "2026-11-02T11:02:09+00:00",
"updated_at": "2026-11-02T11:02:09+00:00"
}
}Send a payout to a bank account
Debits one of your wallets and sends the amount to a Nigerian bank account. The destination is verified by name enquiry first. Fees are charged on top of amount, so the wallet must hold amount + fee. Send an Idempotency-Key so a retry after a timeout cannot pay twice.
Headers
- Idempotency-Keystring
Optional, up to 255 characters. Retrying with the same key and the same body within 24 hours returns the original response (with header
Idempotent-Replayed: true) instead of moving money again. The same key with a different body is rejected withidempotency_key_reused; a key whose first request is still running returns 409idempotency_key_in_progress. A request that fails validation does not use up its key.Example:
"payout-2026-11-02-000123"
Body
- debit_wallet_idstring (uuid)required
idof the wallet to debit. Must be one of your wallets. - credit_account_numberstringrequired
10-digit NUBAN of the beneficiary.
Example:
"0123456789" - credit_account_bank_codestringrequired
6-digit bank code from GET /banks/ng.
Example:
"000013" - amountintegerrequired
Amount in kobo (₦10,000.00 = 1000000). Whole numbers only.
Example: 1000000₦10,000.00
- currencystringrequired
One of
NGN - remarkstring
Shown on the beneficiary's statement.
Example:
"Invoice 8812"
Responses
- 201Transfer initiated. Check `data.status`; a pending transfer settles asynchronously.
- 401Missing, invalid or expired access token.
unauthenticated - 409An earlier request with this Idempotency-Key is still running.
idempotency_key_in_progressinsufficient_balance - 422Validation failed, the destination could not be verified, the wallet cannot cover amount + fee, the destination is the wallet's own account, or the Idempotency-Key was used with a different body.
validation_failedaccount_resolution_failedinsufficient_balanceself_transferidempotency_key_reused - 502An upstream bank, biller or identity provider failed. Safe to retry; send the same Idempotency-Key where the endpoint supports one.
provider_error
curl -X POST https://staging.lint.finance/api/partner/v1/wallets/initiate-transfer \
-H "Authorization: Bearer $LINT_ACCESS_TOKEN" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"debit_wallet_id": "9d3c1f0a-5b2e-4c7a-9f10-2b3c4d5e6f70",
"credit_account_number": "0123456789",
"credit_account_bank_code": "000013",
"amount": 1000000,
"currency": "NGN",
"remark": "Invoice 8812"
}'{
"status": true,
"message": "Transfer initiated successfully",
"data": {
"id": "8f14e45f-ceea-467a-9575-1d3a2b6f0c11",
"amount": 1000000,
"fee": 5375,
"total": 1005375,
"currency": "NGN",
"status": "pending",
"reference": "b7d7eaf3db594caeb95b4ef9b46e38341785231752",
"description": "Transfer to Ada Obi",
"type": "WITHDRAWAL",
"date": "2026-11-02T10:04:11+00:00",
"wallet": {}
}
}List wallets
Your own wallets and your customers' wallets, newest first.
Query parameters
- customer_walletsboolean
1for customer wallets only,0for your own wallets only; omit for both.
Responses
- 200Wallets
- 401Missing, invalid or expired access token.
unauthenticated - 422A field failed validation.
validation_failed
curl -X GET https://staging.lint.finance/api/partner/v1/wallets \
-H "Authorization: Bearer $LINT_ACCESS_TOKEN" \
-H "Accept: application/json"{
"data": [
{
"id": "209bc13c-70ce-450d-8f2e-7a870362912a",
"customer_wallet": true,
"balance": 2500000,
"available_balance": 2500000,
"currency": "NGN",
"country_code": "NG",
"account_details": {
"bank": "SafeHaven Microfinance Bank",
"account_number": "6010172152",
"account_name": "Ada Obi",
"bank_code": "999240"
},
"created_at": "2026-11-02T11:02:09+00:00",
"updated_at": "2026-11-02T11:02:09+00:00"
}
]
}Retrieve a wallet
Includes the current balances, in kobo. Check available_balance before sending a payout.
Path parameters
- wallet_idstring (uuid)required
Wallet
id.
Responses
- 200The wallet
- 401Missing, invalid or expired access token.
unauthenticated - 404The resource does not exist or belongs to another partner. The two cases are indistinguishable by design.
not_found
curl -X GET https://staging.lint.finance/api/partner/v1/wallets/{wallet_id} \
-H "Authorization: Bearer $LINT_ACCESS_TOKEN" \
-H "Accept: application/json"{
"data": {
"id": "209bc13c-70ce-450d-8f2e-7a870362912a",
"customer_wallet": true,
"balance": 2500000,
"available_balance": 2500000,
"currency": "NGN",
"country_code": "NG",
"account_details": {
"bank": "SafeHaven Microfinance Bank",
"account_number": "6010172152",
"account_name": "Ada Obi",
"bank_code": "999240"
},
"created_at": "2026-11-02T11:02:09+00:00",
"updated_at": "2026-11-02T11:02:09+00:00"
}
}