Skip to main content
POST
Create Payin

Authorizations

Authorization
string
header
required

Secret API key from Settings → Developers → API keys. Example: Authorization: Bearer sk_test_…

Headers

Idempotency-Key
string
required

Client-generated key so retries return the same attempt.

Required string length: 1 - 64

Body

application/json
method
string
required

Funding method (bank_transfer, momo, interac, crypto, apple_pay, …).

Example:

"bank_transfer"

target_currency
string
required

Book currency to credit.

Example:

"GBP"

amount
integer
required

Amount in Ledger minor units (target, unless rail fields set).

Example:

10000

rail_currency
string

Optional rail currency when the payer pays in a different currency.

rail_amount
integer

Amount in rail_currency minor units when set.

redirect_url
string<uri>

Return URL after hosted checkout (required for open banking / Interac / crypto checkout).

country_code
string

ISO country hint.

narration
string

Optional payment memo.

msisdn
string

Mobile number for momo.

channel
string

Momo channel id.

payer_name
string

Optional payer name.

payer_email
string<email>

Optional payer email.

Response

Funding attempt (may include checkout_url)

object
enum<string>

Object type discriminator.

Available options:
payin
id
string<uuid>

Payin attempt id.

stan
string

System trace / reference.

method
string

Funding method.

target_currency
string

Book currency to credit.

rail_currency
string

Currency on the payment rail when different.

amount
integer

Requested amount in target (or primary) minor units.

rail_amount
integer

Amount on the rail in rail minor units.

target_amount
integer

Expected credit to the target book in minor units.

scale
integer

Decimal places for target_currency.

status
string

Lifecycle status (pending, processing, completed, failed, …).

checkout_url
string<uri>

Hosted checkout URL when the method requires a redirect.

redirect_url
string<uri>

Return URL you supplied.

source_kind
string

Origin kind from prepare.

collection_mode
string

Prepare mode (bank_details, crypto_address, …).

network
string

Crypto network when applicable.

instructions
object

Receive instructions for the payer (account number, bank name, wallet address, etc.). Shape depends on collection_mode.

failure_reason
string

Failure message when status is failed.

created_at
string<date-time>

Creation time (UTC).

updated_at
string<date-time>

Last status change (UTC).

completed_at
string<date-time>

When the deposit completed, if successful.

livemode
boolean

true when created with a live key.

environment
enum<string>

Environment of the creating API key.

Available options:
live,
sandbox