Skip to main content
POST
/
payment-requests
/
{paymentRequestId}
/
reversal
Reverse a payment request
curl --request POST \
  --url https://api.venlyfinance.com/v1/payment-requests/{paymentRequestId}/reversal \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "reason": "CUSTOMER_CANCELLATION",
  "description": "Customer requested cancellation",
  "idempotencyKey": "1b4e28ba-2fa1-11d2-883f-0016d3cca427"
}
'
{
  "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"
  }
}
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
To reverse a request by its card-provider reference instead of its ID, use reverse by reference.

Authorizations

Path Parameters

paymentRequestId
string<uuid>
required

Unique payment request identifier

Body

application/json
reason
enum<string>
required

Why a payment request was reversed (recorded for audit).

Available options:
CUSTOMER_CANCELLATION,
MERCHANT_VOID,
ACQUIRER_FAILURE,
NETWORK_DECLINE,
OTHER
idempotencyKey
string
required

Unique key to prevent duplicate operations on retry

Maximum string length: 255
description
string

Optional free-text reason for the reversal

Maximum string length: 1000

Response

Reversal accepted; on-chain processing is asynchronous

success
boolean

Indicates whether the request was successful

result
object