> ## Documentation Index > Fetch the complete documentation index at: https://docs.nxos.io/llms.txt > Use this file to discover all available pages before exploring further. # Correct beneficiary details > Correct the beneficiary of a `LOCKED` fiat payout waiting to be sent, when its `requiredActions` holds a `beneficiary_details` action. Send the fields it lists; the others are ignored. The beneficiary is updated for this payout and every later one, the action leaves `requiredActions`, and operations send the payout: follow it with `GET /v1/transactions/{transactionId}` or `transaction.status.updated`. Returns the transaction. ## OpenAPI ````yaml POST /v1/transactions/{transactionId}/beneficiary-details openapi: 3.0.0 info: title: nxos API version: 1.0.0 contact: name: nxos url: https://nxos.io description: |- The nxos platform API provides programmatic access to accounts, balances, quotes, and trades. All endpoints require API key authentication. servers: - url: https://api.nxos.io description: Production variables: {} - url: https://api.sandbox.nxos.io description: Sandbox variables: {} security: [] tags: - name: Accounts - name: Quotes - name: Beneficiaries - name: Fiat Payouts - name: Crypto Payouts - name: Sandbox Faucet - name: Nxosnet - name: Fees - name: Sub-Org Tiers - name: Assets - name: Funding Methods - name: Transactions - name: Organizations - name: Authorizations - name: Referral invites - name: Referral links - name: Reports - name: Webhooks description: >- Register an HTTPS endpoint to receive events (organization verification, transaction status changes, and finished reports) instead of polling. Deliveries are signed; verify the `svix-signature` header before acting on an event. See the [Webhooks guide](https://docs.nxos.io/core-concepts/webhooks) for the delivery format, signature verification, retries, and broker behavior. Payload shapes are documented in the `…Event` models below. paths: /v1/transactions/{transactionId}/beneficiary-details: post: tags: - Transactions description: >- Correct the beneficiary of a `LOCKED` fiat payout waiting to be sent, when its `requiredActions` holds a `beneficiary_details` action. Send the fields it lists; the others are ignored. The beneficiary is updated for this payout and every later one, the action leaves `requiredActions`, and operations send the payout: follow it with `GET /v1/transactions/{transactionId}` or `transaction.status.updated`. Returns the transaction. operationId: Transactions_correctBeneficiaryDetails parameters: - $ref: '#/components/parameters/ApiKeyAuth' - $ref: '#/components/parameters/IdempotencyKey' - name: transactionId in: path required: true description: Transaction identifier. schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CorrectBeneficiaryDetailsRequest' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/Transaction' '400': description: The server could not understand the request due to invalid syntax. content: application/json: schema: $ref: '#/components/schemas/Error400' examples: 'invalid_request: Content-Type must be application/json.': summary: 'invalid_request: Content-Type must be application/json.' value: error: code: invalid_request message: Content-Type must be application/json. requestId: req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4 'invalid_request: Malformed JSON in request body.': summary: 'invalid_request: Malformed JSON in request body.' value: error: code: invalid_request message: Malformed JSON in request body. requestId: req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4 '401': description: Access is unauthorized. content: application/json: schema: $ref: '#/components/schemas/Error401' '403': description: Access is forbidden. content: application/json: schema: $ref: '#/components/schemas/Error403' examples: acting_org_not_found: summary: acting_org_not_found value: error: code: acting_org_not_found message: >- Nxos-On-Behalf-Of points to an organization that does not exist. requestId: req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4 authorization_required: summary: authorization_required value: error: code: authorization_required message: No active authorization for the requested organization. requestId: req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4 'verification_required: Complete identity verification before moving funds or managing clients': summary: >- verification_required: Complete identity verification before moving funds or managing clients value: error: code: verification_required message: >- Complete identity verification before moving funds or managing clients and recipients. requestId: req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4 '404': description: The server cannot find the requested resource. content: application/json: schema: $ref: '#/components/schemas/Error404' examples: transaction_not_found: summary: transaction_not_found value: error: code: transaction_not_found message: Transaction not found. requestId: req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4 '409': description: The request conflicts with the current state of the server. content: application/json: schema: $ref: '#/components/schemas/Error409' examples: idempotency_request_in_flight: summary: idempotency_request_in_flight value: error: code: idempotency_request_in_flight message: >- A request with this Idempotency-Key is currently being processed. Retry shortly. requestId: req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4 idempotency_key_in_use: summary: idempotency_key_in_use value: error: code: idempotency_key_in_use message: >- This Idempotency-Key was previously used with a different request body. Use a unique key per logical operation. requestId: req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4 beneficiary_already_archived: summary: beneficiary_already_archived value: error: code: beneficiary_already_archived message: The beneficiary of this payout is archived. requestId: req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4 beneficiary_fix_not_requested: summary: beneficiary_fix_not_requested value: error: code: beneficiary_fix_not_requested message: This transaction is not waiting for beneficiary details. requestId: req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4 '422': description: Client error content: application/json: schema: $ref: '#/components/schemas/Error422' examples: validation_error: summary: validation_error value: error: code: validation_error message: Request body failed validation. requestId: req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4 invalid_beneficiary_details: summary: invalid_beneficiary_details value: error: code: invalid_beneficiary_details message: >- Invalid beneficiary details. iban: This IBAN is not valid: check each character. requestId: req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4 '429': description: Client error content: application/json: schema: $ref: '#/components/schemas/Error429' '500': description: Server error content: application/json: schema: $ref: '#/components/schemas/Error500' components: parameters: ApiKeyAuth: name: Authorization in: header required: true description: 'Bearer token. Format: `Bearer `' schema: type: string IdempotencyKey: name: Idempotency-Key in: header required: false description: >- Unique key per logical operation. UUID v4 recommended. Max 255 characters. schema: type: string schemas: CorrectBeneficiaryDetailsRequest: type: object properties: iban: type: string maxLength: 64 description: IBAN, spaces allowed. Checked against its checksum. accountNumber: type: string maxLength: 64 description: Account number, letters and digits, up to 34. swiftCode: type: string maxLength: 32 description: SWIFT / BIC, 8 or 11 characters. bankName: type: string maxLength: 140 description: The recipient's bank name. firstName: type: string maxLength: 140 description: >- For an individual beneficiary, with `lastName`, when `beneficiaryName` is asked. lastName: type: string maxLength: 140 description: >- For an individual beneficiary, with `firstName`, when `beneficiaryName` is asked. businessName: type: string maxLength: 140 description: For a business beneficiary, when `beneficiaryName` is asked. addressLine1: type: string maxLength: 140 description: The recipient's street address. city: type: string maxLength: 140 description: The recipient's city. country: type: string maxLength: 2 description: The recipient's country, ISO 3166-1 alpha-2. description: |- The corrected beneficiary details. Send the fields listed in the `beneficiary_details` required action; any other field is ignored. The beneficiary is updated for this payout and every later one. example: iban: GB82WEST12345698765432 Transaction: anyOf: - $ref: '#/components/schemas/CryptoPayinTransactionRecord' - $ref: '#/components/schemas/CryptoPayoutTransactionRecord' - $ref: '#/components/schemas/FiatPayinTransactionRecord' - $ref: '#/components/schemas/FiatPayoutTransactionRecord' - $ref: '#/components/schemas/TradeTransactionRecord' - $ref: '#/components/schemas/TransferTransactionRecord' - $ref: '#/components/schemas/NxosnetTransferTransactionRecord' - $ref: '#/components/schemas/CreditAdjustmentTransactionRecord' - $ref: '#/components/schemas/CommissionTransactionRecord' - $ref: '#/components/schemas/DebitAdjustmentTransactionRecord' description: >- A transaction, discriminated by `type`. Use the `type` field to narrow the `details` payload — each variant has a different shape. The envelope (status, amount, asset, fee, timestamps) is uniform across variants. Variants: - `CRYPTO_PAYIN` → `details` is `TransactionCryptoPayinDetails` - `CRYPTO_PAYOUT` → `details` is `TransactionCryptoPayoutDetails` - `FIAT_PAYIN` → `details` is `TransactionFiatPayinDetails` - `FIAT_PAYOUT` → `details` is `TransactionFiatPayoutDetails` - `TRADE` → `details` is `TransactionTradeDetails` - `TRANSFER` → `details` is `TransactionTransferDetails` - `NXOSNET_TRANSFER` → `details` is `TransactionNxosnetTransferDetails` - `CREDIT_ADJUSTMENT` → `details` is `TransactionCreditAdjustmentDetails` - `COMMISSION` → `details` is `TransactionCommissionDetails` - `DEBIT_ADJUSTMENT` → `details` is `TransactionDebitAdjustmentDetails` Error400: type: object required: - error properties: error: $ref: '#/components/schemas/ErrorBody' description: Standard error response returned by all endpoints on failure. Error401: type: object required: - error properties: error: $ref: '#/components/schemas/ErrorBody' description: Standard error response returned by all endpoints on failure. example: error: code: missing_api_key message: 'Missing or invalid Authorization header. Expected: Bearer ' requestId: req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4 Error403: type: object required: - error properties: error: $ref: '#/components/schemas/ErrorBody' description: Standard error response returned by all endpoints on failure. Error404: type: object required: - error properties: error: $ref: '#/components/schemas/ErrorBody' description: Standard error response returned by all endpoints on failure. Error409: type: object required: - error properties: error: $ref: '#/components/schemas/ErrorBody' description: Standard error response returned by all endpoints on failure. Error422: type: object required: - error properties: error: $ref: '#/components/schemas/ErrorBody' description: Standard error response returned by all endpoints on failure. Error429: type: object required: - error properties: error: $ref: '#/components/schemas/ErrorBody' description: Standard error response returned by all endpoints on failure. example: error: code: rate_limited message: 'Rate limit exceeded: 1000 requests per minute. Retry in 23 seconds.' requestId: req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4 Error500: type: object required: - error properties: error: $ref: '#/components/schemas/ErrorBody' description: Standard error response returned by all endpoints on failure. example: error: code: internal_error message: An unexpected error occurred. requestId: req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4 CryptoPayinTransactionRecord: type: object required: - type - details properties: type: type: string enum: - CRYPTO_PAYIN details: $ref: '#/components/schemas/TransactionCryptoPayinDetails' allOf: - $ref: '#/components/schemas/TransactionBase' title: Crypto payin CryptoPayoutTransactionRecord: type: object required: - type - details properties: type: type: string enum: - CRYPTO_PAYOUT details: $ref: '#/components/schemas/TransactionCryptoPayoutDetails' allOf: - $ref: '#/components/schemas/TransactionBase' title: Crypto payout FiatPayinTransactionRecord: type: object required: - type - details properties: type: type: string enum: - FIAT_PAYIN details: $ref: '#/components/schemas/TransactionFiatPayinDetails' allOf: - $ref: '#/components/schemas/TransactionBase' title: Fiat payin FiatPayoutTransactionRecord: type: object required: - type - details properties: type: type: string enum: - FIAT_PAYOUT details: $ref: '#/components/schemas/TransactionFiatPayoutDetails' allOf: - $ref: '#/components/schemas/TransactionBase' title: Fiat payout TradeTransactionRecord: type: object required: - type - details properties: type: type: string enum: - TRADE details: $ref: '#/components/schemas/TransactionTradeDetails' allOf: - $ref: '#/components/schemas/TransactionBase' title: Trade TransferTransactionRecord: type: object required: - type - details properties: type: type: string enum: - TRANSFER details: $ref: '#/components/schemas/TransactionTransferDetails' allOf: - $ref: '#/components/schemas/TransactionBase' title: Transfer NxosnetTransferTransactionRecord: type: object required: - type - details properties: type: type: string enum: - NXOSNET_TRANSFER details: $ref: '#/components/schemas/TransactionNxosnetTransferDetails' allOf: - $ref: '#/components/schemas/TransactionBase' title: Nxosnet transfer CreditAdjustmentTransactionRecord: type: object required: - type - details properties: type: type: string enum: - CREDIT_ADJUSTMENT details: $ref: '#/components/schemas/TransactionCreditAdjustmentDetails' allOf: - $ref: '#/components/schemas/TransactionBase' title: Credit adjustment CommissionTransactionRecord: type: object required: - type - details properties: type: type: string enum: - COMMISSION details: $ref: '#/components/schemas/TransactionCommissionDetails' allOf: - $ref: '#/components/schemas/TransactionBase' title: Commission DebitAdjustmentTransactionRecord: type: object required: - type - details properties: type: type: string enum: - DEBIT_ADJUSTMENT details: $ref: '#/components/schemas/TransactionDebitAdjustmentDetails' allOf: - $ref: '#/components/schemas/TransactionBase' title: Debit adjustment ErrorBody: type: object required: - code - message - requestId properties: code: allOf: - $ref: '#/components/schemas/ErrorCode' description: Machine-readable error code. message: type: string description: Human-readable error message. requestId: type: string description: Unique identifier for this request, useful for debugging. TransactionCryptoPayinDetails: type: object required: - chainName - chainTransactionId - fromAddress - toAddress - blockHeight - blockTimestamp properties: chainName: type: string description: Chain identifier (e.g. `ETHEREUM_MAINNET`). chainTransactionId: type: string description: On-chain transaction hash. fromAddress: type: string nullable: true description: >- On-chain sender address. Null when not parseable from the chain event. toAddress: type: string description: Destination address (one of the customer's deposit addresses). blockHeight: type: integer format: int32 nullable: true description: Block height the transaction landed in. blockTimestamp: type: string allOf: - $ref: '#/components/schemas/dateTimeString' nullable: true description: On-chain block timestamp (distinct from the platform's `createdAt`). description: Crypto deposit details — the on-chain receipt that funded the account. TransactionBase: type: object required: - object - transactionId - accountId - status - description - tags - amount - asset - fee - requiredActions - createdAt - updatedAt properties: object: type: string enum: - transaction description: Object type. Always `transaction`. transactionId: type: string description: Unique transaction identifier. accountId: type: string description: >- Account this transaction belongs to. Always one of your organization's accounts (the listing query enforces ownership). status: allOf: - $ref: '#/components/schemas/TransactionStatus' description: Current status. See `TransactionStatus` for transitions. description: type: string nullable: true description: Optional human-readable description. tags: type: array items: type: string description: >- Free-form tags set at create time (e.g. `["crypto_payout", "ethereum_mainnet"]`). amount: type: string allOf: - $ref: '#/components/schemas/amount' nullable: true description: >- Primary amount in major units. For most types this is the amount the customer's account moved by. For TRADE this is null — trades have two distinct assets in play; see `details.from` and `details.to` instead. asset: type: string nullable: true description: >- Asset code of the primary amount. Null for TRADE — see `details.from` / `details.to`. fee: allOf: - $ref: '#/components/schemas/TransactionFee' description: >- Service-fee breakdown. Always populated; every component is zero when no service fee applied. Note: trade spread fees are NOT here — they live in `details.spread` on TRADE transactions. requiredActions: type: array items: $ref: '#/components/schemas/RequiredAction' description: >- What you must still provide. While `status` is `ACTION_REQUIRED`: the documents to upload. On a `LOCKED` fiat payout waiting for corrected details: one `beneficiary_details` action with the fields to correct. Empty otherwise. createdAt: allOf: - $ref: '#/components/schemas/dateTimeString' description: When the transaction was created (platform clock). updatedAt: allOf: - $ref: '#/components/schemas/dateTimeString' description: When the transaction was last updated. description: Common fields shared by every transaction variant. TransactionCryptoPayoutDetails: type: object required: - chainName - chainTransactionId - toAddress - beneficiaryId - blockHeight - blockTimestamp properties: chainName: type: string description: Chain identifier (e.g. `ETHEREUM_MAINNET`). chainTransactionId: type: string nullable: true description: >- On-chain transaction hash. Null while the payout is still in LOCKED state pre-broadcast. toAddress: type: string description: Destination address. beneficiaryId: type: string nullable: true description: Beneficiary the payout was sent to. blockHeight: type: integer format: int32 nullable: true description: Block height once confirmed. Null while still LOCKED. blockTimestamp: type: string allOf: - $ref: '#/components/schemas/dateTimeString' nullable: true description: On-chain block timestamp once confirmed. Null while still LOCKED. description: Crypto withdrawal details. TransactionFiatPayinDetails: type: object required: - method - fundingMethodId - senderName - senderAccount - senderBankName - senderBankCode - remittanceInformation properties: method: type: string description: Method (e.g. `WIRE`). fundingMethodId: type: string nullable: true description: Funding method this deposit landed on. senderName: type: string nullable: true description: Sender name as reported by the originating bank. senderAccount: type: string nullable: true description: Sender's account identifier (IBAN/account number). senderBankName: type: string nullable: true description: Sender's bank name. senderBankCode: type: string nullable: true description: Sender's bank SWIFT/BIC. remittanceInformation: type: string nullable: true description: Free-form remittance information attached to the wire. description: Fiat deposit (wire receipt) details. TransactionFiatPayoutDetails: type: object required: - beneficiaryId - method - bankName - swiftCode - accountNumber - iban - currency - country - swiftUetr properties: beneficiaryId: type: string description: Beneficiary the payout was sent to. method: type: string description: Method (e.g. `WIRE`). bankName: type: string description: Receiving bank name. swiftCode: type: string nullable: true description: Receiving bank SWIFT/BIC. accountNumber: type: string nullable: true description: Account number. iban: type: string nullable: true description: IBAN. currency: type: string description: Currency. country: type: string nullable: true description: Country code of the receiving bank. swiftUetr: type: string nullable: true description: >- SWIFT's end-to-end reference (UETR) for the wire, once the bank has sent it. This is the handle a correspondent bank recognises, so it is what lets you or your recipient trace the payment downstream. Null until the payout settles, and on rails that have no SWIFT leg. Once the payout is `COMPLETED` and this is set, the bank's SWIFT copy can be downloaded with `GET /v1/transactions/{transactionId}/swift-copy`. description: Fiat withdrawal (SWIFT wire) details. TransactionTradeDetails: type: object required: - from - to - spread - quoteId - appliedRate properties: from: allOf: - $ref: '#/components/schemas/Money' description: Source money — what the user spent. to: allOf: - $ref: '#/components/schemas/Money' description: Destination money — what the user received. spread: type: object allOf: - $ref: '#/components/schemas/Money' nullable: true description: >- Spread fee charged on this trade, in the source asset. Null when no spread applied. quoteId: type: string nullable: true description: >- Quote ID this trade was executed against. Null if the trade was created outside the quote flow. appliedRate: type: string nullable: true description: >- Applied conversion rate, as a decimal string (e.g. `"1.0850"` for EUR→USD). Always `from / to` in the natural direction. description: >- Trade (swap) details — currency conversion against the platform's quoted rate. Trades have two distinct assets in play, so amounts are nested as `Money` objects rather than flat `amount` + `asset` pairs: - `from` — what the user spent - `to` — what the user received - `spread` — fee charged for the trade (in the source asset) Note: the envelope-level `amount` and `asset` fields are NULL on trades — there's no single principal. Use `details.from` and `details.to` instead. The envelope-level `fee` (TransactionFee) is for service fees and stays zero on trades; the trade economics live entirely in `details.spread`. TransactionTransferDetails: type: object required: - transferType properties: transferType: type: string description: >- Subtype of internal transfer (free-form string, used by ops tooling). description: Internal transfer details (between accounts within the platform). TransactionNxosnetTransferDetails: type: object required: - beneficiaryId - targetHandle - targetOrganizationName - sourceHandle - sourceOrganizationName - note properties: beneficiaryId: type: string description: Beneficiary the transfer was sent to (sender side). targetHandle: type: string description: Recipient's NxosNet handle. targetOrganizationName: type: string nullable: true description: >- Recipient organization's display name. Null if the recipient has hidden their org name. sourceHandle: type: string nullable: true description: Sender's NxosNet handle (recipient side). sourceOrganizationName: type: string nullable: true description: >- Sender organization's display name. Null if the sender has hidden their org name. note: type: string nullable: true description: Free-form note attached to the transfer. description: >- NxosNet transfer details — instant handle-based transfer between platform users. TransactionCreditAdjustmentDetails: type: object required: - kind - reason properties: kind: allOf: - $ref: '#/components/schemas/CreditAdjustmentKind' description: Credit adjustment kind — analytics discriminator. reason: type: string description: Human-readable reason shown on the customer's transaction history. description: >- Credit adjustment details — ex-gratia credit issued by the platform (promo, apology, goodwill, correction). TransactionCommissionDetails: type: object required: - sourceTransactionId - referralLinkId - referredOrganizationId - referredOrganizationName - appliedCommissionBps properties: sourceTransactionId: type: string description: Source transaction (the trade that earned this commission). referralLinkId: type: string description: Referral link the commission was earned through. referredOrganizationId: type: string description: The org whose trade earned this commission (the referred org). referredOrganizationName: type: string description: Display name of the referred org. appliedCommissionBps: type: integer format: int32 description: >- Commission rate applied at payment time, in basis points (10000 = 100%). Snapshotted — survives later settings changes. description: Commission details — referral commission paid to a referrer. TransactionDebitAdjustmentDetails: type: object required: - kind - reason properties: kind: allOf: - $ref: '#/components/schemas/DebitAdjustmentKind' description: Debit adjustment kind — analytics discriminator. reason: type: string description: Human-readable reason shown on the customer's transaction history. description: >- Debit adjustment details — platform-initiated debit (the banking-statement "debit adjustment"). ErrorCode: type: string enum: - missing_api_key - authentication_failed - invalid_api_key - forbidden - acting_org_not_found - authorization_required - swap_direction_not_allowed - sub_org_tier_not_available - service_not_enabled - not_found - organization_not_found - account_not_found - quote_not_found - beneficiary_not_found - transaction_not_found - funding_method_not_found - authorization_not_found - nxosnet_handle_not_found - sub_org_tier_not_found - report_not_found - quote_expired - quote_already_used - beneficiary_already_archived - beneficiary_not_archived - beneficiary_blocked - transaction_blocked - transaction_not_held - beneficiary_fix_not_requested - fee_schedule_drifted - nxosnet_not_enabled - nxosnet_handle_taken - chain_send_failed - swift_copy_not_found - swift_copy_not_ready - bank_unavailable - verification_closed - idempotency_key_in_use - idempotency_request_in_flight - referral_invite_already_accepted - report_not_ready - too_many_pending_reports - invalid_request - insufficient_funds - trade_size_out_of_bounds - validation_error - invalid_document - too_many_documents - document_too_large - invalid_beneficiary_details - document_not_found - document_not_uploaded - share_token_invalid - verification_import_unsupported - verification_required - rate_limited - webhooks_unavailable - internal_error description: All possible error codes returned by the API. dateTimeString: type: string description: ISO 8601 timestamp string. TransactionStatus: type: string enum: - EXPECTED - ACTION_REQUIRED - LOCKED - COMPLETED - DECLINED - REFUNDED description: >- Transaction status. Async transactions (e.g. crypto payouts) progress LOCKED → COMPLETED via the cron confirmer; sync transactions land at COMPLETED directly. amount: type: string description: >- Monetary amount as a decimal string in major units (e.g., `"10.50"` for ten dollars and fifty cents). Amounts are always returned at the asset's native precision — for example, USDT amounts have 6 decimal places (`"10.500000"`). Clients should parse amounts as arbitrary-precision decimals, never as floating-point numbers, to avoid rounding errors. Internally, the platform stores all amounts as integer subunits and converts at the API boundary. TransactionFee: type: object required: - fixed - bps - bpsAmount - total - asset properties: fixed: allOf: - $ref: '#/components/schemas/amount' description: >- Flat component charged regardless of the principal. Zero when the schedule has no fixed component. bps: type: integer format: int32 description: >- Rate applied to the principal, in basis points (1 bp = 0.01%, so 50 bps = 0.5%). Zero when the schedule has no rate component. bpsAmount: allOf: - $ref: '#/components/schemas/amount' description: >- Rate-based component, derived from `bps` and the principal and rounded at charge time. Zero when `bps` is zero. total: allOf: - $ref: '#/components/schemas/amount' description: >- Total fee charged: `fixed + bpsAmount`. The single number surfaced to customers as "Fee". asset: type: string description: >- Asset code the fee is denominated in. Always matches the transaction's principal asset — fees are never FX-converted. description: >- Fee breakdown for a transaction. Always present on every transaction response; when no fee applies, every amount is zero and `bps` is zero. Construction: total = fixed + bpsAmount (the number the customer is charged on top of the principal) bpsAmount = round(principal × bps / 10_000) (the rate-based component, rounded at charge time) Fixed and rate components are independent — any combination of zero and non-zero is valid: - Flat fee only (e.g. SWIFT $50): fixed > 0, bps = 0, bpsAmount = 0 - Rate fee only (e.g. 50 bps): fixed = 0, bps > 0, bpsAmount > 0 - Combined: fixed > 0, bps > 0, bpsAmount > 0 - No fee: everything zero All `amount` fields are denominated in `asset` — the same asset as the transaction's principal. The `bps` value is the rate that was applied at charge time, preserved so clients can re-derive "what percentage was this?" without recomputing from fee ÷ principal. example: fixed: '50.00' bps: 0 bpsAmount: '0.00' total: '50.00' asset: USD RequiredAction: anyOf: - $ref: '#/components/schemas/DocumentRequiredAction' - $ref: '#/components/schemas/BeneficiaryDetailsRequiredAction' description: >- Something you must provide before the transaction can go on: a document for a held transaction, or the beneficiary details of a payout waiting to be sent. Money: type: object required: - amount - asset properties: amount: allOf: - $ref: '#/components/schemas/amount' description: Amount in major units (e.g. `"10.50"`). asset: type: string description: Asset code (e.g. `USDC`, `USD`, `EUR`). description: >- A monetary value paired with its asset code. Amount is in major units; parse as arbitrary-precision decimal, never as float. CreditAdjustmentKind: type: string enum: - PROMO - APOLOGY - GOODWILL - CORRECTION description: Reason category for a CREDIT_ADJUSTMENT. DebitAdjustmentKind: type: string enum: - ACCOUNT_CLOSURE - CORRECTION - OTHER description: Reason category for a DEBIT_ADJUSTMENT. DocumentRequiredAction: type: object required: - type - holdId properties: type: allOf: - $ref: '#/components/schemas/RequirementType' description: The document type to upload. holdId: type: string description: The hold this document is for. description: A document you must upload before a held transaction can be reviewed. title: Document BeneficiaryDetailsRequiredAction: type: object required: - type - fixRequestId - fields - note properties: type: type: string enum: - beneficiary_details description: Always `beneficiary_details`. fixRequestId: type: string description: The correction request this action answers. fields: type: array items: $ref: '#/components/schemas/BeneficiaryFixField' description: The fields to correct. Only these are read from your answer. note: type: string description: What operations ask you to correct, in their words. description: >- Operations need corrected beneficiary details on a `LOCKED` fiat payout, before sending it or after the bank refused them. The amount is already debited and stays reserved; send the corrected `fields` to `POST /v1/transactions/{transactionId}/beneficiary-details`, then operations send the payout. title: Beneficiary details example: type: beneficiary_details fixRequestId: pfix_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4 fields: - iban note: >- Our bank needs the recipient's IBAN for UK payouts. Please add it exactly as it appears on their bank statement. RequirementType: type: string enum: - invoice - source_of_funds - counterparty_details description: A document type a held transaction can require. BeneficiaryFixField: type: string enum: - iban - accountNumber - swiftCode - bankName - beneficiaryName - addressLine1 - city - country description: |- A beneficiary field to correct. `beneficiaryName` is `firstName` and `lastName` for an individual, `businessName` for a business. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.