API reference
Checkout
Hosted checkout sessions. Send the payer to the session’s url; Lint posts checkout.session.completed when they pay, or checkout.session.expired if they don’t.
Simulate the payer paying (sandbox)
Sandbox only: sends a test transfer for the session's full amount, as if the payer had paid on the checkout page, so you can exercise your checkout.session.completed handling end to end. The session completes when the transfer lands, usually within a few seconds. In production it does nothing.
Path parameters
- sessionstring (uuid)required
The session
idreturned at creation.Example:
"9d3c1f0a-5b2e-4c7a-9f10-2b3c4d5e6f70"
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 - 409The session is paid or expired.
invalid_session_state - 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/checkout/sessions/9d3c1f0a-5b2e-4c7a-9f10-2b3c4d5e6f70/simulate-payment \
-H "Authorization: Bearer $LINT_ACCESS_TOKEN" \
-H "Accept: application/json"{
"message": "Payment simulated. The session completes when the transfer lands."
}Create a checkout session
Starts a hosted checkout for one payment. Send the payer to the returned url: Lint's page shows your business name, the amount and your description, and gives the payer a bank account for exactly that amount. When they pay, Lint posts checkout.session.completed to your webhook endpoints and the money lands in your Lint wallet, less Lint's fee. If they don't pay by expires_at, you get checkout.session.expired.
After paying, the payer is sent to success_url with session_id added to its query string. Treat that redirect as a hint, not proof: confirm with the webhook or GET the session before you fulfil. Safe to retry with an Idempotency-Key header.
Headers
- Idempotency-Keystring
Makes the call safe to retry: the same key and body returns the first session instead of creating another.
Example:
"create-order-8812"
Body
- amountintegerrequired
What the payer pays, in kobo (₦12,500.00 = 1250000). Whole numbers only.
Example: 1250000₦12,500.00
- currencystringrequired
One of
NGN - referencestring
Your order ID. Unique across your checkout sessions. Returned on the session and in every webhook.
Example:
"order_8812" - descriptionstring
Shown to the payer under the amount.
Example:
"2 x Golden Morn 12x500g" - customerobject
Who is paying, for your records. Not shown to the payer.
- namestring
Example:
"Ada Obi" - emailstring (email)
Example:
"ada@example.com" - phonestring
Example:
"2348000000000"
- success_urlstring (uri)
Where the payer goes after paying.
session_idis appended. Without one, the page just confirms the payment.Example:
"https://shop.example.com/orders/8812/thanks" - cancel_urlstring (uri)
Where the payer goes if they back out, or come back after the session expired.
Example:
"https://shop.example.com/cart" - expires_ininteger
Seconds until the session expires unpaid: 15 minutes to 7 days. Defaults to 24 hours. Bank accounts the page gives the payer never outlive the session.
Example:
86400 - metadataobject
Up to 20 string values of your own, returned on the session and in webhooks. Never shown to the payer.
Example:
{"cart_id":"c_19"}
Responses
- 201Session created
- 401Missing, invalid or expired access token.
unauthenticated - 403The partner account has not completed BVN verification.
bvn_not_verified - 409An earlier request with this Idempotency-Key is still running.
idempotency_key_in_progress - 422Invalid fields, a reference you've used before ( on ), an Idempotency-Key reused with a different body, or your Lint wallet isn't set up yet.
validation_failedreferenceidempotency_key_reusedaccount_not_ready - 500Unexpected error on Lint's side.
server_error
curl -X POST https://staging.lint.finance/api/partner/v1/checkout/sessions/create \
-H "Authorization: Bearer $LINT_ACCESS_TOKEN" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"amount": 1250000,
"currency": "NGN",
"reference": "order_8812",
"description": "2 x Golden Morn 12x500g",
"customer": {
"name": "Ada Obi",
"email": "ada@example.com",
"phone": "2348000000000"
},
"success_url": "https://shop.example.com/orders/8812/thanks",
"cancel_url": "https://shop.example.com/cart",
"expires_in": 86400,
"metadata": {
"cart_id": "c_19"
}
}'{
"data": {
"id": "9d3c1f0a-5b2e-4c7a-9f10-2b3c4d5e6f70",
"status": "open",
"amount": 1250000,
"amount_paid": 0,
"currency": "NGN",
"reference": "order_8812",
"description": "2 x Golden Morn 12x500g",
"customer": {
"name": "Ada Obi",
"email": "ada@example.com",
"phone": "2348000000000"
},
"metadata": {
"cart_id": "c_19"
},
"url": "https://lint.finance/checkout/Xk3n9QpL2vT8rW1y",
"success_url": "https://shop.example.com/orders/8812/thanks",
"cancel_url": "https://shop.example.com/cart",
"expires_at": "2026-11-04T10:00:00+00:00",
"paid_at": null,
"payment": {
"transaction_reference": "LNT-20261103-8812",
"amount": 1250000,
"fees": 5000,
"settled_amount": 1245000
},
"created_at": "2026-11-03T10:00:00+00:00"
},
"message": "Checkout session created"
}Retrieve a checkout session
The session's current state. Use it to confirm a payment before fulfilling, or to reconcile if you missed a webhook.
Path parameters
- sessionstring (uuid)required
The session
idreturned at creation.Example:
"9d3c1f0a-5b2e-4c7a-9f10-2b3c4d5e6f70"
Responses
- 200The session
- 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/checkout/sessions/9d3c1f0a-5b2e-4c7a-9f10-2b3c4d5e6f70 \
-H "Authorization: Bearer $LINT_ACCESS_TOKEN" \
-H "Accept: application/json"{
"data": {
"id": "9d3c1f0a-5b2e-4c7a-9f10-2b3c4d5e6f70",
"status": "open",
"amount": 1250000,
"amount_paid": 0,
"currency": "NGN",
"reference": "order_8812",
"description": "2 x Golden Morn 12x500g",
"customer": {
"name": "Ada Obi",
"email": "ada@example.com",
"phone": "2348000000000"
},
"metadata": {
"cart_id": "c_19"
},
"url": "https://lint.finance/checkout/Xk3n9QpL2vT8rW1y",
"success_url": "https://shop.example.com/orders/8812/thanks",
"cancel_url": "https://shop.example.com/cart",
"expires_at": "2026-11-04T10:00:00+00:00",
"paid_at": null,
"payment": {
"transaction_reference": "LNT-20261103-8812",
"amount": 1250000,
"fees": 5000,
"settled_amount": 1245000
},
"created_at": "2026-11-03T10:00:00+00:00"
},
"message": "Checkout session retrieved"
}