API Specification (YAML)
openapi: 3.0.0
info:
title: CryptoProc API
description: |
API for integrating payment acceptance (SBP, Cards, Cryptocurrency) on your website.
# 🔐 Authorization (Keys)
In your project settings in the dashboard, you will find two different keys:
- **API Key** — public identifier of the project.
- **Secret Key** (also known as Webhook Secret) — private password for secure server-to-server interaction.
> **Important!** All requests to the API for creating invoices must be authorized using the **Secret Key**. Do not use the API Key for these purposes. Pass the Secret Key in the header: `Authorization: Bearer <Your_Secret_Key>`.
# ⚠️ Integration Errors
The API always returns JSON with a `success: false` field and a text description of the error in `message` if something goes wrong. Handle the following HTTP statuses for your system to correctly react to integration errors:
* **400 Bad Request** — Parameters error (for example, forgot to pass amount, specified a negative value, or forgot project_id).
* **401 Unauthorized** — Authorization error. API Key passed instead of Secret Key, or the key is invalid/missing.
* **403 Forbidden** — Project not found, doesn't belong to you, or is blocked (status other than active).
* **405 Method Not Allowed** — Invalid HTTP method used (only POST is allowed).
* **500 Internal Server Error** — Internal server error.
version: 1.0.0
servers:
- url: /api
description: Main Server
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: Use your Secret Key as a Bearer token.
security:
- bearerAuth: []
paths:
/payment/create:
post:
summary: Create Payment Invoice
description: Creates a new invoice and returns a unique link to the payment form. Make sure you pass the correct `project_id` and a valid `Secret Key` in the headers.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- project_id
- amount
properties:
project_id:
type: integer
description: ID of your project
example: 123
amount:
type: number
description: Payment amount in Rubles (must be greater than zero)
example: 1500.50
description:
type: string
description: Payment purpose (will be shown to the client)
example: Payment of order #456
responses:
'200':
description: Invoice created successfully
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
invoice_id:
type: string
format: uuid
example: "f47ac10b-58cc-4372-a567-0e02b2c3d479"
payment_url:
type: string
format: uri
example: "https://coinso.io/pay/f47ac10b-58cc-4372-a567-0e02b2c3d479"
'400':
description: Validation error of parameters (negative amount, no project_id)
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: false
message:
type: string
example: "Invalid parameters"
'401':
description: Authorization error (API Key passed instead of Secret Key, or key is invalid)
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: false
message:
type: string
example: "Invalid Secret Key"
'403':
description: Project not found or blocked (status is not active)
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: false
message:
type: string
example: "Project not found or not active"
'405':
description: Invalid HTTP method used (only POST is allowed)
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: false
message:
type: string
example: "Method Not Allowed"
/webhook-example:
post:
summary: Webhook payment notification (Your server)
description: POST requests will be sent to your Webhook URL (specified in the project settings) upon successful payment or cancellation. To verify the webhook authenticity, check the IP or verify the cryptographic signature if configured.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
event:
type: string
enum: [payment.success, payment.failed]
example: payment.success
transaction_id:
type: integer
example: 98765
amount:
type: number
example: 1500.50
currency:
type: string
example: RUB
payment_method:
type: string
example: sbp
status:
type: string
example: completed
responses:
'200':
description: Your server must return a 200 OK status to confirm successful receipt of the webhook.