{ "openapi": "3.1.0", "info": { "title": "Monetasync API", "version": "0.2.0", "description": "Crypto payment acceptance. Every monetary value is a string holding an integer count of the asset's smallest unit; parse with BigInt, never with Number()." }, "servers": [ { "url": "https://www.monetasync.com" } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Your sk_test_ or sk_live_ secret key" } }, "schemas": { "Payment": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "CREATED", "ACTIVE", "DETECTED", "CONFIRMING", "PARTIALLY_PAID", "PAID", "OVERPAID", "EXPIRED", "LATE_PAYMENT", "CANCELLED", "REVIEW_REQUIRED", "REFUND_REQUESTED" ] }, "mode": { "type": "string", "enum": [ "test", "live" ] }, "order_id": { "type": "string", "nullable": true }, "display_currency": { "type": "string" }, "display_amount_minor": { "type": "string", "description": "Display-currency minor units, integer string" }, "asset": { "type": "string", "nullable": true }, "network": { "type": "string", "nullable": true }, "required_amount": { "type": "string", "nullable": true, "description": "Crypto base units, integer string" }, "amount_received": { "type": "string", "description": "Crypto base units, integer string" }, "platform_fee": { "type": "string", "nullable": true }, "merchant_credit": { "type": "string", "nullable": true }, "deposit_address": { "type": "string", "nullable": true }, "checkout_url": { "type": "string" } } } } }, "security": [ { "bearerAuth": [] } ], "paths": { "/v1/payments": { "post": { "summary": "Create a payment", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Replaying the same key returns the original response instead of creating a second payment." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "amount" ], "properties": { "amount": { "type": "string", "pattern": "^\\d+(\\.\\d{1,2})?$", "example": "100.00" }, "display_currency": { "type": "string", "default": "USD" }, "order_id": { "type": "string" }, "description": { "type": "string" }, "customer_email": { "type": "string" }, "fee_payer": { "type": "string", "enum": [ "customer", "merchant" ], "default": "customer" }, "success_url": { "type": "string" }, "cancel_url": { "type": "string" }, "locale": { "type": "string", "enum": [ "ar", "en" ] }, "metadata": { "type": "object", "additionalProperties": true } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Unauthorized" } } }, "get": { "summary": "List recent payments", "responses": { "200": { "description": "OK" } } } }, "/v1/payments/{id}": { "get": { "summary": "Retrieve a payment", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" } } } }, "404": { "description": "Not found" } } } }, "/v1/balances": { "get": { "summary": "Merchant balances, derived from the ledger", "responses": { "200": { "description": "OK" } } } }, "/v1/networks": { "get": { "summary": "Per-network operational state", "security": [], "responses": { "200": { "description": "OK" } } } }, "/v1/assets": { "get": { "summary": "Asset and network pairs", "security": [], "responses": { "200": { "description": "OK" } } } }, "/v1/payment-links": { "post": { "summary": "Create a payment link", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Replaying the same key returns the original response with idempotent-replay: true. Reusing a key with a different body returns 409 rather than silently replaying." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "title" ], "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "amount": { "type": "string", "pattern": "^\\d+(\\.\\d{1,2})?$", "example": "150.00", "description": "Required for kind \"fixed\". Display-currency decimal string." }, "display_currency": { "type": "string", "default": "USD" }, "kind": { "type": "string", "enum": [ "fixed", "customer_amount", "donation", "product" ], "default": "fixed" }, "accepted_assets": { "type": "array", "items": { "type": "string" } }, "accepted_networks": { "type": "array", "items": { "type": "string" } }, "require_email": { "type": "boolean", "default": false }, "redirect_url": { "type": "string" }, "single_use": { "type": "boolean", "default": false }, "max_uses": { "type": "integer" }, "expires_at": { "type": "string", "format": "date-time" }, "metadata": { "type": "object", "additionalProperties": true } } } } } }, "responses": { "201": { "description": "Created; `url` is the shareable link" }, "400": { "description": "Invalid request" }, "409": { "description": "Idempotency-Key reused with a different body" } } }, "get": { "summary": "List payment links", "responses": { "200": { "description": "OK" } } } }, "/v1/payment-links/{id}": { "get": { "summary": "Retrieve a payment link", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "404": { "description": "Not found" } } }, "delete": { "summary": "Archive a payment link", "description": "Archived, not deleted: links already sent to customers must keep resolving and their payment history must stay intact.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Archived" }, "404": { "description": "Not found" } } } }, "/v1/payouts": { "post": { "summary": "Request a payout", "description": "The destination must already be an allowlisted payout address that has finished its cooldown. Declines for business reasons (insufficient balance, verification required, address in cooldown) return 422 with a bilingual message.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Replaying the same key returns the original response with idempotent-replay: true. Reusing a key with a different body returns 409 rather than silently replaying." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "asset", "network", "amount_base", "destination" ], "properties": { "asset": { "type": "string", "example": "USDT" }, "network": { "type": "string", "example": "tron" }, "amount_base": { "type": "string", "pattern": "^\\d+$", "example": "1000000", "description": "Integer count of the asset's smallest unit. 1000000 is 1 USDT at 6 decimals. Decimal strings are rejected so no rounding can happen here." }, "destination": { "type": "string" }, "memo": { "type": "string" }, "fee_payer": { "type": "string", "enum": [ "merchant", "platform" ], "default": "merchant" }, "execution_key": { "type": "string", "description": "Your own key for this logical payout. Prevents a resubmitted form paying twice." } } } } } }, "responses": { "201": { "description": "Payout requested" }, "400": { "description": "Invalid request" }, "422": { "description": "Declined by a business rule" } } }, "get": { "summary": "List payouts", "responses": { "200": { "description": "OK" } } } }, "/v1/payouts/{id}": { "get": { "summary": "Retrieve a payout", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "404": { "description": "Not found" } } } }, "/v1/payout-addresses": { "post": { "summary": "Add a payout address", "description": "A new address serves a 24-hour cooldown before it can receive a payout. This is the control that stops a stolen API key draining a balance to a fresh address.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Replaying the same key returns the original response with idempotent-replay: true. Reusing a key with a different body returns 409 rather than silently replaying." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "asset", "network", "address" ], "properties": { "asset": { "type": "string" }, "network": { "type": "string" }, "address": { "type": "string" }, "label": { "type": "string" }, "memo": { "type": "string" } } } } } }, "responses": { "201": { "description": "Created, in cooldown" }, "422": { "description": "Rejected" } } }, "get": { "summary": "List payout addresses", "responses": { "200": { "description": "OK" } } } }, "/v1/payout-addresses/{id}": { "delete": { "summary": "Remove a payout address", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Removed" }, "404": { "description": "Not found" } } } }, "/v1/webhook-endpoints": { "post": { "summary": "Register a webhook endpoint", "description": "The signing secret is returned in this response and never again. Store it immediately.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Replaying the same key returns the original response with idempotent-replay: true. Reusing a key with a different body returns 409 rather than silently replaying." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri", "description": "Must be https://" }, "events": { "type": "array", "items": { "type": "string" }, "default": [ "*" ], "description": "Event types to receive, or [\"*\"] for all." } } } } } }, "responses": { "201": { "description": "Created; contains the one-time secret" }, "400": { "description": "Invalid url or event type" } } }, "get": { "summary": "List webhook endpoints", "description": "Secrets are never included.", "responses": { "200": { "description": "OK" } } } }, "/v1/webhook-endpoints/{id}": { "delete": { "summary": "Delete a webhook endpoint", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deleted" }, "404": { "description": "Not found" } } } }, "/v1/events": { "get": { "summary": "Webhook delivery log", "description": "Every delivery to your endpoints with its attempt count and last response code.", "responses": { "200": { "description": "OK" } } } }, "/v1/verification": { "get": { "summary": "Verification status", "description": "Whether payouts are currently open, and how close cumulative deposits are to the threshold that makes identity verification mandatory. Documents are uploaded from the dashboard only.", "responses": { "200": { "description": "OK" } } } } } }