Skip to main content
POST
Submit a transaction for spend review
The answer (201) is the transaction, with its spendReview now PENDING_APPROVAL and the approval request opened for it in policyRequest. The approvers have a month to decide; the review then becomes APPROVED or DECLINED (declineOutcome DENIED, CANCELED or EXPIRED). When the matching policy approves on its own (autoAction APPROVE with a policy), the review is APPROVED at once, with autoApproved true, and any money the policy moves to the wallet moves now. Preview what will happen with GET .../spend-review; the request has no body. Any transaction that moved money can be submitted — a purchase, a payment or money received — once, while it has no review or its review was DECLINED. Changing its custom fields with PUT .../custom-fields resets the review, so it can be submitted again — with one exception: once a policy approved the transaction automatically, it can only be approved automatically again, so when its new values need an approver, submitting answers 409 SPEND_REVIEW_NOT_REQUESTABLE every time. Its stored custom fields are checked first: a required transaction custom field with no value is a 422. The policies are never skipped: when they can’t be evaluated, the answer is a 503 and nothing changes. On the organization’s main wallet, only organization admins can submit; on another wallet, organization admins and the users it is shared with as OWNER or USER. Use default as walletId for the main wallet, and send x-environment: LIVE for production wallets.

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 (24 hexadecimal characters), or default for the organization's main wallet.

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

ID of the transaction (24 hexadecimal characters).

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

Response

Successful response

The transaction just submitted for review, with the approval request opened for it.

​
_id
string
required

ID of the transaction.

Example:

"6710c9a2b4d3e80012c9a1e4"

​
environment
enum<string>
required

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

Available options:
LIVE,
TEST
Example:

"LIVE"

​
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 organization's account.

Example:

"66f2a1c7b4d3e80012c9a0b4"

​
walletId
string
required

ID of the wallet.

Example:

"66f2a3d1b4d3e80012c9a0d2"

​
availableBalanceBefore
number | null
required

Balance of that category before the transaction, in cents (BRL). Can be null.

Example:

1250000

​
financialImpactType
enum<string>
required

Effect on the balance: DEBIT (money out), CREDIT (money in) or NONE (no effect — a declined or authorization-only card transaction, a failed transfer).

Available options:
DEBIT,
CREDIT,
NONE
Example:

"CREDIT"

​
responseCode
number
required

Result code. 0 is success; for a card, a few other codes are approvals too (such as 10, partially approved) and the rest are decline reasons, such as 51 (insufficient funds). Use financialImpactType to know whether money moved.

Example:

0

​
msgType
number
required

Kind of message: 1100 (card authorization), 1120 (card settlement or credit), 1400 (card refund), 1420 (card reversal), 1600 (Pix or boleto), 1220 (transfer between wallets, or TED), 1722 (charge), 8900 / 8901 / 8902 (fee).

Example:

1600

​
txnType
number
required

Operation type: for a card, ISO 8583 codes such as 0 (purchase) or 14 (return); for the others, 12 (credit), 13 (debit), 36 (Pix received), 39 (Pix or boleto paid) or 27 (a refund).

Example:

36

​
effectiveAt
string<date-time>
required

When the transaction happened. Lists are ordered by it, and the period filters apply to it.

Example:

"2026-10-17T13:42:58.000Z"

​
billingAmount
number
required

Amount charged to or credited on the wallet, in cents (BRL).

Example:

15000

​
billingAmountAuthorized
number
required

Amount authorized, in cents (BRL). The totals add this one up.

Example:

15000

​
createdAt
string<date-time>
required

When the record was created.

Example:

"2026-10-17T13:43:01.000Z"

​
updatedAt
string<date-time>
required

When the record last changed.

Example:

"2026-10-17T13:43:01.000Z"

​
policyRequest
object
required

The approval request opened for the review.

​
cardId
string

ID of the card, on a card transaction or a fee charged on a card.

Example:

"66f2a4b8b4d3e80012c9a0e1"

​
balanceCategory
string

Balance category of the wallet the amount was taken from or added to, such as FLEX_INTERNATIONAL, FLEX_NATIONAL, ADS, TRAVEL, HOTEL, AIRLINES, GAS, FOOD or CASHBACK.

Example:

"FLEX_INTERNATIONAL"

​
billingCurrency
string

Currency of the billed amounts, as an ISO 4217 numeric code: 986 (Brazilian real). Absent on a few boleto transactions.

Example:

"986"

​
cardTransaction
object

Details of a card purchase, its settlement or refund.

​
pixTransaction
object

Details of a Pix sent or received.

​
boletoTransaction
object

Details of a boleto paid or received.

​
tedTransaction
object

Details of a TED sent.

​
p2pTransaction
object

Details of a transfer between wallets at Portão 3.

​
feeTransaction
object

Details of a fee.

​
enrichment
object

Merchant and spending category recognized for a card purchase. Absent on older ones.

​
customFields
object

Values of the organization's transaction custom fields, keyed by each field's slug. Absent when the transaction has none. On a few older transactions it is still an array of custom field entries, from before values were keyed by slug.

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

Example:
​
spendReview
object

The expense review, once the transaction was submitted for approval.

​
spendReviewSubmissionLeaseUntil
string<date-time>

Until when a submission for review is being processed. Absent otherwise.

Example:

"2026-11-02T18:07:11.000Z"

​
receipts
string

Receipt attached to an older transaction.

Example:

"https://files.example.com/receipt.pdf"

​
external
object

References of the transaction outside its ledger record. Absent on a transfer between wallets that failed.

​
processingType
enum<string>

INSTANT (processed as it happened) or DELAYED (processed later, such as a payment scheduled for a later day). Absent on a few older transactions.

Available options:
INSTANT,
DELAYED
Example:

"INSTANT"

​
internalErrorCode
string

Why a transaction that moved no money failed, such as INSUFFICIENT_FUNDS, LIMIT_EXCEEDED or REJECTED_BY_ANTIFRAUD_PREVENTION_RULES.

Example:

"LIMIT_EXCEEDED"

​
__v
number

Version of the record. Absent on a few older ones.

Example:

0