API reference
Virtual accounts
One-time bank account numbers that accept a single payment. Lint posts virtual_account.payment_received to your callback URL when the money lands.
Simulate a payment into a virtual account (sandbox)
Sandbox only: sends a test transfer into the virtual account so you can exercise your webhook handling end to end. In production it does nothing.
Path parameters
- virtualAccountstring (uuid)required
The virtual account
idreturned at creation.Example:
"9d3c1f0a-5b2e-4c7a-9f10-2b3c4d5e6f70"
Body
- amountintegerrequired
Amount to send, in kobo. Whole numbers only.
Example: 500000₦5,000.00
Responses
- 200Transfer sent
- 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 - 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/payments/virtual-accounts/9d3c1f0a-5b2e-4c7a-9f10-2b3c4d5e6f70/simulate-transfer \
-H "Authorization: Bearer $LINT_ACCESS_TOKEN" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
"amount": 500000
}'{
"message": "Transfer simulated successfully"
}Create a one-time virtual account
Provisions a bank account number that accepts a single payment. Show the account number, bank and amount to your payer; when they pay, Lint posts virtual_account.payment_received to callback_url and the payment shows on GET .../payment-status. The older path POST /api/partner/v1/payments/virtual-accounts behaves identically and remains supported.
Body
- amountintegerrequired
Amount expected, in kobo (₦5,000.00 = 500000). Whole numbers only.
Example: 500000₦5,000.00
- currencystringrequired
ISO 4217 currency code. Only NGN is supported.
Example:
"NGN" - callback_urlstring (uri)required
Where Lint posts the signed
virtual_account.payment_receivedevent for this account.Example:
"https://api.yourcompany.com/lint/webhooks" - validityinteger
Seconds the account accepts payment for, up to 24 hours (86400). After that the payer's bank refuses transfers to it, so create a new account for a payer who comes back later. Defaults to the platform default when omitted.
Example:
1800 - amount_controlstring
How a payment that does not match
amountis treated. Defaults to FIXED.One of
FIXED,ALLOW_UNDERPAYMENT,ALLOW_OVERPAYMENT - referencestring
Your own reference. Must be unique across your virtual accounts; returned in webhooks as
external_reference.Example:
"order_8812"
Responses
- 201Virtual account created
- 401Missing, invalid or expired access token.
unauthenticated - 403The partner account has not completed BVN verification.
bvn_not_verified - 422A field failed validation.
validation_failed - 500Unexpected error on Lint's side.
server_error - 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/payments/virtual-accounts/create \
-H "Authorization: Bearer $LINT_ACCESS_TOKEN" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
"amount": 500000,
"currency": "NGN",
"callback_url": "https://api.yourcompany.com/lint/webhooks",
"validity": 1800,
"amount_control": "FIXED",
"reference": "order_8812"
}'{
"data": {
"id": "517cadd0-3d20-435e-8187-72fe9c1b2a40",
"payment_status": "PENDING",
"account_number": "6020012029",
"bank_code": "999240",
"bank_name": "SAFE HAVEN SANDBOX BANK",
"account_name": "Your Business Checkout",
"reference": "order_8812",
"amount": 500000,
"amount_paid": 0,
"currency": "NGN",
"valid_until": "2026-11-02T10:34:00.000000Z",
"amount_control": "FIXED",
"callback_url": "https://api.yourcompany.com/lint/webhooks",
"transaction": {}
},
"message": "Virtual account created successfully"
}Retrieve a virtual account and its payment status
Use this to reconcile if a webhook was missed. amount_paid is in kobo and is 0 until a payment arrives.
Path parameters
- virtualAccountstring (uuid)required
The virtual account
idreturned at creation.Example:
"9d3c1f0a-5b2e-4c7a-9f10-2b3c4d5e6f70"
Responses
- 200The virtual account
- 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/payments/virtual-accounts/9d3c1f0a-5b2e-4c7a-9f10-2b3c4d5e6f70/payment-status \
-H "Authorization: Bearer $LINT_ACCESS_TOKEN" \
-H "Accept: application/json"{
"data": {
"id": "517cadd0-3d20-435e-8187-72fe9c1b2a40",
"payment_status": "PENDING",
"account_number": "6020012029",
"bank_code": "999240",
"bank_name": "SAFE HAVEN SANDBOX BANK",
"account_name": "Your Business Checkout",
"reference": "order_8812",
"amount": 500000,
"amount_paid": 0,
"currency": "NGN",
"valid_until": "2026-11-02T10:34:00.000000Z",
"amount_control": "FIXED",
"callback_url": "https://api.yourcompany.com/lint/webhooks",
"transaction": {}
},
"message": "Virtual account status retrieved successfully"
}