> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cdp.coinbase.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Refund Checkout

> Initiates a refund for a completed checkout. Only `COMPLETED` or `PARTIALLY_REFUNDED` checkouts can be refunded.



## OpenAPI

````yaml post /api/v1/checkouts/{id}/refund
openapi: 3.0.3
info:
  title: Checkouts API
  description: >
    The Checkouts API enables developers to create and manage checkouts for
    cryptocurrency payments.


    Checkouts provide a simple way to accept payments by generating an
    embeddable URL that handles

    the payment flow, including address generation, transaction monitoring, and
    status updates.


    Each checkout is single-use — it accepts one payment and then moves to a
    terminal state. Create a new checkout for each transaction.
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
  version: 1.0.0
  contact:
    name: Coinbase Business
    email: business@coinbase.com
    url: https://www.coinbase.com/business
servers:
  - url: https://business.coinbase.com
    description: The production server of the Checkouts API.
security:
  - apiKeyAuth: []
tags:
  - name: Checkouts
    description: Operations for creating and managing checkouts
paths:
  /api/v1/checkouts/{id}/refund:
    post:
      tags:
        - Checkouts
      summary: Refund Checkout
      description: >-
        Initiates a refund for a completed checkout. Only `COMPLETED` or
        `PARTIALLY_REFUNDED` checkouts can be refunded.
      operationId: refundCheckout
      parameters:
        - name: id
          in: path
          required: true
          description: The checkout ID.
          schema:
            type: string
            pattern: ^[0-9a-f]{24}$
            example: 68f7a946db0529ea9b6d3a12
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RefundCheckoutRequest'
      responses:
        '200':
          description: Refund initiated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RefundCheckoutResult'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - apiKeyAuth: []
