> ## Documentation Index > Fetch the complete documentation index at: https://developers.stablepay.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create Reversal > Submit a reversal claim against a succeeded payout that the recipient has reversed. Submitting a second claim for the same payout returns the existing one. ## OpenAPI ````yaml POST /v1/reversals openapi: 3.0.3 info: title: Stablepay Money API description: > The Stablepay Money API enables wallet issuers to execute stablecoin-to-fiat payouts across Sub-Saharan Africa via M-Pesa, mobile money, and bank transfers. version: 0.5.0 contact: name: Stablepay Engineering email: hello@stablepay.io servers: - url: https://api.stablepay.ai description: Production security: - BearerAuth: [] tags: - name: Health description: Service liveness check. - name: FX description: Live FX rate conversion between USDC and local fiat currencies. - name: Payments description: Submit and track stablecoin-to-fiat payout requests. - name: Balances description: >- Live on-chain USDC and native token balances for the tenant's custody wallets. - name: Analytics description: >- Pre-aggregated payment analytics — volume, success rates, corridor breakdowns, and daily time series. - name: Reversals description: Reversals of succeeded payouts. - name: Customers description: | KYC API for DeFi wallets. Onboard and verify your end-users, then link their wallet addresses so verified identity travels with their on-chain activity. - name: Webhooks description: Register endpoints and manage outbound event delivery. - name: Admin description: >- Ops-only endpoints for tenant management and payment operations. Requires an admin-scoped API key. paths: /v1/reversals: post: tags: - Reversals summary: Request a reversal description: > Submit a reversal claim against a succeeded payout that the recipient has reversed. Submitting a second claim for the same payout returns the existing one. operationId: requestReversal requestBody: required: true content: application/json: schema: type: object properties: stablepayReference: type: string description: The original payout's payment ID. example: ISS_KE01K5D3W8ZQ4FZXQJHBVYFT9K3E reversalReference: type: string description: >- The recipient's official reversal confirmation reference. Stablepay verifies this with the provider. example: QGR7X8T2PL reason: type: string description: Your own note about the claim. example: customer requested reversal required: - stablepayReference - reversalReference example: stablepayReference: ISS_KE01K5D3W8ZQ4FZXQJHBVYFT9K3E reversalReference: QGR7X8T2PL reason: customer requested reversal responses: '201': description: Claim lodged, or the existing claim for this payout. content: application/json: schema: allOf: - $ref: '#/components/schemas/Reversal' - type: object properties: alreadyExisted: type: boolean description: >- True when a claim for this payout had already been lodged. example: false example: reversalId: ISS_RV01K5D3W8ZQ4FZXQJHBVYFT9K3F paymentId: ISS_KE01K5D3W8ZQ4FZXQJHBVYFT9K3E stablepayReference: ISS_KE01K5D3W8ZQ4FZXQJHBVYFT9K3E reversalReference: QGR7X8T2PL blockchain: SOLANA status: pending_review reversalAmountUsdc: '10.500000' toAddress: 4Nd1mXKqRtPvYbGfJhAeZwQsUcTnVpLgDkRyXmWtB9Cq reversalTxHash: null failureReason: null reason: customer requested reversal createdAt: '2026-10-14T09:12:04.000Z' reviewedAt: null sentAt: null confirmedAt: null alreadyExisted: false '400': description: > The payout cannot be reversed — no such payment on your account, it is not a payout, or it has not succeeded. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: notFound: summary: No such payment on this account value: code: payout_reversal_payment_not_found message: >- No payment ISS_KE01K5D3W8ZQ4FZXQJHBVYFT9K3E for this account. notSucceeded: summary: Payout has not succeeded value: code: payout_reversal_not_succeeded message: >- Payment ISS_KE01K5D3W8ZQ4FZXQJHBVYFT9K3E is 'failed', not 'succeeded' — only a settled payout can be reversed. notPayout: summary: Not an outbound payout value: code: payout_reversal_not_money_out message: >- Payment ISS_KE01K5D3W8ZQ4FZXQJHBVYFT9K3E is not an outbound payout — only payouts can be reversed. '401': description: Invalid or missing API key. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: Reversal: type: object properties: reversalId: type: string description: The reversal ID. Use it to check the claim's status. example: ISS_RV01K5D3W8ZQ4FZXQJHBVYFT9K3F paymentId: type: string description: The payout being reversed. example: ISS_KE01K5D3W8ZQ4FZXQJHBVYFT9K3E stablepayReference: type: string description: The payment reference supplied on the claim. example: ISS_KE01K5D3W8ZQ4FZXQJHBVYFT9K3E reversalReference: type: string description: The recipient's reversal confirmation reference. example: QGR7X8T2PL blockchain: type: string description: Chain the reversal is paid on. Taken from the original payout. example: SOLANA status: type: string enum: - pending_review - approved - sending - confirmed - rejected - failed description: | pending_review: lodged, awaiting verification. No money has moved. approved: verified by Stablepay; the reversal is queued. sending: the reversal is in flight. confirmed: the reversal is confirmed on-chain. rejected: could not be verified. No money moved. failed: the reversal was attempted and did not complete. example: pending_review reversalAmountUsdc: type: string description: Full original amount returned, in USDC. example: '10.500000' toAddress: type: string description: >- Your funding wallet on that chain. Resolved by Stablepay, never supplied on the claim. example: 4Nd1mXKqRtPvYbGfJhAeZwQsUcTnVpLgDkRyXmWtB9Cq reversalTxHash: type: string nullable: true description: >- On-chain hash of the reversal transaction. Null until the reversal is sent. example: null failureReason: type: string nullable: true description: Why the reversal failed. Null unless status is failed. example: null reason: type: string nullable: true description: The note supplied on the claim, or the rejection note. example: customer requested reversal createdAt: type: string format: date-time description: When the claim was lodged. reviewedAt: type: string format: date-time nullable: true description: When the claim was approved or rejected. Null while pending_review. example: null sentAt: type: string format: date-time nullable: true description: When the reversal was broadcast. Null until sent. example: null confirmedAt: type: string format: date-time nullable: true description: When the reversal was confirmed on-chain. Null until confirmed. example: null required: - reversalId - paymentId - stablepayReference - reversalReference - blockchain - status - reversalAmountUsdc - toAddress - reversalTxHash - failureReason - reason - createdAt - reviewedAt - sentAt - confirmedAt ErrorResponse: type: object properties: statusCode: type: integer example: 400 code: type: string description: Machine-readable error code. example: validation_error message: type: string description: Human-readable error message. example: fiatAmount must be a positive number. required: - statusCode - message securitySchemes: BearerAuth: type: http scheme: bearer description: | Stablepay API key. Include as `Authorization: Bearer `. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.