{"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":{"/gateway-api/v1/invoices":{"post":{"security":[{"MerchantNetworkAccessKey":[]}],"description":"Creates an invoice of `amount` rials for the merchant network's activated merchant, payable for one\nhour, for the payer with `payer_mobile` (created when unknown). Redirect the payer to `pay_url`.\nStore `id` with the order and confirm the payment with the consume endpoint; the parameters the\npayer brings back to `callback_url` are informational only. A repeated request with the same\n`external_order_id` returns the existing invoice with 200 and a new `pay_url`; with another\n`amount` or `payer_mobile` it returns 409 `invoice_order_conflict`.","consumes":["application/json"],"produces":["application/json"],"tags":["Invoices"],"summary":"Create an online invoice","parameters":[{"description":"Invoice","name":"request","in":"body","required":true,"schema":{"$ref":"#/definitions/httpapi.createOnlineInvoiceRequest"}}],"responses":{"200":{"description":"the order's existing invoice","schema":{"$ref":"#/definitions/httpapi.createOnlineInvoiceResponse"}},"201":{"description":"created","schema":{"$ref":"#/definitions/httpapi.createOnlineInvoiceResponse"}},"400":{"description":"invalid_request","schema":{"$ref":"#/definitions/httpx.ErrorBody"}},"401":{"description":"invalid_access_key","schema":{"$ref":"#/definitions/httpx.ErrorBody"}},"403":{"description":"access_denied","schema":{"$ref":"#/definitions/httpx.ErrorBody"}},"404":{"description":"merchant_not_found","schema":{"$ref":"#/definitions/httpx.ErrorBody"}},"409":{"description":"merchant_not_payable, invoice_order_conflict","schema":{"$ref":"#/definitions/httpx.ErrorBody"}},"422":{"description":"merchant_id_mismatch","schema":{"$ref":"#/definitions/httpx.ErrorBody"}},"500":{"description":"internal_error","schema":{"$ref":"#/definitions/httpx.ErrorBody"}}}}},"/gateway-api/v1/invoices/{invoice_id}":{"get":{"security":[{"MerchantNetworkAccessKey":[]}],"description":"Returns the invoice in any status, for reconciliation and support; it never changes the invoice and\ndoes not replace consume. `paid` means the payer paid in full and the invoice awaits consume.\nAn invoice of another network's merchant, an onsite invoice, or an unknown ID returns 404.","produces":["application/json"],"tags":["Invoices"],"summary":"Get an online invoice","parameters":[{"type":"string","description":"Invoice ID","name":"invoice_id","in":"path","required":true}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/httpapi.gatewayInvoiceResponse"}},"401":{"description":"invalid_access_key","schema":{"$ref":"#/definitions/httpx.ErrorBody"}},"403":{"description":"access_denied","schema":{"$ref":"#/definitions/httpx.ErrorBody"}},"404":{"description":"invoice_not_found","schema":{"$ref":"#/definitions/httpx.ErrorBody"}},"500":{"description":"internal_error","schema":{"$ref":"#/definitions/httpx.ErrorBody"}}}}},"/gateway-api/v1/invoices/{invoice_id}/consume":{"post":{"security":[{"MerchantNetworkAccessKey":[]}],"description":"Confirms the payment: a `paid` invoice becomes `success` with `consumed_at`. Read `invoice_id` from\nthe stored order, never from the parameters the payer brought back. A `success` invoice returns\n200 with `already_consumed` true; any other status returns 409 `invoice_not_consumable`. A\n`paid` invoice must be consumed within 30 minutes of its `paid_at`; afterwards consume returns 409\n`invoice_not_consumable` and RingPay refunds the payer. The request has no body.","produces":["application/json"],"tags":["Invoices"],"summary":"Consume a paid online invoice","parameters":[{"type":"string","description":"Invoice ID","name":"invoice_id","in":"path","required":true}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/httpapi.consumeInvoiceResponse"}},"401":{"description":"invalid_access_key","schema":{"$ref":"#/definitions/httpx.ErrorBody"}},"403":{"description":"access_denied","schema":{"$ref":"#/definitions/httpx.ErrorBody"}},"404":{"description":"invoice_not_found","schema":{"$ref":"#/definitions/httpx.ErrorBody"}},"409":{"description":"invoice_not_consumable: not paid, or past the consume window","schema":{"$ref":"#/definitions/httpx.ErrorBody"}},"500":{"description":"internal_error","schema":{"$ref":"#/definitions/httpx.ErrorBody"}}}}}},"definitions":{"httpapi.consumeInvoiceResponse":{"type":"object","properties":{"already_consumed":{"description":"True when an earlier request consumed the invoice; nothing changed.","type":"boolean"},"amount":{"description":"Rials.","type":"string","example":"1500000"},"consumed_at":{"type":"string","example":"2026-11-07T09:06:00Z"},"created_at":{"type":"string","example":"2026-11-07T09:00:00Z"},"external_id":{"description":"The merchant's ID in the merchant network.","type":"string","example":"shop-1"},"external_order_id":{"type":"string","example":"order-42"},"id":{"type":"string","example":"86Rf07xd4z"},"merchant_id":{"type":"string","example":"khb"},"paid_at":{"type":"string","example":"2026-11-07T09:05:00Z"},"payer_mobile":{"type":"string","example":"+989121234567"},"payment_due_at":{"type":"string","example":"2026-11-07T10:00:00Z"},"status":{"description":"paid: the payer paid in full but the network has not consumed the\ninvoice; only success is a final payment.","type":"string","enum":["initiated","partially_paid","paid","success","canceled","refunding","partially_refunded","refunded"]}}},"httpapi.createOnlineInvoiceRequest":{"type":"object","required":["amount","callback_url","external_order_id","payer_mobile"],"properties":{"amount":{"description":"Rials, a positive whole number.","type":"string","example":"1500000"},"callback_url":{"description":"Where the payer returns after paying; an absolute https URL.","type":"string","example":"https://shop.example.com/orders/42/return"},"external_id":{"type":"string","maxLength":128,"example":"shop-1"},"external_order_id":{"description":"The network's order reference. A repeated request with the same\nreference returns the same invoice.","type":"string","maxLength":128,"example":"order-42"},"merchant_id":{"description":"The merchant receiving the payment: merchant_id, external_id, or both.","type":"string"},"payer_mobile":{"description":"E.164 format.","type":"string","example":"+989121234567"}}},"httpapi.createOnlineInvoiceResponse":{"type":"object","properties":{"id":{"type":"string","example":"86Rf07xd4z"},"pay_url":{"description":"The RingPay payment page with a token valid until payment_due_at.","type":"string","example":"https://ipg-pay.ring.ir/?token=eyJhbGciOi..."},"payment_due_at":{"type":"string","example":"2026-11-07T10:00:00Z"}}},"httpapi.gatewayInvoiceResponse":{"type":"object","properties":{"amount":{"description":"Rials.","type":"string","example":"1500000"},"consumed_at":{"type":"string","example":"2026-11-07T09:06:00Z"},"created_at":{"type":"string","example":"2026-11-07T09:00:00Z"},"external_id":{"description":"The merchant's ID in the merchant network.","type":"string","example":"shop-1"},"external_order_id":{"type":"string","example":"order-42"},"id":{"type":"string","example":"86Rf07xd4z"},"merchant_id":{"type":"string","example":"khb"},"paid_at":{"type":"string","example":"2026-11-07T09:05:00Z"},"payer_mobile":{"type":"string","example":"+989121234567"},"payment_due_at":{"type":"string","example":"2026-11-07T10:00:00Z"},"status":{"description":"paid: the payer paid in full but the network has not consumed the\ninvoice; only success is a final payment.","type":"string","enum":["initiated","partially_paid","paid","success","canceled","refunding","partially_refunded","refunded"]}}},"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"}}}