components:
  parameters:
    IdempotencyKey:
      name: X-Idempotency-Key
      in: header
      required: false
      description: >
        An optional [UUID v4](https://www.uuidgenerator.net/version4) request
        header for making requests safely retryable.
      schema:
        type: string
        maxLength: 36
        minLength: 36
        pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
      example: 8e03978e-40d5-43e8-bc93-6894a57f9324
  schemas:
    RefundCheckoutRequest:
      type: object
      required:
        - amount
      properties:
        amount:
          type: string
          description: >-
            Refund amount. Must be > 0 and not exceed remaining refundable
            amount.
          pattern: ^\d+(\.\d{1,2})?$
          example: '25.00'
        currency:
          type: string
          description: >
            Currency of the refund amount. If omitted, defaults to the
            checkout's original fiat currency (or USDC if the payment was in
            USDC). Supported currencies: any fiat currency supported by the
            checkout creation API.
          example: USDC
        reason:
          type: string
          description: Optional reason for the refund.
          maxLength: 500
          example: Customer requested refund
    RefundCheckoutResult:
      type: object
      required:
        - checkout
        - refund
      properties:
        checkout:
          $ref: '#/components/schemas/CheckoutResponse'
        refund:
          $ref: '#/components/schemas/RefundResponse'
    CheckoutResponse:
      allOf:
        - $ref: '#/components/schemas/PaymentResponseDetailBase'
        - type: object
          required:
            - status
          properties:
            status:
              $ref: '#/components/schemas/PaymentStatus'
    RefundResponse:
      type: object
      required:
        - id
        - checkoutId
        - amount
        - status
        - createdAt
        - currency
      properties:
        id:
          type: string
          description: Unique refund identifier.
          pattern: ^[0-9a-f]{24}$
        checkoutId:
          type: string
          description: The ID of the checkout this refund is associated with.
        amount:
          type: string
          description: The refund amount in USDC (settlement currency).
        status:
          $ref: '#/components/schemas/RefundStatus'
        reason:
          type: string
          description: The reason for the refund.
        transactionHash:
          type: string
          description: Blockchain transaction hash. Present when refund is completed.
        createdAt:
          $ref: '#/components/schemas/Timestamp'
        completedAt:
          $ref: '#/components/schemas/Timestamp'
        fiatAmount:
          type: string
          description: >-
            Original refund amount in the requested fiat currency. Only present
            for non-USDC refunds.
        fiatCurrency:
          type: string
          description: >-
            Original fiat currency code (e.g., "USD", "EUR"). Only present for
            non-USDC refunds.
        exchangeRate:
          type: string
          description: >-
            Exchange rate used for fiat-to-USDC conversion. Only present for
            non-USDC refunds.
        currency:
          type: string
          description: The settlement currency for the refund. Always "USDC".
          example: USDC
    Error:
      description: >-
        An error response including the code for the type of error and a
        human-readable message describing the error.
      type: object
      properties:
        errorType:
          $ref: '#/components/schemas/ErrorType'
        errorMessage:
          description: The error message.
          type: string
        correlationId:
          description: >-
            A unique identifier for the request that generated the error. This
            can be used to help debug issues with the API.
          type: string
          example: 41deb8d59a9dc9a7-IAD
        errorLink:
          description: A link to the corresponding error documentation.
          type: string
      required:
        - errorType
        - errorMessage
      example:
        errorType: invalid_request
        errorMessage: Invalid request.
        correlationId: 41deb8d59a9dc9a7-IAD
    PaymentResponseDetailBase:
      allOf:
        - $ref: '#/components/schemas/PaymentResponseBase'
        - type: object
          properties:
            refunds:
              type: array
              description: >-
                List of refunds associated with this payment. Only present when
                refunds exist.
              items:
                $ref: '#/components/schemas/RefundResponse'
    PaymentStatus:
      type: string
      description: >
        The status of the payment.

        - `ACTIVE` The payable endpoint is active and can accept payments.

        - `PROCESSING` The payment is being processed.

        - `DEACTIVATED` The payable endpoint has been manually deactivated.

        - `EXPIRED` The payable endpoint has expired based on the expiresAt
        timestamp.

        - `COMPLETED` The payable endpoint has been successfully paid.

        - `FAILED` The payment has failed due to a payment error.

        - `REFUNDED` The payment has been fully refunded.

        - `PARTIALLY_REFUNDED` The payment has been partially refunded.
      enum:
        - ACTIVE
        - PROCESSING
        - DEACTIVATED
        - EXPIRED
        - COMPLETED
        - FAILED
        - REFUNDED
        - PARTIALLY_REFUNDED
      example: ACTIVE
    RefundStatus:
      type: string
      description: |
        The status of the refund.
        - `PENDING` The refund is being processed.
        - `COMPLETED` The refund has been successfully completed.
        - `FAILED` The refund has failed.
      enum:
        - PENDING
        - COMPLETED
        - FAILED
      x-enum-varnames:
        - RefundStatusPENDING
        - RefundStatusCOMPLETED
        - RefundStatusFAILED
      example: PENDING
    Timestamp:
      type: string
      format: date-time
      description: Timestamp in RFC 3339 format.
      example: '2024-03-20T10:30:00Z'
    ErrorType:
      description: >-
        The code that indicates the type of error that occurred. These error
        codes can be used to determine how to handle the error.
      type: string
      example: invalid_request
      enum:
        - already_exists
        - bad_gateway
        - forbidden
        - idempotency_error
        - internal_server_error
        - invalid_request
        - not_found
        - rate_limit_exceeded
        - request_canceled
        - service_unavailable
        - timed_out
        - unauthorized
    PaymentResponseBase:
      type: object
      required:
        - id
        - url
        - amount
        - currency
        - network
        - address
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          description: Unique payment identifier.
          example: 68f7a946db0529ea9b6d3a12
          pattern: ^[0-9a-f]{24}$
        url:
          type: string
          format: uri
          description: The hosted payment page URL.
          example: >-
            https://payments.coinbase.com/payment-links/pl_01h8441j23abcd1234567890ef
        amount:
          type: string
          description: Numeric value representing the amount (maximum 2 decimal places).
          example: '100.50'
        currency:
          type: string
          description: The currency code for the amount.
          example: USDC
        network:
          $ref: '#/components/schemas/Network'
        address:
          type: string
          description: The blockchain address where funds should be sent.
          example: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
        tokenAddress:
          type: string
          description: The token contract address (for ERC-20 tokens).
          example: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
        description:
          type: string
          description: Human-readable description of the payment.
          example: 'Payment for order #12345'
        expiresAt:
          $ref: '#/components/schemas/Timestamp'
        metadata:
          $ref: '#/components/schemas/Metadata'
        successRedirectUrl:
          type: string
          format: uri
          description: >-
            Optional URL to redirect the user to after successful payment
            authorization. This indicates the user has successfully authorized
            the payment, not that the payment has been completed.
          example: https://example.com/success
        failRedirectUrl:
          type: string
          format: uri
          description: >-
            Optional URL to redirect the user to after failed payment
            authorization.
          example: https://example.com/failed
        createdAt:
          $ref: '#/components/schemas/Timestamp'
        updatedAt:
          $ref: '#/components/schemas/Timestamp'
        settlement:
          $ref: '#/components/schemas/Settlement'
        fiatAmount:
          type: string
          description: >-
            The original amount in fiat currency before conversion to USDC. Only
            present if payment was created with a fiat currency.
          example: '100.00'
        fiatCurrency:
          type: string
          description: >-
            The original fiat currency code (e.g., USD, EUR, SGD). Only present
            if payment was created with a fiat currency.
          example: USD
        transactionHash:
          type: string
          description: >-
            The blockchain transaction hash for the completed payment. Only
            present when status is COMPLETED, REFUNDED, or PARTIALLY_REFUNDED.
          example: '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef'
        refundedAmount:
          type: string
          description: >-
            The total amount that has been refunded. Only present when a refund
            has been initiated.
          example: '25.00'
    Network:
      type: string
      description: >-
        The blockchain network for the payment. Defaults to base if not
        specified. More networks will be added in the future.
      enum:
        - base
      default: base
      example: base
    Metadata:
      type: object
      description: >-
        Optional metadata as key-value pairs to be passed through the payment
        flow.
      additionalProperties:
        type: string
        maxLength: 100
      maxProperties: 20
      example:
        invoiceId: '12345'
        reference: 'Payment for invoice #12345'
        customerId: cust_abc123
    Settlement:
      type: object
      description: >-
        Financial breakdown of the transaction showing the total amount charged,
        fees deducted, and net amount received.
      required:
        - totalAmount
        - feeAmount
        - netAmount
        - currency
      properties:
        totalAmount:
          type: string
          description: >-
            The full amount charged to the payer. This equals netAmount +
            feeAmount.
          example: '100.00'
        feeAmount:
          type: string
          description: >-
            The fee deducted from the total amount ($1.25 of the requested
            amount of $100 with a fee rate of 1.25%).
          example: '1.25'
        netAmount:
          type: string
          description: >-
            The amount the payment requester receives after fees ($98.75 of the
            requested amount of $100 with a fee rate of 1.25%).
          example: '98.75'
        currency:
          type: string
          description: >-
            The currency of the settlement amounts. This is the currency the
            merchant receives.
          example: USDC
  responses:
    BadRequestError:
      description: Invalid request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            invalid_request:
              value:
                errorType: invalid_request
                errorMessage: Invalid request parameters.
    UnauthorizedError:
      description: Unauthorized.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            unauthorized:
              value:
                errorType: unauthorized
                errorMessage: The request is not properly authenticated.
    ForbiddenError:
      description: User forbidden from performing the action.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            forbidden:
              value:
                errorType: forbidden
                errorMessage: User forbidden from performing the action.
    NotFoundError:
      description: Resource not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            not_found:
              value:
                errorType: not_found
                errorMessage: The requested resource was not found.
    RateLimitExceeded:
      description: Rate limit exceeded.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            rate_limit_exceeded:
              value:
                errorType: rate_limit_exceeded
                errorMessage: Rate limit exceeded.
    InternalServerError:
      description: Internal server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            internal_server_error:
              value:
                errorType: internal_server_error
                errorMessage: An internal server error occurred. Please try again later.
  securitySchemes:
    apiKeyAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >
        A JWT signed using your CDP API Key Secret, encoded in base64. Refer to
        the

        [Generate Bearer
        Token](https://docs.cdp.coinbase.com/api-reference/v2/authentication#2-generate-bearer-token)

        section of our Authentication docs for information on how to generate
        your Bearer Token.

````