openapi: 3.1.0
info:
  title: CoinGate Payment Gateway Conversions Orders 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: Orders
  description: Create and manage payment orders
paths:
  /orders:
    post:
      summary: Create Order
      description: Create an order at CoinGate and redirect the shopper to the invoice (payment_url).
      operationId: create-order
      tags:
      - Orders
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - price_amount
              - price_currency
              - title
              - description
              properties:
                order_id:
                  type: string
                  description: 'Merchant''s custom order ID. We recommend using a unique order ID. Example: CGORDER-12345.'
                price_amount:
                  type: number
                  format: double
                  description: 'The price set by the merchant. Example: 1050.99.'
                price_currency:
                  type: string
                  description: ISO 4217 currency code defining the currency for pricing.
                receive_currency:
                  type: string
                  description: ISO 4217 currency code specifying settlement currency. Use DO_NOT_CONVERT to keep payment in original currency.
                title:
                  type: string
                  description: 'Min 3 - Max 150 characters. Example: product title, order id, or cart id.'
                description:
                  type: string
                  description: Min 3 - Max 500 characters. Cart items, product details or other information.
                callback_url:
                  type: string
                  description: URL for automated order status change notifications.
                cancel_url:
                  type: string
                  description: Redirect URL when buyer cancels the order.
                success_url:
                  type: string
                  description: Redirect URL after successful payment.
                token:
                  type: string
                  description: Custom token to validate payment callback notification.
                shopper:
                  $ref: '#/components/schemas/Shopper'
      responses:
        '200':
          description: Order created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    get:
      summary: List Orders
      description: Retrieve information of all placed orders.
      operationId: list-orders
      tags:
      - Orders
      parameters:
      - name: per_page
        in: query
        description: 'How many orders per page. Max: 100. Default: 100.'
        schema:
          type: integer
          format: int32
          default: 100
          maximum: 100
      - name: page
        in: query
        schema:
          type: integer
          format: int32
          default: 1
      - name: sort
        in: query
        description: 'Sort orders by field. Available: created_at_asc, created_at_desc.'
        schema:
          type: string
          default: created_at_desc
          enum:
          - created_at_asc
          - created_at_desc
      - name: created_at[from]
        in: query
        description: 'Filter by order creation time (from). Example: 2018-09-01'
        schema:
          type: string
          format: date
      - name: created_at[to]
        in: query
        description: 'Filter by order creation time (to). Example: 2018-09-30'
        schema:
          type: string
          format: date
      - name: status
        in: query
        description: Filter by order status.
        schema:
          type: string
      - name: paid_at[from]
        in: query
        description: 'Filter by order paid time (from). Example: 2018-09-01'
        schema:
          type: string
          format: date
      - name: paid_at[to]
        in: query
        description: 'Filter by order paid time (to). Example: 2018-09-30'
        schema:
          type: string
          format: date
      responses:
        '200':
          description: List of orders
          content:
            application/json:
              schema:
                type: object
                properties:
                  current_page:
                    type: integer
                  per_page:
                    type: integer
                  total_orders:
                    type: integer
                  total_pages:
                    type: integer
                  orders:
                    type: array
                    items:
                      $ref: '#/components/schemas/Order'
        '400':
          description: Bad request
  /orders/{id}:
    get:
      summary: Get Order
      description: Retrieve information about a specific order by its CoinGate ID.
      operationId: get-order
      tags:
      - Orders
      parameters:
      - name: id
        in: path
        description: CoinGate Order ID
        required: true
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: Order details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '404':
          description: Order not found
          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
    Order:
      type: object
      properties:
        id:
          type: integer
        status:
          type: string
          description: Order status (new, pending, confirming, paid, invalid, expired, canceled, refunded)
        title:
          type: string
        do_not_convert:
          type: boolean
        orderable_type:
          type: string
        orderable_id:
          type: integer
        price_currency:
          type: string
        price_amount:
          type: string
        pay_currency:
          type: string
        pay_amount:
          type: string
        lightning_network:
          type: boolean
        receive_currency:
          type: string
        receive_amount:
          type: string
        created_at:
          type: string
          format: date-time
        expire_at:
          type: string
          format: date-time
        paid_at:
          type: string
          format: date-time
        payment_address:
          type: string
        payment_gateway:
          type: string
        order_id:
          type: string
        payment_url:
          type: string
        payment_request_uri:
          type: string
        underpaid_amount:
          type: string
        overpaid_amount:
          type: string
        is_refundable:
          type: boolean
        conversion_rate:
          type: string
        token:
          type: string
        refunds:
          type: array
          items: {}
        voids:
          type: array
          items: {}
        fees:
          type: array
          items: {}
        blockchain_transactions:
          type: array
          items: {}
    Shopper:
      type: object
      description: Optional shopper information for Travel Rule compliance and checkout prefill
      properties:
        type:
          type: string
          enum:
          - business
          - personal
        ip_address:
          type: string
        email:
          type: string
          format: email
        first_name:
          type: string
        last_name:
          type: string
        date_of_birth:
          type: string
          format: date
        residence_address:
          type: string
        residence_postal_code:
          type: string
        residence_city:
          type: string
        residence_country:
          type: string
          description: Alpha-2 country code
        company_details:
          type: object
          properties:
            name:
              type: string
            code:
              type: string
            incorporation_date:
              type: string
              format: date
            incorporation_country:
              type: string
            address:
              type: string
            postal_code:
              type: string
            city:
              type: string
            country:
              type: string
  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