openapi: 3.1.0
info:
  title: CoinGate Payment Gateway Conversions Refunds API
  description: REST API for accepting cryptocurrency payments, managing orders, processing refunds, handling payouts, performing currency conversions, and accessing merchant ledger and billing data. Supports both production and sandbox environments.
  version: '2'
  contact:
    name: CoinGate Support
    url: https://coingate.com/contact
    email: support@coingate.com
  termsOfService: https://coingate.com/terms
  x-logo:
    url: https://coingate.com/images/coingate-logo.png
servers:
- url: https://api.coingate.com/api/v2
  description: Production
- url: https://api-sandbox.coingate.com/api/v2
  description: Sandbox
security:
- bearerAuth: []
tags:
- name: Refunds
  description: Process order refunds
paths:
  /orders/{order_id}/refunds:
    post:
      summary: Create Order Refund
      description: Create a refund for a specific order.
      operationId: create-refund
      tags:
      - Refunds
      parameters:
      - name: order_id
        in: path
        description: ID of the order to be refunded
        required: true
        schema:
          type: integer
          format: int32
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - amount
              - address
              - currency_id
              - platform_id
              - reason
              - email
              - ledger_account_id
              properties:
                amount:
                  type: number
                  format: double
                  description: Requesting amount in order price currency to refund
                address:
                  type: string
                  description: Cryptocurrency address to which the refund will be sent
                address_memo:
                  type: string
                currency_id:
                  type: integer
                  format: int32
                  description: ID of the currency in which the refund will be issued
                platform_id:
                  type: integer
                  format: int32
                  description: Platform ID associated with the selected refund currency
                reason:
                  type: string
                  description: Reason for issuing the refund
                email:
                  type: string
                  format: email
                  description: Customer will receive updates on refund status to this email
                ledger_account_id:
                  type: string
                  description: Ledger balance from which the refund amount will be deducted
                callback_url:
                  type: string
                  description: URL for automated refund status change notifications
                skip_user_address_confirmation:
                  type: boolean
                  default: false
                  description: Skip email confirmation of crypto address to shopper
      responses:
        '200':
          description: Refund created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Refund'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Error:
      type: object
      properties:
        message:
          type: string
          description: Human-readable error message
        reason:
          type: string
          description: Machine-readable error reason code
        errors:
          type: array
          items:
            type: string
          description: List of validation errors
    Refund:
      type: object
      properties:
        id:
          type: integer
        request_amount:
          type: string
        refund_amount:
          type: string
        address:
          type: string
        status:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        skip_user_address_confirmation:
          type: boolean
        processor:
          type: string
        order:
          type: object
        refund_currency:
          type: object
        transactions:
          type: array
          items: {}
        ledger_account:
          type: object
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API Token authentication. Obtain your API token from the CoinGate merchant dashboard.
externalDocs:
  description: CoinGate Developer Documentation
  url: https://developer.coingate.com/docs/api-overview