Skip to main content
Move money from one of your users’ balances to another user’s balance. You request the transfer, the sender approves it with their passkey, and the money lands in the recipient’s balance, ready for their cards.
The response is a transfer in pending_approval, with an approval_url:
Send the approval_url to the sender. Nothing moves until they open it, see the amount and the recipient, and approve with their passkey. The sender has 24 hours; after that the request is expired and you request a new one. The sender can also decline, and the transfer reads declined. Both people must be users of your company, connected with the same credential mode. A user of another company is refused as if they did not exist, and no transfer is made:
A requested transfer holds its amount against the sender’s balance until it completes, fails, expires or is declined. A second request the balance cannot cover is refused with insufficient_funds, and available_cents says what is left:
A transfer counts against the spend limits you set on the sender. A request the limits do not leave room for is refused with wallet_spend_limit_exceeded, and the error says which limit and how much is left:
A transfer starts counting when the sender approves it, not when you request it. Two requests can each fit the limit on their own and pass it together; the one approved second then ends failed with wallet_spend_limit_exceeded, and nothing moves. A transfer that ends failed, declined or expired stops counting.

Follow a transfer

Get the transfer to learn where it stands. The money starts moving the moment the sender approves, and usually lands within a minute. A read moves no money. A transfer’s decision records what the sender decided, when, with which method, and from which country when known:
Keep it as your record of the sender’s consent. Agentcard stores the IP address and browser of the request the sender decided from, and the API does not return them. Transfers move real money, so they need a production credential. A sandbox credential is refused with sandbox_not_supported, on a read of a transfer as well as a request for one.