{"openapi":"3.1.0","info":{"title":"NOMA Merchant API","description":"Server-to-server merchant integration. Guides: [Getting started](https://nomapay.io/developers) · [Acquiring](https://nomapay.io/developers/acquiring) · [QR Payment](https://nomapay.io/developers/qr-payment) · [Transfers](https://nomapay.io/developers/transfers). Sign requests with x-api-key, x-timestamp (Unix milliseconds) and x-signature = hex(HMAC-SHA256(api_secret, METHOD + PATH_WITHOUT_QUERY + timestamp + SHA256hex(raw_body))). Keep secrets on your backend. Client certificates are not required. ","version":"1.0.1"},"paths":{"/v1/payments/methods":{"get":{"tags":["Acquiring"],"summary":"Available payment methods","description":"Methods your store can accept right now (for example SBP, cards, wallets, crypto), with currency and amount limits in minor units.","operationId":"list_payment_methods","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"parameters":[{"name":"x-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"x-timestamp","in":"header","required":true,"schema":{"type":"string"}},{"name":"x-signature","in":"header","required":true,"schema":{"type":"string"}}]}},"/v1/payments":{"post":{"tags":["Acquiring"],"summary":"Create a payment","description":"Creates a payment for your customer with a method from GET /v1/payments/methods. Returns checkout data and the public checkout token. Requires Idempotency-Key.","operationId":"create_payment","responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"parameters":[{"name":"x-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"x-timestamp","in":"header","required":true,"schema":{"type":"string"}},{"name":"x-signature","in":"header","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":128}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"method":{"description":"Method from GET /v1/payments/methods","pattern":"^(sbp|mir|visa|mastercard|apple_pay|google_pay|usdt|usdt_trc|usdt_bsc|usdt_erc|btc)$","title":"Method","type":"string"},"amount_minor":{"description":"Сумма в minor units (копейки/центы)","exclusiveMinimum":0,"maximum":9223372036854775807,"title":"Amount Minor","type":"integer"},"description":{"anyOf":[{"maxLength":255,"type":"string"},{"type":"null"}],"title":"Description"},"metadata":{"anyOf":[{"type":"object"},{"type":"null"}],"title":"Metadata"},"customer_email":{"anyOf":[{"maxLength":254,"pattern":"^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$","type":"string"},{"type":"null"}],"description":"Buyer's email; required when the method has requires_customer_email: true","title":"Customer Email"},"customer_phone":{"anyOf":[{"description":"Buyer's phone in international format, e.g. +79001234567","maxLength":16,"pattern":"^\\+[1-9]\\d{6,14}$","type":"string"},{"type":"null"}],"description":"Buyer's phone in international format (+79001234567); required when the method has requires_customer_phone: true","title":"Customer Phone"},"merchant_order_id":{"anyOf":[{"maxLength":128,"minLength":1,"type":"string"},{"type":"null"}],"description":"Your order number (optional); returned in responses and webhooks","title":"Merchant Order Id"}},"required":["method","amount_minor"],"title":"CreatePaymentRequest","type":"object"}}}}}},"/v1/payments/{payment_id}":{"get":{"tags":["Acquiring"],"summary":"Get a payment","description":"Current payment status: pending, paid, paid_late, expired or cancelled.","operationId":"get_payment","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"parameters":[{"name":"x-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"x-timestamp","in":"header","required":true,"schema":{"type":"string"}},{"name":"x-signature","in":"header","required":true,"schema":{"type":"string"}},{"name":"payment_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/v1/terminal/payments/methods":{"get":{"tags":["QR Terminal"],"summary":"Available QR Terminal methods","description":"Methods your store can accept through QR Terminal right now, with currency and amount limits in minor units.","operationId":"list_terminal_methods","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"parameters":[{"name":"x-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"x-timestamp","in":"header","required":true,"schema":{"type":"string"}},{"name":"x-signature","in":"header","required":true,"schema":{"type":"string"}}]}},"/v1/terminal/payments":{"post":{"tags":["QR Terminal"],"summary":"Issue a QR Terminal payment","description":"Creates a payment through QR Terminal with a method from GET /v1/terminal/payments/methods. Returns the QR payload and the public checkout token. Requires Idempotency-Key.","operationId":"create_terminal_payment","responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"parameters":[{"name":"x-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"x-timestamp","in":"header","required":true,"schema":{"type":"string"}},{"name":"x-signature","in":"header","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":128}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"method":{"description":"Method from GET /v1/payments/methods","pattern":"^(sbp|mir|visa|mastercard|apple_pay|google_pay|usdt|usdt_trc|usdt_bsc|usdt_erc|btc)$","title":"Method","type":"string"},"amount_minor":{"description":"Сумма в minor units (копейки/центы)","exclusiveMinimum":0,"maximum":9223372036854775807,"title":"Amount Minor","type":"integer"},"description":{"anyOf":[{"maxLength":255,"type":"string"},{"type":"null"}],"title":"Description"},"metadata":{"anyOf":[{"type":"object"},{"type":"null"}],"title":"Metadata"},"customer_email":{"anyOf":[{"maxLength":254,"pattern":"^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$","type":"string"},{"type":"null"}],"description":"Buyer's email; required when the method has requires_customer_email: true","title":"Customer Email"},"customer_phone":{"anyOf":[{"description":"Buyer's phone in international format, e.g. +79001234567","maxLength":16,"pattern":"^\\+[1-9]\\d{6,14}$","type":"string"},{"type":"null"}],"description":"Buyer's phone in international format (+79001234567); required when the method has requires_customer_phone: true","title":"Customer Phone"},"merchant_order_id":{"anyOf":[{"maxLength":128,"minLength":1,"type":"string"},{"type":"null"}],"description":"Your order number (optional); returned in responses and webhooks","title":"Merchant Order Id"}},"required":["method","amount_minor"],"title":"CreatePaymentRequest","type":"object"}}}}}},"/v1/terminal/payments/{payment_id}":{"get":{"tags":["QR Terminal"],"summary":"Get a QR Terminal payment","description":"Current payment status: pending, paid, paid_late, expired or cancelled.","operationId":"get_terminal_payment","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"parameters":[{"name":"x-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"x-timestamp","in":"header","required":true,"schema":{"type":"string"}},{"name":"x-signature","in":"header","required":true,"schema":{"type":"string"}},{"name":"payment_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/v1/payouts/cny":{"post":{"tags":["Transfers"],"summary":"Create a CNY Alipay transfer (deprecated)","description":"Deprecated: use POST /v1/transfers with currency CNY and method alipay. Kept for existing integrations; sends payout.* webhooks.","operationId":"create_cny_payout","deprecated":true,"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"parameters":[{"name":"x-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"x-timestamp","in":"header","required":true,"schema":{"type":"string"}},{"name":"x-signature","in":"header","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":128}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"amount_minor":{"description":"CNY fen (100 = 1 yuan)","exclusiveMinimum":0,"maximum":9223372036854775807,"title":"Amount Minor","type":"integer"},"payment_details":{"description":"Alipay recipient details","maxLength":2048,"minLength":1,"title":"Payment Details","type":"string"},"external_user_id":{"maxLength":255,"minLength":1,"title":"External User Id","type":"string"},"max_debit_usdt_micro":{"description":"Maximum total debit including fee, in millionths of USDT","exclusiveMinimum":0,"maximum":9223372036854775807,"title":"Max Debit Usdt Micro","type":"integer"},"merchant_order_id":{"anyOf":[{"maxLength":128,"minLength":1,"type":"string"},{"type":"null"}],"description":"Your order number (optional); returned in responses and webhooks","title":"Merchant Order Id"}},"required":["amount_minor","payment_details","external_user_id","max_debit_usdt_micro"],"title":"CreateCnyPayoutRequest","type":"object"}}}}}},"/v1/payouts/methods":{"get":{"tags":["QR Payment"],"summary":"Available QR methods","description":"Local QR payment methods your store can use, by country and currency.","operationId":"list_qr_methods","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"parameters":[{"name":"x-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"x-timestamp","in":"header","required":true,"schema":{"type":"string"}},{"name":"x-signature","in":"header","required":true,"schema":{"type":"string"}}]}},"/v1/payouts":{"post":{"tags":["QR Payment"],"summary":"Pay a QR code","description":"Pays a local QR code from your payQR deposit. The rate, spread and fee are fixed at creation. Requires Idempotency-Key.","operationId":"create_payout","responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"parameters":[{"name":"x-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"x-timestamp","in":"header","required":true,"schema":{"type":"string"}},{"name":"x-signature","in":"header","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":128}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"method":{"default":"sbp","description":"Local QR method from GET /v1/payouts/methods","pattern":"^[a-z][a-z0-9_]{0,31}$","title":"Method","type":"string"},"qr_payload":{"maxLength":2048,"minLength":8,"title":"Qr Payload","type":"string"},"amount_minor":{"description":"Amount in minor units of the QR currency","exclusiveMinimum":0,"maximum":9223372036854775807,"title":"Amount Minor","type":"integer"},"description":{"anyOf":[{"maxLength":255,"type":"string"},{"type":"null"}],"title":"Description"},"metadata":{"anyOf":[{"type":"object"},{"type":"null"}],"title":"Metadata"},"merchant_order_id":{"anyOf":[{"maxLength":128,"minLength":1,"type":"string"},{"type":"null"}],"description":"Your order number (optional); returned in responses and webhooks","title":"Merchant Order Id"}},"required":["qr_payload","amount_minor"],"title":"CreatePayoutRequest","type":"object"}}}}}},"/v1/payouts/{payout_id}":{"get":{"tags":["QR Payment"],"summary":"Get a QR payment","description":"Status: pending, processing, needs_review, completed, failed or cancelled.","operationId":"get_payout","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"parameters":[{"name":"x-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"x-timestamp","in":"header","required":true,"schema":{"type":"string"}},{"name":"x-signature","in":"header","required":true,"schema":{"type":"string"}},{"name":"payout_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/v1/payouts/{payout_id}/cancel":{"post":{"tags":["QR Payment"],"summary":"Cancel a QR payment","description":"Only while the status is pending; the reserve returns to the deposit.","operationId":"cancel_payout","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"parameters":[{"name":"x-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"x-timestamp","in":"header","required":true,"schema":{"type":"string"}},{"name":"x-signature","in":"header","required":true,"schema":{"type":"string"}},{"name":"payout_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/v1/transfers/currencies":{"get":{"tags":["Transfers"],"summary":"Available currencies and methods","description":"Currencies and methods your store can use right now, with amount limits in minor units of each currency.","operationId":"list_transfer_currencies","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"parameters":[{"name":"x-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"x-timestamp","in":"header","required":true,"schema":{"type":"string"}},{"name":"x-signature","in":"header","required":true,"schema":{"type":"string"}}]}},"/v1/transfers":{"post":{"tags":["Transfers"],"summary":"Create a transfer","description":"Transfers funds to a recipient from your payout deposit. The rate, spread and fee are fixed at creation. Requires Idempotency-Key and a unique external_id.","operationId":"create_transfer","responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"parameters":[{"name":"x-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"x-timestamp","in":"header","required":true,"schema":{"type":"string"}},{"name":"x-signature","in":"header","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":128}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"description":"POST /v1/transfers: a transfer to a recipient in the given currency.","properties":{"currency":{"description":"ISO 4217 currency, e.g. CNY","pattern":"^[A-Z]{3}$","title":"Currency","type":"string"},"method":{"description":"Method from GET /v1/transfers/currencies, e.g. alipay","pattern":"^[a-z][a-z0-9_]{0,31}$","title":"Method","type":"string"},"amount_minor":{"description":"Amount in minor units of the currency (CNY: fen, 100 = 1 yuan)","exclusiveMinimum":0,"maximum":9223372036854775807,"title":"Amount Minor","type":"integer"},"recipient_id":{"anyOf":[{"maxLength":255,"minLength":1,"type":"string"},{"type":"null"}],"description":"Recipient account ID for the method (Alipay: phone or email)","title":"Recipient Id"},"recipient_name":{"anyOf":[{"maxLength":255,"minLength":1,"type":"string"},{"type":"null"}],"description":"Recipient name as registered with the method","title":"Recipient Name"},"payment_details":{"anyOf":[{"maxLength":2048,"minLength":1,"type":"string"},{"type":"null"}],"description":"Optional extra details; not a replacement for recipient fields","title":"Payment Details"},"external_id":{"description":"Your unique transfer number; one transfer per value","pattern":"^[A-Za-z0-9._:-]{1,128}$","title":"External Id","type":"string"},"external_user_id":{"description":"Your stable recipient ID (not an order number)","maxLength":255,"minLength":1,"title":"External User Id","type":"string"},"max_debit_usdt_micro":{"description":"Maximum total debit including fee, in millionths of USDT","exclusiveMinimum":0,"maximum":9223372036854775807,"title":"Max Debit Usdt Micro","type":"integer"},"merchant_order_id":{"anyOf":[{"maxLength":128,"minLength":1,"type":"string"},{"type":"null"}],"description":"Your order number (optional); returned in responses and webhooks","title":"Merchant Order Id"}},"required":["currency","method","amount_minor","external_id","external_user_id","max_debit_usdt_micro"],"title":"CreateTransferRequest","type":"object"}}}}},"get":{"tags":["Transfers"],"summary":"List transfers","description":"Newest first. Query: limit (1–100, default 50), offset, status.","operationId":"list_transfers","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"parameters":[{"name":"x-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"x-timestamp","in":"header","required":true,"schema":{"type":"string"}},{"name":"x-signature","in":"header","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","default":50}},{"name":"offset","in":"query","schema":{"type":"integer","default":0}},{"name":"status","in":"query","schema":{"type":"string"}}]}},"/v1/transfers/by-external-id/{external_id}":{"get":{"tags":["Transfers"],"summary":"Get a transfer by external_id","description":"Looks up a transfer by your own transfer number.","operationId":"get_transfer_by_external_id","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"parameters":[{"name":"x-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"x-timestamp","in":"header","required":true,"schema":{"type":"string"}},{"name":"x-signature","in":"header","required":true,"schema":{"type":"string"}},{"name":"external_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/v1/transfers/{transfer_id}":{"get":{"tags":["Transfers"],"summary":"Get a transfer","description":"Status: processing, needs_review, completed, failed or cancelled.","operationId":"get_transfer","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"parameters":[{"name":"x-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"x-timestamp","in":"header","required":true,"schema":{"type":"string"}},{"name":"x-signature","in":"header","required":true,"schema":{"type":"string"}},{"name":"transfer_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/v1/transfers/{transfer_id}/cancel":{"post":{"tags":["Transfers"],"summary":"Cancel a transfer","description":"Possible only until the transfer is taken into work by the payment network; otherwise 409 not_cancellable.","operationId":"cancel_transfer","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"parameters":[{"name":"x-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"x-timestamp","in":"header","required":true,"schema":{"type":"string"}},{"name":"x-signature","in":"header","required":true,"schema":{"type":"string"}},{"name":"transfer_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/v1/events":{"get":{"tags":["General"],"summary":"Event feed","description":"All webhook events of your store in order, for recovery after missed deliveries. Query: after (sequence number), limit.","operationId":"list_events","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"parameters":[{"name":"x-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"x-timestamp","in":"header","required":true,"schema":{"type":"string"}},{"name":"x-signature","in":"header","required":true,"schema":{"type":"string"}},{"name":"after","in":"query","schema":{"type":"integer","default":0}},{"name":"limit","in":"query","schema":{"type":"integer","default":50}}]}},"/v1/balances":{"get":{"tags":["General"],"summary":"Balances","description":"payin_rub, payin_usdt (acquiring), deposit_usdt (payQR deposit), payout_usdt (payout deposit), terminal_rub, terminal_usdt (QR Terminal). Minor units; USDT in millionths.","operationId":"get_balances","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"parameters":[{"name":"x-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"x-timestamp","in":"header","required":true,"schema":{"type":"string"}},{"name":"x-signature","in":"header","required":true,"schema":{"type":"string"}}]}}},"tags":[{"name":"General","description":"Event feed and balances shared by all products. Authentication, signing and webhooks: see the Getting started guide.","externalDocs":{"description":"Getting started","url":"https://nomapay.io/developers"}},{"name":"Acquiring","description":"payin: your customers pay your store. Start with GET /v1/payments/methods.","externalDocs":{"description":"Acquiring guide","url":"https://nomapay.io/developers/acquiring"}},{"name":"QR Terminal","description":"terminal: a separate acceptance gateway for in-store QR payments. Same flow as Acquiring with its own fees and balances. Start with GET /v1/terminal/payments/methods.","externalDocs":{"description":"QR Terminal guide","url":"https://nomapay.io/developers/terminal"}},{"name":"QR Payment","description":"payQR: NOMA pays local QR codes from your payQR deposit (USDT). Start with GET /v1/payouts/methods.","externalDocs":{"description":"QR Payment guide","url":"https://nomapay.io/developers/qr-payment"}},{"name":"Transfers","description":"payout: transfers to recipients by currency and method, funded from your payout deposit (USDT). Start with GET /v1/transfers/currencies.","externalDocs":{"description":"Transfers guide","url":"https://nomapay.io/developers/transfers"}}]}