Charge Wallet

Charges a holder's wallet: moves money from the wallet to your ledger account.

Use it when the holder spends wallet money with you. The charge completes in the same call: the 201 response is
charged. The amount is taken from the wallet's balances in this order: depositSettled, then depositUnsettled, then
customerCredited. A wallet balance never goes below zero. The holder can dispute a charge (see Wallet Disputes).

Requires the Wallet Management permission (see Invite Wallet Holder). No webhook is sent for charges.

Retries. Send a referenceId. A repeat with the same referenceId, amount and memo returns the existing charge
with 200 and never charges twice. A referenceId is used up by a charge that failed: the repeat returns the failed
charge. Use a new referenceId to try again.

Errors

  • 400 VALIDATION_ERROR: a field is missing or invalid, or a field is not part of the request
  • 400 CHARGE_INVALID_AMOUNT: amount has more decimals than the wallet's currency allows
  • 404 NOT_FOUND: the wallet does not exist, or holderId is not its holder
  • 409 CHARGE_ALREADY_EXISTS: a charge with this referenceId exists with a different amount or memo
  • 409 WALLET_INSUFFICIENT_FUNDS: the wallet's balance is less than amount. The charge is recorded as failed
  • 409 CHARGE_INVALID_MEMO: memo is longer than 1009 characters. The charge is recorded as failed
  • 409 CUSTOMER_FROZEN: your wallet program is frozen. Contact Payment Labs support. If the message says the charge is
    still requested, retry with the same referenceId once the freeze lifts
  • Any other 409: the charge was refused and recorded as failed, with the same code in failureCode
Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Path Params
string
required

The holder's user ID, as returned by Search Wallets or Invite Wallet Holder.

string
required

The wallet ID, starting with W-, as returned by Search Wallets or Invite Wallet Holder.

Body Params

A charge on a holder's wallet.

string
length between 1 and 128

Your own unique reference for this charge, 1–128 characters. Makes a retry safe: a second request with the same
referenceId and the same amount and memo returns the existing charge. Without it, every request creates a new
charge.

string
required

The amount to take from the wallet, as a decimal string in the wallet's currency, with no more decimals than the
currency allows.

string
length ≤ 1009

What the charge is for. The holder sees it in their wallet history. Leading and trailing spaces are removed.

Responses

Language
Credentials
Bearer
JWT
URL
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json