{"openapi":"3.1.0","info":{"title":"Paid.my Merchant API","version":"1.0","description":"Accept crypto payments with hosted checkout, invoices, static deposit addresses and automated payouts. All requests and responses are JSON. Monetary amounts are transmitted as strings to preserve decimal precision.","contact":{"url":"https://paid.my"}},"servers":[{"url":"https://paid.my/api/v1","description":"Production"}],"tags":[{"name":"Payments","description":"Invoices, hosted checkout and static deposit addresses."},{"name":"Payouts","description":"Send crypto from your balance to any external address."},{"name":"General","description":"Account-level reads — balances."},{"name":"Common","description":"Public reference data — no API key required."}],"components":{"securitySchemes":{"merchantKey":{"type":"apiKey","in":"header","name":"merchant-api-key","description":"Merchant-scope key (`paidmy_mk_*`, sandbox `paidmy_smk_*`). Payments and static addresses. Also accepted: `merchant_api_key` (OxaPay-compatible; some proxies strip underscore headers) or `Authorization: Bearer <key>`."},"payoutKey":{"type":"apiKey","in":"header","name":"payout-api-key","description":"Payout-scope key (`paidmy_pk_*`, sandbox `paidmy_spk_*`). Sending and reading payouts. Also accepted: `payout_api_key` or `Authorization: Bearer <key>`."},"generalKey":{"type":"apiKey","in":"header","name":"general-api-key","description":"General-scope key (`paidmy_gk_*`, sandbox `paidmy_sgk_*`). Account-level reads such as balances. Also accepted: `general_api_key` or `Authorization: Bearer <key>`."}},"schemas":{"Error":{"type":"object","properties":{"type":{"type":"string","description":"Error class.","enum":["validation_error","auth_error","forbidden","not_found","conflict","rate_limited","internal_error"]},"key":{"type":"string","description":"Offending field, when applicable.","nullable":true},"message":{"type":"string","description":"Human-readable message."}}},"Payment":{"type":"object","properties":{"track_id":{"type":"string","description":"Payment identifier.","example":"9YfKp2hQ7Wm3"},"status":{"type":"string","description":"See Payment statuses.","enum":["new","waiting","paying","paid","underpaid","expired","refunding","refunded","failed"],"example":"paid"},"amount":{"type":"string","description":"Invoice amount in `currency`. Decimal string — never parse into a float for accounting.","example":"100"},"currency":{"type":"string","description":"Invoice currency (fiat or crypto code).","example":"USD"},"pay_currency":{"type":"string","description":"Crypto the payer selected.","nullable":true,"example":"USDT"},"network":{"type":"string","description":"Chain the payer selected.","nullable":true,"example":"TRON"},"pay_amount":{"type":"string","description":"Exact crypto amount requested from the payer. Decimal string — never parse into a float for accounting.","example":"100.5"},"received_amount":{"type":"string","description":"Crypto received so far. Decimal string — never parse into a float for accounting.","example":"100.5"},"credited_amount":{"type":"string","description":"Amount credited to your balance after fees. Decimal string — never parse into a float for accounting.","example":"99.495"},"fee_amount":{"type":"string","description":"Platform fee. Decimal string — never parse into a float for accounting.","example":"1.005"},"rate":{"type":"string","description":"Locked crypto/fiat rate. Decimal string — never parse into a float for accounting.","example":"0.999"},"address":{"type":"string","description":"Deposit address allocated for this payment.","nullable":true},"memo":{"type":"string","description":"Memo/tag where the chain needs one.","nullable":true},"fee_paid_by_payer":{"type":"integer","description":"1 if the payer covered the fee.","enum":[0,1]},"under_paid_coverage":{"type":"number","description":"Accepted shortfall, percent (0–60)."},"lifetime":{"type":"integer","description":"Lifetime in minutes.","example":60},"order_id":{"type":"string","description":"Your order reference.","nullable":true},"email":{"type":"string","description":"Payer email.","nullable":true},"description":{"type":"string","description":"Description shown on the payment page.","nullable":true},"sandbox":{"type":"boolean","description":"True for sandbox payments."},"auto_convert":{"type":"boolean","description":"Whether the credited amount is auto-converted to USDT."},"conversion":{"type":"object","nullable":true,"description":"Auto-convert progress; null when not enabled or not yet credited. Conversion starts after the deposit is swept to our hot wallet (typically within ~15 minutes of payment).","properties":{"status":{"type":"string","description":"waiting_sweep | swapping | completed | failed | below_minimum","example":"completed"},"from_currency":{"type":"string","description":"Coin the customer paid in.","example":"SOL"},"to_currency":{"type":"string","description":"Always USDT.","example":"USDT"},"amount":{"type":"string","description":"Credited amount being converted. Decimal string — never parse into a float for accounting.","example":"0.5"},"to_amount":{"type":"string","description":"USDT credited once completed.","nullable":true,"example":"98.12"},"swap_track_id":{"type":"string","description":"Swap identifier (visible under Swap → history).","nullable":true},"note":{"type":"string","description":"Reason when failed / below minimum.","nullable":true},"completed_at":{"type":"integer","description":"Completion time. Unix timestamp (seconds).","example":1755169200,"nullable":true}}},"expired_at":{"type":"integer","description":"Expiry. Unix timestamp (seconds).","example":1755169200},"date":{"type":"integer","description":"Creation. Unix timestamp (seconds).","example":1755169200},"paid_at":{"type":"integer","description":"Paid time. Unix timestamp (seconds).","example":1755169200,"nullable":true},"txs":{"type":"array","description":"On-chain deposits matched to this payment.","items":{"type":"object","properties":{"tx_hash":{"type":"string","description":"Transaction hash."},"amount":{"type":"string","description":"Deposit amount. Decimal string — never parse into a float for accounting.","example":"100"},"confirmations":{"type":"integer","description":"Confirmations seen."},"status":{"type":"string","description":"detected | confirmed | credited | orphaned"},"date":{"type":"integer","description":"Detection time. Unix timestamp (seconds).","example":1755169200}}}}}},"Payout":{"type":"object","properties":{"track_id":{"type":"string","description":"Payout identifier.","example":"Zx9v8W7uQ6Tp"},"status":{"type":"string","description":"See Payout statuses.","enum":["processing","pending","confirming","confirmed","canceled","rejected","failed"],"example":"confirmed"},"amount":{"type":"string","description":"Amount delivered to the destination. Decimal string — never parse into a float for accounting.","example":"25"},"fee":{"type":"string","description":"Network fee charged on top. Decimal string — never parse into a float for accounting.","example":"1"},"currency":{"type":"string","description":"Currency code.","example":"USDT"},"network":{"type":"string","description":"Chain id.","example":"TRON"},"address":{"type":"string","description":"Destination address."},"memo":{"type":"string","description":"Memo/tag.","nullable":true},"tx_hash":{"type":"string","description":"On-chain transaction hash once broadcast.","nullable":true},"sandbox":{"type":"boolean","description":"True for sandbox payouts."},"date":{"type":"integer","description":"Creation. Unix timestamp (seconds).","example":1755169200},"confirmed_at":{"type":"integer","description":"Confirmation time. Unix timestamp (seconds).","example":1755169200,"nullable":true}}},"StaticAddress":{"type":"object","properties":{"track_id":{"type":"string","description":"Static address identifier.","example":"Ab3dEfGh1jKl"},"network":{"type":"string","description":"Chain id.","example":"TRON"},"currency":{"type":"string","description":"Restricted currency, or null for any enabled token on the chain.","nullable":true,"example":"USDT"},"address":{"type":"string","description":"The permanent deposit address."},"memo":{"type":"string","description":"Memo/tag where the chain needs one.","nullable":true},"have_tx":{"type":"boolean","description":"Whether any deposit has been received."},"sandbox":{"type":"boolean","description":"True for sandbox addresses."},"date":{"type":"integer","description":"Creation. Unix timestamp (seconds).","example":1755169200}}}}},"paths":{"/payment/invoice":{"post":{"operationId":"createInvoice","tags":["Payments"],"summary":"Create an invoice","description":"Creates a payment and returns a hosted checkout URL. Redirect your customer to `payment_url`; they pick a coin and network there, and the exact pay amount and deposit address are allocated at that moment.","security":[{"merchantKey":[]}],"x-idempotent":true,"x-rate-bucket":"60 / minute","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["amount"],"properties":{"amount":{"type":"number","description":"Invoice amount in `currency`. Must be > 0.","example":100},"currency":{"type":"string","description":"Fiat (USD, EUR, GBP) or a crypto code.","default":"USD"},"lifetime":{"type":"integer","description":"Minutes until expiry.","minimum":15,"maximum":2880,"default":60},"fee_paid_by_payer":{"oneOf":[{"type":"boolean"},{"type":"integer","enum":[0,1]}],"description":"Charge the platform fee to the payer. Default: API key setting, then account setting."},"under_paid_coverage":{"type":"number","description":"Accepted shortfall in percent. Default: API key setting, then account setting.","minimum":0,"maximum":60},"callback_url":{"type":"string","description":"Webhook target for this invoice. Default: API key callback URL, then account default.","format":"uri"},"return_url":{"type":"string","description":"Shown to the payer after payment.","format":"uri"},"order_id":{"type":"string","description":"Your reference. Unique per merchant — reuse returns 409.","maxLength":128},"email":{"type":"string","description":"Payer email for your records.","format":"email"},"description":{"type":"string","description":"Shown on the payment page.","maxLength":512},"thanks_message":{"type":"string","description":"Shown after payment completes.","maxLength":512},"to_currency":{"type":"string","description":"Set to `USDT` to auto-convert the credited amount to USDT once the deposit is swept (no extra Paid.my fee; swap.my spread applies). Omit to use the API key's Auto-convert setting.","enum":["USDT"]},"sandbox":{"type":"boolean","description":"Force sandbox (implied when using a sandbox key)."}}},"example":{"amount":100,"currency":"USD","order_id":"order-1042","callback_url":"https://yoursite.com/webhooks/paidmy"}}}},"responses":{"200":{"description":"Invoice created.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"track_id":{"type":"string","description":"Payment identifier."},"payment_url":{"type":"string","description":"Hosted checkout URL.","format":"uri"},"expired_at":{"type":"integer","description":"Expiry. Unix timestamp (seconds).","example":1755169200},"date":{"type":"integer","description":"Creation. Unix timestamp (seconds).","example":1755169200}}},"message":{"type":"string","description":"Human-readable result.","example":"Success"},"error":{"$ref":"#/components/schemas/Error","nullable":true},"status":{"type":"integer","description":"HTTP status mirrored in the body.","example":200},"version":{"type":"string","description":"API version.","example":"1.0"}},"required":["data","message","error","status","version"]},"example":{"data":{"track_id":"9YfKp2hQ7Wm3","payment_url":"https://paid.my/pay/9YfKp2hQ7Wm3","expired_at":1755172800,"date":1755169200},"message":"Success","error":null,"status":200,"version":"1.0"}}}},"400":{"description":"Validation error (`error.type = validation_error`, `error.key` names the field)."},"401":{"description":"Missing/invalid API key, or wrong scope (`auth_error`)."},"409":{"description":"`order_id` already used, or idempotency-key body mismatch."},"429":{"description":"Rate limited (`rate_limited`); honour the `Retry-After` header."}}}},"/payment/white-label":{"post":{"operationId":"createWhiteLabel","tags":["Payments"],"summary":"Create a white-label payment","description":"Creates a payment **and** locks the pay currency in one call, returning the deposit `address`, exact `pay_amount`, `memo`, locked `rate` and a `qr_code` image, so you can render the payment screen inside your own checkout or app instead of redirecting to the hosted page. Everything downstream (detection, crediting, webhooks, `GET /payment/{track_id}`) is identical to a normal invoice. The address is reserved only for `lifetime`; funds sent after expiry are not credited automatically.","security":[{"merchantKey":[]}],"x-idempotent":true,"x-rate-bucket":"60 / minute","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["amount","pay_currency"],"properties":{"amount":{"type":"number","description":"Invoice amount in `currency`. Must be > 0.","example":100},"currency":{"type":"string","description":"Fiat (USD, EUR, GBP) or a crypto code.","default":"USD"},"pay_currency":{"type":"string","description":"Crypto the payer will send.","example":"USDT"},"network":{"type":"string","description":"Chain id. Required when `pay_currency` is available on more than one network (the error lists them).","example":"TRON"},"lifetime":{"type":"integer","description":"Minutes the address stays valid.","minimum":15,"maximum":2880,"default":60},"fee_paid_by_payer":{"oneOf":[{"type":"boolean"},{"type":"integer","enum":[0,1]}],"description":"Charge the platform fee to the payer. Default: API key setting, then account setting."},"under_paid_coverage":{"type":"number","description":"Accepted shortfall in percent. Default: API key setting, then account setting.","minimum":0,"maximum":60},"callback_url":{"type":"string","description":"Webhook target for this payment.","format":"uri"},"order_id":{"type":"string","description":"Your reference. Unique per merchant; reuse returns 409.","maxLength":128},"email":{"type":"string","description":"Payer email for your records.","format":"email"},"description":{"type":"string","description":"Your note.","maxLength":512},"to_currency":{"type":"string","description":"Set to `USDT` to auto-convert the credited amount to USDT once swept. Omit to use the API key's Auto-convert setting.","enum":["USDT"]},"sandbox":{"type":"boolean","description":"Force sandbox (implied when using a sandbox key)."}}},"example":{"amount":100,"currency":"USD","pay_currency":"USDT","network":"TRON","order_id":"order-1043"}}}},"responses":{"200":{"description":"Payment created and address allocated. Same fields as *Get a payment*, plus `payment_url` and `qr_code`.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"track_id":{"type":"string","description":"Payment identifier.","example":"9YfKp2hQ7Wm3"},"status":{"type":"string","description":"See Payment statuses.","enum":["new","waiting","paying","paid","underpaid","expired","refunding","refunded","failed"],"example":"paid"},"amount":{"type":"string","description":"Invoice amount in `currency`. Decimal string — never parse into a float for accounting.","example":"100"},"currency":{"type":"string","description":"Invoice currency (fiat or crypto code).","example":"USD"},"pay_currency":{"type":"string","description":"Crypto the payer selected.","nullable":true,"example":"USDT"},"network":{"type":"string","description":"Chain the payer selected.","nullable":true,"example":"TRON"},"pay_amount":{"type":"string","description":"Exact crypto amount requested from the payer. Decimal string — never parse into a float for accounting.","example":"100.5"},"received_amount":{"type":"string","description":"Crypto received so far. Decimal string — never parse into a float for accounting.","example":"100.5"},"credited_amount":{"type":"string","description":"Amount credited to your balance after fees. Decimal string — never parse into a float for accounting.","example":"99.495"},"fee_amount":{"type":"string","description":"Platform fee. Decimal string — never parse into a float for accounting.","example":"1.005"},"rate":{"type":"string","description":"Locked crypto/fiat rate. Decimal string — never parse into a float for accounting.","example":"0.999"},"address":{"type":"string","description":"Deposit address allocated for this payment.","nullable":true},"memo":{"type":"string","description":"Memo/tag where the chain needs one.","nullable":true},"fee_paid_by_payer":{"type":"integer","description":"1 if the payer covered the fee.","enum":[0,1]},"under_paid_coverage":{"type":"number","description":"Accepted shortfall, percent (0–60)."},"lifetime":{"type":"integer","description":"Lifetime in minutes.","example":60},"order_id":{"type":"string","description":"Your order reference.","nullable":true},"email":{"type":"string","description":"Payer email.","nullable":true},"description":{"type":"string","description":"Description shown on the payment page.","nullable":true},"sandbox":{"type":"boolean","description":"True for sandbox payments."},"auto_convert":{"type":"boolean","description":"Whether the credited amount is auto-converted to USDT."},"conversion":{"type":"object","nullable":true,"description":"Auto-convert progress; null when not enabled or not yet credited. Conversion starts after the deposit is swept to our hot wallet (typically within ~15 minutes of payment).","properties":{"status":{"type":"string","description":"waiting_sweep | swapping | completed | failed | below_minimum","example":"completed"},"from_currency":{"type":"string","description":"Coin the customer paid in.","example":"SOL"},"to_currency":{"type":"string","description":"Always USDT.","example":"USDT"},"amount":{"type":"string","description":"Credited amount being converted. Decimal string — never parse into a float for accounting.","example":"0.5"},"to_amount":{"type":"string","description":"USDT credited once completed.","nullable":true,"example":"98.12"},"swap_track_id":{"type":"string","description":"Swap identifier (visible under Swap → history).","nullable":true},"note":{"type":"string","description":"Reason when failed / below minimum.","nullable":true},"completed_at":{"type":"integer","description":"Completion time. Unix timestamp (seconds).","example":1755169200,"nullable":true}}},"expired_at":{"type":"integer","description":"Expiry. Unix timestamp (seconds).","example":1755169200},"date":{"type":"integer","description":"Creation. Unix timestamp (seconds).","example":1755169200},"paid_at":{"type":"integer","description":"Paid time. Unix timestamp (seconds).","example":1755169200,"nullable":true},"txs":{"type":"array","description":"On-chain deposits matched to this payment.","items":{"type":"object","properties":{"tx_hash":{"type":"string","description":"Transaction hash."},"amount":{"type":"string","description":"Deposit amount. Decimal string — never parse into a float for accounting.","example":"100"},"confirmations":{"type":"integer","description":"Confirmations seen."},"status":{"type":"string","description":"detected | confirmed | credited | orphaned"},"date":{"type":"integer","description":"Detection time. Unix timestamp (seconds).","example":1755169200}}}},"payment_url":{"type":"string","description":"Hosted checkout URL, should you still want to offer it.","format":"uri"},"qr_code":{"type":"string","description":"SVG QR image of the wallet-app payment URI for `address` / `pay_amount`.","format":"uri"}}},"message":{"type":"string","description":"Human-readable result.","example":"Success"},"error":{"$ref":"#/components/schemas/Error","nullable":true},"status":{"type":"integer","description":"HTTP status mirrored in the body.","example":200},"version":{"type":"string","description":"API version.","example":"1.0"}},"required":["data","message","error","status","version"]},"example":{"data":{"track_id":"9YfKp2hQ7Wm3","status":"waiting","amount":"100","currency":"USD","pay_currency":"USDT","network":"TRON","pay_amount":"101.01","received_amount":"0","credited_amount":null,"fee_amount":"1.01","rate":"0.9999","address":"TQmZ1hVh7…","memo":null,"fee_paid_by_payer":1,"under_paid_coverage":0,"lifetime":60,"order_id":"order-1043","email":null,"description":null,"sandbox":false,"expired_at":1755172800,"date":1755169200,"paid_at":null,"txs":[],"payment_url":"https://paid.my/pay/9YfKp2hQ7Wm3","qr_code":"https://paid.my/api/pay/9YfKp2hQ7Wm3/qr"},"message":"Success","error":null,"status":200,"version":"1.0"}}}},"400":{"description":"Validation error. `error.key` is `pay_currency` (not accepted / rate unavailable) or `network` (ambiguous or unavailable; the message lists valid networks)."},"401":{"description":"Missing/invalid API key, or wrong scope (`auth_error`)."},"409":{"description":"`order_id` already used, or idempotency-key body mismatch."},"429":{"description":"Rate limited (`rate_limited`); honour the `Retry-After` header."}}}},"/payment/{track_id}":{"get":{"operationId":"getPayment","tags":["Payments"],"summary":"Get a payment","security":[{"merchantKey":[]}],"parameters":[{"name":"track_id","in":"path","required":true,"schema":{"type":"string","description":"Payment identifier."}}],"responses":{"200":{"description":"The payment.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Payment"},"message":{"type":"string","description":"Human-readable result.","example":"Success"},"error":{"$ref":"#/components/schemas/Error","nullable":true},"status":{"type":"integer","description":"HTTP status mirrored in the body.","example":200},"version":{"type":"string","description":"API version.","example":"1.0"}},"required":["data","message","error","status","version"]},"example":{"data":{"track_id":"9YfKp2hQ7Wm3","status":"paid","amount":"100","currency":"USD","pay_currency":"USDT","network":"TRON","pay_amount":"100.5","received_amount":"100.5","credited_amount":"99.495","fee_amount":"1.005","rate":"0.999","address":"TQmZ1hVh7…","memo":null,"fee_paid_by_payer":1,"under_paid_coverage":0,"lifetime":60,"order_id":"order-1042","email":"payer@example.com","description":"Pro plan","sandbox":false,"expired_at":1755172800,"date":1755169200,"paid_at":1755169980,"txs":[{"tx_hash":"6f9c2c6f6f0a…","amount":"100.5","confirmations":21,"status":"credited","date":1755169900}]},"message":"Success","error":null,"status":200,"version":"1.0"}}}},"400":{"description":"Validation error (`error.type = validation_error`, `error.key` names the field)."},"401":{"description":"Missing/invalid API key, or wrong scope (`auth_error`)."},"404":{"description":"Unknown `track_id`."},"429":{"description":"Rate limited (`rate_limited`); honour the `Retry-After` header."}}}},"/payment":{"get":{"operationId":"listPayments","tags":["Payments"],"summary":"List payments","security":[{"merchantKey":[]}],"parameters":[{"name":"page","in":"query","schema":{"type":"integer","description":"Page number.","minimum":1,"default":1}},{"name":"size","in":"query","schema":{"type":"integer","description":"Page size.","minimum":1,"maximum":200,"default":10}},{"name":"status","in":"query","schema":{"type":"string","description":"Filter by status, e.g. `paid`, `waiting`."}},{"name":"order_id","in":"query","schema":{"type":"string","description":"Filter by your order reference."}},{"name":"sort_type","in":"query","schema":{"type":"string","description":"Sort by creation date.","enum":["asc","desc"],"default":"desc"}}],"responses":{"200":{"description":"Paginated payments.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"list":{"type":"array","items":{"$ref":"#/components/schemas/Payment"}},"meta":{"type":"object","properties":{"page":{"type":"integer","description":"Current page."},"last_page":{"type":"integer","description":"Last page number."},"total":{"type":"integer","description":"Total items."}}}}},"message":{"type":"string","description":"Human-readable result.","example":"Success"},"error":{"$ref":"#/components/schemas/Error","nullable":true},"status":{"type":"integer","description":"HTTP status mirrored in the body.","example":200},"version":{"type":"string","description":"API version.","example":"1.0"}},"required":["data","message","error","status","version"]},"example":{"data":{"list":[{"track_id":"9YfKp2hQ7Wm3","status":"paid","amount":"100","currency":"USD"}],"meta":{"page":1,"last_page":4,"total":38}},"message":"Success","error":null,"status":200,"version":"1.0"}}}},"400":{"description":"Validation error (`error.type = validation_error`, `error.key` names the field)."},"401":{"description":"Missing/invalid API key, or wrong scope (`auth_error`)."},"429":{"description":"Rate limited (`rate_limited`); honour the `Retry-After` header."}}}},"/payment/accepted-currencies":{"get":{"operationId":"acceptedCurrencies","tags":["Payments"],"summary":"Accepted currencies","description":"Currency codes your account accepts (all enabled currencies, intersected with your dashboard allowlist if set).","security":[{"merchantKey":[]}],"responses":{"200":{"description":"Currency codes.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"list":{"type":"array","items":{"type":"string"}}}},"message":{"type":"string","description":"Human-readable result.","example":"Success"},"error":{"$ref":"#/components/schemas/Error","nullable":true},"status":{"type":"integer","description":"HTTP status mirrored in the body.","example":200},"version":{"type":"string","description":"API version.","example":"1.0"}},"required":["data","message","error","status","version"]},"example":{"data":{"list":["BTC","ETH","USDT","USDC","TRX","LTC","SOL","BNB","POL","GRAM"]},"message":"Success","error":null,"status":200,"version":"1.0"}}}},"400":{"description":"Validation error (`error.type = validation_error`, `error.key` names the field)."},"401":{"description":"Missing/invalid API key, or wrong scope (`auth_error`)."},"429":{"description":"Rate limited (`rate_limited`); honour the `Retry-After` header."}}}},"/payment/static-address":{"post":{"operationId":"createStaticAddress","tags":["Payments"],"summary":"Create a static address","description":"A permanent deposit address. Every confirmed deposit is credited individually (static-address fee applies) and fires a `static_address.deposit` webhook.","security":[{"merchantKey":[]}],"x-idempotent":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["network"],"properties":{"network":{"type":"string","description":"Chain id, e.g. TRON, ETH, BSC, POLYGON, BTC, LTC, SOL, TON.","example":"TRON"},"currency":{"type":"string","description":"Restrict to one currency; omit to accept any enabled token on the chain.","example":"USDT"},"callback_url":{"type":"string","description":"Webhook target for deposits.","format":"uri"},"order_id":{"type":"string","description":"Reporting only.","maxLength":128},"email":{"type":"string","description":"For your records.","format":"email"},"to_currency":{"type":"string","description":"Set to `USDT` to auto-convert every credited deposit to USDT. Omit to use the API key's Auto-convert setting.","enum":["USDT"]}}},"example":{"network":"TRON","currency":"USDT"}}}},"responses":{"200":{"description":"Address allocated.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"track_id":{"type":"string","description":"Identifier."},"network":{"type":"string","description":"Chain id."},"currency":{"type":"string","description":"Currency or null.","nullable":true},"address":{"type":"string","description":"Deposit address."},"memo":{"type":"string","description":"Memo/tag.","nullable":true},"date":{"type":"integer","description":"Creation. Unix timestamp (seconds).","example":1755169200}}},"message":{"type":"string","description":"Human-readable result.","example":"Success"},"error":{"$ref":"#/components/schemas/Error","nullable":true},"status":{"type":"integer","description":"HTTP status mirrored in the body.","example":200},"version":{"type":"string","description":"API version.","example":"1.0"}},"required":["data","message","error","status","version"]},"example":{"data":{"track_id":"Ab3dEfGh1jKl","network":"TRON","currency":"USDT","address":"TVxq8…","memo":null,"date":1755169200},"message":"Success","error":null,"status":200,"version":"1.0"}}}},"400":{"description":"Validation error (`error.type = validation_error`, `error.key` names the field)."},"401":{"description":"Missing/invalid API key, or wrong scope (`auth_error`)."},"429":{"description":"Rate limited (`rate_limited`); honour the `Retry-After` header."}}},"get":{"operationId":"listStaticAddresses","tags":["Payments"],"summary":"List static addresses","security":[{"merchantKey":[]}],"parameters":[{"name":"page","in":"query","schema":{"type":"integer","description":"Page number.","minimum":1,"default":1}},{"name":"size","in":"query","schema":{"type":"integer","description":"Page size.","minimum":1,"maximum":200,"default":10}},{"name":"network","in":"query","schema":{"type":"string","description":"Filter by chain id."}}],"responses":{"200":{"description":"Paginated static addresses.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"list":{"type":"array","items":{"$ref":"#/components/schemas/StaticAddress"}},"meta":{"type":"object","properties":{"page":{"type":"integer","description":"Current page."},"last_page":{"type":"integer","description":"Last page number."},"total":{"type":"integer","description":"Total items."}}}}},"message":{"type":"string","description":"Human-readable result.","example":"Success"},"error":{"$ref":"#/components/schemas/Error","nullable":true},"status":{"type":"integer","description":"HTTP status mirrored in the body.","example":200},"version":{"type":"string","description":"API version.","example":"1.0"}},"required":["data","message","error","status","version"]},"example":{"data":{"list":[{"track_id":"Ab3dEfGh1jKl","network":"TRON","currency":"USDT","address":"TVxq8…","memo":null,"have_tx":true,"sandbox":false,"date":1755169200}],"meta":{"page":1,"last_page":1,"total":3}},"message":"Success","error":null,"status":200,"version":"1.0"}}}},"400":{"description":"Validation error (`error.type = validation_error`, `error.key` names the field)."},"401":{"description":"Missing/invalid API key, or wrong scope (`auth_error`)."},"429":{"description":"Rate limited (`rate_limited`); honour the `Retry-After` header."}}}},"/payment/static-address/revoke":{"post":{"operationId":"revokeStaticAddress","tags":["Payments"],"summary":"Revoke a static address","description":"Deposits arriving after revocation are **not** credited automatically.","security":[{"merchantKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["address"],"properties":{"address":{"type":"string","description":"The address to revoke."}}},"example":{"address":"TVxq8…"}}}},"responses":{"200":{"description":"Revoked.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"revoked":{"type":"boolean","description":"Always true on success."}}},"message":{"type":"string","description":"Human-readable result.","example":"Success"},"error":{"$ref":"#/components/schemas/Error","nullable":true},"status":{"type":"integer","description":"HTTP status mirrored in the body.","example":200},"version":{"type":"string","description":"API version.","example":"1.0"}},"required":["data","message","error","status","version"]},"example":{"data":{"revoked":true},"message":"Success","error":null,"status":200,"version":"1.0"}}}},"400":{"description":"Validation error (`error.type = validation_error`, `error.key` names the field)."},"401":{"description":"Missing/invalid API key, or wrong scope (`auth_error`)."},"404":{"description":"Address not found."},"429":{"description":"Rate limited (`rate_limited`); honour the `Retry-After` header."}}}},"/payout":{"post":{"operationId":"createPayout","tags":["Payouts"],"summary":"Send a payout","description":"Sends crypto to an external address. `amount + fee` is held from your available balance immediately and settled on confirmation (or released on failure). Use an `Idempotency-Key` — retries are then safe.","security":[{"payoutKey":[]}],"x-idempotent":true,"x-rate-bucket":"10 / minute","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["address","currency","amount"],"properties":{"address":{"type":"string","description":"Destination address (the recipient's wallet).","example":"TXYZ…"},"currency":{"type":"string","description":"Currency code.","example":"USDT"},"amount":{"type":"number","description":"Amount to deliver — the fee is charged on top.","example":25},"network":{"type":"string","description":"Chain id. Required when the currency exists on more than one enabled network.","example":"TRON"},"memo":{"type":"string","description":"Memo/tag for chains that use one (e.g. TON exchanges).","maxLength":256},"callback_url":{"type":"string","description":"Webhook target for this payout.","format":"uri"},"description":{"type":"string","description":"Your note.","maxLength":512}}},"example":{"address":"TXYZ…","currency":"USDT","amount":25,"network":"TRON"}}}},"responses":{"200":{"description":"Accepted for processing.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"track_id":{"type":"string","description":"Payout identifier."},"status":{"type":"string","description":"Always `processing` on creation."}}},"message":{"type":"string","description":"Human-readable result.","example":"Success"},"error":{"$ref":"#/components/schemas/Error","nullable":true},"status":{"type":"integer","description":"HTTP status mirrored in the body.","example":200},"version":{"type":"string","description":"API version.","example":"1.0"}},"required":["data","message","error","status","version"]},"example":{"data":{"track_id":"Zx9v8W7uQ6Tp","status":"processing"},"message":"Success","error":null,"status":200,"version":"1.0"}}}},"400":{"description":"Validation error. `error.key` is `amount` (insufficient balance), `network` (unavailable pair), `below_minimum`, or `not_allowlisted`."},"401":{"description":"Missing/invalid API key, or wrong scope (`auth_error`)."},"409":{"description":"Idempotency-key body mismatch or request still processing."},"429":{"description":"Rate limited (`rate_limited`); honour the `Retry-After` header."}}},"get":{"operationId":"listPayouts","tags":["Payouts"],"summary":"List payouts","security":[{"payoutKey":[]}],"parameters":[{"name":"page","in":"query","schema":{"type":"integer","description":"Page number.","minimum":1,"default":1}},{"name":"size","in":"query","schema":{"type":"integer","description":"Page size.","minimum":1,"maximum":200,"default":10}},{"name":"status","in":"query","schema":{"type":"string","description":"Filter by status."}}],"responses":{"200":{"description":"Paginated payouts.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"list":{"type":"array","items":{"$ref":"#/components/schemas/Payout"}},"meta":{"type":"object","properties":{"page":{"type":"integer","description":"Current page."},"last_page":{"type":"integer","description":"Last page number."},"total":{"type":"integer","description":"Total items."}}}}},"message":{"type":"string","description":"Human-readable result.","example":"Success"},"error":{"$ref":"#/components/schemas/Error","nullable":true},"status":{"type":"integer","description":"HTTP status mirrored in the body.","example":200},"version":{"type":"string","description":"API version.","example":"1.0"}},"required":["data","message","error","status","version"]}}}},"400":{"description":"Validation error (`error.type = validation_error`, `error.key` names the field)."},"401":{"description":"Missing/invalid API key, or wrong scope (`auth_error`)."},"429":{"description":"Rate limited (`rate_limited`); honour the `Retry-After` header."}}}},"/payout/estimate-fee":{"post":{"operationId":"estimatePayoutFee","tags":["Payouts"],"summary":"Estimate the fee","security":[{"payoutKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["currency","network","amount"],"properties":{"currency":{"type":"string","description":"Currency code."},"network":{"type":"string","description":"Chain id."},"amount":{"type":"number","description":"Amount to deliver."}}},"example":{"currency":"USDT","network":"TRON","amount":25}}}},"responses":{"200":{"description":"Fee quote.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"currency":{"type":"string","description":"Currency."},"network":{"type":"string","description":"Chain."},"amount":{"type":"number","description":"Requested amount."},"fee":{"type":"number","description":"Flat network fee."},"total_debit":{"type":"number","description":"Amount + fee held from your balance."},"min_payout":{"type":"number","description":"Minimum payout on this network."}}},"message":{"type":"string","description":"Human-readable result.","example":"Success"},"error":{"$ref":"#/components/schemas/Error","nullable":true},"status":{"type":"integer","description":"HTTP status mirrored in the body.","example":200},"version":{"type":"string","description":"API version.","example":"1.0"}},"required":["data","message","error","status","version"]},"example":{"data":{"currency":"USDT","network":"TRON","amount":25,"fee":1,"total_debit":26,"min_payout":2},"message":"Success","error":null,"status":200,"version":"1.0"}}}},"400":{"description":"Validation error (`error.type = validation_error`, `error.key` names the field)."},"401":{"description":"Missing/invalid API key, or wrong scope (`auth_error`)."},"429":{"description":"Rate limited (`rate_limited`); honour the `Retry-After` header."}}}},"/payout/{track_id}":{"get":{"operationId":"getPayout","tags":["Payouts"],"summary":"Get a payout","security":[{"payoutKey":[]}],"parameters":[{"name":"track_id","in":"path","required":true,"schema":{"type":"string","description":"Payout identifier."}}],"responses":{"200":{"description":"The payout.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Payout"},"message":{"type":"string","description":"Human-readable result.","example":"Success"},"error":{"$ref":"#/components/schemas/Error","nullable":true},"status":{"type":"integer","description":"HTTP status mirrored in the body.","example":200},"version":{"type":"string","description":"API version.","example":"1.0"}},"required":["data","message","error","status","version"]},"example":{"data":{"track_id":"Zx9v8W7uQ6Tp","status":"confirmed","amount":"25","fee":"1","currency":"USDT","network":"TRON","address":"TXYZ…","memo":null,"tx_hash":"b1946ac9…","sandbox":false,"date":1755169200,"confirmed_at":1755169500},"message":"Success","error":null,"status":200,"version":"1.0"}}}},"400":{"description":"Validation error (`error.type = validation_error`, `error.key` names the field)."},"401":{"description":"Missing/invalid API key, or wrong scope (`auth_error`)."},"404":{"description":"Unknown `track_id`."},"429":{"description":"Rate limited (`rate_limited`); honour the `Retry-After` header."}}}},"/general/account/balance":{"get":{"operationId":"accountBalance","tags":["General"],"summary":"Account balances","description":"Every currency balance on your account. `available` is spendable; `pending` is held by in-flight payouts and swaps. `usd` is an indicative valuation at current display prices, not a settlement rate. Sandbox keys return sandbox balances.","security":[{"generalKey":[]}],"responses":{"200":{"description":"Balances keyed by currency.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"balances":{"type":"object","description":"Keyed by currency symbol. Includes zero rows for every enabled currency.","additionalProperties":{"type":"object","properties":{"available":{"type":"string","description":"Spendable balance. Decimal string — never parse into a float for accounting.","example":"120.5"},"pending":{"type":"string","description":"Held by in-flight payouts/swaps. Decimal string — never parse into a float for accounting.","example":"0"},"usd":{"type":"string","description":"Indicative USD value of `available`, or null if no price.","nullable":true,"example":"120.38"}}}},"total_usd":{"type":"string","description":"Sum of all `usd` values. Decimal string — never parse into a float for accounting.","example":"1204.12"},"sandbox":{"type":"boolean","description":"True when queried with a sandbox key."}}},"message":{"type":"string","description":"Human-readable result.","example":"Success"},"error":{"$ref":"#/components/schemas/Error","nullable":true},"status":{"type":"integer","description":"HTTP status mirrored in the body.","example":200},"version":{"type":"string","description":"API version.","example":"1.0"}},"required":["data","message","error","status","version"]},"example":{"data":{"balances":{"BTC":{"available":"0.0125","pending":"0","usd":"802.88"},"USDT":{"available":"120.5","pending":"25","usd":"120.38"},"GRAM":{"available":"0","pending":"0","usd":"0.00"}},"total_usd":"923.26","sandbox":false},"message":"Success","error":null,"status":200,"version":"1.0"}}}},"400":{"description":"Validation error (`error.type = validation_error`, `error.key` names the field)."},"401":{"description":"Missing/invalid API key, or wrong scope (`auth_error`)."},"429":{"description":"Rate limited (`rate_limited`); honour the `Retry-After` header."}}}},"/common/currencies":{"get":{"operationId":"currencies","tags":["Common"],"summary":"Supported currencies","description":"Every enabled currency with its networks, minimums and payout fees. Public — no API key.","responses":{"200":{"description":"Currency map.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","description":"Keyed by currency symbol.","additionalProperties":{"type":"object","properties":{"symbol":{"type":"string","description":"Currency symbol.","example":"USDT"},"name":{"type":"string","description":"Display name.","example":"Tether"},"status":{"type":"boolean","description":"Enabled."},"networks":{"type":"object","description":"Keyed by chain id.","additionalProperties":{"type":"object","properties":{"network":{"type":"string","description":"Chain id.","example":"TRON"},"name":{"type":"string","description":"Chain display name."},"required_confirmations":{"type":"integer","description":"Confirmations before credit."},"contract_address":{"type":"string","description":"Token contract, or null for native coins.","nullable":true},"deposit_min":{"type":"string","description":"Minimum deposit. Decimal string — never parse into a float for accounting.","example":"1"},"withdraw_min":{"type":"string","description":"Minimum payout. Decimal string — never parse into a float for accounting.","example":"5"},"withdraw_fee":{"type":"string","description":"Flat payout fee. Decimal string — never parse into a float for accounting.","example":"1"}}}}}}},"message":{"type":"string","description":"Human-readable result.","example":"Success"},"error":{"$ref":"#/components/schemas/Error","nullable":true},"status":{"type":"integer","description":"HTTP status mirrored in the body.","example":200},"version":{"type":"string","description":"API version.","example":"1.0"}},"required":["data","message","error","status","version"]},"example":{"data":{"USDT":{"symbol":"USDT","name":"Tether","status":true,"networks":{"TRON":{"network":"TRON","name":"TRON","required_confirmations":1,"contract_address":"TR7NHqje…","deposit_min":"0.5","withdraw_min":"2","withdraw_fee":"1"}}}},"message":"Success","error":null,"status":200,"version":"1.0"}}}}}}},"/common/prices":{"get":{"operationId":"prices","tags":["Common"],"summary":"Prices","description":"USD price per unit for every enabled currency, as strings. Public — no API key.","responses":{"200":{"description":"Price map.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","additionalProperties":{"type":"string"}},"message":{"type":"string","description":"Human-readable result.","example":"Success"},"error":{"$ref":"#/components/schemas/Error","nullable":true},"status":{"type":"integer","description":"HTTP status mirrored in the body.","example":200},"version":{"type":"string","description":"API version.","example":"1.0"}},"required":["data","message","error","status","version"]},"example":{"data":{"BTC":"64230.10","ETH":"3120.55","USDT":"1.00","GRAM":"1.40"},"message":"Success","error":null,"status":200,"version":"1.0"}}}}}}}},"webhooks":{"invoice.paid":{"post":{"operationId":"webhookInvoicePaid","tags":["Webhooks"],"summary":"invoice.paid / invoice.paying / invoice.underpaid","description":"POSTed to the invoice's `callback_url` (or your default) when a payment changes state. Signed with HMAC-SHA512 of the raw body in the `HMAC` and `paidmy-signature` headers; `paidmy-event` carries the event type, `paidmy-delivery-id` is unique per delivery. Respond 2xx within 10s.","requestBody":{"content":{"application/json":{"schema":{"type":"object"},"example":{"type":"invoice","track_id":"9YfKp2hQ7Wm3","status":"Paid","amount":"100","currency":"USD","pay_currency":"USDT","pay_amount":"100.5","received_amount":"100.5","fee_paid_by_payer":1,"under_paid_coverage":0,"order_id":"order-1042","email":"payer@example.com","description":"Pro plan","sandbox":false,"date":1755169900}}}},"responses":{"200":{"description":"Acknowledge with any 2xx."}}}},"static_address.deposit":{"post":{"operationId":"webhookStaticDeposit","tags":["Webhooks"],"summary":"static_address.deposit","description":"A deposit on a static address was credited.","requestBody":{"content":{"application/json":{"schema":{"type":"object"},"example":{"type":"static_address","track_id":"Ab3dEfGh1jKl","status":"Paid","address":"TVxq8…","amount":"50","credited_amount":"49","fee":"1","currency":"USDT","network":"TRON","tx_hash":"6f9c2c6f6f0a…","sandbox":false,"date":1755169900}}}},"responses":{"200":{"description":"Acknowledge with any 2xx."}}}},"payout.confirmed":{"post":{"operationId":"webhookPayout","tags":["Webhooks"],"summary":"payout.confirmed / payout.failed","description":"For `payout.failed`, `status` is `Failed` and the held amount + fee is returned to your available balance.","requestBody":{"content":{"application/json":{"schema":{"type":"object"},"example":{"type":"payout","track_id":"Zx9v8W7uQ6Tp","status":"Confirmed","amount":"25","fee":"1","currency":"USDT","network":"TRON","address":"TXYZ…","memo":null,"tx_hash":"b1946ac9…","description":null,"sandbox":false,"date":1755169950}}}},"responses":{"200":{"description":"Acknowledge with any 2xx."}}}}}}