{
  "openapi": "3.1.0",
  "info": {
    "title": "CoinGate Payment Gateway 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"
    }
  },
  "externalDocs": {
    "description": "CoinGate Developer Documentation",
    "url": "https://developer.coingate.com/docs/api-overview"
  },
  "servers": [
    {
      "url": "https://api.coingate.com/api/v2",
      "description": "Production"
    },
    {
      "url": "https://api-sandbox.coingate.com/api/v2",
      "description": "Sandbox"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "API Token authentication. Obtain your API token from the CoinGate merchant dashboard."
      }
    },
    "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"
          }
        }
      },
      "Currency": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "title": {
            "type": "string"
          },
          "kind": {
            "type": "string",
            "enum": ["crypto", "fiat"]
          },
          "symbol": {
            "type": "string"
          }
        }
      },
      "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"
              }
            }
          }
        }
      },
      "LedgerAccount": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "balance": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": ["active", "inactive"]
          },
          "currency": {
            "$ref": "#/components/schemas/Currency"
          }
        }
      },
      "SendRequest": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "status": {
            "type": "string"
          },
          "purpose": {
            "type": "string"
          },
          "callback_url": {
            "type": "string"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "external_id": {
            "type": "string"
          },
          "ledger_account": {
            "$ref": "#/components/schemas/LedgerAccount"
          },
          "input_amount": {
            "type": "string"
          },
          "input_currency": {
            "$ref": "#/components/schemas/Currency"
          },
          "sending_amount": {
            "type": "string"
          },
          "sending_currency": {
            "$ref": "#/components/schemas/Currency"
          },
          "input_to_sending_rate": {
            "type": "string"
          },
          "sending_to_balance_debit_rate": {
            "type": "string"
          },
          "balance_debit_amount": {
            "type": "string"
          },
          "balance_debit_currency": {
            "$ref": "#/components/schemas/Currency"
          },
          "fees": {
            "type": "object"
          },
          "blockchain_transactions": {
            "type": "array",
            "items": {}
          },
          "actions_required": {
            "type": "object",
            "properties": {
              "confirm": {
                "type": "string"
              },
              "cancel": {
                "type": "string"
              }
            }
          },
          "requires_2fa_confirmation": {
            "type": "boolean"
          }
        }
      },
      "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"
          }
        }
      }
    }
  },
  "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"
                }
              }
            }
          }
        }
      }
    },
    "/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"
                }
              }
            }
          }
        }
      }
    },
    "/send_requests": {
      "post": {
        "summary": "Create Send Request",
        "description": "Create a payout send request to transfer crypto to a beneficiary.",
        "operationId": "create-send",
        "tags": ["Send Requests"],
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "required": ["ledger_account_id", "beneficiary_payout_setting_id", "amount", "amount_currency_id", "purpose"],
                "properties": {
                  "ledger_account_id": {
                    "type": "string",
                    "description": "Ledger account ID (see /ledger/accounts)"
                  },
                  "beneficiary_payout_setting_id": {
                    "type": "integer",
                    "format": "int32",
                    "description": "Beneficiary payout setting ID (see /beneficiaries)"
                  },
                  "amount": {
                    "type": "string",
                    "description": "Amount to send"
                  },
                  "amount_currency_id": {
                    "type": "integer",
                    "format": "int32",
                    "description": "Currency ID for the amount (see /currencies)"
                  },
                  "purpose": {
                    "type": "string",
                    "description": "Purpose of the send request"
                  },
                  "callback_url": {
                    "type": "string",
                    "description": "URL for automated send request status change notifications"
                  },
                  "external_id": {
                    "type": "string",
                    "description": "Merchant internal reference ID (must be unique, max 50 chars)"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Send request created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SendRequest"
                }
              }
            }
          },
          "422": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "get": {
        "summary": "List Send Requests",
        "description": "Retrieve a paginated list of all send requests.",
        "operationId": "list-send",
        "tags": ["Send Requests"],
        "parameters": [
          {
            "name": "per_page",
            "in": "query",
            "description": "Records per page",
            "schema": {
              "type": "integer",
              "format": "int32",
              "default": 100
            }
          },
          {
            "name": "page",
            "in": "query",
            "description": "Current page number",
            "schema": {
              "type": "integer",
              "format": "int32",
              "default": 1
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of send requests",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "current_page": {
                      "type": "integer"
                    },
                    "per_page": {
                      "type": "integer"
                    },
                    "total_records": {
                      "type": "integer"
                    },
                    "total_pages": {
                      "type": "integer"
                    },
                    "send_requests": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/SendRequest"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/send_requests/{id}": {
      "get": {
        "summary": "Get Send Request",
        "description": "Retrieve details of a specific send request.",
        "operationId": "get-send",
        "tags": ["Send Requests"],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Send request details",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SendRequest"
                }
              }
            }
          },
          "404": {
            "description": "Send request not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/ledger/conversions": {
      "post": {
        "summary": "Create Conversion",
        "description": "Create a currency conversion between ledger accounts.",
        "operationId": "create-conversion",
        "tags": ["Conversions"],
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "required": ["ledger_account_id", "quote_currency_id", "base_amount"],
                "properties": {
                  "ledger_account_id": {
                    "type": "string",
                    "description": "ID of the ledger account to convert from"
                  },
                  "quote_currency_id": {
                    "type": "integer",
                    "format": "int32",
                    "description": "ID of the target currency to convert to"
                  },
                  "base_amount": {
                    "type": "string",
                    "description": "Amount to convert in the source ledger account currency"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Conversion created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "status": {
                      "type": "string"
                    },
                    "base_amount": {
                      "type": "string"
                    },
                    "quote_amount": {
                      "type": "string"
                    },
                    "base_ledger_account": {
                      "$ref": "#/components/schemas/LedgerAccount"
                    },
                    "quote_ledger_account": {
                      "$ref": "#/components/schemas/LedgerAccount"
                    },
                    "fees": {
                      "type": "object"
                    },
                    "actions_required": {
                      "type": "object"
                    },
                    "created_at": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "expires_at": {
                      "type": "string",
                      "format": "date-time"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "get": {
        "summary": "List Conversions",
        "description": "Retrieve a paginated list of currency conversions.",
        "operationId": "list-conversions",
        "tags": ["Conversions"],
        "parameters": [
          {
            "name": "per_page",
            "in": "query",
            "schema": {
              "type": "integer",
              "format": "int32",
              "default": 100
            }
          },
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "format": "int32",
              "default": 1
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of conversions",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "current_page": {
                      "type": "integer"
                    },
                    "per_page": {
                      "type": "integer"
                    },
                    "total_records": {
                      "type": "integer"
                    },
                    "total_pages": {
                      "type": "integer"
                    },
                    "exchange_transactions": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "status": {
                            "type": "string"
                          },
                          "base_amount": {
                            "type": "string"
                          },
                          "quote_amount": {
                            "type": "string"
                          },
                          "fees": {
                            "type": "object"
                          },
                          "created_at": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "expires_at": {
                            "type": "string",
                            "format": "date-time"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/currencies": {
      "get": {
        "summary": "Get Currencies",
        "description": "Retrieves all supported currencies with optional filtering.",
        "operationId": "currencies",
        "tags": ["Currencies"],
        "security": [],
        "parameters": [
          {
            "name": "native",
            "in": "query",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "enabled",
            "in": "query",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "merchant_pay",
            "in": "query",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "merchant_receive",
            "in": "query",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "kind",
            "in": "query",
            "description": "Filter by currency type. Accepted values: crypto, fiat",
            "schema": {
              "type": "string",
              "enum": ["crypto", "fiat"]
            }
          },
          {
            "name": "symbol",
            "in": "query",
            "description": "Search by currency symbol, e.g. BTC",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of currencies",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "integer"
                      },
                      "title": {
                        "type": "string"
                      },
                      "kind": {
                        "type": "string",
                        "enum": ["crypto", "fiat"]
                      },
                      "symbol": {
                        "type": "string"
                      },
                      "native": {
                        "type": "boolean"
                      },
                      "disabled": {
                        "type": "boolean"
                      },
                      "disabled_message": {
                        "type": "string",
                        "nullable": true
                      },
                      "merchant": {
                        "type": "object",
                        "properties": {
                          "price": {
                            "type": "boolean"
                          },
                          "pay": {
                            "type": "boolean"
                          },
                          "receive": {
                            "type": "boolean"
                          }
                        }
                      },
                      "platforms": {
                        "type": "array",
                        "items": {
                          "type": "object",
                          "properties": {
                            "id": {
                              "type": "integer"
                            },
                            "id_name": {
                              "type": "string"
                            },
                            "title": {
                              "type": "string"
                            },
                            "enabled": {
                              "type": "boolean"
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "tags": [
    {
      "name": "Orders",
      "description": "Create and manage payment orders"
    },
    {
      "name": "Refunds",
      "description": "Process order refunds"
    },
    {
      "name": "Send Requests",
      "description": "Send cryptocurrency payouts to beneficiaries"
    },
    {
      "name": "Conversions",
      "description": "Convert between currencies in ledger accounts"
    },
    {
      "name": "Currencies",
      "description": "Retrieve supported currencies and platforms"
    }
  ]
}