Skip to main content
PUT
Update a transfer request
Only a REQUESTED request can be edited, and only its custom fields and scheduledAt: the amount and category are fixed — cancel the request and create another to change them. Send only what you change. The answer comes with policy re-evaluated for the request as it now stands, since the change can alter what the business policies decide — read it to choose between confirming and sending for approval. Organization admins can edit every wallet’s requests; other users the requests of 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 the transfer request belongs to (24 hexadecimal characters).

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

ID of the transfer request (24 hexadecimal characters).

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

Body

application/json
customFields
object

Values of the organization's transaction custom fields, keyed by each field's slug. Replaces every value the request has: a field you leave out is removed and {} clears them all. Omit it to keep them.


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

Example:
scheduledAt

Day to make the transfer, as YYYY-MM-DD (a date-time counts as its UTC day). A day after today in São Paulo schedules the transfer, today makes it transfer as soon as it is confirmed, and an earlier day is rejected. Omit it to keep the current day.

Example:

"2026-11-12"

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"

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"