curl --request POST \
--url https://20b9-41-90-209-232.ngrok-free.app/v1/payins/prepare \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <idempotency-key>' \
--data '
{
"target_currency": "NGN",
"mode": "bank_details",
"amount": 5000000
}
'{
"object": "payin",
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"status": "pending",
"method": "bank_transfer",
"target_currency": "NGN",
"amount": 5000000,
"collection_mode": "bank_details",
"stan": "IN-2610-ABCDEF12",
"instructions": {
"account_name": "Keette Collections",
"account_number": "0123456789",
"bank_name": "Guaranty Trust Bank",
"bank_code": "058"
},
"created_at": "2026-10-27T13:00:00Z"
}{
"error": {
"type": "authentication_error",
"code": "invalid_api_key",
"message": "Invalid API key provided."
}
}Prepare Payin
Open a deposit intent and return receive instructions (bank details,
crypto address, momo prompt, or Interac). Requires Idempotency-Key.
Modes: bank_details, crypto_address, momo, interac.
curl --request POST \
--url https://20b9-41-90-209-232.ngrok-free.app/v1/payins/prepare \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <idempotency-key>' \
--data '
{
"target_currency": "NGN",
"mode": "bank_details",
"amount": 5000000
}
'{
"object": "payin",
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"status": "pending",
"method": "bank_transfer",
"target_currency": "NGN",
"amount": 5000000,
"collection_mode": "bank_details",
"stan": "IN-2610-ABCDEF12",
"instructions": {
"account_name": "Keette Collections",
"account_number": "0123456789",
"bank_name": "Guaranty Trust Bank",
"bank_code": "058"
},
"created_at": "2026-10-27T13:00:00Z"
}{
"error": {
"type": "authentication_error",
"code": "invalid_api_key",
"message": "Invalid API key provided."
}
}Authorizations
Secret API key from Settings → Developers → API keys.
Example: Authorization: Bearer sk_test_…
Headers
Client-generated key so retries return the same intent.
1 - 64Body
Book currency to credit.
"NGN"
How funds will arrive.
bank_details, crypto_address, momo, interac "bank_details"
Amount the payer sends in source_currency minor units.
5000000
Currency of the receive rail. Defaults to target_currency. For
Interac defaults to CAD; momo may infer KES/TZS from channel.
Required when source_currency differs from target_currency — expected credit in target minor units.
Crypto network (base, ethereum, …). Defaults to base for crypto.
Optional payment reference / memo.
Required for Interac — where the payer returns after approval.
ISO country hint for some rails.
Mobile number for momo (E.164 or local as required by channel).
Momo channel id (e.g. KE-MPESA).
Optional payer display name.
Optional payer email.
Response
Deposit intent with instructions
Object type discriminator.
payin Payin attempt id.
System trace / reference.
Funding method.
Book currency to credit.
Currency on the payment rail when different.
Requested amount in target (or primary) minor units.
Amount on the rail in rail minor units.
Expected credit to the target book in minor units.
Decimal places for target_currency.
Lifecycle status (pending, processing, completed, failed, …).
Hosted checkout URL when the method requires a redirect.
Return URL you supplied.
Origin kind from prepare.
Prepare mode (bank_details, crypto_address, …).
Crypto network when applicable.
Receive instructions for the payer (account number, bank name,
wallet address, etc.). Shape depends on collection_mode.
Failure message when status is failed.
Creation time (UTC).
Last status change (UTC).
When the deposit completed, if successful.
true when created with a live key.
Environment of the creating API key.
live, sandbox