Wallet

Top up by bank transfer

Declare a transfer and get the account to send it to, with a reference code for the memo. The money is pending until it lands.

POST/v1/wallet/bank-transfers

Authorization: BearerBody (JSON)

Live API. A POST to /v1/cards issues a real card.

Authorizations

Authorizationstringrequired

Bearer token: Authorization: Bearer mk_live_.... Create a key in the AgentPay console under Developer, API keys.

Bodyapplication/json

amountnumberrequired

The amount in the transfer currency, above zero.

railstringdefault: ach

Which account to send to.

Available options: ach, wire_domestic, wire_international, uae_local

currencystring

USD, or AED for uae_local. Defaults by rail.

sent_onstring

yyyy-MM-dd, the day the transfer was sent.

sender_bank_namestring

What the statement will show, so the transfer is matched faster.

sender_account_namestring

sender_referencestring

idempotency_keystring

Your own key, up to 80 characters. A retry returns the same declaration.

Response200application/json

funding_event_idstring

statusstring

pending until the money lands.

already_recordedboolean

true when the idempotency_key matched an earlier declaration.

amountnumber

currencystring

railstring

reference_codestring

Eight characters. Goes in the transfer memo.

pending_balancenumber

The wallet's pending after this declaration.

instructionsobject

The account to send to. Show it to the person as it is. Fields depend on the rail: beneficiary_name, account_number, routing_number or swift_bic, iban, bank_name, bank_address, beneficiary_address, reference, note.

request_idstring

The request id, also in the X-Mooj-Request-Id header.

Errors

Status	Code	When
400	`invalid_amount`	`amount` is missing or not above zero.
400	`invalid_request`	`rail` is not one of the four, or the declaration was refused as malformed.
402	`wallet_limit`	The transfer would take the wallet above its ceiling.
402	`funding_budget_reached`	The account's funding budget for the period is reached.
402	`funding_unavailable`	Top-ups are paused for the moment.
502	`bank_transfer_failed`	The declaration could not be recorded. Retry.

Top up by bank transfer

curl -X POST https://api.joomjoo.com/v1/wallet/bank-transfers \
  -H "Authorization: Bearer $AGENTPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount":500,"rail":"wire_domestic","sent_on":"2026-11-03","idempotency_key":"topup-2026-11-03"}'

import { AgentPay } from "@agentpay-global/sdk";

const agentpay = new AgentPay(process.env.AGENTPAY_API_KEY);
const transfer = await agentpay.wallet.declareBankTransfer({ amount: 500, rail: "wire_domestic", sent_on: "2026-11-03", idempotency_key: "topup-2026-11-03" });

import os
from agentpay import AgentPay

agentpay = AgentPay(api_key=os.environ["AGENTPAY_API_KEY"])
transfer = agentpay.wallet.declare_bank_transfer(amount=500, rail="wire_domestic", sent_on="2026-11-03", idempotency_key="topup-2026-11-03")

200

{
  "funding_event_id": "fe_...",
  "status": "pending",
  "already_recorded": false,
  "amount": 500,
  "currency": "USD",
  "rail": "wire_domestic",
  "reference_code": "7K2QW9PD",
  "pending_balance": 500,
  "instructions": {
    "beneficiary_name": "Joomjoo, LLC",
    "account_number": "...",
    "routing_number": "...",
    "bank_name": "Column N.A.",
    "account_type": "Checking",
    "bank_address": "...",
    "beneficiary_address": "...",
    "reference": "7K2QW9PD",
    "note": "Put the reference code in the transfer memo. The wallet is credited when the money lands; subscribe to money.funded to know."
  },
  "request_id": "req_a1b2c3"
}