{"openapi":"3.1.0","info":{"title":"Payrapyd merchant API","version":"1.0.0","description":"Server-to-server API for merchants. Amounts are integer strings in paise (₹1 = \"100\"). Test keys (`pyd_test_…`) only reach the payment simulator: no real money ever moves. Never call this API from a browser or app: your secret key must stay on your server."},"servers":[{"url":"https://sandbox-api.payrapyd.com"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Payments","description":"Orders, checkout and status"},{"name":"Refunds"},{"name":"Webhooks","description":"Signed event notifications to your server"},{"name":"Account"}],"paths":{"/v1/whoami":{"get":{"tags":["Account"],"summary":"Check an API key","operationId":"whoami","responses":{"200":{"description":"The merchant and mode this key belongs to","content":{"application/json":{"schema":{"type":"object","properties":{"merchantId":{"type":"string"},"mode":{"enum":["test","live"]},"keyId":{"type":"string"}}}}}},"401":{"description":"Missing, invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/orders":{"post":{"tags":["Payments"],"summary":"Create a payment order","operationId":"createOrder","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Unique per logical request (8–64 letters, digits, - or _). Repeating a request with the same key and body returns the original result with `Idempotent-Replayed: true`; the same key with a different body is refused (409).","schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{8,64}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateOrder"}}}},"responses":{"200":{"description":"Replay of an earlier identical request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}}}},"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Mode not available on this environment","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Idempotency-Key reused with a different body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"tags":["Payments"],"summary":"List orders, newest first","operationId":"listOrders","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"before","in":"query","description":"Return orders older than this order id","schema":{"type":"string"}}],"responses":{"200":{"description":"A page of orders","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Order"}}}}}}},"401":{"description":"Missing, invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/orders/{id}":{"get":{"tags":["Payments"],"summary":"Get an order (authoritative status)","description":"If the order is pending, its status is first re-checked with the provider. Use this, not the browser return, to decide whether to fulfil.","operationId":"getOrder","parameters":[{"name":"id","in":"path","required":true,"description":"Order id","schema":{"type":"string","pattern":"^pay_[0-9A-HJKMNP-TV-Z]{26}$"}}],"responses":{"200":{"description":"The order","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}}}},"401":{"description":"Missing, invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/orders/{id}/checkout-sessions":{"post":{"tags":["Payments"],"summary":"Get the hosted checkout URL for an order","description":"Redirect the customer (full page) to `checkoutUrl`. Calling again returns the same session.","operationId":"createCheckoutSession","parameters":[{"name":"id","in":"path","required":true,"description":"Order id","schema":{"type":"string","pattern":"^pay_[0-9A-HJKMNP-TV-Z]{26}$"}}],"responses":{"201":{"description":"Checkout session","content":{"application/json":{"schema":{"type":"object","required":["checkoutUrl","expiresAt","attemptId"],"properties":{"checkoutUrl":{"type":"string","format":"uri"},"expiresAt":{"type":"string","format":"date-time"},"attemptId":{"type":"string"}}}}}},"401":{"description":"Missing, invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Order expired or already completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/orders/{id}/refunds":{"post":{"tags":["Refunds"],"summary":"Refund part or all of a paid order","operationId":"createRefund","parameters":[{"name":"id","in":"path","required":true,"description":"Order id","schema":{"type":"string","pattern":"^pay_[0-9A-HJKMNP-TV-Z]{26}$"}},{"name":"Idempotency-Key","in":"header","required":true,"description":"Unique per logical request (8–64 letters, digits, - or _). Repeating a request with the same key and body returns the original result with `Idempotent-Replayed: true`; the same key with a different body is refused (409).","schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{8,64}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["amount"],"additionalProperties":false,"properties":{"amount":{"$ref":"#/components/schemas/Amount"},"reason":{"type":"string","maxLength":255}}}}}},"responses":{"200":{"description":"Replay of an earlier identical request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Refund"}}}},"201":{"description":"Refund (status after the provider was asked)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Refund"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Order not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Order not refundable, amount exceeds what is left, or Idempotency-Key reused","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"tags":["Refunds"],"summary":"List an order's refunds","operationId":"listRefunds","parameters":[{"name":"id","in":"path","required":true,"description":"Order id","schema":{"type":"string","pattern":"^pay_[0-9A-HJKMNP-TV-Z]{26}$"}}],"responses":{"200":{"description":"Refunds","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Refund"}}}}}}},"401":{"description":"Missing, invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Order not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/refunds/{id}":{"get":{"tags":["Refunds"],"summary":"Get a refund","description":"A pending refund is re-tried with the provider (safely: the same refund id is its idempotency key).","operationId":"getRefund","parameters":[{"name":"id","in":"path","required":true,"description":"Refund id","schema":{"type":"string","pattern":"^rfd_[0-9A-HJKMNP-TV-Z]{26}$"}}],"responses":{"200":{"description":"The refund","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Refund"}}}},"401":{"description":"Missing, invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/webhook-endpoints":{"post":{"tags":["Webhooks"],"summary":"Register a webhook endpoint","description":"The response includes the signing secret once. URLs must be https on port 443 and resolve to public addresses.","operationId":"createWebhookEndpoint","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url","events"],"additionalProperties":false,"properties":{"url":{"type":"string","format":"uri"},"events":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/EventType"}}}}}}},"responses":{"201":{"description":"Created (with `secret`)","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEndpoint"},{"type":"object","required":["secret"],"properties":{"secret":{"type":"string","pattern":"^whsec_"}}}]}}}},"400":{"description":"Invalid or refused URL","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"tags":["Webhooks"],"summary":"List webhook endpoints","operationId":"listWebhookEndpoints","responses":{"200":{"description":"Endpoints (secrets are never listed)","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEndpoint"}}}}}}},"401":{"description":"Missing, invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/webhook-endpoints/{id}/disable":{"post":{"tags":["Webhooks"],"summary":"Disable a webhook endpoint","operationId":"disableWebhookEndpoint","parameters":[{"name":"id","in":"path","required":true,"description":"Endpoint id","schema":{"type":"string","pattern":"^whe_[0-9A-HJKMNP-TV-Z]{26}$"}}],"responses":{"200":{"description":"Disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpoint"}}}},"401":{"description":"Missing, invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/webhook-endpoints/{id}/deliveries":{"get":{"tags":["Webhooks"],"summary":"Recent deliveries to an endpoint","operationId":"listWebhookDeliveries","parameters":[{"name":"id","in":"path","required":true,"description":"Endpoint id","schema":{"type":"string","pattern":"^whe_[0-9A-HJKMNP-TV-Z]{26}$"}}],"responses":{"200":{"description":"Last 50 deliveries","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookDelivery"}}}}}}},"401":{"description":"Missing, invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"webhooks":{"event":{"post":{"summary":"Event delivered to your endpoint","description":"Verify `Payrapyd-Signature: t=<unix>,v1=<hex>` = HMAC-SHA256(secret, \"<t>.<raw body>\") in constant time and reject timestamps older than 5 minutes. De-duplicate on `Payrapyd-Event-Id`. Deliveries can repeat and arrive out of order; answer 2xx quickly.","parameters":[{"name":"Payrapyd-Signature","in":"header","required":true,"schema":{"type":"string"}},{"name":"Payrapyd-Event-Id","in":"header","required":true,"schema":{"type":"string"}},{"name":"Payrapyd-Delivery-Attempt","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Event"}}}},"responses":{"200":{"description":"Any 2xx acknowledges the event"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Secret API key, e.g. `Authorization: Bearer pyd_test_…`"}},"schemas":{"Amount":{"type":"string","pattern":"^[0-9]{1,16}$","description":"Integer amount in paise, as a string (\"125050\" = ₹1,250.50)","examples":["125050"]},"EventType":{"enum":["order.succeeded","order.failed","order.expired","refund.succeeded","refund.failed"]},"OrderStatus":{"enum":["created","pending","succeeded","failed","expired","partially_refunded","refunded"]},"CreateOrder":{"type":"object","required":["amount","currency","returnUrl"],"additionalProperties":false,"properties":{"amount":{"$ref":"#/components/schemas/Amount"},"currency":{"const":"INR"},"returnUrl":{"type":"string","format":"uri","description":"https URL the customer returns to, with `?payrapyd_order_id=…` added"},"merchantOrderRef":{"type":"string","pattern":"^[A-Za-z0-9._:/-]{1,64}$"},"description":{"type":"string","maxLength":255}}},"Order":{"type":"object","properties":{"id":{"type":"string"},"object":{"const":"payment_order"},"mode":{"enum":["test","live"]},"simulated":{"type":"boolean","description":"true for sandbox simulator orders: never real money"},"status":{"$ref":"#/components/schemas/OrderStatus"},"amount":{"$ref":"#/components/schemas/Amount"},"currency":{"const":"INR"},"merchantOrderRef":{"type":["string","null"]},"description":{"type":["string","null"]},"returnUrl":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"attempts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"provider":{"type":"string"},"status":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}}}}}},"Refund":{"type":"object","properties":{"id":{"type":"string"},"object":{"const":"refund"},"orderId":{"type":"string"},"status":{"enum":["pending","succeeded","failed"]},"amount":{"$ref":"#/components/schemas/Amount"},"currency":{"const":"INR"},"reason":{"type":["string","null"]},"simulated":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"}}},"WebhookEndpoint":{"type":"object","properties":{"id":{"type":"string"},"object":{"const":"webhook_endpoint"},"url":{"type":"string"},"events":{"type":"array","items":{"$ref":"#/components/schemas/EventType"}},"status":{"enum":["active","disabled"]},"createdAt":{"type":"string","format":"date-time"}}},"WebhookDelivery":{"type":"object","properties":{"id":{"type":"string"},"object":{"const":"webhook_delivery"},"eventId":{"type":"string"},"type":{"$ref":"#/components/schemas/EventType"},"status":{"enum":["pending","succeeded","abandoned"]},"attempts":{"type":"integer"},"lastAttemptAt":{"type":["string","null"],"format":"date-time"},"lastStatus":{"type":["integer","null"]},"lastError":{"type":["string","null"]},"nextAttemptAt":{"type":["string","null"],"format":"date-time"}}},"Event":{"type":"object","properties":{"id":{"type":"string"},"object":{"const":"event"},"type":{"$ref":"#/components/schemas/EventType"},"livemode":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"data":{"type":"object","description":"The order or refund the event is about"}}},"Error":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"fields":{"type":"array","items":{"type":"string"}}}}}}}}}