> ## Documentation Index > Fetch the complete documentation index at: https://docs2.finverse.com/llms.txt > Use this file to discover all available pages before exploring further. # Cancel payout > Cancel Payout by payout_id ## OpenAPI ````yaml /api-reference/openapi.json post /payouts/{payoutId}/cancel openapi: 3.0.0 info: description: Documentation of the early finverse services title: Finverse Public termsOfService: https://example.com contact: name: Maintainers email: info@finverse.com license: name: unknown license version: 0.0.1 servers: - url: https://api.prod.finverse.net security: - Oauth2: - test tags: - name: public description: Publicly accessible endpoints x-group: Public - name: customer description: Customer app and institution endpoints x-group: Customer - name: link description: Finverse Link flows x-group: Link - name: login_identity description: Login identity lifecycle and metadata x-group: Login identity - name: accounts description: Accounts, balances, and account numbers x-group: Accounts - name: statements description: Statements and composite statements x-group: Statements - name: transactions description: Transaction history x-group: Transactions - name: identity_income description: Identity and income insights x-group: Identity & income - name: payment_links description: Payment link creation and checkout x-group: Payment links - name: mandates description: Direct debit mandates x-group: Mandates - name: payments description: Payment initiation and status x-group: Payment operations - name: payouts description: Payouts and scheduled payouts x-group: Payouts - name: payment_users description: Payment user profiles x-group: Payment users - name: payment_accounts description: Payment accounts for users x-group: Payment accounts - name: payment_methods description: Stored payment methods x-group: Payment methods - name: bills description: Bill presentment x-group: Bills - name: disputes description: Payment disputes x-group: Disputes - name: ledger description: Ledger and statements x-group: Ledger paths: /payouts/{payoutId}/cancel: post: tags: - payouts summary: Cancel payout description: Cancel Payout by payout_id operationId: cancelPayout parameters: - description: payout id name: payoutId in: path required: true schema: type: string responses: '200': description: ok content: application/json: schema: $ref: '#/components/schemas/PayoutSnapshotResponse' '400': description: Invalid Request content: application/json: schema: $ref: '#/components/schemas/ErrBodyModelV2' security: - Oauth2: - payout:cancel components: schemas: PayoutSnapshotResponse: required: - live properties: amount: type: integer description: Amount of the payout (in minor currency unit) created_at: type: string format: date-time description: Timestamp when the payout was first created currency: type: string description: Currency of the payout (e.g. HKD) error: $ref: '#/components/schemas/FvEmbeddedErrorModel' description: >- Details on why the payout failed (returned when `status` = `FAILED`). Note: this is used to detail any asynchronous e errors occuring after payout creation; any synchronous errors (e.g. API validation errors, real-time payout errors) will instead be returned directly during `POST /payouts`. fees: type: array items: $ref: '#/components/schemas/Fee' description: Details on the fee(s) to be charged live: description: >- Flag to indicate whether the payment is a test transaction (i.e. from/to a test bank, `live=false`) or a live transaction (i.e. from/to a real bank, `live=true`). type: boolean metadata: description: >- Customer-supplied attributes in key:value format. E.g. `employer_name`: `Apple Inc` type: object additionalProperties: type: string payment_details: $ref: '#/components/schemas/PayoutSnapshotDetails' description: Details on the payout payout_id: type: string description: >- Finverse Payout ID for this payout. Always unique. Creating a payout with different idempotency keys will result in two payouts with different IDs. recipient: $ref: '#/components/schemas/GetMandateSender' description: >- Details on the recipient of the payout Note: In some cases when the payout has been executed by a 3rd party payment gateway, the recipient may not be known. recipient_account: $ref: '#/components/schemas/MandateSenderAccount' description: >- Details on the account receiving the payout Note: In some cases when the payout has been executed by a 3rd party payment gateway, the recipient account may not be known. sender: $ref: '#/components/schemas/MandateRecipient' description: Details on the sender of the payout sender_account: $ref: '#/components/schemas/MandateRecipientAccount' description: >- Details on the Sender's account at Finverse (i.e. the Customer App's settlement account at Finverse) status: type: string enum: - EXECUTED - CREATED - PROCESSING - PROCESSING_FUNDS - CANCELLED - FAILED - FUNDED - SUBMITTED description: >- Current status of the payout. Possible values: `CREATED`, `FUNDED`, `PROCESSING`, `SUBMITTED, EXECUTED`, `CANCELLED`, `FAILED` transaction_date: type: string description: \[DEPRECATED\] Transaction date transaction_time: type: string format: date-time example: '2025-08-22T12:00:00Z' nullable: true description: >- Date/time at which the payout was confirmed as executed. The actual settlement date/time of the payout may be different. In addition, a payout may be recorded at different times on the bank accounts of the sender vs. the recipient. Note: in some cases, the transaction date will be known, but the specific transaction time may not be known. In these cases, the transaction time will be listed as `YYYY-MM-DDT00:00:00Z` (or another fixed time value). type: type: string enum: - MANUAL - SCHEDULED - SETTLEMENT description: >- Specified payout type. Possible values: `MANUAL`, `SCHEDULED`, `SETTLEMENT` updated_at: type: string format: date-time description: Timestamp of the last update to the payout's record ErrBodyModelV2: properties: error: $ref: '#/components/schemas/FvErrorModelV2' FvEmbeddedErrorModel: required: - type - error_code - message - details properties: details: type: string error_code: type: string example: CREDENTIALS_INVALID message: type: string type: description: The error type type: string enum: - LINK_ERROR - API_ERROR example: LINKING_ERROR Fee: required: - amount properties: amount: description: Amount of the fee (in minor currency unit) type: integer example: 100 currency: type: string example: HKD description: Currency of the fee (e.g. HKD) paid_by: type: string enum: - RECIPIENT - SENDER example: RECIPIENT description: >- Party who will be charged the fee. Possible values: `RECIPIENT`, `SENDER` paid_by_account_id: description: >- Finverse Payment Account ID of the party who will be charged the fee. This references the `account_id` of either the `recipient_account` or the `sender_account`. type: string example: The payment account ID PayoutSnapshotDetails: properties: description: type: string description: >- User-facing description for the payout transaction. SWIFT character set includes the following characters: alphanumeric, space, and symbols `/ - ? : ( ) . , ' +` estimated_arrival_time: type: string format: date-time example: '2025-08-22T12:00:00Z' nullable: true description: >- Estimated date/time the payout funds will land in the recipient's account (when available). mandate_id: type: string description: >- `mandate_id` from mandates object. Indicates which direct debit mandate should be used to fund the payout. processor_details: $ref: '#/components/schemas/PayoutProcessorDetails' description: Details on the payment processor for the payout references: $ref: '#/components/schemas/PayoutReferences' scheduled_date: type: string format: date-time nullable: true description: >- Scheduled date when the payout should be executed. Required when payout `type` = `SCHEDULED`. transaction_reference_id: type: string description: >- User-facing transaction reference ID for the payout transaction, generated by Finverse. This value will typically be provided to banks executing the payout and may be displayed on the recipient's bank statement. GetMandateSender: required: - user_id - external_user_id - user_type properties: external_user_id: description: >- Customer App's user ID, representing the end-user making the payment. type: string name: type: string user_details: description: Sender details which will be used for fraud checking. type: array items: $ref: '#/components/schemas/SenderDetail' user_id: description: A unique identifier generated after creating sender type: string user_type: description: >- Type of account held by the Sender at the Institution. Possible values are INDIVIDUAL, BUSINESS type: string enum: - INDIVIDUAL - BUSINESS MandateSenderAccount: type: object properties: account_id: description: A unique identifier generated after creating sender account type: string example: sender_account_id account_number: $ref: '#/components/schemas/RecipientAccountNumber' description: Bank account number details, including account number in plaintext account_number_masked: description: Masked Account number of the sender’s account type: string account_type: description: Type of sender account. type: string enum: - EXTERNAL_ACCOUNT example: EXTERNAL_ACCOUNT accountholder_name: description: Tokenized accountholder name of the sender's account type: string example: 01EP4A1MZDHKETZFRPF0K62S6S accountholder_name_plaintext: description: Accountholder name in plaintext. type: string example: Chan Li Pak nullable: true bank_code: type: string institution_id: description: Finverse Institution ID for the sender’s institution. type: string example: hsbc-hk institution_name: description: Institution Name for the sender’s institution. type: string example: HSBC metadata: description: >- Additional attributes of the sender account in key:value format (e.g. sender_id: 1234). It supports up to 10 key:value pairs, whereas the key and value supports up to 50 and 1000 characters respectively. type: object additionalProperties: type: string user_id: description: >- A unique identifier generated after creating sender (Finverse Payment User ID) type: string example: 01GY6H0JA7BS8EVGY56NSHFX2E MandateRecipient: required: - name properties: name: description: Merchant account name type: string MandateRecipientAccount: required: - account_id - account_type properties: account_id: description: Merchant account ID assigned by Finverse type: string account_type: description: Type of recipient account. type: string enum: - EXTERNAL_ACCOUNT - SETTLEMENT_ACCOUNT example: SETTLEMENT_ACCOUNT FvErrorModelV2: required: - type - error_code - message - details - request_id properties: details: type: string error_code: type: string example: CREDENTIALS_INVALID message: type: string request_id: description: The request_id provided in the request header type: string type: description: The error type type: string enum: - LINK_ERROR - API_ERROR example: LINKING_ERROR PayoutProcessorDetails: properties: processor_id: type: string description: 'ID of the payment processor for the payout. Possible values: ADYEN' processor_reference: type: string description: Payment processor's internal reference for the payout PayoutReferences: properties: recipient_reference: type: string SenderDetail: properties: details_type: description: >- Type of the user identity information submitted. Possible values: `HK_ID`, `PASSPORT`, `HK_BUSINESS_REGISTRATION`, `HK_CERTIFICATE_OF_INCORPORATION`, `ACCOUNTHOLDER_NAME` type: string enum: - HK_ID - PASSPORT - HK_BUSINESS_REGISTRATION - HK_CERTIFICATE_OF_INCORPORATION values: description: >- Value(s) of the user identity information submitted. Min 1 value required, max 10 values. Values in responses are tokenized by Finverse. type: array maxItems: 10 items: type: string RecipientAccountNumber: type: object required: - type - number properties: number: description: >- Account number. Account numbers in responses are tokenized by Finverse. type: string maxLength: 100 minLength: 1 number_plaintext: description: Account number in plaintext type: string maxLength: 100 minLength: 1 nullable: true type: description: 'Type of account number format. Possible values: `IBAN`, `LOCAL`' type: string enum: - LOCAL - IBAN securitySchemes: Oauth2: type: oauth2 flows: clientCredentials: tokenUrl: https://finverse-dev.us.auth0.com/oauth/token scopes: account: Account balance: Balance credit: Credit institution: Institution investment: Investment link: Link test: Test transaction: Transaction ````