{ "openapi": "3.1.0", "info": { "title": "Thuprai Pay Merchant API", "version": "1.0.0", "description": "Server-to-server API for hosted checkout.\n\n**Amounts** are integers in minor units (paisa for NPR, cents for USD). `amount` is tax-inclusive.\n\n**Trust rule:** never fulfill from the browser redirect alone. Always call verify (or an equivalent server check) before fulfillment." }, "servers": [ { "url": "https://pay.awecode.com", "description": "Production" } ], "tags": [ { "name": "Orders", "description": "Create, read, verify, and cancel checkout orders." }, { "name": "Webhooks", "description": "Outbound events to your server." } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API key", "description": "Merchant API key: `Authorization: Bearer ps_...`" } }, "schemas": { "Error": { "type": "object", "properties": { "statusCode": { "type": "integer", "example": 409 }, "statusMessage": { "type": "string" }, "message": { "type": "string" } } }, "Product": { "type": "object", "required": [ "name", "quantity", "amount" ], "properties": { "name": { "type": "string" }, "quantity": { "type": "integer", "minimum": 1 }, "amount": { "type": "integer", "description": "Line total in minor units (not unit price)." }, "description": { "type": [ "string", "null" ] } } }, "CreateOrderRequest": { "type": "object", "required": [ "amount" ], "properties": { "amount": { "type": "integer", "minimum": 1, "description": "Payable total in minor units (tax- and shipping-inclusive).", "example": 150000 }, "tax": { "type": "integer", "minimum": 0, "default": 0 }, "shipping": { "type": "integer", "minimum": 0, "default": 0 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "default": "NPR", "example": "NPR" }, "orderId": { "type": [ "string", "null" ] }, "orderNumber": { "type": [ "string", "null" ] }, "reference": { "type": [ "string", "null" ], "description": "Unique per merchant. Auto-set if omitted." }, "terminalId": { "type": [ "string", "null" ], "format": "uuid" }, "message": { "type": [ "string", "null" ] }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Must be in the future." }, "successRedirectUrl": { "type": [ "string", "null" ], "format": "uri" }, "failureRedirectUrl": { "type": [ "string", "null" ], "format": "uri" }, "products": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/Product" } }, "data": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Pass-through JSON. Not shown on checkout." }, "tags": { "type": [ "array", "null" ], "items": { "type": "string", "maxLength": 64 }, "maxItems": 20 } } }, "CreateOrderResponse": { "type": "object", "required": [ "id", "reference", "checkoutUrl" ], "properties": { "id": { "type": "string", "format": "uuid" }, "reference": { "type": "string" }, "checkoutUrl": { "type": "string", "format": "uri", "description": "Redirect the customer here." } } }, "Order": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "orderId": { "type": [ "string", "null" ] }, "orderNumber": { "type": [ "string", "null" ] }, "reference": { "type": "string" }, "amount": { "type": "integer" }, "currency": { "type": "string" }, "status": { "type": "string", "enum": [ "Open", "Success", "Failed", "Canceled", "Expired" ] }, "data": { "type": [ "object", "null" ], "additionalProperties": true }, "tags": { "type": "array", "items": { "type": "string" } }, "transactionId": { "type": [ "string", "null" ], "format": "uuid" }, "gateway": { "type": [ "string", "null" ] }, "gatewayReference": { "type": [ "string", "null" ] }, "verified": { "type": [ "boolean", "null" ] } } }, "VerifyResponse": { "allOf": [ { "$ref": "#/components/schemas/Order" }, { "type": "object", "properties": { "fulfilled": { "type": "boolean", "description": "Fulfill only when true." }, "verificationResult": { "type": [ "string", "null" ], "enum": [ "Success", "Failed", "Error", "Pending", null ] } } } ] }, "CancelResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "Canceled" ] } } }, "WebhookPayload": { "type": "object", "properties": { "event": { "type": "string", "enum": [ "payment_success", "payment_failed", "receipt_synced" ] }, "id": { "type": "string", "format": "uuid", "description": "Our order UUID. Use for POST /api/orders/{id}/verify." }, "orderId": { "type": "string", "description": "Your create-time orderId if set, otherwise our order UUID." }, "transactionId": { "type": "string", "format": "uuid" }, "amount": { "type": "integer", "description": "Minor units (paisa / cents)." }, "currency": { "type": "string" }, "status": { "type": "string" }, "gateway": { "type": "string" }, "gatewayReference": { "type": [ "string", "null" ] }, "data": { "type": [ "object", "null" ], "additionalProperties": true }, "tags": { "type": "array", "items": { "type": "string" } } } }, "Refund": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Refund id." }, "orderId": { "type": "string", "format": "uuid", "description": "Parent sale order id." }, "reference": { "type": "string", "description": "Idempotency key, unique per merchant." }, "gateway": { "type": "string", "example": "cash" }, "amount": { "type": "integer", "description": "Refund in minor units (tax-inclusive)." }, "tax": { "type": "integer" }, "discount": { "type": "integer" }, "currency": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "Success", "Failed" ] }, "receipt": { "type": [ "object", "null" ], "description": "Credit-note receipt; billNo is the Awecount credit-note voucher_no." }, "fulfilled": { "type": "boolean" }, "verificationResult": { "type": "string" } } } } }, "security": [ { "bearerAuth": [] } ], "paths": { "/api/orders": { "post": { "tags": [ "Orders" ], "operationId": "createOrder", "summary": "Create order", "description": "Creates a checkout order and returns `checkoutUrl` for the customer redirect.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrderRequest" } } } }, "responses": { "200": { "description": "Order created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrderResponse" } } } }, "400": { "description": "Validation failed / bad terminalId", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Merchant disabled" }, "409": { "description": "Duplicate reference", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/orders/{id}": { "get": { "tags": [ "Orders" ], "operationId": "getOrder", "summary": "Get order", "description": "Read order state. For fulfillment, call **verify** - do not fulfill from get alone.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Order", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Not found" } } } }, "/api/orders/{id}/verify": { "post": { "tags": [ "Orders" ], "operationId": "verifyOrder", "summary": "Verify payment", "description": "**Required before fulfillment.** Confirms payment with the gateway. Fulfill only when `fulfilled` is `true`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Verification result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyResponse" }, "examples": { "paid": { "summary": "Paid", "value": { "id": "019f8c2a-7b1e-7000-8000-abcdef012345", "orderId": "1000123", "status": "Success", "verified": true, "fulfilled": true, "verificationResult": "Success", "gateway": "esewa" } }, "pending": { "summary": "Not paid yet", "value": { "id": "019f8c2a-7b1e-7000-8000-abcdef012345", "status": "Open", "verified": false, "fulfilled": false, "verificationResult": "Pending" } } } } } }, "400": { "description": "No payment attempt / cannot verify" }, "401": { "description": "Unauthorized" }, "404": { "description": "Not found" } } } }, "/api/orders/{id}/return": { "post": { "tags": [ "Orders" ], "operationId": "returnOrder", "summary": "Cash sales return", "description": "Partial or full cash sales return against a Success order. Stores a refund row and creates a credit note via Awecount. Idempotent on reference.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Original payment-service order id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "method", "amount", "products", "reference" ], "properties": { "method": { "type": "string", "enum": [ "cash" ] }, "amount": { "type": "integer" }, "tax": { "type": "integer" }, "discount": { "type": "integer" }, "products": { "type": "array", "items": { "type": "object" } }, "reference": { "type": "string" }, "remarks": { "type": "string", "nullable": true }, "currency": { "type": "string" }, "customer": { "type": "object", "nullable": true } } } } } }, "responses": { "200": { "description": "Refund with credit-note receipt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refund" } } } }, "400": { "description": "Validation failed" }, "401": { "description": "Unauthorized" }, "403": { "description": "Cash not enabled" }, "404": { "description": "Not found" }, "409": { "description": "Not returnable / duplicate reference / receipt not ready / exceeds order amount" } } } }, "/api/orders/{id}/exchange": { "post": { "tags": [ "Orders" ], "operationId": "exchangeOrder", "summary": "Order exchange (CN + INV + net settle)", "description": "Amend a Success order: optional cash credit note (return), optional cash tax invoice (sale), optional net settle checkout. Settle never posts a third Awecount sales voucher. Idempotent on reference. settleAmount = max(0, sale.amount - return.amount).", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Original payment-service Success order id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "reference" ], "properties": { "reference": { "type": "string", "description": "Idempotency key (e.g. Fanpark order_adjustments.id)" }, "remarks": { "type": "string", "nullable": true }, "return": { "type": "object", "required": [ "amount", "products" ], "properties": { "amount": { "type": "integer" }, "tax": { "type": "integer" }, "discount": { "type": "integer" }, "products": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } } } }, "sale": { "type": "object", "required": [ "amount", "products" ], "properties": { "amount": { "type": "integer" }, "tax": { "type": "integer" }, "discount": { "type": "integer" }, "products": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } } } }, "settle": { "type": "object", "required": [ "method" ], "properties": { "method": { "type": "string", "enum": [ "digital", "cash" ] }, "successRedirectUrl": { "type": "string", "format": "uri", "nullable": true }, "failureRedirectUrl": { "type": "string", "format": "uri", "nullable": true }, "expiresAt": { "type": "string", "format": "date-time" } } } } } } } }, "responses": { "200": { "description": "Exchange face with optional nested return/sale and settle checkoutUrl", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "reference": { "type": "string" }, "parentOrderId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "Open", "Fulfilled", "Failed" ] }, "settleAmount": { "type": "integer" }, "settleOrderId": { "type": "string", "format": "uuid", "nullable": true }, "checkoutUrl": { "type": "string", "nullable": true }, "fulfilled": { "type": "boolean" }, "return": { "nullable": true, "$ref": "#/components/schemas/Refund" }, "sale": { "nullable": true, "$ref": "#/components/schemas/Order" } } } } } }, "400": { "description": "Validation failed" }, "401": { "description": "Unauthorized" }, "403": { "description": "Cash not enabled" }, "404": { "description": "Not found" }, "409": { "description": "Not exchangeable / duplicate reference / receipt not ready / refund exceeds order" } } } }, "/api/orders/{id}/cancel": { "post": { "tags": [ "Orders" ], "operationId": "cancelOrder", "summary": "Cancel order", "description": "Cancel an `Open` order. Already paid orders cannot be canceled.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Canceled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelResponse" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Not found" }, "409": { "description": "Not cancelable" } } } } }, "webhooks": { "paymentEvent": { "post": { "tags": [ "Webhooks" ], "summary": "Payment success or failure", "description": "Delivered to your configured success/failure webhook URL (`payment_success` / `receipt_synced` → success URL; `payment_failed` → failure URL). Same URL for both is fine.\n\nHeaders:\n- `X-Event-ID` - stable across retries (idempotency)\n- `X-Webhook-Signature: sha256=` - HMAC-SHA256 of raw body with your signing secret (UTF-8)\n\nRetries: max 6 attempts; backoff 1m, 5m, 15m, 1h, 4h, then Exhausted.\n\nBody includes `id` (our order UUID) for verify. Respond `2xx`. Still call **verify** before fulfillment.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "2XX": { "description": "Acknowledge receipt" } } } } } }