Update mutable transfer attributes (metadata)

Optional detail explaining the current status. Present for a transfer that needs OZAV reconciliation, and for one that ended badly (failed, cancelled, expired) once the reason was recorded; code is a catalog error code you can branch on. Absent when no reason was recorded, which is the case for transfers created before this field existed; treat absence as "not stated", never as "no reason". It never contains internal names, native rail error payloads, or a compliance verdict.

The settlement state of one side of a transfer (source or destination). Read-only.

The settlement state of one side of a transfer (source or destination). Read-only.

The amounts and rate of this transfer. They start from the quote when the transfer is created (when the quote carried exchange_conditions.amount_deducted, rate is the all-in target.amount / source.amount, published at 8 decimal places, and differs from the quote's rate by the deducted cost), and on some paths they are updated at settlement: on the fiat-to-stablecoin path (fiat_payment to wallet) source, target and rate are rewritten from the settled amounts as the operation progresses, before the matching transfer.* webhook is sent. On the other paths they keep the quoted values, which are indicative on a floating quote. Read them again from GET /transfers/{transfer_id} or the webhook after the transfer settles; do not cache the values returned at creation.

Public exchange conditions. spread_bps is the additional client-selected spread for the quote, in integer basis points. OZAV cost, floor, margin, split and cost analytics are internal and are not serialized in public API responses.

Originator and beneficiary information for a crypto send, required by BCB Resolution 520/2025 when value leaves custody to an external address.

Read the "Required for an external crypto send" list below before building this object. The fields marked required there are not the same as the ones marked required here: this schema is shared with paths where Travel Rule is supplementary, so it stays permissive. The mandatory set is enforced on destination.type = crypto_address, and a request that misses any of it is refused with 422 TRAVEL_RULE_REQUIRED and a details.missing_fields array naming each one.

Required for an external crypto send

Accepted originator identity documents, by country

The requirement follows the customer's country of residence as held on the customer record - not the country you send inside travel_rule, which is stored but never selects the regime. A country not listed below uses the default set.

To be precise about where that country comes from: you declare it when you create the customer (individual.tax_id.country, or the address), and you can correct it later with PATCH /customers/{id}. Both paths refuse a jurisdiction OZAV does not serve. So the regime is not selectable per request, but it does follow what you declared for that customer - keep it accurate.

If your customer's country is not listed and the default set does not fit its national identifiers, tell us and it gets modelled - the list is data, not code.

A destination that is an OZAV wallet id (ozav_wal_...) is exempt: the value stays in custody and both sides are already verified.

Values inside originator and beneficiary must be plain strings - do not embed internal or third-party references.

What happened to the FX rate lock on this transfer.

Present on the 201 of a create that sent facility_terms_accepted: true, on BRL/Pix flows. A transfer created without the lock has no facility key at all, and its body is byte-for-byte what it has always been.

Two limits worth knowing before you build on it.

It is a create-time outcome, not transfer state. GET /transfers/{id} does not return it, and neither do the transfer.* webhook events after the first one. If you need it later, store it when you receive the 201.

The lock applies to BRL/Pix on-ramp and off-ramp only. The fields are accepted on every combination, but on a crypto_address destination, a wallet-to-wallet move, or the BRS redemption corridor they have no effect and no facility block comes back. Read the absence of the block on those flows as "no lock", not as "locked".

Read locked before you present a price to the payer. A lock can be requested and still not happen, and those cases return 201: the Pix charge is valid and the customer will pay it, so refusing would lose the operation for a condition that only costs the lock. The consequence is that this block is the only thing standing between "the price is fixed" and "the price is whatever the market does before you pay".

| state | locked | What it means | What to do | |---|---|---|---| | locked | true | The rate is fixed until deadline_at. | Deliver before the deadline. Missing it triggers the schedule's penalty. | | not_locked | false | The lock did not happen and there is nothing to correct - typically the shared ceiling had no room, or a withdrawal was covered by the balance already delivered. The transfer is valid. | Nothing, but the conversion uses the rate at execution time. Tell whoever is paying. | | refused | false | The lock was refused by account state - conditions changed between the quote and the acceptance. | Read reason, fix it, and accept again. | | undetermined | false | The hedge may have executed; nothing was recorded as locked. | Do not retry and do not treat as failed. Reconcile with GET /transfers/{id}. |

The references the payment rail produced for this transfer, the ones a bank or an auditor asks for to trace the payment. Returned by GET /transfers/{transfer_id} and GET /transfers for off-ramp transfers (a payout to a payout_destination or to your customer's own account) and for wallet sends (a transfer to a wallet or a crypto_address).

Only the keys that exist are present. A reference appears once the payout step recorded it, never earlier and never made up; a key that does not apply to the rail is simply absent, and the whole object is absent while nothing has been recorded. Read the absence as "not available (yet)", never as "failed". The transfer.* webhook events and the 201 of a create do not carry it: read it again with GET /transfers/{transfer_id} after the transfer settles.

| Key | Rail | What it is | |---|---|---| | end_to_end_id | Pix | The Pix end-to-end id (E...). | | imad | US wire | Input Message Accountability Data. | | omad | US wire | Output Message Accountability Data, when the wire reports it. | | uetr | SWIFT | The end-to-end transaction reference (UUID). | | trace_number | ACH | The ACH trace number. | | ach_reference | ACH | The ACH reference. | | sepa_reference | SEPA | The SEPA payment reference. | | spei_reference | SPEI | The SPEI tracking key. | | tracking_number | Other bank rails | The rail's tracking number. | | tx_hash | On-chain | The transaction hash, present only once the send is confirmed on-chain. | | network | On-chain | The network the transaction settled on (ethereum, polygon, solana, tron, stellar). Present with tx_hash. |

The receiving bank of a fiat payout, masked. Returned by GET /transfers/{transfer_id} and GET /transfers for off-ramp transfers sent to a bank account. Account numbers are never returned whole: account_masked is **** plus the last four characters, and iban_masked keeps the country and check digits and the last four. Only the keys that are known are present; the object is absent when the destination is not a bank account (a Pix key, for instance) or the bank details were not recorded.