Skip to main content
POST
Confirm a transfer request
The business policies are evaluated again on confirmation. The requester can confirm only when they approve the transfer (APPROVE, also when no policy matches) and must have the wallet shared with them as OWNER or USER; organization admins can confirm whatever the policies decide. A request waiting for approval is confirmed automatically once approved — it can’t be confirmed by hand. Every required transaction custom field must have a value. See Business policies and approvals for what an organization admin’s confirmation skips. The request becomes CONFIRMED once the money moves. A request for a future day becomes SCHEDULED instead, and the answer includes the schedule: the money moves on scheduledAt, and cancelling the request cancels it. When the bank refuses the transfer — for example, for insufficient funds — the request becomes FAILED with the reason in failureReason, and the error is returned. A FAILED request can’t be retried: create another one — after an error from an unreachable bank, only once the wallets’ balances show the money didn’t move.

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}$
​
transferRequestId
string
required

ID of the transfer request (24 hexadecimal characters).

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

Response

Successful response

A transfer request just confirmed.

​
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:

"CONFIRMED"

​
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 | null
required

The business policy evaluated on this confirmation, and what it decided. null when the request was confirmed after its approval, and when an organization admin confirmed it while the policies couldn't be evaluated.

​
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"

​
schedule
object

The schedule created when the request is for a future day (status SCHEDULED). Absent when the money moved now.