Credit Wallet

Credits money from your ledger account into a holder's wallet.

Use it to pay a holder into their wallet instead of to their bank. The money lands in customerCredited, which the
holder can spend and withdraw.

Requires the Wallet Management permission (see Invite Wallet Holder).

How it works. The credit is a payment in one of your batches, created and submitted in the same call, with no
separate approval. Name an existing batch with batchId, or create one with batch. The same tax and fee rules as a
payout apply: tax withholding and fees are deducted, and creditedAmount is what reaches the wallet.

  • The holder must have finished onboarding for the tax jurisdiction, or the credit is refused with 409 HOLDER_NOT_PAYABLE.
  • The 201 response usually shows payment-created. The credit moves to credited (or failed) shortly after. Follow
    it with Search Wallet Entries, filtering entryId on the creditId. No webhook is sent for credits.

Retries. Send a referenceId. A repeat with the same referenceId and the same terms returns the existing credit
with 200 and never credits twice; after a 5xx, retry this way. "Same terms" means the same sourceAmount, wallet,
holder, payorMemo and batch (batchId, or batch.name and batch.referenceId), plus paymentCategory and payeeMemo
when you send them.

Errors

  • 400 VALIDATION_ERROR: a field is missing or invalid. Detail codes include CREDIT_BATCH_REQUIRED (send exactly one of
    batchId and batch), CREDIT_INVALID_PAYMENT_CATEGORY (paymentCategory is required with batch),
    CREDIT_BATCH_INVALID (batch.name is missing or batch.referenceId is not a string), or a field that is not part of
    the request
  • 400 CREDIT_INVALID_AMOUNT: sourceAmount has more decimals than the wallet's currency allows
  • 400 CREDIT_BATCH_INVALID: the batch does not exist, is archived, or cannot hold credits
  • 404 NOT_FOUND: the wallet does not exist, or holderId is not its holder
  • 409 CREDIT_ALREADY_EXISTS: a credit with this referenceId exists with different terms
  • 409 CUSTOMER_FROZEN: your wallet program is frozen. Contact Payment Labs support
  • 409 HOLDER_NOT_PAYABLE: the holder has not finished onboarding. Nothing was recorded; retry with the same
    referenceId once they have
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 credit into a holder's wallet.

string
length between 1 and 128

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

string
required

The amount to credit, as a decimal string in the wallet's currency, with no more decimals than the currency allows.
Tax withholding and fees are deducted from it.

string
enum

Payment category of the payment behind the credit. Defaults to the batch's category. Required when you send batch.

string

An existing batch of yours to hold the payment behind the credit. It must not be archived. Send exactly one of batchId
or batch.

batch
object

A new batch to create for the payment behind the credit. Send exactly one of batchId or batch.

string

Your internal note on the credit. The holder does not see it.

string

The note the holder sees on the credit in their wallet history. Defaults to the batch name.

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