> ## Documentation Index > Fetch the complete documentation index at: https://docs.superbank.co/llms.txt > Use this file to discover all available pages before exploring further. # Update settlement request status > Update the status of a settlement request. Use status=PROCESSING to initiate the OUTBOUND payment. Use status=COMPLETED with txHash to complete with reconciliation. Use status=CANCELED to cancel the request. ## OpenAPI ````yaml /openapi/v0/openapi.json put /v0/settlement-requests/{id} openapi: 3.0.0 info: title: Superbank API description: Superbank Developer API for Instant Settlement version: '1.0' contact: {} servers: - url: https://api-sandbox.superbank.co description: Sandbox security: [] tags: [] paths: /v0/settlement-requests/{id}: put: tags: - Settlement Requests summary: Update settlement request status description: >- Update the status of a settlement request. Use status=PROCESSING to initiate the OUTBOUND payment. Use status=COMPLETED with txHash to complete with reconciliation. Use status=CANCELED to cancel the request. operationId: SettlementRequestsController_update parameters: - name: id required: true in: path description: The unique identifier of the settlement request schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateSettlementRequestDto' responses: '200': description: Settlement request updated content: application/json: schema: $ref: '#/components/schemas/SettlementRequestResponseDto' '400': description: Bad request or invalid status transition '404': description: Settlement request not found security: - api-key: [] components: schemas: UpdateSettlementRequestDto: type: object properties: status: type: string description: The status to update the settlement request to enum: - FUNDS_SENT - REQUEST_COMPLETED - REQUEST_CANCELED - PAYIN_CANCELED - PAYIN_UNDER_REVIEW - PAYIN_FAILED - PAYIN_AMOUNT_MISMATCH example: FUNDS_SENT external_id: type: string description: >- An identifier of your choice for this settlement. Same field as `external_id` on create — provided here for clients that set the identifier at FUNDS_SENT time rather than on create. example: order_abc123 maxLength: 255 transaction_id: type: string deprecated: true description: >- **Deprecated — removal: 2026-05-25.** Use `external_id` instead. Both fields map to the same underlying value; if both are sent, `external_id` wins. example: your_trx_123 transaction_hash: type: string description: >- The transaction hash that will be associated with the settlement request example: 5K8z2tF3mN9pQrS4uV6wX7yZ1aB2cD3eF4gH5iJ6kL7m8N9oP0qR1sT2uV3wX4yZ5a required: - status SettlementRequestResponseDto: type: object properties: id: type: string description: The unique identifier of the settlement request example: d4e5f6a7-b8c9-4d0e-a1f2-3b4c5d6e7f8a type: type: string description: The type of settlement request example: FIAT_TO_STABLECOIN enum: - STABLECOIN_TO_STABLECOIN - FIAT_TO_STABLECOIN - STABLECOIN_TO_FIAT - FIAT_TO_FIAT payment_reason: type: string description: Reason for the payment; internal for the sender enum: - CAPITAL_CONTRIBUTIONS - CHARITABLE_CONTRIBUTIONS - CONSULTING_FEES - CORPORATE_TAX_PAYMENTS - DOWN_PAYMENTS_FOR_REAL_ESTATE - EDUCATION_FEES - EMPLOYEE_SALARIES_OR_WAGES - EXPENSES_REIMBURSEMENT - GIFTS - GOVERNMENT_GRANTS - INCOME_TAX_PAYMENTS - INHERITANCE_PAYMENTS - INSURANCE_CLAIM_PAYOUTS - INSURANCE_PREMIUM_PAYMENTS - INVESTMENTS - LOAN_ADVANCES - MORTGAGE_PAYMENTS - OTHER - PAYMENT_FOR_GOODS_AND_SERVICES - PERSONAL_TRANSFERS - REAL_ESTATE_PURCHASES - REMITTANCES - RENT - REPAYMENT_OF_LOANS - ROYALTIES - TRUST_FUND_DISTRIBUTIONS - UTILITY_BILLS - WELFARE_OR_BENEFITS - WINNINGS_AND_PRIZES example: REMITTANCES status: type: string description: The current lifecycle status of the settlement request enum: - REQUEST_STARTED - REQUEST_EXPIRED - REQUEST_CANCELED - REQUEST_COMPLETED - REQUEST_REFUNDED - FUNDS_SENT - FUNDS_RECEIVING_LATE - SETTLEMENT_SENT - SETTLEMENT_COMPLETED - PAYIN_CANCELED - PAYIN_UNDER_REVIEW - PAYIN_FAILED - PAYIN_AMOUNT_MISMATCH - PAYOUT_CANCELED - PAYOUT_UNDER_REVIEW - PAYOUT_FAILED example: REQUEST_STARTED amount: type: string description: The amount of the settlement request example: '99.00' external_id: type: object description: >- An identifier you supplied for this settlement (e.g. your internal order id). Filterable via `GET /v0/settlement-requests?external_id=...`. example: order_abc123 nullable: true metadata: type: object description: >- Free-form key/value pairs you supplied for correlation. Up to 50 string keys (≤40 chars) with string values (≤500 chars). Echoed on every read and webhook; not filterable. example: restaurant_id: rest_42 source: web additionalProperties: type: string nullable: true transaction_id: type: object deprecated: true description: >- **Deprecated — removal: 2026-05-25.** Use `external_id`. Same value, kept for compatibility until the removal date. example: your_trx_123 nullable: true source: description: The source details (for off-ramp) nullable: true type: object allOf: - $ref: '#/components/schemas/SourceResponseDto' destination: type: object description: The destination details for the settlement payment_instructions: description: Instructions describing the inbound payment allOf: - $ref: '#/components/schemas/PaymentInstructionsResponseDto' outbound_payment: description: The outbound payment from the pre-funded wallet to the destination nullable: true type: object allOf: - $ref: '#/components/schemas/PaymentSummaryResponseDto' inbound_payment: description: The inbound payment received from an external source nullable: true type: object allOf: - $ref: '#/components/schemas/PaymentSummaryResponseDto' created_at: type: string description: The timestamp when the settlement request was created example: '2026-01-20T15:17:12.805Z' updated_at: type: string description: The timestamp of the most recent update example: '2026-01-20T15:20:00.000Z' processing_at: type: object description: The timestamp when processing began example: '2026-01-20T15:20:00.000Z' nullable: true completed_at: type: object description: The timestamp when completed example: '2026-01-20T15:25:00.000Z' nullable: true reconciliation_expected_at: type: object description: The timestamp when funds are expected to reconcile example: '2026-01-23T15:20:00.000Z' nullable: true failure_code: type: string description: Structured failure code for programmatic handling enum: - AMOUNT_MISMATCH_UNDERPAYMENT - AMOUNT_MISMATCH_OVERPAYMENT example: AMOUNT_MISMATCH_UNDERPAYMENT nullable: true failure_reason: type: object description: Human-readable failure reason example: 'Amount mismatch: expected 100.00, received 90.00' nullable: true required: - id - type - payment_reason - status - amount - destination - payment_instructions - created_at - updated_at SourceResponseDto: type: object properties: currency: type: string description: The currency of the source funds example: USDC rail: type: string description: The payment rail of the source example: SOLANA wallet_address: type: string description: The wallet address of the source (end-user wallet) example: '0x388C818CA8B9251b393131C08a736A67ccB19297' required: - currency - rail - wallet_address PaymentInstructionsResponseDto: type: object properties: amount: type: string description: >- The amount to send for the inbound payment. For STABLECOIN_TO_FIAT this is the exact crypto amount the end-user must deposit (computed from the destination amount plus fees). example: '729.16' currency: type: string description: The currency of the inbound payment (e.g. USDC, USDT, USD) example: USDC rail: type: string description: The rail of the inbound payment (e.g. SOLANA, TRON, RTP) example: SOLANA wallet_address: type: string description: >- The wallet address for crypto funding. For STABLECOIN_TO_FIAT this is a per-payment deposit wallet — send `amount` of `currency` here. Valid until `valid_until`. example: FRNthe6oqA8fhVMfXMM12rGmFYvejtkmH3bRfYBxWnLB chain: type: string description: The blockchain network for crypto funding example: SOLANA bank_name: type: string description: The bank name for fiat funding (for on-ramp with SUPERBANK) example: JPMorgan Chase account_number: type: string description: The account number for fiat funding example: '123456789' routing_number: type: string description: The routing number for fiat funding example: '021000021' deposit_message: type: string description: >- The deposit message / reference the end-user must include on the bank transfer so the deposit can be matched to this settlement. Missing or altered messages may cause the deposit to be returned. example: SB-39760060 valid_until: type: string description: The timestamp until which the payment instructions remain valid example: '2026-01-20T15:22:12.805Z' destination_amount: type: string description: >- STABLECOIN_TO_FIAT only — the amount delivered to the destination bank account in `destination_currency`. Echoes the requested amount. example: '1000.00' destination_currency: type: string description: STABLECOIN_TO_FIAT only — destination fiat currency example: CAD exchange_rate: type: string description: >- STABLECOIN_TO_FIAT only — locked mid-market rate (destination units per one source unit). example: '1.3788512205' fee: type: object description: >- Combined fee for this settlement. `fixed` is denominated in `currency` (e.g. USDC). `variable` is a fraction (0.005 = 0.5%). `total` is the absolute fee actually charged in `currency` — the cent-rounded figure that reconciles with the deposit amount. example: fixed: 1 variable: 0.005 total: 6 required: - currency - rail - valid_until PaymentSummaryResponseDto: type: object properties: id: type: string description: The unique identifier of the payment example: d4e5f6a7-b8c9-4d0e-a1f2-3b4c5d6e7f8a type: type: string description: The type of payment enum: - PAYIN - PAYOUT example: PAYOUT status: type: string description: The status of the payment enum: - AWAITING_FUNDS - EXPIRED - PENDING - PROCESSING - SENT - COMPLETED - CANCELLED - FAILED - REFUNDED - SCHEDULED - UNDER_REVIEW example: PROCESSING amount: type: string description: The amount of the payment example: '99.00' currency: type: string description: The currency of the payment example: USDC created_at: type: string description: The timestamp when the payment was created example: '2026-01-20T15:20:00.000Z' required: - id - type - status - amount - currency - created_at securitySchemes: api-key: type: apiKey in: header name: X-Api-Key ````