Skip to main content
POST
Request a transfer
Asks to move money from one user’s balance to another user’s balance. Send the approval_url to the sender: the money moves only after they approve with their passkey. Send an Idempotency-Key so a retried request returns the first transfer instead of making a second one.

Authorizations

Authorization
string
header
required

A platform access token. Get one on the Create an access token endpoint by exchanging your client_id + client_secret, then send it as Authorization: Bearer <token>. Tokens live one hour.

Headers

Idempotency-Key
string

Send the same key again to get the same transfer back instead of a second one.

Body

application/json
from_user_id
string
required

The user who sends the money and approves the transfer.

to_user_id
string
required

The user who receives it.

amount_cents
integer
required

What the recipient receives, in cents. From 100 to 1000000.

description
string

A note the sender sees when they approve. Up to 140 characters.

Response

The transfer this Idempotency-Key already made.

object
enum<string>
required

Always wallet_transfer.

Available options:
wallet_transfer
id
string
required

The transfer, wtr_ and 24 characters.

status
enum<string>
required

Where the transfer stands. completed, failed, expired and declined are final.

Available options:
pending_approval,
approved,
submitted,
completed,
failed,
expired,
declined
from_user_id
string
required

The sender.

to_user_id
string
required

The recipient.

amount_cents
integer
required

What the recipient receives, in cents.

currency
enum<string>
Available options:
usd
description
string | null

The note the sender saw.

approval_url
string | null

Where the sender approves, while the status is pending_approval.

expires_at
string<date-time>

When an unanswered request expires.

decision
object | null

How the sender decided, once they have.

tx_hash
string | null

The Base transaction that moved the money.

failure_code
string | null

Why the transfer ended without moving money.

created_at
string<date-time>
completed_at
string<date-time> | null