> ## Documentation Index > Fetch the complete documentation index at: https://docs.venlyfinance.com/llms.txt > Use this file to discover all available pages before exploring further. # Reverse a payment request > Unwind a reserved payment request and return all escrowed funds to the account. Reverses a reserved payment request, returning the full escrow balance to the account wallet through a `REVERSAL` execution. The call returns `202 Accepted` with `status: REVERSING`, and the request becomes `REVERSED` — a final state — once the transfer confirms on-chain. Pass a `reason` (`CUSTOMER_CANCELLATION`, `MERCHANT_VOID`, `ACQUIRER_FAILURE`, `NETWORK_DECLINE`, or `OTHER`); it's recorded on the request. Send a unique `idempotencyKey`; repeating the same key and body returns the original result. **Concept guide:** [Payment requests](/guides/finance/payment-requests) To reverse a request by its card-provider reference instead of its ID, use [reverse by reference](/api-reference/Finance-API/payment-requests/reverse-a-payment-request-by-reference). ## OpenAPI ````yaml api-reference/Finance-API-Specs.yaml POST /payment-requests/{paymentRequestId}/reversal openapi: 3.1.0 info: title: Venly Finance API description: > REST API for the Venly Finance platform: - Party management (Individuals & Organisations) - Account management with party association - Wallet balances & token allowances on supported chains (Base, Avalanche) - Virtual bank account assignment for global payments (EUR SEPA) - Fiat-to-crypto payment sessions (pay-in) - Account-to-account fiat & crypto transfers - EIP-2612 permits and payment requests ## Authentication All endpoints use OAuth2 client credentials. Obtain a token first, then include it in every request: **Step 1 — Get a token:** ```bash curl -X POST https://login.venly.io/auth/realms/VenlyFinance/protocol/openid-connect/token \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "grant_type=client_credentials&client_id={CLIENT_ID}&client_secret={CLIENT_SECRET}" ``` **Step 2 — Use the token:** ``` Authorization: Bearer {access_token} ``` Tokens expire after **5 minutes**. Implement refresh logic in your client. version: 1.1.0 contact: name: Venly Support email: support@venly.io url: https://docs.venlyfinance.com license: name: Proprietary x-logo: url: https://venlyfinance.com/logo.png x-security-contact: security@venly.io servers: - url: https://api.venlyfinance.com/v1 description: Production - url: https://api-staging.venlyfinance.com/v1 description: Staging security: - OAuth2: [] tags: - name: Parties description: Party management (Individuals & Organisations) - name: Accounts description: Account management, party-role associations - name: Wallets description: Blockchain wallet balances - name: Virtual Bank Accounts description: Virtual bank account payment references for global payments - name: Fiat-to-crypto Payment Sessions description: Fiat-to-crypto payment session creation - name: Payment Requests description: Payment request management for card provider integrations - name: Transfers description: Fiat and crypto transfer operations between accounts - name: Permits description: EIP-712 permit signature management for token approvals - name: Allowances description: Token allowance management for wallets paths: /payment-requests/{paymentRequestId}/reversal: post: tags: - Payment Requests summary: Reverse a payment request description: > Unwinds a payment request and returns the entire escrow balance to the account wallet. The call returns `status: REVERSING` with a `PENDING` `REVERSAL` execution; the request becomes `REVERSED` once that transfer confirms on-chain. `REVERSED` is a final state, and `reason` is recorded on the request. Pass a unique `idempotencyKey`. Sending the same key with the same body again returns the original result. operationId: reversePaymentRequest parameters: - $ref: '#/components/parameters/PaymentRequestId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ReversePaymentRequestInput' example: reason: CUSTOMER_CANCELLATION description: Customer requested cancellation idempotencyKey: 1b4e28ba-2fa1-11d2-883f-0016d3cca427 responses: '202': description: Reversal accepted; on-chain processing is asynchronous content: application/json: schema: $ref: '#/components/schemas/SinglePaymentRequestResponse' example: success: true result: id: d4e5f6a7-b8c9-4012-8345-6789abcdef01 accountId: b2a1f0e9-8c7d-4e3a-9f21-0a1b2c3d4e5f amount: fiat: 25 crypto: '25.000000' currency: USD status: REVERSING reversalReason: CUSTOMER_CANCELLATION reversalDescription: Customer requested cancellation executions: - id: b8c9d0e1-f2a3-4456-c789-abcdef012345 walletPairId: f6a7b8c9-d0e1-4234-a567-89abcdef0123 type: REVERSAL chain: BASE asset: USDC amount: 25 exchangeRate: 1 status: PENDING createdAt: '2026-01-15T10:05:00Z' updatedAt: '2026-01-15T10:05:00Z' createdAt: '2026-01-15T09:30:00Z' updatedAt: '2026-01-15T10:05:00Z' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/InternalServerError' components: parameters: PaymentRequestId: name: paymentRequestId in: path required: true description: Unique payment request identifier schema: type: string format: uuid example: d4e5f6a7-b8c9-4012-8345-6789abcdef01 schemas: ReversePaymentRequestInput: type: object required: - reason - idempotencyKey properties: reason: $ref: '#/components/schemas/ReversalReason' description: type: string maxLength: 1000 description: Optional free-text reason for the reversal idempotencyKey: type: string maxLength: 255 description: Unique key to prevent duplicate operations on retry SinglePaymentRequestResponse: allOf: - $ref: '#/components/schemas/BaseResponse' - type: object properties: result: $ref: '#/components/schemas/PaymentRequest' ReversalReason: type: string description: Why a payment request was reversed (recorded for audit). enum: - CUSTOMER_CANCELLATION - MERCHANT_VOID - ACQUIRER_FAILURE - NETWORK_DECLINE - OTHER BaseResponse: type: object properties: success: type: boolean description: Indicates whether the request was successful PaymentRequest: type: object properties: id: type: string format: uuid accountId: type: string format: uuid amount: $ref: '#/components/schemas/PaymentRequestAmount' originalAmount: $ref: '#/components/schemas/PaymentRequestAmount' settlementAmount: $ref: '#/components/schemas/PaymentRequestAmount' settledAmount: $ref: '#/components/schemas/PaymentRequestAmount' shortfallAmount: $ref: '#/components/schemas/PaymentRequestAmount' currency: type: string externalId: type: string description: type: string status: $ref: '#/components/schemas/PaymentRequestStatus' settledAt: type: string format: date-time description: >- When settlement completed (terminal SETTLED / SETTLED_WITH_SHORTFALL) reversalReason: $ref: '#/components/schemas/ReversalReason' reversalDescription: type: string description: Optional free-text reason supplied on reversal reversedAt: type: string format: date-time description: When the reversal completed executions: type: array items: $ref: '#/components/schemas/PaymentExecution' createdAt: type: string format: date-time updatedAt: type: string format: date-time ErrorResponse: type: object description: Error response wrapper properties: success: type: boolean description: Always false for error responses example: false errors: type: array description: List of errors that occurred items: $ref: '#/components/schemas/ErrorBody' result: type: object nullable: true description: Null or omitted when success is false PaymentRequestAmount: type: object description: >- Payment amount, expressed in both the request fiat currency and the settled crypto amount. `amount` is the request's current value; `originalAmount` preserves the value at creation time (the two can diverge after an adjustment). properties: fiat: type: number description: Amount in the request `currency` (e.g. USD) crypto: type: string description: Settled crypto amount as a decimal string (e.g. USDC) PaymentRequestStatus: type: string description: Status of a payment request enum: - PENDING - RESERVED - SETTLING - SETTLED - SETTLED_WITH_SHORTFALL - REVERSING - REVERSED - FAILED PaymentExecution: type: object description: A single on-chain settlement attempt for a payment request properties: id: type: string format: uuid walletPairId: type: string format: uuid type: $ref: '#/components/schemas/PaymentExecutionType' chain: $ref: '#/components/schemas/BlockchainNetwork' asset: type: string amount: type: number exchangeRate: type: number status: $ref: '#/components/schemas/PaymentExecutionStatus' transactionHash: type: string errorMessage: type: string createdAt: type: string format: date-time updatedAt: type: string format: date-time ErrorBody: type: object description: Individual error details properties: code: type: string description: Machine-readable error code example: invalid-request message: type: string description: Human-readable error message example: The request contains invalid parameters. PaymentExecutionType: type: string description: The role an execution plays in a payment request's lifecycle. enum: - AUTHORIZATION - INCREMENTAL_AUTHORIZATION - AUTHORIZATION_ADJUSTMENT - SETTLEMENT - SETTLEMENT_OVERAGE - REFUND - REVERSAL BlockchainNetwork: type: string description: Supported blockchain network enum: - AVALANCHE - BASE - POLYGON PaymentExecutionStatus: type: string description: Status of a single payment-request execution enum: - PENDING - RESERVED - SETTLED - REVERSED - FAILED responses: BadRequest: description: Request validation failed (400) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false errors: - code: invalid-request message: The request contains invalid parameters. Unauthorized: description: Authentication required or failed (401) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false errors: - code: unauthenticated message: Please authenticate to perform this action. Forbidden: description: Caller lacks the required authority/role (403) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false errors: - code: forbidden message: You do not have permission to access this resource. NotFound: description: Resource not found (404) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false errors: - code: account-not-found message: The requested resource was not found. Conflict: description: Resource conflict / optimistic-lock failure (409) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false errors: - code: concurrent-modification message: >- This request has been modified by another user. Please refresh and try again. UnprocessableEntity: description: >- Idempotency conflict — the key was reused with a different body, or replays an operation that originally failed (422) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false errors: - code: idempotency-conflict message: >- This idempotency key was already used with a different request. InternalServerError: description: Unexpected server error (500) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false errors: - code: internal-error message: An unexpected error occurred. Please try again later. securitySchemes: OAuth2: type: oauth2 description: > OAuth2 client credentials flow. Token endpoints: - Staging: https://login-staging.venly.io/auth/realms/VenlyFinance/protocol/openid-connect/token - Production: https://login.venly.io/auth/realms/VenlyFinance/protocol/openid-connect/token flows: clientCredentials: tokenUrl: >- https://login-staging.venly.io/auth/realms/VenlyFinance/protocol/openid-connect/token scopes: {} ````