> ## 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.

# Get Reversal

> Retrieve a reversal and its current status.



## OpenAPI

````yaml GET /v1/reversals/{reversalId}
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/{reversalId}:
    get:
      tags:
        - Reversals
      summary: Get a reversal
      description: Retrieve a reversal and its current status.
      operationId: getReversal
      parameters:
        - name: reversalId
          in: path
          required: true
          schema:
            type: string
          description: The reversal ID.
          example: ISS_RV01K5D3W8ZQ4FZXQJHBVYFT9K3F
      responses:
        '200':
          description: Reversal found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Reversal'
              examples:
                pendingReview:
                  summary: Awaiting verification
                  value:
                    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
                confirmed:
                  summary: Funds returned and confirmed on-chain
                  value:
                    reversalId: ISS_RV01K5D3W8ZQ4FZXQJHBVYFT9K3F
                    paymentId: ISS_KE01K5D3W8ZQ4FZXQJHBVYFT9K3E
                    stablepayReference: ISS_KE01K5D3W8ZQ4FZXQJHBVYFT9K3E
                    reversalReference: QGR7X8T2PL
                    blockchain: SOLANA
                    status: confirmed
                    reversalAmountUsdc: '10.500000'
                    toAddress: 4Nd1mXKqRtPvYbGfJhAeZwQsUcTnVpLgDkRyXmWtB9Cq
                    reversalTxHash: >-
                      5VfYmQ2kRtNpXwJbGhAeZsUcTnVpLgDkRyXmWtB9CqHd3PnLsEaWxZrFjMvTkYbQuRdNhGcJpAeVtXmWsB7Df2Kq
                    failureReason: null
                    reason: customer requested reversal
                    createdAt: '2026-10-14T09:12:04.000Z'
                    reviewedAt: '2026-10-14T11:40:00.000Z'
                    sentAt: '2026-10-14T11:41:12.000Z'
                    confirmedAt: '2026-10-14T11:41:38.000Z'
                rejected:
                  summary: Could not be verified
                  value:
                    reversalId: ISS_RV01K5D3W8ZQ4FZXQJHBVYFT9K3F
                    paymentId: ISS_KE01K5D3W8ZQ4FZXQJHBVYFT9K3E
                    stablepayReference: ISS_KE01K5D3W8ZQ4FZXQJHBVYFT9K3E
                    reversalReference: QGR7X8T2PL
                    blockchain: SOLANA
                    status: rejected
                    reversalAmountUsdc: '10.500000'
                    toAddress: 4Nd1mXKqRtPvYbGfJhAeZwQsUcTnVpLgDkRyXmWtB9Cq
                    reversalTxHash: null
                    failureReason: null
                    reason: reversal reference could not be verified with the provider
                    createdAt: '2026-10-14T09:12:04.000Z'
                    reviewedAt: '2026-10-14T11:40:00.000Z'
                    sentAt: null
                    confirmedAt: null
        '400':
          description: Reversal not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: payout_reversal_not_found
                message: Payout reversal ISS_RV01K5D3W8ZQ4FZXQJHBVYFT9K3F not found.
        '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 <key>`.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.