{ "item": [ { "id": "be956002-c405-4972-86f7-d70b596abd5f", "name": "Payments", "description": { "content": "Create, inspect, and mutate gateway payments.", "type": "text/plain" }, "item": [ { "id": "76f634ba-8c4e-4ede-8ac6-258e0889ed5b", "name": "Create a gateway payment. [DEPRECATED — use `/v1/trades`]", "request": { "name": "Create a gateway payment. [DEPRECATED — use `/v1/trades`]", "description": {}, "url": { "path": [ "v1", "payments" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "auth": { "type": "apikey", "apikey": [ { "key": "key", "value": "X-API-Key" }, { "key": "value", "value": "{{apiKey}}" }, { "key": "in", "value": "header" } ] }, "body": { "mode": "raw", "raw": "{\n \"order_id\": \"\",\n \"amount\": \"\",\n \"currency\": \"\",\n \"payment_methods\": [\n \"\"\n ],\n \"customer_email\": \"\",\n \"notify_url\": \"\",\n \"return_url\": \"\",\n \"metadata\": {\n \"key_0\": 6603,\n \"key_1\": \"string\",\n \"key_2\": 9349\n }\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "id": "3ed1ce52-79ce-44bd-a459-4fa259a380fc", "name": "Payment created and matched (or matching).", "originalRequest": { "url": { "path": [ "v1", "payments" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"order_id\": \"\",\n \"amount\": \"\",\n \"currency\": \"SGD\",\n \"payment_methods\": [\n \"\"\n ],\n \"customer_email\": \"\",\n \"notify_url\": \"\",\n \"return_url\": \"\",\n \"metadata\": {\n \"key_0\": 7808.76095322194\n }\n}", "options": { "raw": { "language": "json" } } } }, "status": "Created", "code": 201, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"data\": {\n \"id\": \"3bf5ed68-101c-1078-8149-7f39b06d0b49\",\n \"merchant_id\": \"0c4bb3cd-3572-387a-1219-fd2fdba0efdf\",\n \"order_id\": \"string\",\n \"amount\": \"-07\",\n \"currency\": \"USD\",\n \"status\": \"payment_pending\",\n \"expires_at\": \"2000-02-28T23:01:05.375Z\",\n \"version\": 7385,\n \"created_at\": \"1998-06-06T12:17:32.634Z\",\n \"updated_at\": \"1973-04-02T01:51:22.485Z\",\n \"aggregator_id\": \"string\",\n \"sub_merchant_id\": \"string\",\n \"sub_merchant_name\": \"string\",\n \"upstream_trade_no\": \"string\",\n \"checkout_url\": \"http://VlhQKyEV.wialv,AuMtweG\",\n \"notify_url\": \"http://JjwHqfiIHetakuVdKmbykskdAumCskwUd.ddmuui31Cpa6xfnw7L\",\n \"return_url\": \"https://RxatDHdNBOFWSRcGlnopRf.bognXftq2GX+TbrtUksT.EMdHaJ1lPEY,i8MitM0UjyP1F.F.C9opIxKbEvQwefg6y,SVHo2\",\n \"customer_email\": \"WLvNwxF1tCGT@aehcirBYLvWAqeMBRCUJlk.hf\",\n \"customer_name\": \"string\",\n \"metadata\": {\n \"key_0\": 6443,\n \"key_1\": true,\n \"key_2\": true\n },\n \"match_type\": \"string\",\n \"matched_at\": \"2025-11-22T08:56:20.818Z\",\n \"completed_at\": \"1993-06-23T14:55:54.479Z\",\n \"failed_at\": \"2001-06-28T09:34:11.976Z\",\n \"failure_reason\": \"string\",\n \"matches\": [\n {\n \"id\": \"2fc688c5-7fdc-348e-b71f-a2f2a477247a\",\n \"trade_id\": \"fac695ed-0b5a-1392-b3cb-7a951a20a36f\",\n \"seller_id\": \"0fee6b04-3627-79a3-1e42-004675409ba8\",\n \"allocated_fiat_amount\": 3477,\n \"allocated_token_amount\": 9776,\n \"rate\": 7599,\n \"match_order\": 8391,\n \"status\": \"string\"\n },\n {\n \"id\": \"39edaf36-352d-d27f-daf2-559a2e977da4\",\n \"trade_id\": \"8532511d-1401-c959-7350-4ad40ec082b6\",\n \"seller_id\": \"a9259353-0ddd-b87a-12bb-746d37cdadc2\",\n \"allocated_fiat_amount\": 2839,\n \"allocated_token_amount\": 9275,\n \"rate\": 1514,\n \"match_order\": 4232,\n \"status\": \"string\"\n }\n ]\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "e0db007a-676e-4136-a78c-e7c5d4d2dcd7", "name": "Validation error.", "originalRequest": { "url": { "path": [ "v1", "payments" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"order_id\": \"\",\n \"amount\": \"\",\n \"currency\": \"SGD\",\n \"payment_methods\": [\n \"\"\n ],\n \"customer_email\": \"\",\n \"notify_url\": \"\",\n \"return_url\": \"\",\n \"metadata\": {\n \"key_0\": 7808.76095322194\n }\n}", "options": { "raw": { "language": "json" } } } }, "status": "Bad Request", "code": 400, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "6590bbf0-2a9b-4f99-b697-a4eac139a44d", "name": "Missing or invalid API key.", "originalRequest": { "url": { "path": [ "v1", "payments" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"order_id\": \"\",\n \"amount\": \"\",\n \"currency\": \"SGD\",\n \"payment_methods\": [\n \"\"\n ],\n \"customer_email\": \"\",\n \"notify_url\": \"\",\n \"return_url\": \"\",\n \"metadata\": {\n \"key_0\": 7808.76095322194\n }\n}", "options": { "raw": { "language": "json" } } } }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "d24ea761-9d3b-461a-89db-59bdc77a447d", "name": "Duplicate `order_id`, or insufficient liquidity.", "originalRequest": { "url": { "path": [ "v1", "payments" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"order_id\": \"\",\n \"amount\": \"\",\n \"currency\": \"SGD\",\n \"payment_methods\": [\n \"\"\n ],\n \"customer_email\": \"\",\n \"notify_url\": \"\",\n \"return_url\": \"\",\n \"metadata\": {\n \"key_0\": 7808.76095322194\n }\n}", "options": { "raw": { "language": "json" } } } }, "status": "Conflict", "code": 409, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "7ebf21da-dac1-4330-ad74-e33806d312e9", "name": "Internal error.", "originalRequest": { "url": { "path": [ "v1", "payments" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"order_id\": \"\",\n \"amount\": \"\",\n \"currency\": \"SGD\",\n \"payment_methods\": [\n \"\"\n ],\n \"customer_email\": \"\",\n \"notify_url\": \"\",\n \"return_url\": \"\",\n \"metadata\": {\n \"key_0\": 7808.76095322194\n }\n}", "options": { "raw": { "language": "json" } } } }, "status": "Internal Server Error", "code": 500, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "6b21b459-eb9a-44cd-b29e-57020033c9f8", "name": "List payments for the authenticated merchant.", "request": { "name": "List payments for the authenticated merchant.", "description": {}, "url": { "path": [ "v1", "payments" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "key": "status", "value": "" }, { "disabled": false, "key": "from", "value": "", "description": "Lower bound on `created_at` (RFC 3339)." }, { "disabled": false, "key": "to", "value": "", "description": "Upper bound on `created_at` (RFC 3339)." }, { "disabled": false, "key": "limit", "value": "20" }, { "disabled": false, "key": "offset", "value": "0" } ], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "auth": { "type": "apikey", "apikey": [ { "key": "key", "value": "X-API-Key" }, { "key": "value", "value": "{{apiKey}}" }, { "key": "in", "value": "header" } ] } }, "response": [ { "id": "815b251b-cd1e-470e-93fd-c74291be25f2", "name": "Paginated list of payments.", "originalRequest": { "url": { "path": [ "v1", "payments" ], "host": [ "{{baseUrl}}" ], "query": [ { "key": "status", "value": "payment_sent" }, { "key": "from", "value": "" }, { "key": "to", "value": "" }, { "key": "limit", "value": "20" }, { "key": "offset", "value": "0" } ], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"data\": [\n {\n \"id\": \"6c9476f6-767d-080a-286c-e5ed15e15545\",\n \"merchant_id\": \"e63569f4-21a7-e41c-99bf-497f2eb1e115\",\n \"order_id\": \"string\",\n \"amount\": \"033\",\n \"currency\": \"SGD\",\n \"status\": \"payment_sent\",\n \"expires_at\": \"2022-04-07T05:25:41.572Z\",\n \"version\": 4989,\n \"created_at\": \"2003-06-01T16:32:19.784Z\",\n \"updated_at\": \"1990-05-13T12:37:50.707Z\",\n \"aggregator_id\": \"string\",\n \"sub_merchant_id\": \"string\",\n \"sub_merchant_name\": \"string\",\n \"upstream_trade_no\": \"string\",\n \"checkout_url\": \"http://wuGLDREehzFFbYMnNd.debXYH6OOvn44IM59,\",\n \"notify_url\": \"http://gBVPWsZnuKt.lieoW+blVPPLgX,+M0ZyXgB6CkGpAeUESIHKd,z6qbmdXJbmFPG,vYB4b8+Yn-T4L0l1FoldSwzzCL3CpBHdmZP\",\n \"return_url\": \"https://pfUtnToFMpdbfio.wtZe4x3-kF7\",\n \"customer_email\": \"ZW0VtqH-TG@WNnycYaQNnOBtlUSbegvsP.to\",\n \"customer_name\": \"string\",\n \"metadata\": {\n \"key_0\": true,\n \"key_1\": 2125\n },\n \"match_type\": \"string\",\n \"matched_at\": \"2020-01-16T12:27:53.602Z\",\n \"completed_at\": \"2008-03-26T13:25:10.074Z\",\n \"failed_at\": \"1967-10-20T04:42:36.980Z\",\n \"failure_reason\": \"string\"\n },\n {\n \"id\": \"56604730-1611-13c8-ab60-8e6dac093d2d\",\n \"merchant_id\": \"fe72e8d8-13b1-c795-7095-0dc1ee1604e5\",\n \"order_id\": \"string\",\n \"amount\": \"32436753\",\n \"currency\": \"THB\",\n \"status\": \"payment_sent\",\n \"expires_at\": \"1954-11-01T09:14:17.815Z\",\n \"version\": 8146,\n \"created_at\": \"1994-07-31T20:24:38.071Z\",\n \"updated_at\": \"1964-04-23T05:18:08.917Z\",\n \"aggregator_id\": \"string\",\n \"sub_merchant_id\": \"string\",\n \"sub_merchant_name\": \"string\",\n \"upstream_trade_no\": \"string\",\n \"checkout_url\": \"http://VnXLsb.nmqlcmZDRF8X06XwsCxyPNi,iUg5RQ6Doj6jTmHat9E4.rw\",\n \"notify_url\": \"https://MrfxGOOHENZld.dbn9MU.JOe+a\",\n \"return_url\": \"http://TfMgrbNWGDxorUBNOfLutsocxTah.skiwYn8KN.V8YSLjIxjcfIq1skNiWvB+SbnhlJU2oNS6AUd36qyg74-5C\",\n \"customer_email\": \"7FDExWg@aMXMLndB.yxda\",\n \"customer_name\": \"string\",\n \"metadata\": {\n \"key_0\": false,\n \"key_1\": false\n },\n \"match_type\": \"string\",\n \"matched_at\": \"2026-01-09T02:05:07.927Z\",\n \"completed_at\": \"2019-04-01T11:26:38.335Z\",\n \"failed_at\": \"2000-02-19T12:25:34.619Z\",\n \"failure_reason\": \"string\"\n }\n ],\n \"meta\": {\n \"total\": 8374,\n \"limit\": 1227,\n \"offset\": 9983\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "eff2208d-3356-4f1b-8bc1-c414c289e874", "name": "Missing or invalid API key.", "originalRequest": { "url": { "path": [ "v1", "payments" ], "host": [ "{{baseUrl}}" ], "query": [ { "key": "status", "value": "payment_sent" }, { "key": "from", "value": "" }, { "key": "to", "value": "" }, { "key": "limit", "value": "20" }, { "key": "offset", "value": "0" } ], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "4ee69608-316d-4c1b-b752-16c627382b1b", "name": "Internal error.", "originalRequest": { "url": { "path": [ "v1", "payments" ], "host": [ "{{baseUrl}}" ], "query": [ { "key": "status", "value": "payment_sent" }, { "key": "from", "value": "" }, { "key": "to", "value": "" }, { "key": "limit", "value": "20" }, { "key": "offset", "value": "0" } ], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Internal Server Error", "code": 500, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "428d759d-3fd2-41f9-b3b8-26e6d6cf9842", "name": "Get a payment by ID.", "request": { "name": "Get a payment by ID.", "description": { "content": "If the payment is in `matched` or `payment_pending` state and the\n`expires_at` deadline has passed, this endpoint lazily transitions\nthe payment to `expired` (and fires a `payment.expired` webhook).\n", "type": "text/plain" }, "url": { "path": [ "v1", "payments", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) Payment ID (UUID v4)." } ] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "auth": { "type": "apikey", "apikey": [ { "key": "key", "value": "X-API-Key" }, { "key": "value", "value": "{{apiKey}}" }, { "key": "in", "value": "header" } ] } }, "response": [ { "id": "c3a5515b-bd96-415c-a0b8-247b646691ea", "name": "Payment details.", "originalRequest": { "url": { "path": [ "v1", "payments", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) Payment ID (UUID v4)." } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"data\": {\n \"id\": \"965b42dc-db27-5486-3319-427ea489c8ba\",\n \"merchant_id\": \"1be60c5a-42de-25a9-a1a5-48e09dd2da13\",\n \"order_id\": \"string\",\n \"amount\": \"869061\",\n \"currency\": \"THB\",\n \"status\": \"payment_pending\",\n \"expires_at\": \"2012-09-23T02:05:17.497Z\",\n \"version\": 8988,\n \"created_at\": \"2006-12-07T00:46:50.484Z\",\n \"updated_at\": \"2006-11-13T12:55:42.831Z\",\n \"aggregator_id\": \"string\",\n \"sub_merchant_id\": \"string\",\n \"sub_merchant_name\": \"string\",\n \"upstream_trade_no\": \"string\",\n \"checkout_url\": \"http://aonIXOXSCbLsqaPrTiVVrDrTLtIh.vwRJdzJehbuAgpvCP6EG+ENbhWTxqcP8cheK\",\n \"notify_url\": \"http://lscTOABTgeugJnhkgxX.pfcyRvUu0sdJZ0\",\n \"return_url\": \"https://nJBf.yitmb6hz7QbCVkV5Dg9G-bdJPvvwgYBZRKdVmmQIXJf-kC\",\n \"customer_email\": \"JwtNtN@WIvubxIqMqwMdtRbyZTuKFf.ns\",\n \"customer_name\": \"string\",\n \"metadata\": {\n \"key_0\": \"string\",\n \"key_1\": \"string\"\n },\n \"match_type\": \"string\",\n \"matched_at\": \"2016-06-09T00:31:45.691Z\",\n \"completed_at\": \"1959-06-22T18:07:40.496Z\",\n \"failed_at\": \"1983-11-17T15:01:18.568Z\",\n \"failure_reason\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "67a44f13-24b0-4f36-858a-a2f95d12a482", "name": "Invalid ID format.", "originalRequest": { "url": { "path": [ "v1", "payments", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) Payment ID (UUID v4)." } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Bad Request", "code": 400, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "9afc0303-8cc0-42d0-b049-334824eded29", "name": "Missing or invalid API key.", "originalRequest": { "url": { "path": [ "v1", "payments", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) Payment ID (UUID v4)." } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "2f1dbf7c-3040-486d-9097-53f9c3035e9a", "name": "Payment not found, or not owned by this merchant.", "originalRequest": { "url": { "path": [ "v1", "payments", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) Payment ID (UUID v4)." } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "09fac658-e341-4e2c-9b59-88478bb473d0", "name": "Fetch the data needed to render the checkout widget.", "request": { "name": "Fetch the data needed to render the checkout widget.", "description": {}, "url": { "path": [ "v1", "payments", ":id", "checkout" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) Payment ID (UUID v4)." } ] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "auth": { "type": "apikey", "apikey": [ { "key": "key", "value": "X-API-Key" }, { "key": "value", "value": "{{apiKey}}" }, { "key": "in", "value": "header" } ] } }, "response": [ { "id": "ff584d9a-2cf8-4d06-bd92-32749d02d69a", "name": "Checkout view-model.", "originalRequest": { "url": { "path": [ "v1", "payments", ":id", "checkout" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) Payment ID (UUID v4)." } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"data\": {\n \"payment\": {\n \"id\": \"81ded356-a1dc-4c01-36b6-4fa02f5e1b75\",\n \"order_id\": \"string\",\n \"amount\": \"-56\",\n \"currency\": \"SGD\",\n \"status\": \"expired\",\n \"expires_at\": \"2007-11-06T13:48:43.050Z\",\n \"return_url\": \"http://jxJnRMvWFeeTa.yjPOsrhQrjvu9sNWxLayU\"\n },\n \"merchant\": {\n \"id\": \"7449ed53-7e7b-f8e2-262c-ca4f8fecc959\"\n }\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "9d10aead-e474-4388-a90d-737e2e74ed81", "name": "Invalid ID format.", "originalRequest": { "url": { "path": [ "v1", "payments", ":id", "checkout" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) Payment ID (UUID v4)." } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Bad Request", "code": 400, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "9e1cd46b-ebf1-4855-afc6-22124c416efd", "name": "Missing or invalid API key.", "originalRequest": { "url": { "path": [ "v1", "payments", ":id", "checkout" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) Payment ID (UUID v4)." } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "d8d8191c-06d5-4903-a466-e34e9f75f7df", "name": "Payment not found, or not owned by this merchant.", "originalRequest": { "url": { "path": [ "v1", "payments", ":id", "checkout" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) Payment ID (UUID v4)." } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "1af18dae-f1a1-4a16-8f8b-a8fbdec1620a", "name": "Cancel a payment that is still in an early (pre-paid) state.", "request": { "name": "Cancel a payment that is still in an early (pre-paid) state.", "description": { "content": "Cancellation is only permitted when the payment is in `created` or\n`matching` status — see `PaymentStatus.CanCancel()`.\n", "type": "text/plain" }, "url": { "path": [ "v1", "payments", ":id", "cancel" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) Payment ID (UUID v4)." } ] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "POST", "auth": { "type": "apikey", "apikey": [ { "key": "key", "value": "X-API-Key" }, { "key": "value", "value": "{{apiKey}}" }, { "key": "in", "value": "header" } ] } }, "response": [ { "id": "c433aef3-a82e-4de4-83a5-bae8e1909c5e", "name": "Payment cancelled.", "originalRequest": { "url": { "path": [ "v1", "payments", ":id", "cancel" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) Payment ID (UUID v4)." } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"data\": {\n \"id\": \"965b42dc-db27-5486-3319-427ea489c8ba\",\n \"merchant_id\": \"1be60c5a-42de-25a9-a1a5-48e09dd2da13\",\n \"order_id\": \"string\",\n \"amount\": \"869061\",\n \"currency\": \"THB\",\n \"status\": \"payment_pending\",\n \"expires_at\": \"2012-09-23T02:05:17.497Z\",\n \"version\": 8988,\n \"created_at\": \"2006-12-07T00:46:50.484Z\",\n \"updated_at\": \"2006-11-13T12:55:42.831Z\",\n \"aggregator_id\": \"string\",\n \"sub_merchant_id\": \"string\",\n \"sub_merchant_name\": \"string\",\n \"upstream_trade_no\": \"string\",\n \"checkout_url\": \"http://aonIXOXSCbLsqaPrTiVVrDrTLtIh.vwRJdzJehbuAgpvCP6EG+ENbhWTxqcP8cheK\",\n \"notify_url\": \"http://lscTOABTgeugJnhkgxX.pfcyRvUu0sdJZ0\",\n \"return_url\": \"https://nJBf.yitmb6hz7QbCVkV5Dg9G-bdJPvvwgYBZRKdVmmQIXJf-kC\",\n \"customer_email\": \"JwtNtN@WIvubxIqMqwMdtRbyZTuKFf.ns\",\n \"customer_name\": \"string\",\n \"metadata\": {\n \"key_0\": \"string\",\n \"key_1\": \"string\"\n },\n \"match_type\": \"string\",\n \"matched_at\": \"2016-06-09T00:31:45.691Z\",\n \"completed_at\": \"1959-06-22T18:07:40.496Z\",\n \"failed_at\": \"1983-11-17T15:01:18.568Z\",\n \"failure_reason\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "c1080777-a805-4ba4-9771-a36a6599e5ad", "name": "Invalid ID format.", "originalRequest": { "url": { "path": [ "v1", "payments", ":id", "cancel" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) Payment ID (UUID v4)." } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": {} }, "status": "Bad Request", "code": 400, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "5c08b060-63e4-4f5b-8911-672fe048b002", "name": "Missing or invalid API key.", "originalRequest": { "url": { "path": [ "v1", "payments", ":id", "cancel" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) Payment ID (UUID v4)." } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": {} }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "c8d031a5-766b-434d-87de-e014e6d08ea3", "name": "Payment not found, or not owned by this merchant.", "originalRequest": { "url": { "path": [ "v1", "payments", ":id", "cancel" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) Payment ID (UUID v4)." } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": {} }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "74f208b6-1d82-448e-8c25-7316e2e686b5", "name": "Payment is past the cancellable window.", "originalRequest": { "url": { "path": [ "v1", "payments", ":id", "cancel" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) Payment ID (UUID v4)." } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": {} }, "status": "Conflict", "code": 409, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "58a78d6c-5d72-4a87-9c2e-75deec102652", "name": "Upload a payment proof image and transition to `confirming`.", "request": { "name": "Upload a payment proof image and transition to `confirming`.", "description": { "content": "Accepts a multipart form with a single file field named `proof`. The\npayment must be in `matched` or `payment_pending` state for the\nupload to be accepted.\n", "type": "text/plain" }, "url": { "path": [ "v1", "payments", ":id", "proof" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) Payment ID (UUID v4)." } ] }, "header": [ { "key": "Content-Type", "value": "multipart/form-data" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "auth": { "type": "apikey", "apikey": [ { "key": "key", "value": "X-API-Key" }, { "key": "value", "value": "{{apiKey}}" }, { "key": "in", "value": "header" } ] }, "body": { "mode": "formdata", "formdata": [ { "key": "proof", "type": "file", "description": "(Required) The payment proof image (any common raster format)." } ] } }, "response": [ { "id": "74ec0669-8e31-4515-b1a8-dc62d1b344bf", "name": "Proof accepted; payment is now `confirming`.", "originalRequest": { "url": { "path": [ "v1", "payments", ":id", "proof" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) Payment ID (UUID v4)." } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "formdata", "formdata": [ { "description": { "content": "(Required) The payment proof image (any common raster format).", "type": "text/plain" }, "key": "proof", "value": "", "type": "text" } ] } }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"data\": {\n \"payment_id\": \"840f95ad-9c03-05df-e741-fa6a49ca2309\",\n \"status\": \"created\",\n \"message\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "1bf5d3c1-f9ae-4a5e-9cdc-746f8b0349ca", "name": "Invalid ID format, or missing `proof` field.", "originalRequest": { "url": { "path": [ "v1", "payments", ":id", "proof" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) Payment ID (UUID v4)." } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "formdata", "formdata": [ { "description": { "content": "(Required) The payment proof image (any common raster format).", "type": "text/plain" }, "key": "proof", "value": "", "type": "text" } ] } }, "status": "Bad Request", "code": 400, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "518db7ad-1a33-4334-bb44-7f88da0e9920", "name": "Missing or invalid API key.", "originalRequest": { "url": { "path": [ "v1", "payments", ":id", "proof" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) Payment ID (UUID v4)." } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "formdata", "formdata": [ { "description": { "content": "(Required) The payment proof image (any common raster format).", "type": "text/plain" }, "key": "proof", "value": "", "type": "text" } ] } }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "dd0b936a-bbc8-4909-b7a7-a913fc6621d5", "name": "Payment not found, or not owned by this merchant.", "originalRequest": { "url": { "path": [ "v1", "payments", ":id", "proof" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) Payment ID (UUID v4)." } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "formdata", "formdata": [ { "description": { "content": "(Required) The payment proof image (any common raster format).", "type": "text/plain" }, "key": "proof", "value": "", "type": "text" } ] } }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "07517e2f-201c-4c79-af0a-628cb10044b0", "name": "Payment is not in a state that accepts proof.", "originalRequest": { "url": { "path": [ "v1", "payments", ":id", "proof" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) Payment ID (UUID v4)." } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "formdata", "formdata": [ { "description": { "content": "(Required) The payment proof image (any common raster format).", "type": "text/plain" }, "key": "proof", "value": "", "type": "text" } ] } }, "status": "Conflict", "code": 409, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "b8882c7b-a0ce-4c2a-83a0-b185b873d3ea", "name": "Internal error while reading the proof file.", "originalRequest": { "url": { "path": [ "v1", "payments", ":id", "proof" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) Payment ID (UUID v4)." } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "formdata", "formdata": [ { "description": { "content": "(Required) The payment proof image (any common raster format).", "type": "text/plain" }, "key": "proof", "value": "", "type": "text" } ] } }, "status": "Internal Server Error", "code": 500, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "22dcc7a3-19f4-4fe9-a8eb-339fccac9bc2", "name": "PNG render of the dynamic PromptPay QR for a payment.", "request": { "name": "PNG render of the dynamic PromptPay QR for a payment.", "description": { "content": "Public endpoint — no `X-API-Key` required. Access control is by\nunguessable UUID, matching the seller-facing checkout page. Only\navailable for THB payments; returns `NOT_TH` otherwise.\n", "type": "text/plain" }, "url": { "path": [ "v1", "payments", ":id", "promptpay-qr" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) Payment ID (UUID v4)." } ] }, "header": [ { "key": "Accept", "value": "image/png" } ], "method": "GET", "auth": null }, "response": [ { "id": "3ff114f7-6b14-4d8f-92a2-1e03df77a9c8", "name": "PNG image of the EMVCo PromptPay QR.", "originalRequest": { "url": { "path": [ "v1", "payments", ":id", "promptpay-qr" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) Payment ID (UUID v4)." } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "image/png" } ], "method": "GET", "body": {} }, "status": "OK", "code": 200, "header": [ { "disabled": false, "description": "`public, max-age=300`.", "key": "Cache-Control", "value": "string" }, { "key": "Content-Type", "value": "image/png" } ], "body": "string", "cookie": [], "_postman_previewlanguage": "text" }, { "id": "aa610cab-363c-4812-b39f-1ffd00b6c561", "name": "Invalid payment ID, or payment is not THB.", "originalRequest": { "url": { "path": [ "v1", "payments", ":id", "promptpay-qr" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) Payment ID (UUID v4)." } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Bad Request", "code": 400, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "edec0d75-e890-4e09-a2dd-b262a2678c41", "name": "Handler was not configured with a DB pool, or an internal render error occurred.", "originalRequest": { "url": { "path": [ "v1", "payments", ":id", "promptpay-qr" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) Payment ID (UUID v4)." } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Internal Server Error", "code": 500, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } } ], "event": [] }, { "id": "b0a26f89-bf93-442f-8b56-d768338e2a62", "name": "Rates", "description": { "content": "Liquidity and pricing snapshots for supported currencies.", "type": "text/plain" }, "item": [ { "id": "12a0f1e6-c649-4524-8b06-d89d70995f6c", "name": "Snapshot of liquidity and best-rate for a currency/payment-method pair.", "request": { "name": "Snapshot of liquidity and best-rate for a currency/payment-method pair.", "description": {}, "url": { "path": [ "v1", "rates" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "key": "currency", "value": "", "description": "(Required) " }, { "disabled": false, "key": "payment_method", "value": "", "description": "(Required) E.g. `payid`, `promptpay`, `bank_transfer`." } ], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "auth": { "type": "apikey", "apikey": [ { "key": "key", "value": "X-API-Key" }, { "key": "value", "value": "{{apiKey}}" }, { "key": "in", "value": "header" } ] } }, "response": [ { "id": "165856b3-0304-493d-b8d2-512be3475429", "name": "Rate snapshot.", "originalRequest": { "url": { "path": [ "v1", "rates" ], "host": [ "{{baseUrl}}" ], "query": [ { "key": "currency", "value": "" }, { "key": "payment_method", "value": "" } ], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"data\": {\n \"currency\": \"THB\",\n \"payment_method\": \"string\",\n \"total_available_fiat\": 6718,\n \"seller_count\": 569,\n \"best_rate\": 2816,\n \"estimated_token_amount\": 1449\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "2af5c6b2-af00-4d74-8b0a-23945ecae8e6", "name": "Missing required query parameter.", "originalRequest": { "url": { "path": [ "v1", "rates" ], "host": [ "{{baseUrl}}" ], "query": [ { "key": "currency", "value": "" }, { "key": "payment_method", "value": "" } ], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Bad Request", "code": 400, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "4db67b65-5334-4016-a099-bc06c597142f", "name": "Missing or invalid API key.", "originalRequest": { "url": { "path": [ "v1", "rates" ], "host": [ "{{baseUrl}}" ], "query": [ { "key": "currency", "value": "" }, { "key": "payment_method", "value": "" } ], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "0e23b1f8-be73-4e22-92f3-8ca179bedc8a", "name": "Matching service unreachable or returned an error.", "originalRequest": { "url": { "path": [ "v1", "rates" ], "host": [ "{{baseUrl}}" ], "query": [ { "key": "currency", "value": "" }, { "key": "payment_method", "value": "" } ], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Internal Server Error", "code": 500, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } } ], "event": [] }, { "id": "44a6f044-3219-4586-9ee5-e57d3d2cb1d9", "name": "Reference", "description": { "content": "Read-only reference data (e.g. Thai bank directory).", "type": "text/plain" }, "item": [ { "id": "24d2d44c-1777-4dcc-b0a3-4d6c43750d69", "name": "Directory of Thai banks supported as settlement destinations.", "request": { "name": "Directory of Thai banks supported as settlement destinations.", "description": { "content": "Public — no authentication required. Response is cached server-side\nfor 1 hour; clients get `Cache-Control: public, max-age=3600`.\n", "type": "text/plain" }, "url": { "path": [ "v1", "reference", "thai-banks" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "auth": null }, "response": [ { "id": "b38d8cf6-6c89-455a-8ca9-2654b8e7f506", "name": "Bank directory.", "originalRequest": { "url": { "path": [ "v1", "reference", "thai-banks" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"data\": {\n \"banks\": [\n {\n \"code\": \"string\",\n \"short_name\": \"string\",\n \"name_en\": \"string\",\n \"name_th\": \"string\"\n },\n {\n \"code\": \"string\",\n \"short_name\": \"string\",\n \"name_en\": \"string\",\n \"name_th\": \"string\"\n }\n ]\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "6482109a-a084-4e34-acc4-4edd289b3043", "name": "Database unreachable.", "originalRequest": { "url": { "path": [ "v1", "reference", "thai-banks" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Internal Server Error", "code": 500, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } } ], "event": [] }, { "id": "18652f32-1612-432f-b79f-6a4e518cd808", "name": "PromptPay", "description": { "content": "PromptPay (Thailand) EMVCo QR helpers.", "type": "text/plain" }, "item": [ { "id": "ae0897ce-9950-4bd7-8890-755c29ef3ea9", "name": "PNG render of the dynamic PromptPay QR for a payment.", "request": { "name": "PNG render of the dynamic PromptPay QR for a payment.", "description": { "content": "Public endpoint — no `X-API-Key` required. Access control is by\nunguessable UUID, matching the seller-facing checkout page. Only\navailable for THB payments; returns `NOT_TH` otherwise.\n", "type": "text/plain" }, "url": { "path": [ "v1", "payments", ":id", "promptpay-qr" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) Payment ID (UUID v4)." } ] }, "header": [ { "key": "Accept", "value": "image/png" } ], "method": "GET", "auth": null }, "response": [ { "id": "e167c774-f6d9-4d6b-afe0-2d61e405795d", "name": "PNG image of the EMVCo PromptPay QR.", "originalRequest": { "url": { "path": [ "v1", "payments", ":id", "promptpay-qr" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) Payment ID (UUID v4)." } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "image/png" } ], "method": "GET", "body": {} }, "status": "OK", "code": 200, "header": [ { "disabled": false, "description": "`public, max-age=300`.", "key": "Cache-Control", "value": "string" }, { "key": "Content-Type", "value": "image/png" } ], "body": "string", "cookie": [], "_postman_previewlanguage": "text" }, { "id": "eecffd5a-63fd-4581-9e9f-6df382526add", "name": "Invalid payment ID, or payment is not THB.", "originalRequest": { "url": { "path": [ "v1", "payments", ":id", "promptpay-qr" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) Payment ID (UUID v4)." } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Bad Request", "code": 400, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "29d996d0-5b7c-4d62-999c-bb0eb6ae3f00", "name": "Handler was not configured with a DB pool, or an internal render error occurred.", "originalRequest": { "url": { "path": [ "v1", "payments", ":id", "promptpay-qr" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) Payment ID (UUID v4)." } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Internal Server Error", "code": 500, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "88d696eb-6679-4e02-9920-f37790529cce", "name": "Generate an EMVCo PromptPay payload string from a PromptPay ID + amount.", "request": { "name": "Generate an EMVCo PromptPay payload string from a PromptPay ID + amount.", "description": { "content": "Public endpoint. Returns the EMVCo payload string; the caller (widget\nor mobile) renders the QR client-side.\n", "type": "text/plain" }, "url": { "path": [ "v1", "promptpay", "qr" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "auth": null, "body": { "mode": "raw", "raw": "{\n \"promptpay_id\": \"\",\n \"amount\": \"\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "id": "9e88f696-0bcf-460a-bee9-18a29bbb82e8", "name": "Payload generated.", "originalRequest": { "url": { "path": [ "v1", "promptpay", "qr" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"promptpay_id\": \"\",\n \"amount\": \"\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"data\": {\n \"payload\": \"string\",\n \"promptpay_id\": \"string\",\n \"currency\": \"string\",\n \"dynamic\": false\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "75cbf0c9-a009-4c4b-b025-45c496d70ce4", "name": "Validation error (missing ID, negative amount, malformed ID).", "originalRequest": { "url": { "path": [ "v1", "promptpay", "qr" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"promptpay_id\": \"\",\n \"amount\": \"\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Bad Request", "code": 400, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } } ], "event": [] }, { "id": "1d4220d5-e4e2-4385-b976-eecf7da26a34", "name": "Settlements", "description": { "content": "Merchant payout batches, pending accruals, reports, exports, disputes, adjustments, audit log, retry.", "type": "text/plain" }, "item": [ { "id": "c75632c7-6569-4171-874f-198d870965fe", "name": "List settlements (cursor-paginated) for the authenticated merchant.", "request": { "name": "List settlements (cursor-paginated) for the authenticated merchant.", "description": {}, "url": { "path": [ "v1", "settlements" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "key": "status", "value": "" }, { "disabled": false, "key": "cursor", "value": "", "description": "Opaque cursor from `pagination.next_cursor` of a prior response." }, { "disabled": false, "key": "limit", "value": "20" } ], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "auth": { "type": "apikey", "apikey": [ { "key": "key", "value": "X-API-Key" }, { "key": "value", "value": "{{apiKey}}" }, { "key": "in", "value": "header" } ] } }, "response": [ { "id": "24ccb5c5-e984-4271-afec-dff574990d05", "name": "Paginated settlements.", "originalRequest": { "url": { "path": [ "v1", "settlements" ], "host": [ "{{baseUrl}}" ], "query": [ { "key": "status", "value": "" }, { "key": "cursor", "value": "" }, { "key": "limit", "value": "20" } ], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"data\": [\n {\n \"id\": \"eedeb524-5d7e-cb13-a392-b1fd1c363a6c\",\n \"merchant_id\": \"f21c9f1c-fadc-a9ef-666c-f1f200ef42c8\",\n \"period_start\": \"1949-07-01T19:18:05.989Z\",\n \"period_end\": \"1988-04-24T18:04:33.590Z\",\n \"total_volume\": 7676,\n \"total_fees\": 4699,\n \"net_amount\": 6166,\n \"currency\": \"THB\",\n \"status\": \"pending\",\n \"includes_sub_merchants\": true,\n \"created_at\": \"1951-01-01T08:32:24.017Z\",\n \"updated_at\": \"2000-07-07T15:43:40.023Z\",\n \"aggregator_id\": \"string\",\n \"payout_reference\": \"string\",\n \"payout_tx_hash\": \"string\",\n \"settled_at\": \"1974-07-09T10:08:15.440Z\"\n },\n {\n \"id\": \"068c0cd5-5c05-f6ad-bb0d-5f52de1f9d15\",\n \"merchant_id\": \"ef483647-fa70-ea00-50aa-0bd6b603a4e9\",\n \"period_start\": \"2008-12-28T21:53:43.809Z\",\n \"period_end\": \"1956-11-24T21:28:10.241Z\",\n \"total_volume\": 2615,\n \"total_fees\": 6945,\n \"net_amount\": 9451,\n \"currency\": \"AUD\",\n \"status\": \"pending\",\n \"includes_sub_merchants\": true,\n \"created_at\": \"1963-12-12T01:20:44.412Z\",\n \"updated_at\": \"2005-04-15T23:26:53.525Z\",\n \"aggregator_id\": \"string\",\n \"payout_reference\": \"string\",\n \"payout_tx_hash\": \"string\",\n \"settled_at\": \"2004-11-20T14:06:24.167Z\"\n }\n ],\n \"pagination\": {\n \"has_more\": false,\n \"next_cursor\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "9c5b31db-6e2b-4b22-b9c8-07d680501372", "name": "Missing or invalid API key.", "originalRequest": { "url": { "path": [ "v1", "settlements" ], "host": [ "{{baseUrl}}" ], "query": [ { "key": "status", "value": "" }, { "key": "cursor", "value": "" }, { "key": "limit", "value": "20" } ], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "5466b2b3-0a9c-4eae-b33f-eefbac31ce5d", "name": "Internal error.", "originalRequest": { "url": { "path": [ "v1", "settlements" ], "host": [ "{{baseUrl}}" ], "query": [ { "key": "status", "value": "" }, { "key": "cursor", "value": "" }, { "key": "limit", "value": "20" } ], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Internal Server Error", "code": 500, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "702e32f8-ef54-4b0c-97b6-acb3e5353bdd", "name": "Summary of unsettled accruals grouped by currency.", "request": { "name": "Summary of unsettled accruals grouped by currency.", "description": {}, "url": { "path": [ "v1", "settlements", "pending" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "auth": { "type": "apikey", "apikey": [ { "key": "key", "value": "X-API-Key" }, { "key": "value", "value": "{{apiKey}}" }, { "key": "in", "value": "header" } ] } }, "response": [ { "id": "3e1ca7d7-68df-48ad-b63a-1a3e1b20ebe5", "name": "Pending summaries (one per currency).", "originalRequest": { "url": { "path": [ "v1", "settlements", "pending" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"data\": [\n {\n \"merchant_id\": \"10348d2b-3110-4fd4-7e6f-e8a89408979d\",\n \"currency\": \"AUD\",\n \"pending_volume\": 1932,\n \"pending_fees\": 2757,\n \"pending_net\": 9274,\n \"pending_count\": 2647\n },\n {\n \"merchant_id\": \"a378bc21-7ede-d453-cba7-6c8fb32e8759\",\n \"currency\": \"SGD\",\n \"pending_volume\": 5853,\n \"pending_fees\": 8757,\n \"pending_net\": 5293,\n \"pending_count\": 8364\n }\n ]\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "a3abac92-d080-4295-88e9-decff5916d47", "name": "Missing or invalid API key.", "originalRequest": { "url": { "path": [ "v1", "settlements", "pending" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "5523848f-f66d-4b2f-9308-50f56f73c259", "name": "Aggregate settlement report for a date range.", "request": { "name": "Aggregate settlement report for a date range.", "description": {}, "url": { "path": [ "v1", "settlements", "report" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "key": "from", "value": "", "description": "(Required) Start of range (YYYY-MM-DD, inclusive)." }, { "disabled": false, "key": "to", "value": "", "description": "(Required) End of range (YYYY-MM-DD, inclusive — extended server-side to end-of-day)." }, { "disabled": false, "key": "currency", "value": "" } ], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "auth": { "type": "apikey", "apikey": [ { "key": "key", "value": "X-API-Key" }, { "key": "value", "value": "{{apiKey}}" }, { "key": "in", "value": "header" } ] } }, "response": [ { "id": "e31e0d9f-739f-4b12-bc31-b4b12f031e21", "name": "Report.", "originalRequest": { "url": { "path": [ "v1", "settlements", "report" ], "host": [ "{{baseUrl}}" ], "query": [ { "key": "from", "value": "" }, { "key": "to", "value": "" }, { "key": "currency", "value": "" } ], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"data\": {\n \"period\": {\n \"from\": \"string\",\n \"to\": \"string\"\n },\n \"total_settlements\": 761,\n \"total_volume\": 3734,\n \"total_fees\": 235,\n \"total_net_paid\": 5921,\n \"total_pending\": 214,\n \"by_status\": {\n \"key_0\": {\n \"count\": 8665,\n \"net_amount\": 2502\n },\n \"key_1\": {\n \"count\": 9182,\n \"net_amount\": 2550\n },\n \"key_2\": {\n \"count\": 3573,\n \"net_amount\": 8042\n },\n \"key_3\": {\n \"count\": 8607,\n \"net_amount\": 8203\n }\n },\n \"payout_methods\": {\n \"key_0\": {\n \"count\": 7545,\n \"net_amount\": 554\n },\n \"key_1\": {\n \"count\": 4132,\n \"net_amount\": 9546\n }\n },\n \"currency\": \"string\",\n \"average_settlement_time_hours\": 3774.4029618347217\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "1ea5e26a-1a1c-40e4-a70d-db608e549849", "name": "Missing or malformed `from`/`to`.", "originalRequest": { "url": { "path": [ "v1", "settlements", "report" ], "host": [ "{{baseUrl}}" ], "query": [ { "key": "from", "value": "" }, { "key": "to", "value": "" }, { "key": "currency", "value": "" } ], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Bad Request", "code": 400, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "bbd19e2b-aa23-4d92-a0d4-82402b338039", "name": "Missing or invalid API key.", "originalRequest": { "url": { "path": [ "v1", "settlements", "report" ], "host": [ "{{baseUrl}}" ], "query": [ { "key": "from", "value": "" }, { "key": "to", "value": "" }, { "key": "currency", "value": "" } ], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "d8c34d4e-7b1a-4196-9bd1-c7be279504f9", "name": "Export settlements as JSON or CSV.", "request": { "name": "Export settlements as JSON or CSV.", "description": { "content": "`format=pdf` is accepted but currently renders CSV under a different\nfilename (full PDF export is deferred to a future session).\n", "type": "text/plain" }, "url": { "path": [ "v1", "settlements", "export" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "key": "from", "value": "", "description": "(Required) " }, { "disabled": false, "key": "to", "value": "", "description": "(Required) " }, { "disabled": false, "key": "currency", "value": "" }, { "disabled": false, "key": "format", "value": "json" } ], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "auth": { "type": "apikey", "apikey": [ { "key": "key", "value": "X-API-Key" }, { "key": "value", "value": "{{apiKey}}" }, { "key": "in", "value": "header" } ] } }, "response": [ { "id": "135e738c-b4c2-4f45-9c29-b7d21db38897", "name": "Export payload in the requested format.", "originalRequest": { "url": { "path": [ "v1", "settlements", "export" ], "host": [ "{{baseUrl}}" ], "query": [ { "key": "from", "value": "" }, { "key": "to", "value": "" }, { "key": "currency", "value": "" }, { "key": "format", "value": "json" } ], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"data\": {\n \"settlements\": [\n {\n \"id\": \"84851302-5675-5fcd-dce1-2a1d6b8ecb02\",\n \"merchant_id\": \"00f73e71-aa7f-3a46-256a-72665dbf76dd\",\n \"period_start\": \"1954-04-02T15:30:41.399Z\",\n \"period_end\": \"1988-03-25T09:37:31.777Z\",\n \"total_volume\": 5531,\n \"total_fees\": 7841,\n \"net_amount\": 7836,\n \"currency\": \"SGD\",\n \"status\": \"string\",\n \"created_at\": \"2007-04-09T07:14:03.071Z\",\n \"payout_reference\": \"string\",\n \"payout_tx_hash\": \"string\",\n \"settled_at\": \"2019-06-24T05:41:13.862Z\"\n },\n {\n \"id\": \"6d475d08-af2f-0057-b88d-e187038d098c\",\n \"merchant_id\": \"aace3fec-659e-6736-cabf-40731aded95b\",\n \"period_start\": \"2005-01-16T21:53:33.466Z\",\n \"period_end\": \"1999-11-11T10:58:13.408Z\",\n \"total_volume\": 7505,\n \"total_fees\": 4540,\n \"net_amount\": 6847,\n \"currency\": \"SGD\",\n \"status\": \"string\",\n \"created_at\": \"1977-09-09T18:14:15.912Z\",\n \"payout_reference\": \"string\",\n \"payout_tx_hash\": \"string\",\n \"settled_at\": \"1969-04-22T15:18:38.897Z\"\n }\n ],\n \"generated_at\": \"1954-11-25T20:09:36.881Z\",\n \"format\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "2fdbfe66-98c4-426b-b71c-57039b397bb5", "name": "Missing or malformed `from`/`to`.", "originalRequest": { "url": { "path": [ "v1", "settlements", "export" ], "host": [ "{{baseUrl}}" ], "query": [ { "key": "from", "value": "" }, { "key": "to", "value": "" }, { "key": "currency", "value": "" }, { "key": "format", "value": "json" } ], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Bad Request", "code": 400, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "c3502cee-c362-4b23-a2b8-dd41b6c939cb", "name": "Missing or invalid API key.", "originalRequest": { "url": { "path": [ "v1", "settlements", "export" ], "host": [ "{{baseUrl}}" ], "query": [ { "key": "from", "value": "" }, { "key": "to", "value": "" }, { "key": "currency", "value": "" }, { "key": "format", "value": "json" } ], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "378248f9-6ad2-4f3b-b175-bc55c92aab72", "name": "List settlement adjustments for the authenticated merchant.", "request": { "name": "List settlement adjustments for the authenticated merchant.", "description": {}, "url": { "path": [ "v1", "settlements", "adjustments" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "key": "status", "value": "" } ], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "auth": { "type": "apikey", "apikey": [ { "key": "key", "value": "X-API-Key" }, { "key": "value", "value": "{{apiKey}}" }, { "key": "in", "value": "header" } ] } }, "response": [ { "id": "996f0a6b-0b67-4dd4-b440-f84d6d28d02b", "name": "Adjustments (possibly empty array).", "originalRequest": { "url": { "path": [ "v1", "settlements", "adjustments" ], "host": [ "{{baseUrl}}" ], "query": [ { "key": "status", "value": "" } ], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"data\": [\n {\n \"id\": \"b886c21d-dd26-4569-898b-02556abedb73\",\n \"settlement_id\": \"6f091e99-cd3a-a55c-d995-462ea065086e\",\n \"adjustment_type\": \"string\",\n \"amount\": 5193,\n \"currency\": \"THB\",\n \"reason\": \"string\",\n \"status\": \"applied\",\n \"created_at\": \"2009-07-04T05:26:54.364Z\",\n \"updated_at\": \"1984-01-21T16:11:41.776Z\",\n \"evidence_urls\": [\n \"https://xc.xzzlkRuNPf0TAsESwd6aezsq7\",\n \"https://LkFbOQODzWmbJbKhTVe.lsgsjQ9IKogjWH1B9i78Ey6Avd,iDFczxHQ9qfkn1Gb,it2jn3PcfH96Z.Q,lHXbGRdn3ayPE\"\n ],\n \"requested_by\": \"string\",\n \"approved_by\": \"string\",\n \"applied_at\": \"1951-07-26T01:54:15.533Z\"\n },\n {\n \"id\": \"33186122-c72a-782b-2a30-b68c1c3fec35\",\n \"settlement_id\": \"31f4d95e-57ab-1849-934e-dac1bf79fec1\",\n \"adjustment_type\": \"string\",\n \"amount\": 5713,\n \"currency\": \"SGD\",\n \"reason\": \"string\",\n \"status\": \"approved\",\n \"created_at\": \"1960-09-15T20:19:57.748Z\",\n \"updated_at\": \"1976-04-16T17:33:24.577Z\",\n \"evidence_urls\": [\n \"https://AGKQkbciuXwxsqSskrFoWnJOkDsMNyX.bbR6Ykh+D5o\",\n \"http://AkvlznWMbQZqjODHoZ.wadnuAnmInxNPNuxEs5HRqso4s4Inz4Ml\"\n ],\n \"requested_by\": \"string\",\n \"approved_by\": \"string\",\n \"applied_at\": \"1959-04-12T12:01:00.861Z\"\n }\n ]\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "bbbf7fdb-f1cd-45c6-9f9a-1009215ba8fc", "name": "Missing or invalid API key.", "originalRequest": { "url": { "path": [ "v1", "settlements", "adjustments" ], "host": [ "{{baseUrl}}" ], "query": [ { "key": "status", "value": "" } ], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "6a5a912e-f895-473d-a645-ac1ab966d31a", "name": "Get a settlement with its line items.", "request": { "name": "Get a settlement with its line items.", "description": {}, "url": { "path": [ "v1", "settlements", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) Settlement ID (UUID v4)." } ] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "auth": { "type": "apikey", "apikey": [ { "key": "key", "value": "X-API-Key" }, { "key": "value", "value": "{{apiKey}}" }, { "key": "in", "value": "header" } ] } }, "response": [ { "id": "a1d8906f-89eb-49c9-9cd2-cf0bbd3624a5", "name": "Settlement with line items.", "originalRequest": { "url": { "path": [ "v1", "settlements", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) Settlement ID (UUID v4)." } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"data\": {\n \"created_at\": \"2012-02-26T14:25:35.564Z\",\n \"currency\": \"THB\",\n \"id\": \"256b48ce-b9b5-3df9-ad90-c42172a0de25\",\n \"includes_sub_merchants\": false,\n \"line_items\": [\n {\n \"id\": \"39d92979-9652-61ed-56dd-9ddd61b1cff5\",\n \"payment_id\": \"57b83b2f-e88a-957d-3d96-d71b872df9fb\",\n \"merchant_id\": \"c81bc19e-b0d8-1ff9-59d5-2919a9f8c927\",\n \"gross_amount\": 9718,\n \"platform_fee\": 8238,\n \"net_amount\": 9606,\n \"currency\": \"THB\",\n \"status\": \"batched\",\n \"completed_at\": \"2009-05-30T17:06:53.167Z\",\n \"created_at\": \"1964-02-20T07:08:41.062Z\",\n \"settlement_id\": \"string\"\n },\n {\n \"id\": \"59e594db-ad91-d860-033c-93f06c8e8014\",\n \"payment_id\": \"4a4cd4bb-5e8c-ab5b-75b5-00f3e2afba27\",\n \"merchant_id\": \"f9a62bac-5a4d-3a03-7bf0-99dc5589e420\",\n \"gross_amount\": 2532,\n \"platform_fee\": 1186,\n \"net_amount\": 825,\n \"currency\": \"AUD\",\n \"status\": \"batched\",\n \"completed_at\": \"2023-10-30T07:48:05.161Z\",\n \"created_at\": \"2019-01-30T09:07:57.969Z\",\n \"settlement_id\": \"string\"\n }\n ],\n \"merchant_id\": \"fef36197-e0d8-bfe2-b137-fe1c04d1be93\",\n \"net_amount\": 5946,\n \"period_end\": \"1995-10-30T06:10:54.739Z\",\n \"period_start\": \"1950-07-23T02:56:58.440Z\",\n \"status\": \"voided\",\n \"total_fees\": 7751,\n \"total_volume\": 9341,\n \"updated_at\": \"1977-11-11T02:37:27.106Z\",\n \"aggregator_id\": \"string\",\n \"payout_reference\": \"string\",\n \"payout_tx_hash\": \"string\",\n \"settled_at\": \"2021-06-06T05:18:02.307Z\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "8b0935e1-b3fc-49e2-aa82-442b56238220", "name": "Invalid ID format.", "originalRequest": { "url": { "path": [ "v1", "settlements", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) Settlement ID (UUID v4)." } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Bad Request", "code": 400, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "8cf51bae-95f5-4824-b613-bb88661811b7", "name": "Missing or invalid API key.", "originalRequest": { "url": { "path": [ "v1", "settlements", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) Settlement ID (UUID v4)." } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "13c4b106-bfb2-4ffc-9ce5-a8e8f6c5d878", "name": "Settlement not found, or not owned by this merchant.", "originalRequest": { "url": { "path": [ "v1", "settlements", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) Settlement ID (UUID v4)." } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "0d6b14f6-d26f-41d1-a299-eef95e995bda", "name": "Merchant-visible audit trail for a settlement.", "request": { "name": "Merchant-visible audit trail for a settlement.", "description": {}, "url": { "path": [ "v1", "settlements", ":id", "audit-log" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) Settlement ID (UUID v4)." } ] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "auth": { "type": "apikey", "apikey": [ { "key": "key", "value": "X-API-Key" }, { "key": "value", "value": "{{apiKey}}" }, { "key": "in", "value": "header" } ] } }, "response": [ { "id": "c97bf78a-d1e4-4955-afb1-fb9149495c13", "name": "Audit entries (possibly empty).", "originalRequest": { "url": { "path": [ "v1", "settlements", ":id", "audit-log" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) Settlement ID (UUID v4)." } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"data\": [\n {\n \"id\": \"98ff9872-fff5-4415-3940-3783661f035a\",\n \"settlement_id\": \"52df5afd-06da-5c66-b743-426980b8f1af\",\n \"action\": \"string\",\n \"actor_type\": \"string\",\n \"created_at\": \"1962-02-21T19:34:43.495Z\",\n \"previous_status\": \"string\",\n \"new_status\": \"string\",\n \"actor_id\": \"string\",\n \"metadata\": {\n \"key_0\": 8223.692519745702\n },\n \"ip_address\": \"string\"\n },\n {\n \"id\": \"143c4d46-459f-fcd9-625c-b1fbb4012374\",\n \"settlement_id\": \"228b4c79-9338-41bf-3a02-93eb0d2ac298\",\n \"action\": \"string\",\n \"actor_type\": \"string\",\n \"created_at\": \"1950-08-31T14:38:17.628Z\",\n \"previous_status\": \"string\",\n \"new_status\": \"string\",\n \"actor_id\": \"string\",\n \"metadata\": {\n \"key_0\": false,\n \"key_1\": 740.4239505780907\n },\n \"ip_address\": \"string\"\n }\n ]\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "78b3b501-684e-4681-9033-768e2d0e430f", "name": "Invalid ID format.", "originalRequest": { "url": { "path": [ "v1", "settlements", ":id", "audit-log" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) Settlement ID (UUID v4)." } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Bad Request", "code": 400, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "accf8341-7f23-4c92-b2a3-6aedbc00d010", "name": "Missing or invalid API key.", "originalRequest": { "url": { "path": [ "v1", "settlements", ":id", "audit-log" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) Settlement ID (UUID v4)." } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "4cd786dd-a253-41d7-8867-2e401d3fd122", "name": "Settlement not found, or not owned by this merchant.", "originalRequest": { "url": { "path": [ "v1", "settlements", ":id", "audit-log" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) Settlement ID (UUID v4)." } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "cbab4ef5-a0c2-443d-b310-614e3b64dbf2", "name": "Retry a failed settlement by resetting it to `pending`.", "request": { "name": "Retry a failed settlement by resetting it to `pending`.", "description": {}, "url": { "path": [ "v1", "settlements", ":id", "retry" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) Settlement ID (UUID v4)." } ] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "POST", "auth": { "type": "apikey", "apikey": [ { "key": "key", "value": "X-API-Key" }, { "key": "value", "value": "{{apiKey}}" }, { "key": "in", "value": "header" } ] } }, "response": [ { "id": "410eb08f-daa2-4367-9f97-9160eff0e108", "name": "Settlement reset to `pending` for re-payout.", "originalRequest": { "url": { "path": [ "v1", "settlements", ":id", "retry" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) Settlement ID (UUID v4)." } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"data\": {\n \"id\": \"93247382-9446-5078-a144-49fcae43e64c\",\n \"merchant_id\": \"1820be5e-2b24-563e-b555-f3754008478c\",\n \"period_start\": \"2017-01-18T11:52:30.334Z\",\n \"period_end\": \"2009-06-24T17:16:31.244Z\",\n \"total_volume\": 4187,\n \"total_fees\": 8670,\n \"net_amount\": 3294,\n \"currency\": \"SGD\",\n \"status\": \"pending\",\n \"includes_sub_merchants\": true,\n \"created_at\": \"1975-03-03T05:39:40.179Z\",\n \"updated_at\": \"2021-07-19T02:23:38.715Z\",\n \"aggregator_id\": \"string\",\n \"payout_reference\": \"string\",\n \"payout_tx_hash\": \"string\",\n \"settled_at\": \"1996-06-20T14:03:57.425Z\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "c71304db-07cb-4981-a43c-98876f719410", "name": "Invalid ID format.", "originalRequest": { "url": { "path": [ "v1", "settlements", ":id", "retry" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) Settlement ID (UUID v4)." } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": {} }, "status": "Bad Request", "code": 400, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "ee219271-2bd0-49f7-bd3a-ff276f47c0e9", "name": "Missing or invalid API key.", "originalRequest": { "url": { "path": [ "v1", "settlements", ":id", "retry" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) Settlement ID (UUID v4)." } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": {} }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "38248ab8-417e-4873-9482-304af2d5dd54", "name": "Settlement not found, or not owned by this merchant.", "originalRequest": { "url": { "path": [ "v1", "settlements", ":id", "retry" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) Settlement ID (UUID v4)." } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": {} }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "4a01f418-080b-4ba3-af3a-f50bb4b8de11", "name": "Settlement is not in `failed` status.", "originalRequest": { "url": { "path": [ "v1", "settlements", ":id", "retry" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) Settlement ID (UUID v4)." } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": {} }, "status": "Conflict", "code": 409, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "4ef0cc57-f0bc-4a4c-94a9-0d57b63f50e3", "name": "Open a dispute against a completed settlement.", "request": { "name": "Open a dispute against a completed settlement.", "description": {}, "url": { "path": [ "v1", "settlements", ":id", "dispute" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) Settlement ID (UUID v4)." } ] }, "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "auth": { "type": "apikey", "apikey": [ { "key": "key", "value": "X-API-Key" }, { "key": "value", "value": "{{apiKey}}" }, { "key": "in", "value": "header" } ] }, "body": { "mode": "raw", "raw": "{\n \"reason\": \"\",\n \"expected_amount\": \"\",\n \"evidence_urls\": [\n \"\",\n \"\"\n ]\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "id": "83e00be0-c289-4611-8487-a40f12c9a17e", "name": "Dispute created as a new adjustment in `pending` status.", "originalRequest": { "url": { "path": [ "v1", "settlements", ":id", "dispute" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) Settlement ID (UUID v4)." } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"reason\": \"\",\n \"expected_amount\": \"\",\n \"evidence_urls\": [\n \"\",\n \"\"\n ]\n}", "options": { "raw": { "language": "json" } } } }, "status": "Created", "code": 201, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"data\": {\n \"id\": \"fb7a7a2b-761c-e344-8af0-83884b162486\",\n \"settlement_id\": \"a59735c6-39f4-d60c-179c-1fc5f86606ef\",\n \"adjustment_type\": \"string\",\n \"amount\": 9721,\n \"currency\": \"THB\",\n \"reason\": \"string\",\n \"status\": \"pending\",\n \"created_at\": \"1967-02-17T04:52:42.867Z\",\n \"updated_at\": \"2023-10-27T05:38:59.382Z\",\n \"evidence_urls\": [\n \"http://oqPlqIycXXvtqKoUYhgUTNHLu.oqB1WLGXGcjS0ID\",\n \"http://dedcfQWyCpWvoLDeXkhjoHl.xrzT8gZH9CyjDvyKbv3-ps,LYB\"\n ],\n \"requested_by\": \"string\",\n \"approved_by\": \"string\",\n \"applied_at\": \"1958-10-06T22:54:56.219Z\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "e92b95f1-4911-4d15-b556-2ef7f7013e6e", "name": "Invalid ID format or malformed body.", "originalRequest": { "url": { "path": [ "v1", "settlements", ":id", "dispute" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) Settlement ID (UUID v4)." } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"reason\": \"\",\n \"expected_amount\": \"\",\n \"evidence_urls\": [\n \"\",\n \"\"\n ]\n}", "options": { "raw": { "language": "json" } } } }, "status": "Bad Request", "code": 400, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "63165c9b-83ec-4482-ad7e-79ac4e4d0f50", "name": "Missing or invalid API key.", "originalRequest": { "url": { "path": [ "v1", "settlements", ":id", "dispute" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) Settlement ID (UUID v4)." } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"reason\": \"\",\n \"expected_amount\": \"\",\n \"evidence_urls\": [\n \"\",\n \"\"\n ]\n}", "options": { "raw": { "language": "json" } } } }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "fd81b783-20eb-4d67-a86d-a847191f6a07", "name": "Settlement not found, or not owned by this merchant.", "originalRequest": { "url": { "path": [ "v1", "settlements", ":id", "dispute" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) Settlement ID (UUID v4)." } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"reason\": \"\",\n \"expected_amount\": \"\",\n \"evidence_urls\": [\n \"\",\n \"\"\n ]\n}", "options": { "raw": { "language": "json" } } } }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "fb760fb8-8a78-456c-81fd-783c4bd77e21", "name": "Only `completed` settlements can be disputed.", "originalRequest": { "url": { "path": [ "v1", "settlements", ":id", "dispute" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) Settlement ID (UUID v4)." } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"reason\": \"\",\n \"expected_amount\": \"\",\n \"evidence_urls\": [\n \"\",\n \"\"\n ]\n}", "options": { "raw": { "language": "json" } } } }, "status": "Conflict", "code": 409, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } } ], "event": [] }, { "id": "4a7fa251-9312-4a1c-95cb-1e81a82e468c", "name": "Webhooks", "description": { "content": "Webhook delivery history for the authenticated merchant.", "type": "text/plain" }, "item": [ { "id": "44628db1-e72b-4688-b89a-10deff3b6afb", "name": "Recent webhook delivery attempts for this merchant.", "request": { "name": "Recent webhook delivery attempts for this merchant.", "description": {}, "url": { "path": [ "v1", "webhooks", "deliveries" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "key": "limit", "value": "20" }, { "disabled": false, "key": "offset", "value": "0" } ], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "auth": { "type": "apikey", "apikey": [ { "key": "key", "value": "X-API-Key" }, { "key": "value", "value": "{{apiKey}}" }, { "key": "in", "value": "header" } ] } }, "response": [ { "id": "d8d6f6fb-d409-4492-bf68-ade929342ca9", "name": "Delivery attempts (possibly empty).", "originalRequest": { "url": { "path": [ "v1", "webhooks", "deliveries" ], "host": [ "{{baseUrl}}" ], "query": [ { "key": "limit", "value": "20" }, { "key": "offset", "value": "0" } ], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"data\": [\n {\n \"id\": \"adf57dd1-f15b-64c4-b8e0-9637dd57eaab\",\n \"merchant_id\": \"5f2ab6af-9f7c-7fc9-7ef7-0342a5abad76\",\n \"payment_id\": \"ca9a64a3-6039-c886-f4a8-91428f1c4b60\",\n \"event\": \"settlement.adjustment_applied\",\n \"url\": \"http://sofJYnnMEjecRr.blxBgp-VrqjQfFQj,M2Q3l5cUVMLj\",\n \"response_status\": 7422,\n \"attempt\": 8915,\n \"success\": false,\n \"created_at\": \"2006-05-06T02:55:42.536Z\",\n \"request_body\": \"string\",\n \"response_body\": \"string\",\n \"error_message\": \"string\"\n },\n {\n \"id\": \"fd2ee748-3e92-d0a1-58e4-b89d094ddde2\",\n \"merchant_id\": \"9551094f-2dbe-dca5-6512-26caf490f034\",\n \"payment_id\": \"d5d0b8c5-225a-5916-2011-b1f49dde8b78\",\n \"event\": \"settlement.completed\",\n \"url\": \"http://VYRUFbL.czSaYbfbaAfVYhhXh\",\n \"response_status\": 3686,\n \"attempt\": 4855,\n \"success\": true,\n \"created_at\": \"2006-05-03T03:56:42.786Z\",\n \"request_body\": \"string\",\n \"response_body\": \"string\",\n \"error_message\": \"string\"\n }\n ],\n \"meta\": {\n \"total\": 6663,\n \"limit\": 3350,\n \"offset\": 3821\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "583c03cb-2afd-44d2-bf0c-ade65537e3d7", "name": "Missing or invalid API key.", "originalRequest": { "url": { "path": [ "v1", "webhooks", "deliveries" ], "host": [ "{{baseUrl}}" ], "query": [ { "key": "limit", "value": "20" }, { "key": "offset", "value": "0" } ], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } } ], "event": [] }, { "id": "2ac595ea-d81f-4e19-a2d3-f16c954dfd5b", "name": "FX", "description": { "content": "Foreign-exchange reference prices (read) and quote locks (write). Served by the `fx-service`\non port :4003 (moved from :3011 in S099 BUG-192 — settlement-service collision), scraped by\nPrometheus directly (Rule 26 — api-gateway does **not** proxy `/metrics` or `/fx/*`).\nIntroduced in Session 098.\n", "type": "text/plain" }, "item": [], "event": [] }, { "id": "a2745ac0-d2a9-42e3-858f-09ada99e0231", "name": "Merchants", "description": { "content": "Merchant-scoped read endpoints (balance, receive-capacity, marketplace role).\nAuthenticated via MerchantJWTAuth + MerchantDashboardAuth dual-path (Rule 22).\nIntroduced incrementally across S100 (routing) and S101 (deposit model). Tag\ndeclared in S102(b) WS9 fold-in to align with operation-level tag usage.\n", "type": "text/plain" }, "item": [ { "id": "0acc9b6c-ebaf-4ba7-b050-2d74cc1f40c5", "name": "Merchant PAY balance + deficit projection.", "request": { "name": "Merchant PAY balance + deficit projection.", "description": { "content": "Returns the merchant's available PAY balance, buffer cushion, net\noutbound obligation (sum of validated-pending receiver obligations),\nand projected deficit in micro-PAY along with prospective penalty\nAPR (bps), entry fee (USD-quoted, settled in PAY), and countdown\ndays. Backed by `merchant_deficit_v` (mig 058).\n\n**Scoping**: the path `id` MUST equal the merchant the caller is\nscoped to via `MerchantJWTAuth` or `MerchantDashboardAuth`.\nCross-merchant reads return `403 FORBIDDEN`.\n\nVisible to merchant: `available_micro_pay`, `buffer_micro_pay`,\n`net_obligation_micro_pay`, `deficit_micro_pay`, `apr_bps`,\n`entry_fee_usd`, `countdown_days`. Admin-only fields\n(`buffer_threshold_micro_pay`, `buffer_last_recalc_at`,\n`trailing_30d_volume_micro_pay`) are NOT projected here — see\n`/admin/deficit/{merchantId}` for those.\n", "type": "text/plain" }, "url": { "path": [ "v1", "merchants", ":id", "balance" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) Merchant ID (UUID v4). MUST equal the caller's scope." } ] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "auth": { "type": "apikey", "apikey": [ { "key": "key", "value": "X-API-Key" }, { "key": "value", "value": "{{apiKey}}" }, { "key": "in", "value": "header" } ] } }, "response": [ { "id": "84f00911-bc20-44b1-aa27-dd7b58d64959", "name": "Balance snapshot.", "originalRequest": { "url": { "path": [ "v1", "merchants", ":id", "balance" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) Merchant ID (UUID v4). MUST equal the caller's scope." } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "8f3d6ab9-c051-4ca3-b05d-72187db0f7ff", "name": "Missing/invalid merchant credential.", "originalRequest": { "url": { "path": [ "v1", "merchants", ":id", "balance" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) Merchant ID (UUID v4). MUST equal the caller's scope." } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "ff927eb5-2004-4265-b24a-f0a0b21e4910", "name": "Cross-merchant read attempt (path id != caller scope).", "originalRequest": { "url": { "path": [ "v1", "merchants", ":id", "balance" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) Merchant ID (UUID v4). MUST equal the caller's scope." } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Forbidden", "code": 403, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "2c3a3aee-b1c5-41ae-8427-3940afd0c491", "name": "Merchant has no PAY balance row yet.", "originalRequest": { "url": { "path": [ "v1", "merchants", ":id", "balance" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) Merchant ID (UUID v4). MUST equal the caller's scope." } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } } ], "event": [] }, { "id": "c1cd6685-b523-4677-9ac4-cf4f24a18907", "name": "PendingFunds", "description": { "content": "Pending-funds lifecycle: create on top-up intent, validate via the configured\nReceiptValidator (NullValidator in AU per Rule 22, EasySlipValidator in TH),\nand confirm via receiver-side proof (`/v1/pending-funds/{id}/receiver-confirm`,\nS102). Status terminals: `confirmed` (verified → ledger mint), `failed`\n(validator denial or receiver-confirm window expiry per S102(b) Gate G.1.A),\n`expired` (TTL-elapsed before any receiver action). Tag declared in S102(b)\nWS9 fold-in.\n", "type": "text/plain" }, "item": [ { "id": "2cf67c2f-7925-41a8-a63c-83b1d7cc39ea", "name": "Receiver-side proof on a pending_funds row.", "request": { "name": "Receiver-side proof on a pending_funds row.", "description": { "content": "S102 (PR #125). The receiver of a pending_funds row that previously\npassed buyer-side validation (status =\n`validated_pending_receiver_confirm`) submits their own receipt\nevidence; the gateway runs it through the configured\nReceiptValidator (EasySlip in TH; Null in AU per Rule 22) and either:\n\n * `verified` — mints PAY into the receiver's available account via\n ledger-service (idempotency key = pending_funds.id) and flips\n `pending_funds.status → confirmed`.\n * `failed` — flips `status → failed` with `failure_reason` derived\n from the validator's `FailureCode`.\n * `unverified` / `timeout` — row stays in\n `validated_pending_receiver_confirm`, attempt counter bumps.\n After `RECEIVER_CONFIRM_MAX_ATTEMPTS` non-verified, non-timeout\n attempts the row is auto-failed with\n `failure_reason='max_attempts_exceeded'`.\n * `malformed` — caller-side rejection (bad base64, unsupported\n content_type); 400 returned without invoking the validator.\n\n**Posture (LAW)**: TokenPay never touches fiat. The validator's\nOCR amount is persisted to `receiver_confirm_audit.validator_response`\nfor audit trail only and never crosses the ledger boundary. The PAY\nmint amount on the verified path is derived from\n`pending_funds.amount_minor`, not from the validator response.\n\n**Append-only audit**: every call that reaches the validator (i.e.\noutcome ∈ verified|failed|unverified|timeout, but NOT malformed) writes\nexactly one row to `receiver_confirm_audit` (mig 059) within the same\nDB transaction as the `pending_funds` status update. The audit table\nhas a database-level trigger rejecting UPDATE / DELETE / TRUNCATE\nfrom application code (ADR-102-2).\n\n**Caller**: must be the receiver of the row. Buyer / third-party\ncallers receive `403 PENDING_FUNDS_NOT_RECEIVER`.\n", "type": "text/plain" }, "url": { "path": [ "v1", "pending-funds", ":id", "receiver-confirm" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) pending_funds row ID." } ] }, "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "auth": { "type": "apikey", "apikey": [ { "key": "key", "value": "X-API-Key" }, { "key": "value", "value": "{{apiKey}}" }, { "key": "in", "value": "header" } ] }, "body": { "mode": "raw", "raw": "{\n \"content_type\": \"\",\n \"receipt_base64\": \"\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "id": "98106e10-73d4-4d41-9e10-96993a4fc710", "name": "Audit row inserted. Inspect `outcome` to determine resolution\n(the HTTP code is 201 even on validator-fail / unverified, since\nthe call did record an audit attempt).\n", "originalRequest": { "url": { "path": [ "v1", "pending-funds", ":id", "receiver-confirm" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) pending_funds row ID." } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"content_type\": \"\",\n \"receipt_base64\": \"iVBORw0KGgoAAAANSUhEUgAA...\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Created", "code": 201, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"pending_funds\": {\n \"key_0\": 3802,\n \"key_1\": \"string\",\n \"key_2\": false\n },\n \"audit_id\": \"559aa6d3-f22a-6d05-b6fa-142b04a6dbcf\",\n \"outcome\": \"malformed\",\n \"attempt_index\": 5191,\n \"attempts_remaining\": 7239,\n \"failure_code\": \"string\",\n \"failure_message\": \"string\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "5a53dc1e-cd3f-421e-ba65-92fc5c6ffee5", "name": "Body invalid, content_type unsupported\n(`RECEIVER_CONFIRM_CONTENT_TYPE_UNSUPPORTED`), or receipt_base64\nmalformed (`RECEIVER_CONFIRM_MALFORMED_RECEIPT`).\n", "originalRequest": { "url": { "path": [ "v1", "pending-funds", ":id", "receiver-confirm" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) pending_funds row ID." } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"content_type\": \"\",\n \"receipt_base64\": \"iVBORw0KGgoAAAANSUhEUgAA...\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Bad Request", "code": 400, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "b92c9ad1-6386-420f-83bc-ccb77283dd4b", "name": "Missing caller identity.", "originalRequest": { "url": { "path": [ "v1", "pending-funds", ":id", "receiver-confirm" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) pending_funds row ID." } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"content_type\": \"\",\n \"receipt_base64\": \"iVBORw0KGgoAAAANSUhEUgAA...\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "2651ef91-5c00-4384-91c2-ebc9f940faba", "name": "Caller is not the receiver (`PENDING_FUNDS_NOT_RECEIVER`).", "originalRequest": { "url": { "path": [ "v1", "pending-funds", ":id", "receiver-confirm" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) pending_funds row ID." } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"content_type\": \"\",\n \"receipt_base64\": \"iVBORw0KGgoAAAANSUhEUgAA...\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Forbidden", "code": 403, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "cbb2e680-751a-4f85-bd6d-4bf53562ee47", "name": "pending_funds row not found.", "originalRequest": { "url": { "path": [ "v1", "pending-funds", ":id", "receiver-confirm" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) pending_funds row ID." } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"content_type\": \"\",\n \"receipt_base64\": \"iVBORw0KGgoAAAANSUhEUgAA...\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "c22d5308-372e-4201-8aff-96f5a6cca57d", "name": "Row is terminal (`PENDING_FUNDS_TERMINAL`) or not in status\n`validated_pending_receiver_confirm`\n(`PENDING_FUNDS_VALIDATION_UNVERIFIED`).\n", "originalRequest": { "url": { "path": [ "v1", "pending-funds", ":id", "receiver-confirm" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) pending_funds row ID." } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"content_type\": \"\",\n \"receipt_base64\": \"iVBORw0KGgoAAAANSUhEUgAA...\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Conflict", "code": 409, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "40d13a1b-3484-413b-bdb6-db47309da935", "name": "Verified outcome but ledger-service is unavailable\n(`PENDING_FUNDS_LEDGER_UNAVAILABLE`). Tx rolled back; no audit\nrow written; receiver may retry without consuming a slot.\n", "originalRequest": { "url": { "path": [ "v1", "pending-funds", ":id", "receiver-confirm" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) pending_funds row ID." } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"content_type\": \"\",\n \"receipt_base64\": \"iVBORw0KGgoAAAANSUhEUgAA...\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Bad Gateway", "code": 502, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } } ], "event": [] }, { "id": "bee2a5cc-8f25-4843-a86b-2a3779df170b", "name": "SellOrders", "description": { "content": "Outbound payouts / sell-order lifecycle (S103(a) PR #130). Merchant or end-user\ninitiates a sell order against PAY held in their available account; the gateway\ndrives the lifecycle `pending → matched → cash_leg_in_flight → completed` (or\n`→ failed` on `expired_unmatched`, `cash_leg_retry_exhausted`, or\n`cancelled_by_merchant`). The `disputed` status value is intentionally absent in\nS103(a); it is added in S103(b) via `ALTER TYPE sell_order_status ADD VALUE`.\n\n**Posture (LAW)**: the \"cash leg\" is the merchant's external rail (their bank,\ntheir PSP); TokenPay records `cash_leg_attempts` + `last_cash_leg_attempt_at` and\nburns PAY on completion via the existing ledger-service HTTP client. No payment\nprocessor wired, no fiat balance held.\n\n**Match-layer integrity** (ADR-103a-3): `sell_orders.matched_buy_order_id` is\nplain `UUID NULL` in S103(a) (the `buy_orders` table doesn't ship until S103(b)).\nThe FK constraint is added in mig 061 once `buy_orders` is live.\n\n**No dispute creation** (ADR-103a-2) in S103(a). Cash-leg failure terminal flips\n`sell_orders.status → failed` with `failure_reason='cash_leg_retry_exhausted'`\nand fires `sell_order.failed` webhook only. S103(b) adds `gateway.dispute.opened`\nalongside (additive, not replacing).\n\nIncludes admin read-only views over `receiver_confirm_audit` (S102 mig 059)\nunder `/admin/audit/receiver-confirm*` — these reuse the existing audit table\nwith no new migration; they are grouped under SellOrders because they ship in\nthe same PR. Tag declared in S103(a) WS9.\n", "type": "text/plain" }, "item": [ { "id": "4b29639b-6f46-4eaa-aa27-8a5e78e9c5f0", "name": "List sell orders for the authenticated merchant.", "request": { "name": "List sell orders for the authenticated merchant.", "description": { "content": "Cursor-paginated list of sell orders owned by the authenticated merchant.\nFilterable by `status` (multi-select), `currency`, `target_currency`, and\ncreation-window (`created_after`, `created_before`).\n\nDual-path auth: MerchantJWTAuth (programmatic) + MerchantDashboardAuth\n(browser session) per Rule 22 (S103(a)).\n", "type": "text/plain" }, "url": { "path": [ "v1", "merchant-sell-orders" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "key": "status", "value": ",", "description": "Filter by status (comma-separated for multi-select)." }, { "disabled": false, "key": "cursor", "value": "", "description": "Opaque pagination cursor returned by the previous page." }, { "disabled": false, "key": "limit", "value": "25" } ], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "auth": { "type": "apikey", "apikey": [ { "key": "key", "value": "X-API-Key" }, { "key": "value", "value": "{{apiKey}}" }, { "key": "in", "value": "header" } ] } }, "response": [ { "id": "d6b6e260-4a1b-4e4f-bbc8-b8d9e6b82205", "name": "Paginated list of sell orders.", "originalRequest": { "url": { "path": [ "v1", "merchant-sell-orders" ], "host": [ "{{baseUrl}}" ], "query": [ { "key": "status", "value": "," }, { "key": "cursor", "value": "" }, { "key": "limit", "value": "25" } ], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"items\": [\n {\n \"id\": \"fedef4b9-db6e-df77-4f38-38dc087daf4e\",\n \"merchant_id\": \"9cb331db-4317-007f-bce7-87e4f1bd1c52\",\n \"amount_pay\": \"string\",\n \"cash_leg_destination\": \"string\",\n \"status\": \"failed\",\n \"created_at\": \"1992-05-12T00:05:35.925Z\",\n \"expires_at\": \"2022-08-24T18:09:19.541Z\",\n \"cash_leg_attempts\": 4867,\n \"updated_at\": \"1966-01-12T17:13:24.028Z\",\n \"target_fiat_amount\": \"string\",\n \"target_currency\": \"string\",\n \"matched_buy_order_id\": \"2d7a1a4f-fcdf-a5d3-48d5-5bfdd1ae1b4f\",\n \"last_cash_leg_attempt_at\": \"2025-12-02T20:58:11.843Z\",\n \"failure_reason\": \"string\"\n },\n {\n \"id\": \"1c1393b9-c9c3-5fa7-77d0-68a6ed4eeda9\",\n \"merchant_id\": \"13ef6638-9968-8b86-2414-1a14bb8ad6a0\",\n \"amount_pay\": \"string\",\n \"cash_leg_destination\": \"string\",\n \"status\": \"cash_leg_in_flight\",\n \"created_at\": \"1957-06-05T01:43:58.556Z\",\n \"expires_at\": \"1966-08-19T12:42:23.332Z\",\n \"cash_leg_attempts\": 7366,\n \"updated_at\": \"2009-03-02T16:13:51.164Z\",\n \"target_fiat_amount\": \"string\",\n \"target_currency\": \"string\",\n \"matched_buy_order_id\": \"899d9ab3-9d98-4fa4-6ebd-614b598706a0\",\n \"last_cash_leg_attempt_at\": \"1957-02-24T07:55:27.621Z\",\n \"failure_reason\": \"string\"\n }\n ],\n \"next_cursor\": \"string\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "7a5cca56-d1b3-48a2-809f-baac1cae48a5", "name": "Missing or invalid caller identity.", "originalRequest": { "url": { "path": [ "v1", "merchant-sell-orders" ], "host": [ "{{baseUrl}}" ], "query": [ { "key": "status", "value": "," }, { "key": "cursor", "value": "" }, { "key": "limit", "value": "25" } ], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "07cbc92b-ffe8-4bf9-a287-7bd0b5ae0ab0", "name": "Create a new sell order.", "request": { "name": "Create a new sell order.", "description": { "content": "Creates a sell order against PAY held in the merchant's available\naccount. The handler sets `expires_at = NOW() + SELL_ORDER_PENDING_TTL_HOURS`\n(per ADR-103a-1 Q2; sweeper does not infer the deadline).\n\n**Idempotency**: required `Idempotency-Key` header (UUIDv4 recommended).\nRepeated calls with the same key + same body return the same sell_order\nrow; same key + different body returns 409 `IDEMPOTENCY_KEY_CONFLICT`.\n\n**Posture (LAW)**: the `target_fiat_amount` + `target_currency` are\nrecorded for audit and merchant-facing display only; TokenPay does not\ninitiate a fiat transfer. The merchant's external rail executes the cash\nleg; the merchant calls `confirm-cash-leg` when the rail completes.\n", "type": "text/plain" }, "url": { "path": [ "v1", "merchant-sell-orders" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "disabled": false, "description": "(Required) ", "key": "Idempotency-Key", "value": "" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "auth": { "type": "apikey", "apikey": [ { "key": "key", "value": "X-API-Key" }, { "key": "value", "value": "{{apiKey}}" }, { "key": "in", "value": "header" } ] }, "body": { "mode": "raw", "raw": "{\n \"amount_pay\": \"\",\n \"cash_leg_destination\": \"\",\n \"target_fiat_amount\": \"\",\n \"target_currency\": \"\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "id": "808ff8b8-5802-4a74-866b-386ce2fd4e5b", "name": "Sell order created.", "originalRequest": { "url": { "path": [ "v1", "merchant-sell-orders" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "disabled": false, "description": "(Required) ", "key": "Idempotency-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"amount_pay\": \"\",\n \"cash_leg_destination\": \"\",\n \"target_fiat_amount\": \"\",\n \"target_currency\": \"\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Created", "code": 201, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"id\": \"3bcd90b6-2130-f572-8564-00501e41e68d\",\n \"merchant_id\": \"3c8d53b0-1035-2b0e-a986-2c1339ab4374\",\n \"amount_pay\": \"string\",\n \"cash_leg_destination\": \"string\",\n \"status\": \"matched\",\n \"created_at\": \"1963-03-14T04:57:53.084Z\",\n \"expires_at\": \"2010-03-04T15:50:28.590Z\",\n \"cash_leg_attempts\": 9132,\n \"updated_at\": \"1954-07-16T13:13:07.682Z\",\n \"target_fiat_amount\": \"string\",\n \"target_currency\": \"string\",\n \"matched_buy_order_id\": \"38c3ef47-b34c-d5a3-8745-83dc023b3795\",\n \"last_cash_leg_attempt_at\": \"2003-06-21T09:09:50.973Z\",\n \"failure_reason\": \"string\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "f2b6df68-1f2b-440c-9649-c5148007ba50", "name": "Body invalid (missing fields, bad currency pair, amount ≤ 0).", "originalRequest": { "url": { "path": [ "v1", "merchant-sell-orders" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "disabled": false, "description": "(Required) ", "key": "Idempotency-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"amount_pay\": \"\",\n \"cash_leg_destination\": \"\",\n \"target_fiat_amount\": \"\",\n \"target_currency\": \"\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Bad Request", "code": 400, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "c47402bd-d0c5-4856-b93d-dccaa0224b56", "name": "Missing or invalid caller identity.", "originalRequest": { "url": { "path": [ "v1", "merchant-sell-orders" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "disabled": false, "description": "(Required) ", "key": "Idempotency-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"amount_pay\": \"\",\n \"cash_leg_destination\": \"\",\n \"target_fiat_amount\": \"\",\n \"target_currency\": \"\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "c77701dc-c9c4-4c56-92fb-0af30ede0ab8", "name": "Idempotency-Key conflict (`IDEMPOTENCY_KEY_CONFLICT`) or insufficient\navailable PAY balance (`SELL_ORDER_INSUFFICIENT_BALANCE`).\n", "originalRequest": { "url": { "path": [ "v1", "merchant-sell-orders" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "disabled": false, "description": "(Required) ", "key": "Idempotency-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"amount_pay\": \"\",\n \"cash_leg_destination\": \"\",\n \"target_fiat_amount\": \"\",\n \"target_currency\": \"\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Conflict", "code": 409, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "8acfba10-0d9e-427a-b306-8b3065f06963", "name": "Read a single sell order.", "request": { "name": "Read a single sell order.", "description": { "content": "Returns the sell order for the given UUID. The caller must be the\nowning merchant; cross-merchant reads return 403\n`SELL_ORDER_NOT_OWNER`.\n", "type": "text/plain" }, "url": { "path": [ "v1", "merchant-sell-orders", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) " } ] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "auth": { "type": "apikey", "apikey": [ { "key": "key", "value": "X-API-Key" }, { "key": "value", "value": "{{apiKey}}" }, { "key": "in", "value": "header" } ] } }, "response": [ { "id": "e3aca63d-dc1a-4e83-b06f-189fc83f0b31", "name": "Sell order detail.", "originalRequest": { "url": { "path": [ "v1", "merchant-sell-orders", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) " } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"id\": \"3bcd90b6-2130-f572-8564-00501e41e68d\",\n \"merchant_id\": \"3c8d53b0-1035-2b0e-a986-2c1339ab4374\",\n \"amount_pay\": \"string\",\n \"cash_leg_destination\": \"string\",\n \"status\": \"matched\",\n \"created_at\": \"1963-03-14T04:57:53.084Z\",\n \"expires_at\": \"2010-03-04T15:50:28.590Z\",\n \"cash_leg_attempts\": 9132,\n \"updated_at\": \"1954-07-16T13:13:07.682Z\",\n \"target_fiat_amount\": \"string\",\n \"target_currency\": \"string\",\n \"matched_buy_order_id\": \"38c3ef47-b34c-d5a3-8745-83dc023b3795\",\n \"last_cash_leg_attempt_at\": \"2003-06-21T09:09:50.973Z\",\n \"failure_reason\": \"string\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "30a9db01-c1bc-4df8-962a-7035e86d2dfd", "name": "Missing or invalid caller identity.", "originalRequest": { "url": { "path": [ "v1", "merchant-sell-orders", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) " } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "17c19aea-2272-4a6a-a6e1-b33e2c4ba21d", "name": "Caller is not the owner (`SELL_ORDER_NOT_OWNER`).", "originalRequest": { "url": { "path": [ "v1", "merchant-sell-orders", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) " } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Forbidden", "code": 403, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "fab0ef28-f8ec-493d-8fa9-832425643cdb", "name": "Sell order not found.", "originalRequest": { "url": { "path": [ "v1", "merchant-sell-orders", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) " } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "3e896447-2265-4e44-9987-99ec24eb3fce", "name": "Confirm the merchant has executed the cash leg externally.", "request": { "name": "Confirm the merchant has executed the cash leg externally.", "description": { "content": "Merchant signal that they have executed the fiat cash leg via their\nexternal rail. The handler:\n 1. Asserts the sell_order is in `cash_leg_in_flight` (else 409).\n 2. Increments `cash_leg_attempts` and updates `last_cash_leg_attempt_at`.\n 3. Validates external receipt evidence in the request body (handler\n persists for audit; no validator integration in S103(a)).\n 4. On success: flips status → `completed`, fires `sell_order.completed`\n webhook, and burns PAY via ledger-service (idempotency key =\n `sell_order.id`).\n\n**Idempotency**: required `Idempotency-Key` header. Repeated calls with\nthe same key are no-ops.\n\n**Retry policy**: if cash leg fails (rail rejects, OCR mismatch, etc.),\nmerchant calls again with new `Idempotency-Key`. The sweeper\n(`SweepCashLegRetryExhausted`) flips to `failed` after\n`CASH_LEG_RETRY_MAX` attempts past `CASH_LEG_RETRY_TIMEOUT_HOURS`.\nADR-103a-2: no dispute auto-creation in S103(a).\n", "type": "text/plain" }, "url": { "path": [ "v1", "merchant-sell-orders", ":id", "confirm-cash-leg" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) " } ] }, "header": [ { "disabled": false, "description": "(Required) ", "key": "Idempotency-Key", "value": "" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "auth": { "type": "apikey", "apikey": [ { "key": "key", "value": "X-API-Key" }, { "key": "value", "value": "{{apiKey}}" }, { "key": "in", "value": "header" } ] }, "body": { "mode": "raw", "raw": "{\n \"external_reference\": \"\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "id": "d5c42ecc-9d5a-4227-b6f3-8e6d2b666df6", "name": "Cash leg recorded. Inspect response `outcome` to determine resolution\n(`completed`, `cash_leg_in_flight` for retry-pending, or `failed` if\nsweeper has already flipped).\n", "originalRequest": { "url": { "path": [ "v1", "merchant-sell-orders", ":id", "confirm-cash-leg" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) " } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "disabled": false, "description": "(Required) ", "key": "Idempotency-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"external_reference\": \"\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"id\": \"3bcd90b6-2130-f572-8564-00501e41e68d\",\n \"merchant_id\": \"3c8d53b0-1035-2b0e-a986-2c1339ab4374\",\n \"amount_pay\": \"string\",\n \"cash_leg_destination\": \"string\",\n \"status\": \"matched\",\n \"created_at\": \"1963-03-14T04:57:53.084Z\",\n \"expires_at\": \"2010-03-04T15:50:28.590Z\",\n \"cash_leg_attempts\": 9132,\n \"updated_at\": \"1954-07-16T13:13:07.682Z\",\n \"target_fiat_amount\": \"string\",\n \"target_currency\": \"string\",\n \"matched_buy_order_id\": \"38c3ef47-b34c-d5a3-8745-83dc023b3795\",\n \"last_cash_leg_attempt_at\": \"2003-06-21T09:09:50.973Z\",\n \"failure_reason\": \"string\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "9956cfa1-f0b0-4f5b-87f0-63895aea17fe", "name": "Body invalid (missing receipt evidence, malformed base64).", "originalRequest": { "url": { "path": [ "v1", "merchant-sell-orders", ":id", "confirm-cash-leg" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) " } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "disabled": false, "description": "(Required) ", "key": "Idempotency-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"external_reference\": \"\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Bad Request", "code": 400, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "48694aa1-58c3-4d09-ac4e-5904ba5d08b2", "name": "Missing or invalid caller identity.", "originalRequest": { "url": { "path": [ "v1", "merchant-sell-orders", ":id", "confirm-cash-leg" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) " } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "disabled": false, "description": "(Required) ", "key": "Idempotency-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"external_reference\": \"\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "0c229308-8240-43f6-99bc-69d6bc568f57", "name": "Caller is not the owner (`SELL_ORDER_NOT_OWNER`).", "originalRequest": { "url": { "path": [ "v1", "merchant-sell-orders", ":id", "confirm-cash-leg" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) " } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "disabled": false, "description": "(Required) ", "key": "Idempotency-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"external_reference\": \"\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Forbidden", "code": 403, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "27e0e781-d4b7-40e5-a6c4-7f97cb4f32ca", "name": "Sell order not found.", "originalRequest": { "url": { "path": [ "v1", "merchant-sell-orders", ":id", "confirm-cash-leg" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) " } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "disabled": false, "description": "(Required) ", "key": "Idempotency-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"external_reference\": \"\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "6c82f269-8247-4d2d-9801-c1d6e5c3493d", "name": "Sell order not in `cash_leg_in_flight` (`SELL_ORDER_BAD_STATE`) or\nIdempotency-Key conflict (`IDEMPOTENCY_KEY_CONFLICT`).\n", "originalRequest": { "url": { "path": [ "v1", "merchant-sell-orders", ":id", "confirm-cash-leg" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) " } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "disabled": false, "description": "(Required) ", "key": "Idempotency-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"external_reference\": \"\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Conflict", "code": 409, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "a2bcfb9f-bf63-4f80-8064-920393d3e2cd", "name": "Burn failed because ledger-service is unavailable\n(`SELL_ORDER_LEDGER_UNAVAILABLE`). Tx rolled back; merchant may\nretry without consuming a slot.\n", "originalRequest": { "url": { "path": [ "v1", "merchant-sell-orders", ":id", "confirm-cash-leg" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) " } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "disabled": false, "description": "(Required) ", "key": "Idempotency-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"external_reference\": \"\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Bad Gateway", "code": 502, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "b3315ab0-0b67-4caf-aeb1-8fae72752396", "name": "Admin read-only list of receiver-confirm audit rows.", "request": { "name": "Admin read-only list of receiver-confirm audit rows.", "description": { "content": "Super-admin only. Cursor-paginated list of `receiver_confirm_audit`\nrows (S102 mig 059 — no new table in S103(a)). Filterable by `outcome`\n(multi-select: `verified` / `failed` / `unverified` / `timeout`),\n`pending_funds_id`, and `validator_kind` (`null` / `easyslip`).\n\n**Append-only invariant** (ADR-102-2): this endpoint is read-only;\nthe gateway has no UPDATE / DELETE path on `receiver_confirm_audit`.\nS3 cold archival of rows older than 90 days ships in S103(b) per\nADR-102-2 retention.\n", "type": "text/plain" }, "url": { "path": [ "admin", "audit", "receiver-confirm" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "key": "outcome", "value": "," }, { "disabled": false, "key": "pending_funds_id", "value": "" }, { "disabled": false, "key": "validator_kind", "value": "" }, { "disabled": false, "key": "cursor", "value": "" }, { "disabled": false, "key": "limit", "value": "25" } ], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "auth": { "type": "apikey", "apikey": [ { "key": "key", "value": "X-API-Key" }, { "key": "value", "value": "{{apiKey}}" }, { "key": "in", "value": "header" } ] } }, "response": [ { "id": "c4369909-c7ee-4de7-bfc1-ae31731e1a70", "name": "Paginated list of audit rows.", "originalRequest": { "url": { "path": [ "admin", "audit", "receiver-confirm" ], "host": [ "{{baseUrl}}" ], "query": [ { "key": "outcome", "value": "," }, { "key": "pending_funds_id", "value": "" }, { "key": "validator_kind", "value": "" }, { "key": "cursor", "value": "" }, { "key": "limit", "value": "25" } ], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"items\": [\n {\n \"id\": \"f2f86fbc-4ef6-491e-280a-6e351f1a0121\",\n \"pending_funds_id\": \"bc86bbd0-2b7e-f528-632a-f4010c29e5d9\",\n \"validator_kind\": \"string\",\n \"outcome\": \"malformed\",\n \"validator_latency_ms\": 2798,\n \"decided_at\": \"1987-11-05T22:57:19.125Z\",\n \"attempt_index\": 6317,\n \"created_at\": \"1993-07-23T05:57:24.815Z\",\n \"validator_response\": {\n \"key_0\": true,\n \"key_1\": 8591\n },\n \"failure_code\": \"string\",\n \"failure_message\": \"string\",\n \"decided_by_user_id\": \"be6af245-d726-7c0e-6da3-a23debd7c5e3\"\n },\n {\n \"id\": \"b0ea3064-ff4e-51a7-3604-01b849ef763d\",\n \"pending_funds_id\": \"3016ad37-7edf-3c44-3bb1-8dc616ad03a3\",\n \"validator_kind\": \"string\",\n \"outcome\": \"verified\",\n \"validator_latency_ms\": 5380,\n \"decided_at\": \"2004-06-14T10:05:47.160Z\",\n \"attempt_index\": 3473,\n \"created_at\": \"1995-02-03T03:11:03.957Z\",\n \"validator_response\": {\n \"key_0\": 1366.2050338848485\n },\n \"failure_code\": \"string\",\n \"failure_message\": \"string\",\n \"decided_by_user_id\": \"8e4209ce-a710-cce0-e34d-62b4ec2ed6cd\"\n }\n ],\n \"next_cursor\": \"string\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "9fb3867f-32a3-42c0-8a32-a531b6a5f451", "name": "Missing caller identity.", "originalRequest": { "url": { "path": [ "admin", "audit", "receiver-confirm" ], "host": [ "{{baseUrl}}" ], "query": [ { "key": "outcome", "value": "," }, { "key": "pending_funds_id", "value": "" }, { "key": "validator_kind", "value": "" }, { "key": "cursor", "value": "" }, { "key": "limit", "value": "25" } ], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "0d81cf7b-e3d0-4b55-8862-c6df25dd8c92", "name": "Caller is not super-admin (`ADMIN_FORBIDDEN`).", "originalRequest": { "url": { "path": [ "admin", "audit", "receiver-confirm" ], "host": [ "{{baseUrl}}" ], "query": [ { "key": "outcome", "value": "," }, { "key": "pending_funds_id", "value": "" }, { "key": "validator_kind", "value": "" }, { "key": "cursor", "value": "" }, { "key": "limit", "value": "25" } ], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Forbidden", "code": 403, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "3b62a241-487f-46e2-b4f8-2da05e96416c", "name": "Admin read-only detail for a single audit row.", "request": { "name": "Admin read-only detail for a single audit row.", "description": { "content": "Super-admin only. Returns the full audit row including the JSONB\n`validator_response` for diff inspection. Read-only; no mutation\npath exists in S103(a).\n", "type": "text/plain" }, "url": { "path": [ "admin", "audit", "receiver-confirm", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) " } ] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "auth": { "type": "apikey", "apikey": [ { "key": "key", "value": "X-API-Key" }, { "key": "value", "value": "{{apiKey}}" }, { "key": "in", "value": "header" } ] } }, "response": [ { "id": "f838c4c9-4950-4739-b808-76312e8b7074", "name": "Audit row detail.", "originalRequest": { "url": { "path": [ "admin", "audit", "receiver-confirm", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) " } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"id\": \"fa53ee47-864b-0876-b88c-e3f3a9fa7e9b\",\n \"pending_funds_id\": \"ad9fb010-031a-b276-506e-bddb1f969a70\",\n \"validator_kind\": \"string\",\n \"outcome\": \"unverified\",\n \"validator_latency_ms\": 588,\n \"decided_at\": \"1963-09-22T23:20:33.293Z\",\n \"attempt_index\": 6737,\n \"created_at\": \"2010-01-04T22:14:14.323Z\",\n \"validator_response\": {\n \"key_0\": 6184,\n \"key_1\": \"string\",\n \"key_2\": false\n },\n \"failure_code\": \"string\",\n \"failure_message\": \"string\",\n \"decided_by_user_id\": \"8c00b82e-f0b8-0f25-647a-389eb1843e59\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "e7212144-5e78-4f57-be7a-bdfc2b0090a9", "name": "Missing caller identity.", "originalRequest": { "url": { "path": [ "admin", "audit", "receiver-confirm", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) " } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "3baf1b4f-e376-4227-aa81-aa47aeca62b8", "name": "Caller is not super-admin (`ADMIN_FORBIDDEN`).", "originalRequest": { "url": { "path": [ "admin", "audit", "receiver-confirm", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) " } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Forbidden", "code": 403, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "a4200768-2879-44a0-9969-1387515e9089", "name": "Audit row not found.", "originalRequest": { "url": { "path": [ "admin", "audit", "receiver-confirm", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) " } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } } ], "event": [] }, { "id": "055c4022-1297-43fc-9dfb-37ab88601f6d", "name": "Gateway Disputes", "description": { "content": "TokenPay dispute lifecycle (S103(b) Phase 1). A `dispute` row tracks an\nadversarial event against a `sell_order`: cash-leg failure (auto-opened\nin S103(b) Phase 2A), merchant-initiated complaint, or chargeback. The\ngateway drives the lifecycle `opened → investigating → (resolved |\nescalated)`; resolution is super-admin-only and may emit a ledger\n`mint` (favor merchant), `burn` (favor counterparty), or no-op\ndepending on the outcome + originating sell_order kind.\n\n**Posture (LAW)**: dispute resolution moves PAY through ledger-service\n(mint/burn) only — NEVER fiat. The `cash_leg_failure` kind originates\nfrom a sell-order's external cash leg failing on the merchant's rail;\nTokenPay records the dispute and (in Phase 2A) auto-opens it, but the\nfiat reconciliation happens off-platform.\n\n**Auth model** (ADR-103b-1 Q4): merchant-facing endpoints use\nMerchantJWTAuth + MerchantDashboardAuth dual-path (Rule 22). Admin\nendpoints use `InternalServiceAuth` token — super-admin enforcement\nis upstream at api-gateway (mirrors S103(a) `/admin/audit/receiver-confirm`).\nThe `gateway_dispute_events.actor_user_id` column captures the resolving\nuser-id from the upstream-validated header.\n\n**Phase split** (ADR-103b-1):\n- **Phase 1 (this PR)** — schema (mig 061) + 7 routes + 3 webhook\n events (`gateway.dispute.opened`, `gateway.dispute.resolved`, `gateway.dispute.escalated`).\n- **Phase 2A** — wires cash-leg sweeper callback to\n `OpenGatewayCashLegFailureDispute` under `GATEWAY_DISPUTE_AUTO_OPEN_ENABLED`.\n- **Phase 2B** — admin-web + merchant-dashboard UIs.\n- **Phase 2C** — audit-archival worker + `buy_orders` write paths +\n `sell_orders.matched_buy_order_id` FK addition.\n\n**Webhook contract** (ADR-103b-1 Q3): `gateway.dispute.opened` fires alongside\nthe existing S103(a) `sell_order.failed` (additive, NOT replacing).\nMerchants integrated against S103(a) sell-order webhooks see no\nbreaking change. Tag declared in S103(b) Phase 1.\n", "type": "text/plain" }, "item": [ { "id": "d4c928e3-f594-4f3d-90dc-cbc7e5494f13", "name": "List disputes for the authenticated merchant.", "request": { "name": "List disputes for the authenticated merchant.", "description": { "content": "Cursor-paginated list of disputes scoped to the authenticated\nmerchant via the `sell_orders.merchant_id` join. Filterable by\n`status` (multi-select) and `kind` (multi-select).\n\nDual-path auth: MerchantJWTAuth (programmatic) + MerchantDashboardAuth\n(browser session) per Rule 22.\n", "type": "text/plain" }, "url": { "path": [ "v1", "merchant-disputes" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "key": "status", "value": "," }, { "disabled": false, "key": "kind", "value": "," }, { "disabled": false, "key": "cursor", "value": "" }, { "disabled": false, "key": "limit", "value": "25" } ], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "auth": { "type": "apikey", "apikey": [ { "key": "key", "value": "X-API-Key" }, { "key": "value", "value": "{{apiKey}}" }, { "key": "in", "value": "header" } ] } }, "response": [ { "id": "444bf763-2d90-419c-b628-abff083c5d04", "name": "Paginated list of disputes.", "originalRequest": { "url": { "path": [ "v1", "merchant-disputes" ], "host": [ "{{baseUrl}}" ], "query": [ { "key": "status", "value": "," }, { "key": "kind", "value": "," }, { "key": "cursor", "value": "" }, { "key": "limit", "value": "25" } ], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"items\": [\n {\n \"id\": \"669e17d3-630f-c938-71d3-2c17cf4f9a7c\",\n \"sell_order_id\": \"d889f563-61fd-582a-f459-e84dd3d893c6\",\n \"kind\": \"cash_leg_failure\",\n \"status\": \"resolved\",\n \"opened_at\": \"1975-03-27T09:14:18.275Z\",\n \"created_at\": \"2002-02-11T18:12:32.007Z\",\n \"updated_at\": \"2012-11-14T19:00:42.884Z\",\n \"pending_funds_id\": \"509eab10-2e69-89c6-29a0-5208bd6ccb9d\",\n \"resolved_at\": \"1947-03-26T15:35:41.909Z\",\n \"resolution_actor_user_id\": \"06a65119-4ba5-70c1-3485-46ea96f8a32f\",\n \"resolution_notes\": \"string\"\n },\n {\n \"id\": \"66a05101-949a-b012-e3c6-2e0e94c05db1\",\n \"sell_order_id\": \"c4d48d00-1a5d-cd15-34f8-787ea4448cb9\",\n \"kind\": \"chargeback\",\n \"status\": \"opened\",\n \"opened_at\": \"2003-07-17T19:20:24.413Z\",\n \"created_at\": \"2025-04-25T09:34:36.567Z\",\n \"updated_at\": \"1981-09-10T20:42:57.529Z\",\n \"pending_funds_id\": \"1c9e9b61-9f26-9c19-b23b-96da5b3fbcff\",\n \"resolved_at\": \"1999-10-16T17:36:26.749Z\",\n \"resolution_actor_user_id\": \"8a491c6a-b27e-e138-fa2d-ee4bfdd9837c\",\n \"resolution_notes\": \"string\"\n }\n ],\n \"next_cursor\": \"string\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "7c766d94-8f80-476b-9eaa-821b11be9bd4", "name": "Missing or invalid caller identity.", "originalRequest": { "url": { "path": [ "v1", "merchant-disputes" ], "host": [ "{{baseUrl}}" ], "query": [ { "key": "status", "value": "," }, { "key": "kind", "value": "," }, { "key": "cursor", "value": "" }, { "key": "limit", "value": "25" } ], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "6f53ff34-acc0-4b86-8f56-be8b5e33ad7b", "name": "Create a merchant-initiated dispute.", "request": { "name": "Create a merchant-initiated dispute.", "description": { "content": "Creates a `dispute` row with `kind='merchant_dispute'`, `status='opened'`\nagainst the referenced `sell_order_id`. The handler asserts the caller\nowns the referenced sell_order (cross-merchant returns 403\n`GATEWAY_DISPUTE_CROSS_MERCHANT`). Emits `gateway.dispute.opened` webhook.\n\n**Idempotency**: required `Idempotency-Key` header (UUIDv4 recommended).\nRepeated calls with the same key + same body return the same dispute\nrow; same key + different body returns 409 `IDEMPOTENCY_KEY_CONFLICT`.\n\n**Posture (LAW)**: dispute creation persists an audit row and emits a\nwebhook only — no fiat or PAY ledger op fires at open time. Ledger\nops are deferred to admin resolution.\n", "type": "text/plain" }, "url": { "path": [ "v1", "merchant-disputes" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "disabled": false, "description": "(Required) ", "key": "Idempotency-Key", "value": "" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "auth": { "type": "apikey", "apikey": [ { "key": "key", "value": "X-API-Key" }, { "key": "value", "value": "{{apiKey}}" }, { "key": "in", "value": "header" } ] }, "body": { "mode": "raw", "raw": "{\n \"sell_order_id\": \"\",\n \"notes\": \"\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "id": "718b6618-8a6c-41a7-a8b7-7a131f8919d7", "name": "Gateway dispute created.", "originalRequest": { "url": { "path": [ "v1", "merchant-disputes" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "disabled": false, "description": "(Required) ", "key": "Idempotency-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"sell_order_id\": \"\",\n \"notes\": \"\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Created", "code": 201, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"id\": \"1dc9638d-1b14-179d-cb84-106e3050a86f\",\n \"sell_order_id\": \"f3ee8ebf-1dc5-d64a-9073-56c699bd3ca5\",\n \"kind\": \"chargeback\",\n \"status\": \"escalated\",\n \"opened_at\": \"1963-04-30T16:52:02.665Z\",\n \"created_at\": \"1984-11-26T08:49:27.926Z\",\n \"updated_at\": \"1950-09-03T20:18:49.909Z\",\n \"pending_funds_id\": \"41f59ba1-0c12-a2c3-673a-05c5544f2871\",\n \"resolved_at\": \"2007-04-14T00:02:27.100Z\",\n \"resolution_actor_user_id\": \"f2605631-fd29-9abf-98cb-5418d4c7cf88\",\n \"resolution_notes\": \"string\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "409f981c-e5c8-42a3-9721-e09aa5d60b2e", "name": "Body invalid (missing `sell_order_id`, malformed UUID, notes empty or > 4000 chars).", "originalRequest": { "url": { "path": [ "v1", "merchant-disputes" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "disabled": false, "description": "(Required) ", "key": "Idempotency-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"sell_order_id\": \"\",\n \"notes\": \"\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Bad Request", "code": 400, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "c5a45595-06c0-4bd7-b890-887d7fb28fde", "name": "Missing or invalid caller identity.", "originalRequest": { "url": { "path": [ "v1", "merchant-disputes" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "disabled": false, "description": "(Required) ", "key": "Idempotency-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"sell_order_id\": \"\",\n \"notes\": \"\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "e492ed64-09e3-47df-82a8-46840ae49ba2", "name": "Caller is not the owner of the referenced sell_order (`GATEWAY_DISPUTE_CROSS_MERCHANT`).", "originalRequest": { "url": { "path": [ "v1", "merchant-disputes" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "disabled": false, "description": "(Required) ", "key": "Idempotency-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"sell_order_id\": \"\",\n \"notes\": \"\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Forbidden", "code": 403, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "13ffaa1d-2924-42a4-884b-db03c621af11", "name": "Referenced sell_order not found.", "originalRequest": { "url": { "path": [ "v1", "merchant-disputes" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "disabled": false, "description": "(Required) ", "key": "Idempotency-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"sell_order_id\": \"\",\n \"notes\": \"\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "41a8f053-2ebb-4e5b-973b-92c7885a8600", "name": "Idempotency-Key conflict (`IDEMPOTENCY_KEY_CONFLICT`).", "originalRequest": { "url": { "path": [ "v1", "merchant-disputes" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "disabled": false, "description": "(Required) ", "key": "Idempotency-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"sell_order_id\": \"\",\n \"notes\": \"\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Conflict", "code": 409, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "c377a9a9-4544-4484-b6a0-5bcdd6f791ef", "name": "Read a single dispute (merchant-scoped).", "request": { "name": "Read a single dispute (merchant-scoped).", "description": { "content": "Returns the dispute for the given UUID. The caller must own the\nunderlying sell_order; cross-merchant reads return 403\n`GATEWAY_DISPUTE_CROSS_MERCHANT`. Merchant-facing detail does NOT include\nthe `gateway_dispute_events` array (admin-only).\n", "type": "text/plain" }, "url": { "path": [ "v1", "merchant-disputes", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) " } ] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "auth": { "type": "apikey", "apikey": [ { "key": "key", "value": "X-API-Key" }, { "key": "value", "value": "{{apiKey}}" }, { "key": "in", "value": "header" } ] } }, "response": [ { "id": "94ca0ef3-acf6-4461-b22b-9de72adbbb6d", "name": "Gateway dispute detail.", "originalRequest": { "url": { "path": [ "v1", "merchant-disputes", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) " } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"id\": \"1dc9638d-1b14-179d-cb84-106e3050a86f\",\n \"sell_order_id\": \"f3ee8ebf-1dc5-d64a-9073-56c699bd3ca5\",\n \"kind\": \"chargeback\",\n \"status\": \"escalated\",\n \"opened_at\": \"1963-04-30T16:52:02.665Z\",\n \"created_at\": \"1984-11-26T08:49:27.926Z\",\n \"updated_at\": \"1950-09-03T20:18:49.909Z\",\n \"pending_funds_id\": \"41f59ba1-0c12-a2c3-673a-05c5544f2871\",\n \"resolved_at\": \"2007-04-14T00:02:27.100Z\",\n \"resolution_actor_user_id\": \"f2605631-fd29-9abf-98cb-5418d4c7cf88\",\n \"resolution_notes\": \"string\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "f3299c33-952c-40e6-8745-8474a737965c", "name": "Missing or invalid caller identity.", "originalRequest": { "url": { "path": [ "v1", "merchant-disputes", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) " } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "02725b75-ce78-4de2-b6ba-0e53a27b6e90", "name": "Caller is not the owner (`GATEWAY_DISPUTE_CROSS_MERCHANT`).", "originalRequest": { "url": { "path": [ "v1", "merchant-disputes", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) " } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Forbidden", "code": 403, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "a05acbf7-d04e-4f12-afd4-937c0bfce93e", "name": "Gateway dispute not found.", "originalRequest": { "url": { "path": [ "v1", "merchant-disputes", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) " } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "21e4e586-d74f-40a3-a147-12111eb8799a", "name": "Admin list of disputes across all merchants.", "request": { "name": "Admin list of disputes across all merchants.", "description": { "content": "Super-admin-enforced (upstream at api-gateway via `InternalServiceAuth`\ntoken + admin-web super-admin guard middleware, per ADR-103b-1 Q4).\nCursor-paginated list of `disputes` rows. Filterable by `status`\n(multi-select), `kind` (multi-select), `sell_order_id`, and\nopened-window (`opened_after`, `opened_before`).\n", "type": "text/plain" }, "url": { "path": [ "admin", "disputes" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "key": "status", "value": "," }, { "disabled": false, "key": "kind", "value": "," }, { "disabled": false, "key": "sell_order_id", "value": "" }, { "disabled": false, "key": "opened_after", "value": "" }, { "disabled": false, "key": "opened_before", "value": "" }, { "disabled": false, "key": "cursor", "value": "" }, { "disabled": false, "key": "limit", "value": "25" } ], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "auth": { "type": "apikey", "apikey": [ { "key": "key", "value": "X-API-Key" }, { "key": "value", "value": "{{apiKey}}" }, { "key": "in", "value": "header" } ] } }, "response": [ { "id": "8a2c9380-56ae-4f61-893f-8c5c93e59fa4", "name": "Paginated list of disputes.", "originalRequest": { "url": { "path": [ "admin", "disputes" ], "host": [ "{{baseUrl}}" ], "query": [ { "key": "status", "value": "," }, { "key": "kind", "value": "," }, { "key": "sell_order_id", "value": "" }, { "key": "opened_after", "value": "" }, { "key": "opened_before", "value": "" }, { "key": "cursor", "value": "" }, { "key": "limit", "value": "25" } ], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"items\": [\n {\n \"id\": \"9c14d9ce-88db-990b-826a-9fefbded4ab6\",\n \"sell_order_id\": \"8288c1bb-3cf9-98be-4fe7-8887d5d71e35\",\n \"kind\": \"chargeback\",\n \"status\": \"escalated\",\n \"opened_at\": \"1963-02-17T23:38:36.643Z\",\n \"created_at\": \"1962-08-30T17:34:31.004Z\",\n \"updated_at\": \"1991-05-09T12:03:23.526Z\",\n \"pending_funds_id\": \"205a8172-75f3-7d48-20c6-59936c419130\",\n \"resolved_at\": \"1960-04-05T09:16:59.931Z\",\n \"resolution_actor_user_id\": \"3c5d3cd3-989c-c0af-5375-5d47a4f986af\",\n \"resolution_notes\": \"string\"\n },\n {\n \"id\": \"6988e2ad-5e4f-13ae-42dc-8f3b859e6fdd\",\n \"sell_order_id\": \"2703fa90-dde1-3af8-9ded-294ba95e0852\",\n \"kind\": \"cash_leg_failure\",\n \"status\": \"resolved\",\n \"opened_at\": \"1970-08-10T06:37:16.825Z\",\n \"created_at\": \"1960-05-19T07:04:28.499Z\",\n \"updated_at\": \"1979-05-22T12:20:12.366Z\",\n \"pending_funds_id\": \"ce8f71c2-a5f3-bfd4-9bad-3bf04db8c988\",\n \"resolved_at\": \"1972-04-10T02:47:00.104Z\",\n \"resolution_actor_user_id\": \"bc74ad8d-2f9d-9e73-5e78-9fe1a00855ba\",\n \"resolution_notes\": \"string\"\n }\n ],\n \"next_cursor\": \"string\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "4b748feb-795d-42e7-bc75-83edf66a5c40", "name": "Missing caller identity.", "originalRequest": { "url": { "path": [ "admin", "disputes" ], "host": [ "{{baseUrl}}" ], "query": [ { "key": "status", "value": "," }, { "key": "kind", "value": "," }, { "key": "sell_order_id", "value": "" }, { "key": "opened_after", "value": "" }, { "key": "opened_before", "value": "" }, { "key": "cursor", "value": "" }, { "key": "limit", "value": "25" } ], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "dcc39751-bff7-4e4f-b7cc-9d082e650b9c", "name": "Caller is not super-admin (`ADMIN_FORBIDDEN`).", "originalRequest": { "url": { "path": [ "admin", "disputes" ], "host": [ "{{baseUrl}}" ], "query": [ { "key": "status", "value": "," }, { "key": "kind", "value": "," }, { "key": "sell_order_id", "value": "" }, { "key": "opened_after", "value": "" }, { "key": "opened_before", "value": "" }, { "key": "cursor", "value": "" }, { "key": "limit", "value": "25" } ], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Forbidden", "code": 403, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "887b1e06-309d-4677-bfdc-ea4c9471a45a", "name": "Stuck-PAY admin queue (non-terminal disputes ordered oldest-first).", "request": { "name": "Stuck-PAY admin queue (non-terminal disputes ordered oldest-first).", "description": { "content": "Super-admin-enforced. Returns the operational queue of disputes that\nrequire admin attention: all rows with `status IN ('opened',\n'investigating')` ordered by `opened_at ASC` (oldest first). Used\nby the Phase 2B admin-web `/admin/disputes` UI as the default view.\nUnlike `/admin/disputes` this endpoint is NOT cursor-paginated — it\nreturns the full non-terminal set (capped server-side; expected to\nbe small in steady state).\n", "type": "text/plain" }, "url": { "path": [ "admin", "disputes", "queue" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "auth": { "type": "apikey", "apikey": [ { "key": "key", "value": "X-API-Key" }, { "key": "value", "value": "{{apiKey}}" }, { "key": "in", "value": "header" } ] } }, "response": [ { "id": "0fec03ad-5aa6-46a8-b149-c9ce091be4db", "name": "Non-terminal disputes (oldest-first).", "originalRequest": { "url": { "path": [ "admin", "disputes", "queue" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"items\": [\n {\n \"id\": \"5e9f0778-2302-8b72-88d4-87a8fdd4ebd4\",\n \"sell_order_id\": \"839e74da-5d6f-c649-e2fc-dad58ed1cda2\",\n \"kind\": \"merchant_dispute\",\n \"status\": \"investigating\",\n \"opened_at\": \"2011-09-07T16:54:39.358Z\",\n \"created_at\": \"1989-11-22T23:49:44.533Z\",\n \"updated_at\": \"2012-05-25T02:00:53.850Z\",\n \"pending_funds_id\": \"987b5784-6fed-48fe-7036-8bc321b9f664\",\n \"resolved_at\": \"2015-04-26T13:12:02.966Z\",\n \"resolution_actor_user_id\": \"ad94ae3e-24e0-6e30-b9a5-88429ab8f476\",\n \"resolution_notes\": \"string\"\n },\n {\n \"id\": \"896c8d4f-df7e-3364-87e0-4857e3354bea\",\n \"sell_order_id\": \"5847d22f-0a8a-acd8-9517-22b68be56146\",\n \"kind\": \"chargeback\",\n \"status\": \"escalated\",\n \"opened_at\": \"2019-02-24T17:23:29.368Z\",\n \"created_at\": \"2007-07-01T23:44:49.423Z\",\n \"updated_at\": \"1946-06-07T21:34:15.874Z\",\n \"pending_funds_id\": \"0e5352f5-bb39-793c-63c0-81737cf73ce4\",\n \"resolved_at\": \"1949-01-23T09:02:44.066Z\",\n \"resolution_actor_user_id\": \"4a6a25d9-b6dc-1552-53b9-5de8523580ce\",\n \"resolution_notes\": \"string\"\n }\n ]\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "06efe2ee-a13e-4b11-8df8-ce2b76359e28", "name": "Missing caller identity.", "originalRequest": { "url": { "path": [ "admin", "disputes", "queue" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "93ce29e9-cd44-423b-96b9-4aac2b88520c", "name": "Caller is not super-admin (`ADMIN_FORBIDDEN`).", "originalRequest": { "url": { "path": [ "admin", "disputes", "queue" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Forbidden", "code": 403, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "3b35f1f4-8ebb-4c24-8624-5ec44b4301c4", "name": "Admin read of a single dispute (with full event audit trail).", "request": { "name": "Admin read of a single dispute (with full event audit trail).", "description": { "content": "Super-admin-enforced. Returns the dispute row plus the full\n`gateway_dispute_events` audit array (every state transition, with\n`event_kind`, `actor_user_id`, `details JSONB`, `recorded_at`).\nMerchant-facing `/v1/merchant-disputes/{id}` does NOT return the\nevents array; this admin endpoint is the only path that exposes it.\n", "type": "text/plain" }, "url": { "path": [ "admin", "disputes", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) " } ] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "auth": { "type": "apikey", "apikey": [ { "key": "key", "value": "X-API-Key" }, { "key": "value", "value": "{{apiKey}}" }, { "key": "in", "value": "header" } ] } }, "response": [ { "id": "9b0f5700-a2f3-4fec-87df-0f1d6d09be2e", "name": "Gateway dispute detail with events.", "originalRequest": { "url": { "path": [ "admin", "disputes", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) " } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"dispute\": {\n \"id\": \"479e595a-4a09-f1b4-2066-76d16e98a244\",\n \"sell_order_id\": \"580ded48-3885-9fa6-1976-236ec50f206f\",\n \"kind\": \"chargeback\",\n \"status\": \"escalated\",\n \"opened_at\": \"1980-10-09T18:59:35.593Z\",\n \"created_at\": \"1963-04-24T23:41:04.912Z\",\n \"updated_at\": \"1953-10-21T06:07:54.447Z\",\n \"pending_funds_id\": \"3a8cf846-8443-dae1-8375-8f22af22b828\",\n \"resolved_at\": \"2009-10-19T21:44:35.710Z\",\n \"resolution_actor_user_id\": \"df5af6c2-7302-be76-9269-f4f5b840ab05\",\n \"resolution_notes\": \"string\"\n },\n \"events\": [\n {\n \"id\": \"13cbaeef-7be0-f96c-cce5-6470330a9d25\",\n \"gateway_dispute_id\": \"643e0f7a-1e8b-3e25-7770-ceebbab6d8b5\",\n \"event_kind\": \"string\",\n \"details\": {\n \"key_0\": 6036.790101019762\n },\n \"recorded_at\": \"1999-10-22T22:35:47.922Z\",\n \"actor_user_id\": \"f1b41424-dfde-c410-a88b-27866ac46e2d\"\n },\n {\n \"id\": \"6d76f301-e300-42f2-e1be-83fc8ba7782a\",\n \"gateway_dispute_id\": \"26713aea-2832-840e-be1b-799e5a34e3fd\",\n \"event_kind\": \"string\",\n \"details\": {\n \"key_0\": \"string\"\n },\n \"recorded_at\": \"1954-01-27T03:57:18.665Z\",\n \"actor_user_id\": \"1cb37c57-7f41-23ba-836a-c377e754c9e1\"\n }\n ]\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "2d18d2d3-b165-4296-b3ef-438212afe8d5", "name": "Missing caller identity.", "originalRequest": { "url": { "path": [ "admin", "disputes", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) " } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "d1e20013-6c66-46a6-8dbe-3175fa1bb4d5", "name": "Caller is not super-admin (`ADMIN_FORBIDDEN`).", "originalRequest": { "url": { "path": [ "admin", "disputes", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) " } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Forbidden", "code": 403, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "9f252800-1201-4fd6-b9eb-01bd8922f00b", "name": "Gateway dispute not found.", "originalRequest": { "url": { "path": [ "admin", "disputes", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) " } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "fbae0a4b-b201-46eb-b48e-518b75b765a6", "name": "Super-admin resolve a dispute (terminal transition).", "request": { "name": "Super-admin resolve a dispute (terminal transition).", "description": { "content": "Super-admin-enforced. Maps the supplied `outcome` to:\n - `merchant_favored` → status `resolved`; on `cash_leg_failure`\n disputes, mints PAY to the merchant via ledger-service\n (idempotency key = `dispute.id`).\n - `counterparty_favored` → status `resolved`; on `merchant_dispute`\n kinds, burns PAY from the merchant.\n - `no_action` → status `resolved`; no ledger op.\n - `escalated` → status `escalated`; no ledger op.\nOn any non-`no_action` / non-`escalated` outcome the service derives\nthe ledger op from the originating sell_order kind. Single tx covers\nthe dispute UPDATE + `gateway_dispute_events` INSERT + ledger call (rolls\nback atomically on ledger failure).\n\n**Idempotency**: required `Idempotency-Key` header. Repeated calls\nwith the same key are no-ops.\n\n**Auth (Q4)**: super-admin via api-gateway upstream + `InternalServiceAuth`\ntoken; gateway-service does not re-validate the role. The\n`gateway_dispute_events.actor_user_id` column captures the user from the\nupstream-validated header.\n\n**Posture (LAW)**: ledger ops mint or burn PAY only; no fiat. Resolve\non a terminal dispute returns 409 `GATEWAY_DISPUTE_ALREADY_RESOLVED`.\n", "type": "text/plain" }, "url": { "path": [ "admin", "disputes", ":id", "resolve" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) " } ] }, "header": [ { "disabled": false, "description": "(Required) ", "key": "Idempotency-Key", "value": "" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "auth": { "type": "apikey", "apikey": [ { "key": "key", "value": "X-API-Key" }, { "key": "value", "value": "{{apiKey}}" }, { "key": "in", "value": "header" } ] }, "body": { "mode": "raw", "raw": "{\n \"outcome\": \"\",\n \"notes\": \"\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "id": "7dc6c13c-cf79-4162-8952-8e892678e974", "name": "Gateway dispute resolved (terminal status set).", "originalRequest": { "url": { "path": [ "admin", "disputes", ":id", "resolve" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) " } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "disabled": false, "description": "(Required) ", "key": "Idempotency-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"outcome\": \"no_action\",\n \"notes\": \"\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"id\": \"1dc9638d-1b14-179d-cb84-106e3050a86f\",\n \"sell_order_id\": \"f3ee8ebf-1dc5-d64a-9073-56c699bd3ca5\",\n \"kind\": \"chargeback\",\n \"status\": \"escalated\",\n \"opened_at\": \"1963-04-30T16:52:02.665Z\",\n \"created_at\": \"1984-11-26T08:49:27.926Z\",\n \"updated_at\": \"1950-09-03T20:18:49.909Z\",\n \"pending_funds_id\": \"41f59ba1-0c12-a2c3-673a-05c5544f2871\",\n \"resolved_at\": \"2007-04-14T00:02:27.100Z\",\n \"resolution_actor_user_id\": \"f2605631-fd29-9abf-98cb-5418d4c7cf88\",\n \"resolution_notes\": \"string\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "a19ff479-0b1c-4dfc-976a-daf5d6b7882f", "name": "Body invalid (missing/invalid `outcome`, notes empty or > 4000 chars).", "originalRequest": { "url": { "path": [ "admin", "disputes", ":id", "resolve" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) " } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "disabled": false, "description": "(Required) ", "key": "Idempotency-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"outcome\": \"no_action\",\n \"notes\": \"\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Bad Request", "code": 400, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "03b82422-3bd8-4338-83b7-d7be2a8b5b2e", "name": "Missing caller identity.", "originalRequest": { "url": { "path": [ "admin", "disputes", ":id", "resolve" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) " } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "disabled": false, "description": "(Required) ", "key": "Idempotency-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"outcome\": \"no_action\",\n \"notes\": \"\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "c4e28706-f30d-42d0-b296-a188f5f7910c", "name": "Caller is not super-admin (`ADMIN_FORBIDDEN`).", "originalRequest": { "url": { "path": [ "admin", "disputes", ":id", "resolve" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) " } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "disabled": false, "description": "(Required) ", "key": "Idempotency-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"outcome\": \"no_action\",\n \"notes\": \"\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Forbidden", "code": 403, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "edfeeccf-caa0-4538-9ff5-e4205dc6edc5", "name": "Gateway dispute not found.", "originalRequest": { "url": { "path": [ "admin", "disputes", ":id", "resolve" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) " } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "disabled": false, "description": "(Required) ", "key": "Idempotency-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"outcome\": \"no_action\",\n \"notes\": \"\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "02a3983b-034e-404c-84cd-a1dd7d129aa0", "name": "Gateway dispute already in a terminal state (`GATEWAY_DISPUTE_ALREADY_RESOLVED`)\nor Idempotency-Key conflict (`IDEMPOTENCY_KEY_CONFLICT`).\n", "originalRequest": { "url": { "path": [ "admin", "disputes", ":id", "resolve" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) " } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "disabled": false, "description": "(Required) ", "key": "Idempotency-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"outcome\": \"no_action\",\n \"notes\": \"\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Conflict", "code": 409, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "165b20f9-b379-461f-bd84-7adcece7c895", "name": "Ledger op failed. On `merchant_favored` of a `cash_leg_failure`\ndispute when `MINT_SOURCE_ACCOUNT_ID` is unconfigured, returns\n`GATEWAY_DISPUTE_LEDGER_MINT_SOURCE_MISSING` (transaction rolls back).\n", "originalRequest": { "url": { "path": [ "admin", "disputes", ":id", "resolve" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) " } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "disabled": false, "description": "(Required) ", "key": "Idempotency-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"outcome\": \"no_action\",\n \"notes\": \"\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Internal Server Error", "code": 500, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } } ], "event": [] }, { "id": "a402d12f-1773-445b-8ea3-16170db96f93", "name": "BuyOrders", "description": { "content": "TokenPay merchant buy-order surface (S103(b) Phase 2C). A `buy_order`\nis the merchant-side counterparty to an existing `sell_order`: the\nmerchant locks fiat against PAY they want to acquire, and the buy-side\nmatcher pairs pending sells ⇔ buys FIFO inside one atomic TX +\nledger-service `CreateTransaction`. Mint-on-resolution: a successful\nmatch debits `MintSourceAccountID` and credits the buyer-merchant's PAY\navailable account. There is NO `/confirm-cash-leg` verb on buy-side —\nthe cash leg is the merchant's funding leg and is settled at match\ntime inside the matcher's atomic TX (Phase 2C §Q3 lock).\n\n**Posture (LAW)**: buy-order resolution moves PAY through\nledger-service only — NEVER fiat. The matching engine fails-closed\nwhen `MintSourceAccountID` is empty (Rule 33).\n\n**Auth model** (ADR-103b-1 Q4): merchant-facing endpoints use\nMerchantJWTAuth + MerchantDashboardAuth dual-path (Rule 22), same\nstack as `/v1/merchant-sell-orders`. POST verbs go through the\nshared Idempotency middleware (Rule G.3.A).\n\n**Webhook contract**: `buy_order.created`, `buy_order.matched`, and\n`buy_order.cancelled` fire alongside the corresponding sell-side\nlifecycle events. Tag declared in S103(b) Phase 2C.\n", "type": "text/plain" }, "item": [ { "id": "372f18e7-2c12-4dff-a0d7-51bec5e3234e", "name": "List buy_orders for the calling merchant", "request": { "name": "List buy_orders for the calling merchant", "description": { "content": "Cursor-paginated list of `buy_order` rows scoped to the calling\nmerchant. Mirrors `GET /v1/merchant-sell-orders` shape. Auth:\nMerchantJWTAuth + MerchantDashboardAuth.\n", "type": "text/plain" }, "url": { "path": [ "v1", "merchant-buy-orders" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "key": "status", "value": "" }, { "disabled": false, "key": "cursor", "value": "" }, { "disabled": false, "key": "limit", "value": "50" } ], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET" }, "response": [ { "id": "e0a0a97c-ab91-4abd-9933-1c80ff38ab3b", "name": "Buy-order page (rows + next_cursor).", "originalRequest": { "url": { "path": [ "v1", "merchant-buy-orders" ], "host": [ "{{baseUrl}}" ], "query": [ { "key": "status", "value": "" }, { "key": "cursor", "value": "" }, { "key": "limit", "value": "50" } ], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "f555d8f8-84ee-4fbc-b06d-a7ffc000f063", "name": "Missing or invalid merchant JWT.", "originalRequest": { "url": { "path": [ "v1", "merchant-buy-orders" ], "host": [ "{{baseUrl}}" ], "query": [ { "key": "status", "value": "" }, { "key": "cursor", "value": "" }, { "key": "limit", "value": "50" } ], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" } ], "method": "GET", "body": {} }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "text/plain" } ], "body": "", "cookie": [], "_postman_previewlanguage": "text" }, { "id": "c4bc65a8-ca2e-45a7-901d-5cd9dd50b189", "name": "JWT does not authorise the requested merchant_id.", "originalRequest": { "url": { "path": [ "v1", "merchant-buy-orders" ], "host": [ "{{baseUrl}}" ], "query": [ { "key": "status", "value": "" }, { "key": "cursor", "value": "" }, { "key": "limit", "value": "50" } ], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" } ], "method": "GET", "body": {} }, "status": "Forbidden", "code": 403, "header": [ { "key": "Content-Type", "value": "text/plain" } ], "body": "", "cookie": [], "_postman_previewlanguage": "text" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "dea5faac-86ee-4c89-8ca6-a5ce87890854", "name": "Create a buy_order in pending status", "request": { "name": "Create a buy_order in pending status", "description": { "content": "Creates a `buy_order` row in `pending` status. Idempotency-Key\nheader REQUIRED (Rule G.3.A) — duplicate keys within the 24h\nwindow return the original 2xx response. The matcher pairs the\nnew row against pending sells on its next tick (gated by\n`BUY_ORDER_MATCHER_ENABLED`).\n", "type": "text/plain" }, "url": { "path": [ "v1", "merchant-buy-orders" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "disabled": false, "description": "(Required) ", "key": "Idempotency-Key", "value": "" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "", "options": { "raw": { "language": "json" } } } }, "response": [ { "id": "d40def59-2dc8-40a2-b810-88156e16c3ce", "name": "Created — returns the new buy_order row.", "originalRequest": { "url": { "path": [ "v1", "merchant-buy-orders" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "disabled": false, "description": "(Required) ", "key": "Idempotency-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "", "options": { "raw": { "language": "json" } } } }, "status": "Created", "code": 201, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "8b8049ce-6ae2-4e6a-8372-19ce663b55b9", "name": "Validation error (invalid amount, currency, cash_leg_source).", "originalRequest": { "url": { "path": [ "v1", "merchant-buy-orders" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "disabled": false, "description": "(Required) ", "key": "Idempotency-Key", "value": "" } ], "method": "POST", "body": { "mode": "raw", "raw": "", "options": { "raw": { "language": "json" } } } }, "status": "Bad Request", "code": 400, "header": [ { "key": "Content-Type", "value": "text/plain" } ], "body": "", "cookie": [], "_postman_previewlanguage": "text" }, { "id": "fd6597ff-2dfb-4ff3-aa26-0e197078bf1a", "name": "Missing or invalid merchant JWT.", "originalRequest": { "url": { "path": [ "v1", "merchant-buy-orders" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "disabled": false, "description": "(Required) ", "key": "Idempotency-Key", "value": "" } ], "method": "POST", "body": { "mode": "raw", "raw": "", "options": { "raw": { "language": "json" } } } }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "text/plain" } ], "body": "", "cookie": [], "_postman_previewlanguage": "text" }, { "id": "0345cea5-930d-414b-9bcc-4c223fe018da", "name": "Idempotency-Key replay collision with a different request body.", "originalRequest": { "url": { "path": [ "v1", "merchant-buy-orders" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "disabled": false, "description": "(Required) ", "key": "Idempotency-Key", "value": "" } ], "method": "POST", "body": { "mode": "raw", "raw": "", "options": { "raw": { "language": "json" } } } }, "status": "Conflict", "code": 409, "header": [ { "key": "Content-Type", "value": "text/plain" } ], "body": "", "cookie": [], "_postman_previewlanguage": "text" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "5420d5c5-9aaa-47f0-be0e-22c730bfc385", "name": "Fetch a single buy_order by id", "request": { "name": "Fetch a single buy_order by id", "description": {}, "url": { "path": [ "v1", "merchant-buy-orders", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) " } ] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET" }, "response": [ { "id": "2928ba0e-8014-45e1-93fb-124e0c0fa4ab", "name": "Buy-order row.", "originalRequest": { "url": { "path": [ "v1", "merchant-buy-orders", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) " } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "67295b09-89a7-40ca-a494-8a6ae5908ea7", "name": "Buy-order belongs to another merchant.", "originalRequest": { "url": { "path": [ "v1", "merchant-buy-orders", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) " } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" } ], "method": "GET", "body": {} }, "status": "Forbidden", "code": 403, "header": [ { "key": "Content-Type", "value": "text/plain" } ], "body": "", "cookie": [], "_postman_previewlanguage": "text" }, { "id": "ec8f1a7b-56c1-47eb-b4b8-3dafa25a4f81", "name": "Buy-order does not exist.", "originalRequest": { "url": { "path": [ "v1", "merchant-buy-orders", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) " } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" } ], "method": "GET", "body": {} }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "text/plain" } ], "body": "", "cookie": [], "_postman_previewlanguage": "text" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "a600d27c-8974-41a5-b577-151b461f9a93", "name": "Cancel a pending buy_order", "request": { "name": "Cancel a pending buy_order", "description": { "content": "Transitions a buy_order from `pending` to `cancelled`. Only\ncancellable while in `pending`; matched/completed/failed rows\nreturn 409. Idempotency-Key REQUIRED (Rule G.3.A).\n", "type": "text/plain" }, "url": { "path": [ "v1", "merchant-buy-orders", ":id", "cancel" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) " } ] }, "header": [ { "disabled": false, "description": "(Required) ", "key": "Idempotency-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "POST" }, "response": [ { "id": "06b2c95a-8eff-4e4f-b750-2f12f41bbead", "name": "Cancelled — returns the updated buy_order row.", "originalRequest": { "url": { "path": [ "v1", "merchant-buy-orders", ":id", "cancel" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) " } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "disabled": false, "description": "(Required) ", "key": "Idempotency-Key", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "a7905bbd-67c4-47df-b6dc-102f19deca73", "name": "Buy-order belongs to another merchant.", "originalRequest": { "url": { "path": [ "v1", "merchant-buy-orders", ":id", "cancel" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) " } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "disabled": false, "description": "(Required) ", "key": "Idempotency-Key", "value": "" } ], "method": "POST", "body": {} }, "status": "Forbidden", "code": 403, "header": [ { "key": "Content-Type", "value": "text/plain" } ], "body": "", "cookie": [], "_postman_previewlanguage": "text" }, { "id": "a03f3d4d-8555-48d3-8cc1-0da81bfd36de", "name": "Buy-order does not exist.", "originalRequest": { "url": { "path": [ "v1", "merchant-buy-orders", ":id", "cancel" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) " } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "disabled": false, "description": "(Required) ", "key": "Idempotency-Key", "value": "" } ], "method": "POST", "body": {} }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "text/plain" } ], "body": "", "cookie": [], "_postman_previewlanguage": "text" }, { "id": "2a3ed131-cf3b-49bf-b59b-a014aa7aa1e7", "name": "Buy-order is not in a cancellable status.", "originalRequest": { "url": { "path": [ "v1", "merchant-buy-orders", ":id", "cancel" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) " } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: apikey", "type": "text/plain" }, "key": "X-API-Key", "value": "" }, { "disabled": false, "description": "(Required) ", "key": "Idempotency-Key", "value": "" } ], "method": "POST", "body": {} }, "status": "Conflict", "code": 409, "header": [ { "key": "Content-Type", "value": "text/plain" } ], "body": "", "cookie": [], "_postman_previewlanguage": "text" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } } ], "event": [] } ], "event": [], "variable": [ { "type": "string", "value": "https://api.tokenpayment.io", "key": "baseUrl" }, { "key": "api_key", "value": "tk_test_replace_me", "type": "string" } ], "auth": { "type": "apikey", "apikey": [ { "key": "key", "value": "X-API-Key" }, { "key": "value", "value": "{{apiKey}}" }, { "key": "in", "value": "header" } ] }, "info": { "_postman_id": "2b416a8b-f13d-415e-8174-005599ca69d3", "name": "TokenPay Merchant API", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json", "description": { "content": "This document is the machine-readable contract for every v1 merchant-facing\nendpoint served by `gateway-service`. It is the source of truth for the\ndeveloper portal, SDKs, and Postman collection — if the spec and the\nimplementation disagree, the implementation is the bug.\n\nScope boundary:\n * **Included**: the 20 routes under `/v1` that are part of the public\n merchant contract.\n * **Not included**: admin-only routes (`/v1/merchants/*`,\n `/admin/*`), dashboard dual-auth routes (`/v1/merchant-payments`,\n `/v1/merchant-settlements`, `/v1/merchant-webhooks`,\n `/v1/merchants/me/*`), service-to-service endpoints (`/internal/*`),\n and merchant-auth/onboarding/application surfaces\n (`/merchant-auth/*`, `/merchant-onboarding/*`,\n `/merchant-applications/*`).\n\nSee `docs/api/VERSIONING.md` for the stability guarantee and deprecation\npolicy that applies to every operation below.\n\n\nContact Support:\n Name: TokenPay Developer Support\n Email: developers@tokenpayment.io", "type": "text/plain" } } }