Skip to main content
POST
Create a transfer request
A positive amount asks for money from the main wallet; a negative one sends it from this wallet back to the main wallet. The request starts REQUESTED and comes back with policy: what the organization’s business policies decide about it, for information only. From there:
  • APPROVE (also when no policy matches) — confirm it, and the money moves.
  • NONE — send it for approval; once its approvers approve it, it is confirmed automatically.
  • DENY — its requester can’t confirm it; an organization admin can cancel it.
Business policies and approvals walks through the whole flow. Organization admins can confirm a REQUESTED request whatever the policies decide. Send scheduledAt to move the money on a future day instead of on confirmation. Custom fields are checked against the organization’s transaction custom fields; required ones can be filled in later, before the request is sent for approval or confirmed. The wallet can’t be the organization’s main wallet. Organization admins can create requests for every wallet; other users only for the wallets shared with them as OWNER or USER.

Headers

x-environment
enum<string>

Environment of the wallet: LIVE (production) or TEST (sandbox). When you omit it, the request runs in TEST; any other value is rejected.

Available options:
LIVE,
TEST

Path Parameters

realmId
string<uuid>
required

ID of your realm.

Format: UUID

organizationId
string<uuid>
required

ID of the organization the wallet belongs to.

Format: UUID

accountId
string
required

ID of the organization's account (24 hexadecimal characters).

Pattern: ^[0-9a-fA-F]{24}$
walletId
string
required

ID of the wallet that receives or returns the money (24 hexadecimal characters). It can't be the organization's main wallet.

Pattern: ^([0-9a-fA-F]{24}|default)$

Body

application/json
destinationCategory
enum<string>
required

Balance category of this wallet the transfer moves: where the money lands when amount is positive, and where it is taken from when amount is negative. The organization's main wallet always uses FLEX_INTERNATIONAL.

Available options:
FLEX_NATIONAL,
FLEX_INTERNATIONAL,
FOOD,
GAS,
MOBILITY,
TOLL,
FLEX_NATIONAL_WITHOUT_WITHDRAWALS,
ADS,
SAAS,
HOTEL,
AIRLINES,
TRAVEL
Example:

"FLEX_NATIONAL"

amount
integer
required

Amount in cents, never zero. Positive moves money from the organization's main wallet into this wallet; negative sends it from this wallet back to the main wallet.

Example:

250000

description
string

Description of the transfer.

Example:

"Verba de eventos — novembro"

scheduledAt

Day to make the transfer, as YYYY-MM-DD (a date-time counts as its UTC day). Omit it, or send today — in São Paulo — to transfer as soon as the request is confirmed. A day before today in São Paulo is rejected.

Example:

"2026-11-10"

timeZone
string

Time zone that decides what "today" is for scheduledAt. Only America/Sao_Paulo is supported: it is the default, and any other value — another valid time zone included — is read as America/Sao_Paulo.

Example:

"America/Sao_Paulo"

customFields
object

Values of the organization's transaction custom fields, keyed by each field's slug. Each value must fit its field's type and options; required fields can be filled in later, before the request is sent for approval or confirmed.


Example: {"cost-center":"CC-1020"}

Example:

Response

Successful response

A transfer request, with what the organization's business policies say about it.

id
string
required

ID of the transfer request.

Example:

"6720d4f1b4d3e80012c9a2e7"

realmId
string<uuid>
required

ID of the realm.

Example:

"f495ff0c-ab54-4f99-8e92-ca8682e4de9b"

organizationId
string<uuid>
required

ID of the organization.

Example:

"c4bd3f21-dfbd-44e8-8055-68ba15bed410"

accountId
string
required

ID of the account both wallets belong to.

Example:

"66f2a1c7b4d3e80012c9a0b4"

walletId
string
required

ID of the wallet that receives the money — or sends it back, when amount is negative.

Example:

"66f2a3d1b4d3e80012c9a0d2"

environment
enum<string>
required

Environment of the request: LIVE (production) or TEST (sandbox).

Available options:
LIVE,
TEST
Example:

"LIVE"

destinationCategory
enum<string>
required

Balance category of walletId the transfer moves: where the money lands when amount is positive, and where it is taken from when amount is negative. The main wallet always uses FLEX_INTERNATIONAL.

Available options:
FLEX_NATIONAL,
FLEX_INTERNATIONAL,
FOOD,
GAS,
MOBILITY,
TOLL,
FLEX_NATIONAL_WITHOUT_WITHDRAWALS,
ADS,
SAAS,
HOTEL,
AIRLINES,
TRAVEL,
BLOCKED,
CASHBACK
Example:

"FLEX_NATIONAL"

amount
number
required

Amount in cents, never zero. Positive moves money from the organization's main wallet into walletId; negative sends it from walletId back to the main wallet.

