{ "info": { "name": "Shukria Payments — Merchant API", "description": "The complete merchant-facing surface. Everything here matches `merchant/INTEGRATION.md`.\n\n**Every URL is a shukriapg URL.** You never connect to a payment network directly and never hold network credentials.\n\n**Setup**\n1. Set `base_url` (default is the shared test host).\n2. Set `merchantId` and `merchantKey` to the credentials issued to you.\n3. Run **Start a test payment**, pay in the browser, then run **Check payment status** with the same `orderId`.\n\n**The one rule**\nConfirm payments from your server before fulfilling. Browser callbacks and redirect parameters reach you through the customer's browser and can be altered; the status endpoint cannot.", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json" }, "variable": [ { "key": "base_url", "value": "https://shukriapg.ariticapp.com", "description": "Shukria Payments host." }, { "key": "pg_prefix", "value": "/pgpayments", "description": "Path the payment service is served under. Leave as is unless told otherwise." }, { "key": "merchantId", "value": "YOUR_MERCHANT_ID", "description": "Issued to you by Shukria." }, { "key": "merchantKey", "value": "YOUR_MERCHANT_KEY", "description": "Issued to you by Shukria. Keep it in a Postman environment, not here." }, { "key": "orderId", "value": "", "description": "Your order reference. Set automatically by 'Start a test payment'." } ], "item": [ { "name": "1 · Check the integration", "description": "Confirm you can reach Shukria and that your base URL is right.", "item": [ { "name": "Load the payment widget", "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "pm.test('widget is reachable', function () {", " pm.response.to.have.status(200);", "});", "pm.test('looks like the widget script', function () {", " pm.expect(pm.response.text()).to.include('ShukriaPayment');", "});", "console.log('Add this to your checkout page:');", "console.log('');" ] } } ], "request": { "method": "GET", "header": [], "url": { "raw": "{{base_url}}{{pg_prefix}}/shukria-payment-widget.js", "host": [ "{{base_url}}{{pg_prefix}}" ], "path": [ "shukria-payment-widget.js" ] }, "description": "The JavaScript you include on your checkout page.\n\nA 200 here means your `base_url` and `pg_prefix` are correct. If this fails, nothing else will work." }, "response": [] } ] }, { "name": "2 · Take a payment", "description": "In production you call `ShukriaPayment.process()` and the widget opens the payment window for you. This request opens the same window directly, which is useful for testing without building a page first.", "item": [ { "name": "Start a test payment", "event": [ { "listen": "prerequest", "script": { "type": "text/javascript", "exec": [ "// A fresh order reference per attempt — reusing one is rejected.", "pm.collectionVariables.set('orderId', 'ORD_' + Date.now());", "console.log('orderId:', pm.collectionVariables.get('orderId'));" ] } }, { "listen": "test", "script": { "type": "text/javascript", "exec": [ "pm.test('payment page opens', function () {", " pm.expect(pm.response.code).to.be.oneOf([200, 302]);", "});", "", "if (pm.response.code === 400) {", " console.log('Your merchantId is not configured for payments yet.');", "}", "", "console.log('This returns a web page. To actually pay, open the URL below');", "console.log('in a browser, then run \"Check payment status\".');", "console.log(pm.request.url.toString());" ] } } ], "request": { "method": "GET", "header": [], "url": { "raw": "{{base_url}}{{pg_prefix}}/pay/start?merchantId={{merchantId}}&amount=10.00¤cy=AED&order_id={{orderId}}&customer_name=Test Customer&email=test@example.com&phone=+971500000000&description=Postman test&return_url=https://example.com/thanks", "host": [ "{{base_url}}{{pg_prefix}}" ], "path": [ "pay", "start" ], "query": [ { "key": "merchantId", "value": "{{merchantId}}", "description": "Issued to you by Shukria" }, { "key": "amount", "value": "10.00" }, { "key": "currency", "value": "AED" }, { "key": "order_id", "value": "{{orderId}}", "description": "Your reference — unique per attempt" }, { "key": "customer_name", "value": "Test Customer" }, { "key": "email", "value": "test@example.com" }, { "key": "phone", "value": "+971500000000" }, { "key": "description", "value": "Postman test" }, { "key": "return_url", "value": "https://example.com/thanks", "description": "Where the customer lands after paying" } ] }, "description": "Opens a payment page. **Returns HTML** — Postman will show the markup; open the URL in a browser to complete a payment.\n\nThe pre-request script generates a fresh `orderId`, because reusing one from a previous attempt is rejected.\n\nA `400` means your `merchantId` is not yet configured for payments." }, "response": [] } ] }, { "name": "3 · Confirm the outcome", "description": "The authoritative answer. Use it before fulfilling an order, whenever a customer closes the window, and when reconciling.", "item": [ { "name": "Check payment status", "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "const body = pm.response.json();", "", "pm.test('responds 200 (found) or 404 (unknown reference)', function () {", " pm.expect(pm.response.code).to.be.oneOf([200, 404]);", "});", "", "if (pm.response.code === 404) {", " console.log('No payment found for that orderId.');", " return;", "}", "", "const p = body.payment;", "", "pm.test('carries the documented result fields', function () {", " ['status_code','status','order_id','transaction_id',", " 'amount','currency','message'].forEach(function (k) {", " pm.expect(p).to.have.property(k);", " });", "});", "", "// Compare against the number, not the string.", "pm.test('status_code is a number', function () {", " pm.expect(p.status_code).to.be.a('number');", " pm.expect([1200, 1400, 1100]).to.include(p.status_code);", "});", "", "pm.test('no full card number is ever returned', function () {", " if (p.masked_card) pm.expect(p.masked_card).to.match(/[x*]/i);", "});", "", "if (p.status_code === 1200) {", " console.log('PAID — verify server-side, then fulfil. txn:', p.transaction_id);", "} else if (p.status_code === 1400) {", " console.log('FAILED —', p.message, '| retry needs a NEW orderId.');", "} else {", " console.log('PENDING — do NOT fulfil and do NOT fail. Re-check shortly.');", "}" ] } } ], "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}{{pg_prefix}}/pay/status/{{orderId}}", "host": [ "{{base_url}}{{pg_prefix}}" ], "path": [ "pay", "status", "{{orderId}}" ] }, "description": "Query with **your own order reference** — the `orderId` you sent.\n\n```json\n{\n \"success\": true,\n \"payment\": {\n \"status_code\": 1200,\n \"status\": \"success\",\n \"order_id\": \"ORD_123\",\n \"transaction_id\": \"TXN-88213-1\",\n \"amount\": \"6297.90\",\n \"currency\": \"AED\",\n \"message\": \"Payment successful\",\n \"approval_code\": \"OK1234\",\n \"masked_card\": \"512345xxxxxx0008\"\n }\n}\n```\n\n| Code | Meaning | Do |\n|---|---|---|\n| `1200` | Approved, funds captured | Fulfil |\n| `1400` | Declined or cancelled | Offer a retry with a **new** `orderId` |\n| `1100` | Not yet resolved | **Hold.** Do not fulfil, do not fail |\n\n`404` means no payment exists for that reference.\n\n`status_code` is a **number** — compare against `1200`, not `\"1200\"`." }, "response": [] }, { "name": "Re-check a pending payment", "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "const body = pm.response.json();", "", "pm.test('responds 200 (found) or 404 (unknown reference)', function () {", " pm.expect(pm.response.code).to.be.oneOf([200, 404]);", "});", "", "if (pm.response.code === 404) {", " console.log('No payment found for that orderId.');", " return;", "}", "", "const p = body.payment;", "", "pm.test('carries the documented result fields', function () {", " ['status_code','status','order_id','transaction_id',", " 'amount','currency','message'].forEach(function (k) {", " pm.expect(p).to.have.property(k);", " });", "});", "", "// Compare against the number, not the string.", "pm.test('status_code is a number', function () {", " pm.expect(p.status_code).to.be.a('number');", " pm.expect([1200, 1400, 1100]).to.include(p.status_code);", "});", "", "pm.test('no full card number is ever returned', function () {", " if (p.masked_card) pm.expect(p.masked_card).to.match(/[x*]/i);", "});", "", "if (p.status_code === 1200) {", " console.log('PAID — verify server-side, then fulfil. txn:', p.transaction_id);", "} else if (p.status_code === 1400) {", " console.log('FAILED —', p.message, '| retry needs a NEW orderId.');", "} else {", " console.log('PENDING — do NOT fulfil and do NOT fail. Re-check shortly.');", "}" ] } } ], "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}{{pg_prefix}}/pay/status/{{orderId}}?refresh=true", "host": [ "{{base_url}}{{pg_prefix}}" ], "path": [ "pay", "status", "{{orderId}}" ], "query": [ { "key": "refresh", "value": "true" } ] }, "description": "Forces a fresh check with the payment network rather than answering from the last known state.\n\nUse it when a payment has sat at `1100` (pending), or when your records and ours disagree.\n\nThis is slower than the plain status call — use it to resolve a specific payment, not for routine polling." }, "response": [] } ] } ] }