{"swagger":"2.0","info":{"description":"RingPay payment and settlement API. Errors use {\"error\": {\"code\", \"message\"}}; IDs are SQID strings; timestamps are RFC 3339 UTC.","title":"RingPay API","contact":{},"version":"1.0"},"basePath":"/","paths":{"/merchant-network-api/v1/merchants":{"get":{"security":[{"MerchantNetworkAccessKey":[]}],"description":"Returns the merchant network's merchants in any `status`, ordered by `joined_at` then\n`merchant_id`, both descending (latest first); a search does not change the order. `q` keeps\ntitles that contain it, ignoring case, Arabic and Persian ی and ک, Persian and Latin digits, and\na zero-width non-joiner against a space; `external_id` keeps only the merchant with that ID in\nthe merchant network, so at most one. When both are sent a merchant must match both.\nTakes a merchant_access key or a merchant network panel session. `next_page` is the URL of the\nnext page and null on the last one. An invalid `q`, `external_id`, `limit`, or `cursor` returns\n400 `invalid_request`.","produces":["application/json"],"tags":["Merchants"],"summary":"List and search a merchant network's merchants","parameters":[{"type":"string","description":"Part of the title; trimmed, at most 100 characters","name":"q","in":"query"},{"maxLength":128,"type":"string","description":"Merchant ID in the merchant network","name":"external_id","in":"query"},{"maximum":50,"minimum":1,"type":"integer","default":20,"description":"Page size","name":"limit","in":"query"},{"type":"string","description":"Set by next_page; never build it","name":"cursor","in":"query"}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/httpapi.merchantNetworkMerchantListResponse"}},"400":{"description":"invalid_request","schema":{"$ref":"#/definitions/httpx.ErrorBody"}},"401":{"description":"invalid_access_key, or unauthenticated without a key or session","schema":{"$ref":"#/definitions/httpx.ErrorBody"}},"403":{"description":"access_denied","schema":{"$ref":"#/definitions/httpx.ErrorBody"}},"500":{"description":"internal_error","schema":{"$ref":"#/definitions/httpx.ErrorBody"}}}},"post":{"security":[{"MerchantNetworkAccessKey":[]}],"description":"Registers the merchant and its owner user (found or created by mobile) and returns its RingPay ID\nand a one-time login link valid for two minutes. Repeating the request for an `external_id` the\nmerchant network already registered with the same `owner_mobile` changes nothing and returns the existing\nmerchant with a new link and status 200 instead of 201; use the update endpoint to change the\nprofile. Another `owner_mobile` returns 409 `owner_mobile_mismatch` and no link.","consumes":["application/json"],"produces":["application/json"],"tags":["Merchants"],"summary":"Register a merchant network's merchant","parameters":[{"description":"Merchant","name":"request","in":"body","required":true,"schema":{"$ref":"#/definitions/httpapi.registerMerchantRequest"}}],"responses":{"200":{"description":"Already registered","schema":{"$ref":"#/definitions/httpapi.loginLinkResponse"}},"201":{"description":"Registered","schema":{"$ref":"#/definitions/httpapi.loginLinkResponse"}},"400":{"description":"invalid_request","schema":{"$ref":"#/definitions/httpx.ErrorBody"}},"401":{"description":"invalid_access_key, or unauthenticated without a key","schema":{"$ref":"#/definitions/httpx.ErrorBody"}},"403":{"description":"access_denied, also for a panel session","schema":{"$ref":"#/definitions/httpx.ErrorBody"}},"409":{"description":"owner_mobile_mismatch","schema":{"$ref":"#/definitions/httpx.ErrorBody"}},"500":{"description":"internal_error","schema":{"$ref":"#/definitions/httpx.ErrorBody"}}}},"patch":{"security":[{"MerchantNetworkAccessKey":[]}],"description":"Changes only `title`, `description`, `logo_url`, and `link`: an omitted field keeps its value\nand `null` clears `description`, `logo_url`, or `link`. The owner mobile cannot change. Identify the merchant\nby `merchant_id`, `external_id`, or both; both must name the same merchant.","consumes":["application/json"],"produces":["application/json"],"tags":["Merchants"],"summary":"Update a merchant network's merchant profile","parameters":[{"description":"Merchant and changed fields","name":"request","in":"body","required":true,"schema":{"$ref":"#/definitions/httpapi.updateMerchantForMerchantNetworkRequest"}}],"responses":{"204":{"description":"Updated"},"400":{"description":"invalid_request","schema":{"$ref":"#/definitions/httpx.ErrorBody"}},"401":{"description":"invalid_access_key, or unauthenticated without a key","schema":{"$ref":"#/definitions/httpx.ErrorBody"}},"403":{"description":"access_denied, also for a panel session","schema":{"$ref":"#/definitions/httpx.ErrorBody"}},"404":{"description":"merchant_not_found","schema":{"$ref":"#/definitions/httpx.ErrorBody"}},"422":{"description":"merchant_id_mismatch","schema":{"$ref":"#/definitions/httpx.ErrorBody"}},"500":{"description":"internal_error","schema":{"$ref":"#/definitions/httpx.ErrorBody"}}}}},"/merchant-network-api/v1/merchants/login-link":{"post":{"security":[{"MerchantNetworkAccessKey":[]}],"description":"Returns a one-time login link valid for two minutes and revokes the merchant's previous link,\nused or not. Identify the merchant by `merchant_id`, `external_id`, or both; both must name the\nsame merchant. A merchant of another merchant network returns 404 `merchant_not_found`.","consumes":["application/json"],"produces":["application/json"],"tags":["Merchants"],"summary":"Issue a login link for a merchant network's merchant","parameters":[{"description":"Merchant","name":"request","in":"body","required":true,"schema":{"$ref":"#/definitions/httpapi.merchantRef"}}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/httpapi.loginLinkResponse"}},"400":{"description":"invalid_request","schema":{"$ref":"#/definitions/httpx.ErrorBody"}},"401":{"description":"invalid_access_key, or unauthenticated without a key","schema":{"$ref":"#/definitions/httpx.ErrorBody"}},"403":{"description":"access_denied, also for a panel session","schema":{"$ref":"#/definitions/httpx.ErrorBody"}},"404":{"description":"merchant_not_found","schema":{"$ref":"#/definitions/httpx.ErrorBody"}},"422":{"description":"merchant_id_mismatch","schema":{"$ref":"#/definitions/httpx.ErrorBody"}},"500":{"description":"internal_error","schema":{"$ref":"#/definitions/httpx.ErrorBody"}}}}},"/merchant-network-api/v1/merchants/{merchant_id}":{"get":{"security":[{"MerchantNetworkAccessKey":[]}],"description":"Identifies the merchant by its RingPay ID only; to find one by `external_id`, list the\nmerchants with that filter. A merchant of another merchant network returns 404\n`merchant_not_found`. Onboarding and internal KYC details are not included.","produces":["application/json"],"tags":["Merchants"],"summary":"Get a merchant network's merchant","parameters":[{"type":"string","description":"RingPay merchant ID","name":"merchant_id","in":"path","required":true}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/httpapi.merchantForMerchantNetworkResponse"}},"401":{"description":"invalid_access_key, or unauthenticated without a key","schema":{"$ref":"#/definitions/httpx.ErrorBody"}},"403":{"description":"access_denied, also for a panel session","schema":{"$ref":"#/definitions/httpx.ErrorBody"}},"404":{"description":"merchant_not_found","schema":{"$ref":"#/definitions/httpx.ErrorBody"}},"500":{"description":"internal_error","schema":{"$ref":"#/definitions/httpx.ErrorBody"}}}}}},"definitions":{"httpapi.loginLinkResponse":{"type":"object","properties":{"expires_at":{"type":"string","example":"2026-11-02T09:02:00Z"},"login_url":{"description":"Magic link for the owner: <frontend_base_url>/home?login_token=<token>. The frontend sends the\ntoken to POST /merchant-api/v1/auth/token/login. Single use, valid for two minutes.","type":"string","example":"https://panel.ringpay.ir/home?login_token=ABCDEFGHIJKLMNOPQRSTUVWXYZ"},"merchant_id":{"type":"string","example":"86Rf07xd4z"}}},"httpapi.merchantForMerchantNetworkResponse":{"type":"object","properties":{"description":{"type":"string"},"external_id":{"type":"string","example":"shop-1"},"kyc_status":{"type":"string","enum":["pending","accepted"]},"link":{"type":"string"},"logo_url":{"type":"string"},"merchant_id":{"type":"string","example":"86Rf07xd4z"},"title":{"type":"string"}}},"httpapi.merchantNetworkMerchantListResponse":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/definitions/httpapi.merchantNetworkMerchantResponse"}},"next_page":{"description":"URL of the next page; null on the last page.","type":"string"}}},"httpapi.merchantNetworkMerchantResponse":{"type":"object","properties":{"external_id":{"type":"string","example":"shop-1"},"joined_at":{"type":"string","example":"2026-11-01T08:00:00Z"},"kyc_status":{"type":"string","enum":["pending","accepted"]},"logo_url":{"type":"string"},"merchant_id":{"type":"string","example":"86Rf07xd4z"},"status":{"type":"string","enum":["registered","activated","blocked"]},"title":{"type":"string"}}},"httpapi.merchantRef":{"type":"object","properties":{"external_id":{"type":"string","maxLength":128,"example":"shop-1"},"merchant_id":{"type":"string"}}},"httpapi.registerMerchantRequest":{"type":"object","required":["external_id","owner_mobile","title"],"properties":{"description":{"type":"string","maxLength":1000},"external_id":{"description":"Merchant ID in the merchant network's system; unique within the merchant network.","type":"string","maxLength":128,"example":"shop-1"},"link":{"description":"Merchant's own link, for example its website.","type":"string","maxLength":2048,"example":"https://shop.example.com"},"logo_url":{"type":"string","maxLength":2048},"owner_mobile":{"description":"E.164 format, verified by the merchant network with an OTP.","type":"string","example":"+989121234567"},"title":{"type":"string","maxLength":200,"example":"فروشگاه نمونه"}}},"httpapi.updateMerchantForMerchantNetworkRequest":{"type":"object","properties":{"description":{"description":"Omit to keep; null clears.","type":"string"},"external_id":{"type":"string","maxLength":128,"example":"shop-1"},"link":{"description":"Omit to keep; null clears. An absolute http or https URL.","type":"string"},"logo_url":{"description":"Omit to keep; null clears. An absolute http or https URL.","type":"string"},"merchant_id":{"type":"string"},"title":{"description":"Omit to keep; null is rejected.","type":"string"}}},"httpx.ErrorBody":{"type":"object","properties":{"error":{"$ref":"#/definitions/httpx.ErrorDetail"}}},"httpx.ErrorDetail":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}},"securityDefinitions":{"MerchantNetworkAccessKey":{"description":"\"Bearer <key>\": a merchant network's access key, sent server to server only. The merchant-network routes need the merchant_access scope; the gateway routes need gateway_access.","type":"apiKey","name":"Authorization","in":"header"}}}