Example:

250000

requester
object
required

Who created the request.

status
enum<string>
required

Status of the request:

  • REQUESTED — created; it can still be edited, sent for approval or confirmed.
  • PENDING_APPROVAL — waiting for the approvers the business policy names.
  • CONFIRMED — the money moved.
  • SCHEDULED — confirmed for a future day; the money moves on scheduledAt.
  • CANCELLED — cancelled before the money moved.
  • EXPIRED — the approval deadline passed before it was approved.
  • FAILED — the transfer was refused, for the reason in failureReason.
  • DENIED — only on a few requests from the first version of transfer requests.
Available options:
PENDING_APPROVAL,
REQUESTED,
CONFIRMED,
CANCELLED,
EXPIRED,
FAILED,
SCHEDULED,
DENIED
Example:

"REQUESTED"

createdAt
string<date-time>
required

When the request was created.

Example:

"2026-11-02T13:10:22.000Z"

updatedAt
string<date-time>
required

When the request last changed.

Example:

"2026-11-02T13:10:22.000Z"

policy
Policy evaluation · object
required

The business policy that matches the request as it stands, and what it decides: the transfer can be confirmed right away (APPROVE), it needs approval (NONE) or it is refused (DENY). Informative only — nothing is enforced until the request is sent for approval or confirmed.

walletName
string

Name of that wallet when the request was created. Absent when the wallet had no name.

Example:

"Marketing"

defaultWalletId
string

ID of the organization's main wallet when the request was created: the other side of the transfer. Absent only on a few requests from the first version of transfer requests, which carry originWalletId instead.

Example:

"66f2a1d0b4d3e80012c9a0b9"

txnCurrency
string

Currency of the amount, as an ISO 4217 numeric code: 986 (Brazilian real).

Example:

"986"

description
string

Description of the transfer. Absent when none was given.

Example:

"Verba de eventos — novembro"

policyRequestId
string

ID of the approval request opened when the request was sent for approval, or of the automatic approval that confirmed it. Absent otherwise.

Example:

"4d2c1b0a-9f8e-4d7c-8b6a-5f4e3d2c1b0a"

autoResolutionRequestedAt
string<date-time>

When a confirmation first asked for the automatic approval of the matching business policy. Absent when no confirmation needed it.

Example:

"2026-11-02T13:12:05.000Z"

scheduledAt
string<date-time>

Day the transfer is scheduled for. Absent when it transfers as soon as it is confirmed.

Example:

"2026-11-10T00:00:00.000Z"

scheduledTimeZone
string

Time zone scheduledAt was read in — America/Sao_Paulo, the only one supported. Present only with scheduledAt.

Example:

"America/Sao_Paulo"

scheduleId
string<uuid>

ID of the schedule created when a request for a future day was confirmed. Cancel the request to cancel it.

Example:

"8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f"

approvalExpiresAt
string<date-time>

Deadline for the approval: 21:00 (São Paulo time) of the day the transfer is for, and at least one hour after the request was sent for approval. Present once it was sent for approval.

Example:

"2026-11-03T00:00:00.000Z"

confirmedAt
string<date-time>

When the money moved.

Example:

"2026-11-02T13:12:07.000Z"

canceledAt
string<date-time>

When the request was cancelled.

Example:

"2026-11-02T15:40:00.000Z"

failureReason
string

Why the transfer failed, as an error code — for example INSUFFICIENT_FUNDS, ACCOUNT_BLOCKED or BANKING_PROVIDER_UNAVAILABLE. Only on FAILED requests.

Example:

"INSUFFICIENT_FUNDS"

customFields
object

Values of the organization's transaction custom fields, keyed by each field's slug. Absent when the request has none.


Example: {"cost-center":"CC-1020"}

Example:
decision
object

Decision recorded on a few requests from the first version of transfer requests.

deniedAt
string<date-time>

When the request was denied, on a few requests from the first version of transfer requests.

Example:

"2025-11-20T18:05:00.000Z"

originAccountId
string

Account the money came from, on a few requests from the first version of transfer requests.

Example:

"66f2a1c7b4d3e80012c9a0b4"

originWalletId
string

Wallet the money came from, on a few requests from the first version of transfer requests.

Example:

"66f2a1d0b4d3e80012c9a0b9"

sourceCategory
enum<string>

Balance category the money came from, on a few requests from the first version of transfer requests.

Available options:
FLEX_NATIONAL,
FLEX_INTERNATIONAL,
FOOD,
GAS,
MOBILITY,
TOLL,
FLEX_NATIONAL_WITHOUT_WITHDRAWALS,
ADS,
SAAS,
HOTEL,
AIRLINES,
TRAVEL,
BLOCKED,
CASHBACK
Example:

"FLEX_INTERNATIONAL"