Skip to main content
POST
Create a top-up

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

Idempotency-Key
string
required

Required; reuse it only to retry the same request

Path Parameters

id_or_alias
string
required

Customer ID or alias

Body

application/json

Credit sold to the customer, charged or invoiced.

amount
integer<int64>
required

Credit to buy, positive, applying to ALL charges. In minor units of currency, charged one for one without tax: the usage it pays is taxed on the invoice that bills it. With credit_unit, in minor units of that unit (e.g. 500000 is 5,000.00 credits of a unit with precision 2), charged at the unit's price per credit in the customer's currency, plus tax under the unit's product.

collection
enum<string>

CHARGE (default) charges a saved payment method now; SEND_INVOICE issues an invoice and grants the credit once it is paid.

Available options:
CHARGE,
SEND_INVOICE
credit_unit
string | null

Buy credits of this credit unit (its code) instead of money; excludes currency. They are charged in the customer's currency at the customer's agreed price for the unit (the wallet's unit_price), else its list price, plus tax, under the unit's product.

currency
enum<string> | null

Defaults to the customer's currency. SEND_INVOICE sells only in the customer's currency.

Available options:
AED,
AFN,
ALL,
AMD,
ANG,
AOA,
ARS,
AUD,
AWG,
AZN,
BAM,
BBD,
BDT,
BGN,
BHD,
BIF,
BMD,
BND,
BOB,
BRL,
BSD,
BTN,
BWP,
BYN,
BZD,
CAD,
CDF,
CHF,
CLP,
CNH,
CNY,
COP,
CRC,
CUC,
CUP,
CVE,
CZK,
DJF,
DKK,
DOP,
DZD,
EGP,
ERN,
ETB,
EUR,
FJD,
FKP,
GBP,
GEL,
GHS,
GIP,
GMD,
GNF,
GTQ,
GYD,
HKD,
HNL,
HRK,
HTG,
HUF,
IDR,
ILS,
INR,
IQD,
IRR,
ISK,
JMD,
JOD,
JPY,
KES,
KGS,
KHR,
KMF,
KPW,
KRW,
KWD,
KYD,
KZT,
LAK,
LBP,
LKR,
LRD,
LSL,
LYD,
MAD,
MDL,
MGA,
MKD,
MMK,
MNT,
MOP,
MRU,
MUR,
MVR,
MWK,
MXN,
MYR,
MZN,
NAD,
NGN,
NIO,
NOK,
NPR,
NZD,
OMR,
PAB,
PEN,
PGK,
PHP,
PKR,
PLN,
PYG,
QAR,
RON,
RSD,
RUB,
RWF,
SAR,
SBD,
SCR,
SDG,
SEK,
SGD,
SHP,
SLL,
SOS,
SRD,
SSP,
STD,
STN,
SVC,
SYP,
SZL,
THB,
TJS,
TMT,
TND,
TOP,
TRY,
TTD,
TWD,
TZS,
UAH,
UGX,
USD,
UYU,
UZS,
VES,
VND,
VUV,
WST,
XAF,
XCD,
XOF,
XPF,
YER,
ZAR,
ZMW,
ZWL
Example:

"EUR"

expires_at
string<date-time> | null

Absolute expiry of the purchased credit; unset never expires.

payment_method_id
string | null

CHARGE only; defaults to the customer's default payment method.

unit_price
string | null

With credit_unit: the negotiated price of one credit for this purchase, in major units of the customer's currency, as a decimal string (e.g. "0.0008"). Defaults to the wallet's unit_price when set, else the list price; the unit must still have a list price in that currency.

Response

Top-up paid, settling, or awaiting the customer

Where a top-up stands. Its credit is granted once it is paid; wallet.funded reports it.

amount
integer<int64>
required

Credit bought, in minor units of currency, or of credit_unit when set.

currency
enum<string>
required

The money the top-up is charged in.

Available options:
AED,
AFN,
ALL,
AMD,
ANG,
AOA,
ARS,
AUD,
AWG,
AZN,
BAM,
BBD,
BDT,
BGN,
BHD,
BIF,
BMD,
BND,
BOB,
BRL,
BSD,
BTN,
BWP,
BYN,
BZD,
CAD,
CDF,
CHF,
CLP,
CNH,
CNY,
COP,
CRC,
CUC,
CUP,
CVE,
CZK,
DJF,
DKK,
DOP,
DZD,
EGP,
ERN,
ETB,
EUR,
FJD,
FKP,
GBP,
GEL,
GHS,
GIP,
GMD,
GNF,
GTQ,
GYD,
HKD,
HNL,
HRK,
HTG,
HUF,
IDR,
ILS,
INR,
IQD,
IRR,
ISK,
JMD,
JOD,
JPY,
KES,
KGS,
KHR,
KMF,
KPW,
KRW,
KWD,
KYD,
KZT,
LAK,
LBP,
LKR,
LRD,
LSL,
LYD,
MAD,
MDL,
MGA,
MKD,
MMK,
MNT,
MOP,
MRU,
MUR,
MVR,
MWK,
MXN,
MYR,
MZN,
NAD,
NGN,
NIO,
NOK,
NPR,
NZD,
OMR,
PAB,
PEN,
PGK,
PHP,
PKR,
PLN,
PYG,
QAR,
RON,
RSD,
RUB,
RWF,
SAR,
SBD,
SCR,
SDG,
SEK,
SGD,
SHP,
SLL,
SOS,
SRD,
SSP,
STD,
STN,
SVC,
SYP,
SZL,
THB,
TJS,
TMT,
TND,
TOP,
TRY,
TTD,
TWD,
TZS,
UAH,
UGX,
USD,
UYU,
UZS,
VES,
VND,
VUV,
WST,
XAF,
XCD,
XOF,
XPF,
YER,
ZAR,
ZMW,
ZWL
Example:

"EUR"

status
enum<string>
required

SUCCEEDED once paid; otherwise what the payment is waiting for.

Available options:
SUCCEEDED,
PENDING,
REQUIRES_CUSTOMER_ACTION,
AWAITING_PAYMENT
charged_amount
integer<int64> | null

Charged to the payment method, tax included, in minor units of currency; absent until a charge is made.

checkout_url
string | null

Hosted page where the customer completes the payment; present while it awaits them.

credit_unit
string | null

Set when credits of this credit unit were bought: amount is in its minor units.

invoice_id
string | null

The invoice documenting the purchase.

payment_transaction_id
string | null

The charge made on the payment method; absent until a charge is made.