{ "item": [ { "id": "17c95c22-ab71-460a-8b91-30f01e765389", "name": "Partner API", "description": { "content": "", "type": "text/plain" }, "item": [ { "id": "a5e7535b-8b31-46f1-9753-a16445637bd9", "name": "List Merchants", "request": { "name": "List Merchants", "description": { "content": "List merchants linked to the authenticated partner. Partner API keys only.", "type": "text/plain" }, "url": { "path": [ "api", "v1", "merchants" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "auth": null }, "response": [ { "id": "880e9b12-1b7d-4736-8b64-03e97a8c102c", "originalRequest": { "url": { "path": [ "api", "v1", "merchants" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"message\": \"Merchants retrieved successfully\",\n \"code\": \"\",\n \"data\": [\n {\n \"id\": 1,\n \"name\": \"Demo Store Ltd\",\n \"mcc\": \"5734\",\n \"status\": \"active\",\n \"address\": \"1 High Street\",\n \"city\": \"London\",\n \"country_code\": \"GB\",\n \"email\": \"merchant@example.com\",\n \"phone\": \"+441234567890\",\n \"website\": \"https://demo-store.example.com\",\n \"acquirer_id\": 1,\n \"acquirer\": {\n \"id\": 1,\n \"code\": \"qashpay\",\n \"name\": \"QashPay\",\n \"bank_name\": \"Example Bank\",\n \"bank_country_code\": \"GB\",\n \"settlement_currency_code\": \"EUR\",\n \"status\": \"active\",\n \"created_at\": \"2025-01-15T09:00:00.000000Z\",\n \"updated_at\": \"2025-01-15T09:00:00.000000Z\"\n },\n \"transactions_count\": 128,\n \"transaction_stats\": {\n \"total_count\": 128,\n \"total_volume\": 645000\n },\n \"partnership\": {\n \"status\": \"active\",\n \"notes\": \"string\",\n \"approved_at\": \"2025-02-01T12:00:00.000000Z\"\n },\n \"created_at\": \"2025-01-20T09:00:00.000000Z\",\n \"updated_at\": \"2025-05-20T09:18:47.000000Z\"\n },\n {\n \"id\": 1,\n \"name\": \"Demo Store Ltd\",\n \"mcc\": \"5734\",\n \"status\": \"active\",\n \"address\": \"1 High Street\",\n \"city\": \"London\",\n \"country_code\": \"GB\",\n \"email\": \"merchant@example.com\",\n \"phone\": \"+441234567890\",\n \"website\": \"https://demo-store.example.com\",\n \"acquirer_id\": 1,\n \"acquirer\": {\n \"id\": 1,\n \"code\": \"qashpay\",\n \"name\": \"QashPay\",\n \"bank_name\": \"Example Bank\",\n \"bank_country_code\": \"GB\",\n \"settlement_currency_code\": \"EUR\",\n \"status\": \"active\",\n \"created_at\": \"2025-01-15T09:00:00.000000Z\",\n \"updated_at\": \"2025-01-15T09:00:00.000000Z\"\n },\n \"transactions_count\": 128,\n \"transaction_stats\": {\n \"total_count\": 128,\n \"total_volume\": 645000\n },\n \"partnership\": {\n \"status\": \"active\",\n \"notes\": \"string\",\n \"approved_at\": \"2025-02-01T12:00:00.000000Z\"\n },\n \"created_at\": \"2025-01-20T09:00:00.000000Z\",\n \"updated_at\": \"2025-05-20T09:18:47.000000Z\"\n }\n ]\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "bdad5091-165f-4f1f-9843-739b1fb3d4bb", "originalRequest": { "url": { "path": [ "api", "v1", "merchants" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"message\": \"Authentication failed\",\n \"code\": \"ERR_AUTH_FAILED\",\n \"data\": \"string\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "435b6ac8-fce5-41c8-9112-ca5b4dd3dd52", "name": "The API key is not a partner key or the partner account is not active. See the [error catalogue](/api-basics/errors).", "originalRequest": { "url": { "path": [ "api", "v1", "merchants" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Forbidden", "code": 403, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"message\": \"Access denied: This endpoint is only accessible to partners.\",\n \"code\": \"ERR_AUTH_FAILED\",\n \"data\": \"string\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "1ae285c3-2a5c-45b2-b5c0-fa9cc0bd5adc", "name": "Rate limit exceeded. See [rate limits](/api-basics/rate-limits).", "originalRequest": { "url": { "path": [ "api", "v1", "merchants" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Too Many Requests", "code": 429, "header": [ { "disabled": false, "description": "Seconds until the current rate limit window frees up.", "key": "Retry-After", "value": "1749" }, { "disabled": false, "description": "Requests left in the current 60 second window. Sent on every response and 0 here.", "key": "X-RateLimit-Remaining", "value": "1749" }, { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"message\": \"Too many requests\",\n \"code\": \"ERR_RATE_LIMITED\",\n \"data\": \"string\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "e3a9ec31-6b17-4b87-bad1-ab96c5831df4", "name": "Get Merchant", "request": { "name": "Get Merchant", "description": { "content": "Get a specific merchant linked to the authenticated partner. Partner API keys only.", "type": "text/plain" }, "url": { "path": [ "api", "v1", "merchants", ":merchant_id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "1", "key": "merchant_id", "description": "(Required) The ID of the merchant." } ] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "auth": null }, "response": [ { "id": "7310eb50-7d79-48ec-9654-663d969b24f0", "originalRequest": { "url": { "path": [ "api", "v1", "merchants", ":merchant_id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "1", "key": "merchant_id", "description": "(Required) The ID of the merchant." } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"message\": \"Merchant retrieved successfully\",\n \"code\": \"\",\n \"data\": {\n \"id\": 1,\n \"name\": \"Demo Store Ltd\",\n \"mcc\": \"5734\",\n \"status\": \"active\",\n \"address\": \"1 High Street\",\n \"city\": \"London\",\n \"country_code\": \"GB\",\n \"email\": \"merchant@example.com\",\n \"phone\": \"+441234567890\",\n \"website\": \"https://demo-store.example.com\",\n \"acquirer_id\": 1,\n \"acquirer\": {\n \"id\": 1,\n \"code\": \"qashpay\",\n \"name\": \"QashPay\",\n \"bank_name\": \"Example Bank\",\n \"bank_country_code\": \"GB\",\n \"settlement_currency_code\": \"EUR\",\n \"status\": \"active\",\n \"created_at\": \"2025-01-15T09:00:00.000000Z\",\n \"updated_at\": \"2025-01-15T09:00:00.000000Z\"\n },\n \"transactions_count\": 128,\n \"transaction_stats\": {\n \"total_count\": 128,\n \"total_volume\": 645000,\n \"successful_count\": 117,\n \"failed_count\": 11\n },\n \"created_at\": \"2025-01-20T09:00:00.000000Z\",\n \"updated_at\": \"2025-05-20T09:18:47.000000Z\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "63be7d5c-5f7d-49f9-a4e1-92a516a6b7fa", "originalRequest": { "url": { "path": [ "api", "v1", "merchants", ":merchant_id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "1", "key": "merchant_id", "description": "(Required) The ID of the merchant." } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"message\": \"Authentication failed\",\n \"code\": \"ERR_AUTH_FAILED\",\n \"data\": \"string\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "d13a9286-1eeb-410b-8736-14c8d7292b00", "name": "The API key is not a partner key or the partner account is not active. See the [error catalogue](/api-basics/errors).", "originalRequest": { "url": { "path": [ "api", "v1", "merchants", ":merchant_id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "1", "key": "merchant_id", "description": "(Required) The ID of the merchant." } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Forbidden", "code": 403, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"message\": \"Access denied: This endpoint is only accessible to partners.\",\n \"code\": \"ERR_AUTH_FAILED\",\n \"data\": \"string\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "09e4e994-f1bc-49a7-a982-a9d211d1c1b1", "name": "The merchant does not exist or is not linked to your partner account. See the [error catalogue](/api-basics/errors).", "originalRequest": { "url": { "path": [ "api", "v1", "merchants", ":merchant_id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "1", "key": "merchant_id", "description": "(Required) The ID of the merchant." } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"message\": \"Merchant not found.\",\n \"code\": \"ERR_NOT_FOUND\",\n \"data\": \"string\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "ed99cf91-ebee-4cae-9a5c-5596a299b20e", "name": "Rate limit exceeded. See [rate limits](/api-basics/rate-limits).", "originalRequest": { "url": { "path": [ "api", "v1", "merchants", ":merchant_id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "1", "key": "merchant_id", "description": "(Required) The ID of the merchant." } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Too Many Requests", "code": 429, "header": [ { "disabled": false, "description": "Seconds until the current rate limit window frees up.", "key": "Retry-After", "value": "1749" }, { "disabled": false, "description": "Requests left in the current 60 second window. Sent on every response and 0 here.", "key": "X-RateLimit-Remaining", "value": "1749" }, { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"message\": \"Too many requests\",\n \"code\": \"ERR_RATE_LIMITED\",\n \"data\": \"string\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "650af280-0969-4fb4-97f7-dadf21196f4a", "name": "Get Merchant Transactions", "request": { "name": "Get Merchant Transactions", "description": { "content": "Get transactions for a merchant linked to the authenticated partner. Partner API keys only.", "type": "text/plain" }, "url": { "path": [ "api", "v1", "merchants", ":merchant_id", "transactions" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "key": "status", "value": "success", "description": "Filter transactions by status." }, { "disabled": false, "key": "from", "value": "2024-01-01", "description": "Filter transactions created on or after this date." }, { "disabled": false, "key": "to", "value": "2024-12-31", "description": "Filter transactions created on or before this date." }, { "disabled": false, "key": "per_page", "value": "25", "description": "Number of transactions per page. Maximum 100." } ], "variable": [ { "disabled": false, "type": "any", "value": "1", "key": "merchant_id", "description": "(Required) The ID of the merchant." } ] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "auth": null }, "response": [ { "id": "44a0065c-fe9c-4581-a92a-74783156e358", "originalRequest": { "url": { "path": [ "api", "v1", "merchants", ":merchant_id", "transactions" ], "host": [ "{{baseUrl}}" ], "query": [ { "key": "status", "value": "success" }, { "key": "from", "value": "2024-01-01" }, { "key": "to", "value": "2024-12-31" }, { "key": "per_page", "value": "25" } ], "variable": [ { "disabled": false, "type": "any", "value": "1", "key": "merchant_id", "description": "(Required) The ID of the merchant." } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"message\": \"Transactions retrieved successfully\",\n \"code\": \"\",\n \"data\": {\n \"transactions\": [\n {\n \"id\": 123456,\n \"merchant_id\": 1,\n \"merchant_trans_id\": \"ORDER-100045\",\n \"amount\": 5000,\n \"amount_formatted\": \"50 EUR\",\n \"currency\": \"EUR\",\n \"status\": \"success\",\n \"transaction_type\": \"sale\",\n \"description\": \"string\",\n \"acquirer_provider\": \"qashpay\",\n \"acquirer_trans_id\": \"514009742001\",\n \"acquirer_auth_code\": \"012345\",\n \"related_trans_id\": \"string\",\n \"refunded_amount\": 0,\n \"customer\": \"string\",\n \"cardholder\": {\n \"card_last_four\": \"1111\",\n \"card_brand\": \"visa\",\n \"card_expiry_month\": 12,\n \"card_expiry_year\": 2030,\n \"created_at\": \"2025-05-20T09:18:47.000000Z\",\n \"updated_at\": \"2025-05-20T09:18:47.000000Z\"\n },\n \"payment_instrument\": {\n \"payment_instrument_id\": \"pi_01k24d5re8xh1v0c9jc0m8w3ns\",\n \"vault_token\": \"8ac7a4a29852f6f101985300a1b41c2f\",\n \"type\": \"card\",\n \"status\": \"active\",\n \"card_brand\": \"visa\",\n \"card_last_four\": \"1111\",\n \"card_expiry_month\": 12,\n \"card_expiry_year\": 2030,\n \"created_at\": \"2025-05-20T09:18:48.000000Z\",\n \"updated_at\": \"2025-05-20T09:18:48.000000Z\"\n },\n \"ip_address\": \"203.0.113.10\",\n \"created_at\": \"2025-05-20T09:18:47.000000Z\",\n \"updated_at\": \"2025-05-20T09:18:48.000000Z\"\n },\n {\n \"id\": 123456,\n \"merchant_id\": 1,\n \"merchant_trans_id\": \"ORDER-100045\",\n \"amount\": 5000,\n \"amount_formatted\": \"50 EUR\",\n \"currency\": \"EUR\",\n \"status\": \"success\",\n \"transaction_type\": \"sale\",\n \"description\": \"string\",\n \"acquirer_provider\": \"qashpay\",\n \"acquirer_trans_id\": \"514009742001\",\n \"acquirer_auth_code\": \"012345\",\n \"related_trans_id\": \"string\",\n \"refunded_amount\": 0,\n \"customer\": \"string\",\n \"cardholder\": {\n \"card_last_four\": \"1111\",\n \"card_brand\": \"visa\",\n \"card_expiry_month\": 12,\n \"card_expiry_year\": 2030,\n \"created_at\": \"2025-05-20T09:18:47.000000Z\",\n \"updated_at\": \"2025-05-20T09:18:47.000000Z\"\n },\n \"payment_instrument\": {\n \"payment_instrument_id\": \"pi_01k24d5re8xh1v0c9jc0m8w3ns\",\n \"vault_token\": \"8ac7a4a29852f6f101985300a1b41c2f\",\n \"type\": \"card\",\n \"status\": \"active\",\n \"card_brand\": \"visa\",\n \"card_last_four\": \"1111\",\n \"card_expiry_month\": 12,\n \"card_expiry_year\": 2030,\n \"created_at\": \"2025-05-20T09:18:48.000000Z\",\n \"updated_at\": \"2025-05-20T09:18:48.000000Z\"\n },\n \"ip_address\": \"203.0.113.10\",\n \"created_at\": \"2025-05-20T09:18:47.000000Z\",\n \"updated_at\": \"2025-05-20T09:18:48.000000Z\"\n }\n ],\n \"pagination\": {\n \"current_page\": 1,\n \"last_page\": 1,\n \"per_page\": 25,\n \"total\": 1\n }\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "d9ef10d3-21e5-4b94-8ec4-5f09eca79928", "originalRequest": { "url": { "path": [ "api", "v1", "merchants", ":merchant_id", "transactions" ], "host": [ "{{baseUrl}}" ], "query": [ { "key": "status", "value": "success" }, { "key": "from", "value": "2024-01-01" }, { "key": "to", "value": "2024-12-31" }, { "key": "per_page", "value": "25" } ], "variable": [ { "disabled": false, "type": "any", "value": "1", "key": "merchant_id", "description": "(Required) The ID of the merchant." } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"message\": \"Authentication failed\",\n \"code\": \"ERR_AUTH_FAILED\",\n \"data\": \"string\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "a1b5ddda-f6ef-426c-b073-9c1de06016d0", "name": "The API key is not a partner key or the partner account is not active. See the [error catalogue](/api-basics/errors).", "originalRequest": { "url": { "path": [ "api", "v1", "merchants", ":merchant_id", "transactions" ], "host": [ "{{baseUrl}}" ], "query": [ { "key": "status", "value": "success" }, { "key": "from", "value": "2024-01-01" }, { "key": "to", "value": "2024-12-31" }, { "key": "per_page", "value": "25" } ], "variable": [ { "disabled": false, "type": "any", "value": "1", "key": "merchant_id", "description": "(Required) The ID of the merchant." } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Forbidden", "code": 403, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"message\": \"Access denied: This endpoint is only accessible to partners.\",\n \"code\": \"ERR_AUTH_FAILED\",\n \"data\": \"string\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "367be07b-622d-4bd3-852a-b149256183ce", "name": "The merchant does not exist or is not linked to your partner account. See the [error catalogue](/api-basics/errors).", "originalRequest": { "url": { "path": [ "api", "v1", "merchants", ":merchant_id", "transactions" ], "host": [ "{{baseUrl}}" ], "query": [ { "key": "status", "value": "success" }, { "key": "from", "value": "2024-01-01" }, { "key": "to", "value": "2024-12-31" }, { "key": "per_page", "value": "25" } ], "variable": [ { "disabled": false, "type": "any", "value": "1", "key": "merchant_id", "description": "(Required) The ID of the merchant." } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"message\": \"Merchant not found.\",\n \"code\": \"ERR_NOT_FOUND\",\n \"data\": \"string\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "7d352bc0-4477-42b0-8b3b-71747b59e437", "name": "Rate limit exceeded. See [rate limits](/api-basics/rate-limits).", "originalRequest": { "url": { "path": [ "api", "v1", "merchants", ":merchant_id", "transactions" ], "host": [ "{{baseUrl}}" ], "query": [ { "key": "status", "value": "success" }, { "key": "from", "value": "2024-01-01" }, { "key": "to", "value": "2024-12-31" }, { "key": "per_page", "value": "25" } ], "variable": [ { "disabled": false, "type": "any", "value": "1", "key": "merchant_id", "description": "(Required) The ID of the merchant." } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Too Many Requests", "code": 429, "header": [ { "disabled": false, "description": "Seconds until the current rate limit window frees up.", "key": "Retry-After", "value": "1749" }, { "disabled": false, "description": "Requests left in the current 60 second window. Sent on every response and 0 here.", "key": "X-RateLimit-Remaining", "value": "1749" }, { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"message\": \"Too many requests\",\n \"code\": \"ERR_RATE_LIMITED\",\n \"data\": \"string\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } } ], "event": [] }, { "id": "7a40d969-cb32-4025-a022-e285356903ab", "name": "Payment Sessions", "description": { "content": "", "type": "text/plain" }, "item": [ { "id": "b5fbbb9b-662b-42a2-adda-43ae5f26ed69", "name": "Create a payment session", "request": { "name": "Create a payment session", "description": { "content": "Create a redirect payment session and return the provider `checkout_url` to send\nthe customer to. The session expires 15 minutes after creation if the customer\ndoes not complete the hosted payment page.\n\nMerchant API keys act on their own account. Partner API keys must include\n`merchant_id` for a linked merchant.\n\nSessions never accept card data. Requests carrying card, token, CVV or voucher\nfields are rejected with HTTP 422. Duplicate requests reusing an active\n`reference` are rejected with HTTP 409. See the [duplicate protection guide](/guides/duplicate-protection).\n\nFollow the [alternative payment guide](/guides/accept-an-alternative-payment) for the full flow.", "type": "text/plain" }, "url": { "path": [ "api", "v1", "payment-sessions" ], "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 \"amount\": 25,\n \"currency\": \"EUR\",\n \"reference\": \"DEP-2048\",\n \"payment_method\": \"psc\",\n \"customer\": {\n \"first_name\": \"Jane\",\n \"last_name\": \"Doe\",\n \"country_code\": \"GB\",\n \"merchant_customer_id\": \"player-981\"\n },\n \"success_url\": \"https://merchant.example.com/deposit/complete\",\n \"cancel_url\": \"https://merchant.example.com/deposit/cancelled\",\n \"customer_reference\": \"player-981\",\n \"metadata\": {\n \"campaign\": \"welcome\"\n },\n \"merchant_id\": 123\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "id": "64f74dfe-2e20-4df7-9175-2b681b260eb8", "originalRequest": { "url": { "path": [ "api", "v1", "payment-sessions" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"amount\": 25,\n \"currency\": \"EUR\",\n \"reference\": \"DEP-2048\",\n \"payment_method\": \"psc\",\n \"customer\": {\n \"first_name\": \"Jane\",\n \"last_name\": \"Doe\",\n \"country_code\": \"GB\",\n \"merchant_customer_id\": \"player-981\"\n },\n \"success_url\": \"https://merchant.example.com/deposit/complete\",\n \"cancel_url\": \"https://merchant.example.com/deposit/cancelled\",\n \"customer_reference\": \"player-981\",\n \"metadata\": {\n \"campaign\": \"welcome\"\n },\n \"merchant_id\": 123\n}", "options": { "raw": { "language": "json" } } } }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"message\": \"Payment session created\",\n \"code\": \"\",\n \"data\": {\n \"payment_session\": {\n \"payment_session_id\": \"ps_01J8FYK3ZQ4T9RB2M6XD5A7CWE\",\n \"transaction_id\": 4512,\n \"merchant_id\": 123,\n \"merchant_reference\": \"DEP-2048\",\n \"provider\": \"skrill\",\n \"payment_method\": \"psc\",\n \"status\": \"pending_redirect\",\n \"amount\": 2500,\n \"amount_formatted\": \"25.00\",\n \"currency\": \"EUR\",\n \"checkout_url\": \"https://pay.skrill.com/app/?sid=a1b2c3d4e5\",\n \"return_url\": \"https://merchant.example.com/deposit/complete\",\n \"cancel_url\": \"https://merchant.example.com/deposit/cancelled\",\n \"provider_session_id\": \"a1b2c3d4e5\",\n \"provider_transaction_id\": \"string\",\n \"customer_reference\": \"player-981\",\n \"expires_at\": \"2026-08-08T10:30:00.000000Z\",\n \"finalised_at\": \"string\",\n \"created_at\": \"2026-08-08T10:15:00.000000Z\",\n \"updated_at\": \"2026-08-08T10:15:00.000000Z\"\n }\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "d9c678ce-3a54-4f35-b8f5-de508105b048", "name": "Session rejected. The `code` field identifies the reason, for example ERR_PAYMENT_METHOD_NOT_ENABLED when the method, currency or country is not enabled for the merchant. See the [error catalogue](/api-basics/errors).", "originalRequest": { "url": { "path": [ "api", "v1", "payment-sessions" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"amount\": 25,\n \"currency\": \"EUR\",\n \"reference\": \"DEP-2048\",\n \"payment_method\": \"psc\",\n \"customer\": {\n \"first_name\": \"Jane\",\n \"last_name\": \"Doe\",\n \"country_code\": \"GB\",\n \"merchant_customer_id\": \"player-981\"\n },\n \"success_url\": \"https://merchant.example.com/deposit/complete\",\n \"cancel_url\": \"https://merchant.example.com/deposit/cancelled\",\n \"customer_reference\": \"player-981\",\n \"metadata\": {\n \"campaign\": \"welcome\"\n },\n \"merchant_id\": 123\n}", "options": { "raw": { "language": "json" } } } }, "status": "Bad Request", "code": 400, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"message\": \"This payment method is not enabled for the merchant.\",\n \"code\": \"ERR_PAYMENT_METHOD_NOT_ENABLED\",\n \"data\": \"string\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "08f35d1c-7dd5-45de-b80a-5b409fabbe8d", "originalRequest": { "url": { "path": [ "api", "v1", "payment-sessions" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"amount\": 25,\n \"currency\": \"EUR\",\n \"reference\": \"DEP-2048\",\n \"payment_method\": \"psc\",\n \"customer\": {\n \"first_name\": \"Jane\",\n \"last_name\": \"Doe\",\n \"country_code\": \"GB\",\n \"merchant_customer_id\": \"player-981\"\n },\n \"success_url\": \"https://merchant.example.com/deposit/complete\",\n \"cancel_url\": \"https://merchant.example.com/deposit/cancelled\",\n \"customer_reference\": \"player-981\",\n \"metadata\": {\n \"campaign\": \"welcome\"\n },\n \"merchant_id\": 123\n}", "options": { "raw": { "language": "json" } } } }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"message\": \"Authentication failed\",\n \"code\": \"ERR_AUTH_FAILED\",\n \"data\": \"string\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "7ccb8369-241b-4ad8-8085-c48a35f223e6", "name": "A session or transaction with this `reference` already exists. See the [duplicate protection guide](/guides/duplicate-protection).", "originalRequest": { "url": { "path": [ "api", "v1", "payment-sessions" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"amount\": 25,\n \"currency\": \"EUR\",\n \"reference\": \"DEP-2048\",\n \"payment_method\": \"psc\",\n \"customer\": {\n \"first_name\": \"Jane\",\n \"last_name\": \"Doe\",\n \"country_code\": \"GB\",\n \"merchant_customer_id\": \"player-981\"\n },\n \"success_url\": \"https://merchant.example.com/deposit/complete\",\n \"cancel_url\": \"https://merchant.example.com/deposit/cancelled\",\n \"customer_reference\": \"player-981\",\n \"metadata\": {\n \"campaign\": \"welcome\"\n },\n \"merchant_id\": 123\n}", "options": { "raw": { "language": "json" } } } }, "status": "Conflict", "code": 409, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"message\": \"A payment session with this reference already exists.\",\n \"code\": \"ERR_DUPLICATE\",\n \"data\": \"string\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "3d2c1855-867a-4519-833d-84e27a85b5e0", "name": "Validation failed. This includes any request carrying card, token, CVV or voucher data.", "originalRequest": { "url": { "path": [ "api", "v1", "payment-sessions" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"amount\": 25,\n \"currency\": \"EUR\",\n \"reference\": \"DEP-2048\",\n \"payment_method\": \"psc\",\n \"customer\": {\n \"first_name\": \"Jane\",\n \"last_name\": \"Doe\",\n \"country_code\": \"GB\",\n \"merchant_customer_id\": \"player-981\"\n },\n \"success_url\": \"https://merchant.example.com/deposit/complete\",\n \"cancel_url\": \"https://merchant.example.com/deposit/cancelled\",\n \"customer_reference\": \"player-981\",\n \"metadata\": {\n \"campaign\": \"welcome\"\n },\n \"merchant_id\": 123\n}", "options": { "raw": { "language": "json" } } } }, "status": "Unprocessable Entity (WebDAV) (RFC 4918)", "code": 422, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"message\": \"Validation errors\",\n \"code\": \"ERR_VALIDATION_FAILED\",\n \"data\": \"string\",\n \"errors\": {\n \"card\": [\n \"Card, token, CVV and voucher data are not accepted on redirect payment sessions.\"\n ]\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "e12d19b6-c2ea-41c5-a9b0-6a287d5b6abc", "name": "Rate limit exceeded. See [rate limits](/api-basics/rate-limits).", "originalRequest": { "url": { "path": [ "api", "v1", "payment-sessions" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"amount\": 25,\n \"currency\": \"EUR\",\n \"reference\": \"DEP-2048\",\n \"payment_method\": \"psc\",\n \"customer\": {\n \"first_name\": \"Jane\",\n \"last_name\": \"Doe\",\n \"country_code\": \"GB\",\n \"merchant_customer_id\": \"player-981\"\n },\n \"success_url\": \"https://merchant.example.com/deposit/complete\",\n \"cancel_url\": \"https://merchant.example.com/deposit/cancelled\",\n \"customer_reference\": \"player-981\",\n \"metadata\": {\n \"campaign\": \"welcome\"\n },\n \"merchant_id\": 123\n}", "options": { "raw": { "language": "json" } } } }, "status": "Too Many Requests", "code": 429, "header": [ { "disabled": false, "description": "Seconds until the current rate limit window frees up.", "key": "Retry-After", "value": "1749" }, { "disabled": false, "description": "Requests left in the current 60 second window. Sent on every response and 0 here.", "key": "X-RateLimit-Remaining", "value": "1749" }, { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"message\": \"Too many requests\",\n \"code\": \"ERR_RATE_LIMITED\",\n \"data\": \"string\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "dea2fe4c-d881-459a-8f62-fd0ef7869c4d", "name": "The provider could not prepare the hosted session. The session and its transaction are marked failed. Create a new session to retry.", "originalRequest": { "url": { "path": [ "api", "v1", "payment-sessions" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"amount\": 25,\n \"currency\": \"EUR\",\n \"reference\": \"DEP-2048\",\n \"payment_method\": \"psc\",\n \"customer\": {\n \"first_name\": \"Jane\",\n \"last_name\": \"Doe\",\n \"country_code\": \"GB\",\n \"merchant_customer_id\": \"player-981\"\n },\n \"success_url\": \"https://merchant.example.com/deposit/complete\",\n \"cancel_url\": \"https://merchant.example.com/deposit/cancelled\",\n \"customer_reference\": \"player-981\",\n \"metadata\": {\n \"campaign\": \"welcome\"\n },\n \"merchant_id\": 123\n}", "options": { "raw": { "language": "json" } } } }, "status": "Bad Gateway", "code": 502, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"message\": \"Failed to create the payment session with the provider.\",\n \"code\": \"ERR_GATEWAY_ERROR\",\n \"data\": \"string\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "9b65b9e9-b4e9-472a-a822-9af0ea36b651", "name": "Get a payment session", "request": { "name": "Get a payment session", "description": { "content": "Retrieve the current state of a payment session. Poll this endpoint after the\ncustomer returns to your success URL or rely on [webhooks](/guides/webhooks)\nfor the final outcome. A session is only complete when its status is `paid`.\n\nMerchant API keys can read their own sessions. Partner API keys can read\nsessions belonging to linked merchants.", "type": "text/plain" }, "url": { "path": [ "api", "v1", "payment-sessions", ":paymentSession_public_id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "ps_01J8FYK3ZQ4T9RB2M6XD5A7CWE", "key": "paymentSession_public_id", "description": "(Required) The payment session id." } ] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "auth": null }, "response": [ { "id": "d69473f7-cd8e-442c-904b-1357d6c652c0", "originalRequest": { "url": { "path": [ "api", "v1", "payment-sessions", ":paymentSession_public_id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "ps_01J8FYK3ZQ4T9RB2M6XD5A7CWE", "key": "paymentSession_public_id", "description": "(Required) The payment session id." } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"message\": \"Payment session retrieved\",\n \"code\": \"\",\n \"data\": {\n \"payment_session\": {\n \"payment_session_id\": \"ps_01J8FYK3ZQ4T9RB2M6XD5A7CWE\",\n \"transaction_id\": 4512,\n \"merchant_id\": 123,\n \"merchant_reference\": \"DEP-2048\",\n \"provider\": \"skrill\",\n \"payment_method\": \"psc\",\n \"status\": \"paid\",\n \"amount\": 2500,\n \"amount_formatted\": \"25.00\",\n \"currency\": \"EUR\",\n \"checkout_url\": \"https://pay.skrill.com/app/?sid=a1b2c3d4e5\",\n \"return_url\": \"https://merchant.example.com/deposit/complete\",\n \"cancel_url\": \"https://merchant.example.com/deposit/cancelled\",\n \"provider_session_id\": \"a1b2c3d4e5\",\n \"provider_transaction_id\": \"2649912345\",\n \"customer_reference\": \"player-981\",\n \"expires_at\": \"2026-08-08T10:30:00.000000Z\",\n \"finalised_at\": \"2026-08-08T10:18:42.000000Z\",\n \"created_at\": \"2026-08-08T10:15:00.000000Z\",\n \"updated_at\": \"2026-08-08T10:18:42.000000Z\"\n }\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "38816428-96a8-4d1f-be0a-46630945d1e4", "originalRequest": { "url": { "path": [ "api", "v1", "payment-sessions", ":paymentSession_public_id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "ps_01J8FYK3ZQ4T9RB2M6XD5A7CWE", "key": "paymentSession_public_id", "description": "(Required) The payment session id." } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"message\": \"Authentication failed\",\n \"code\": \"ERR_AUTH_FAILED\",\n \"data\": \"string\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "f221fd27-49d9-4d56-b4b8-5dadb05f2f45", "name": "The session belongs to a merchant this API key cannot access.", "originalRequest": { "url": { "path": [ "api", "v1", "payment-sessions", ":paymentSession_public_id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "ps_01J8FYK3ZQ4T9RB2M6XD5A7CWE", "key": "paymentSession_public_id", "description": "(Required) The payment session id." } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Forbidden", "code": 403, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"message\": \"Access denied: Resource not accessible\",\n \"code\": \"ERR_AUTH_FAILED\",\n \"data\": \"string\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "c5221f8f-972b-4a75-aa69-c92c4eca758f", "name": "No payment session with this id exists. See the [error catalogue](/api-basics/errors).", "originalRequest": { "url": { "path": [ "api", "v1", "payment-sessions", ":paymentSession_public_id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "ps_01J8FYK3ZQ4T9RB2M6XD5A7CWE", "key": "paymentSession_public_id", "description": "(Required) The payment session id." } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"message\": \"PaymentSession not found\",\n \"code\": \"ERR_NOT_FOUND\",\n \"data\": \"string\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "e1d3c164-2a08-41b2-b6a8-2ec07451d371", "name": "Rate limit exceeded. See [rate limits](/api-basics/rate-limits).", "originalRequest": { "url": { "path": [ "api", "v1", "payment-sessions", ":paymentSession_public_id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "ps_01J8FYK3ZQ4T9RB2M6XD5A7CWE", "key": "paymentSession_public_id", "description": "(Required) The payment session id." } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Too Many Requests", "code": 429, "header": [ { "disabled": false, "description": "Seconds until the current rate limit window frees up.", "key": "Retry-After", "value": "1749" }, { "disabled": false, "description": "Requests left in the current 60 second window. Sent on every response and 0 here.", "key": "X-RateLimit-Remaining", "value": "1749" }, { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"message\": \"Too many requests\",\n \"code\": \"ERR_RATE_LIMITED\",\n \"data\": \"string\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } } ], "event": [] }, { "id": "224759a3-7b65-4c3a-ae6e-3cbb68303e0c", "name": "Payment Instruments", "description": { "content": "", "type": "text/plain" }, "item": [ { "id": "72463630-7f2d-4ae5-9c0b-57f3f5215289", "name": "List payment instruments", "request": { "name": "List payment instruments", "description": { "content": "List the cards stored in the vault for a merchant. An instrument is\ncreated automatically when a card transaction succeeds and the acquirer\nreturns a vault token. Use the `vault_token` value to charge the stored\ncard again, as described in the [returning customers guide](/guides/returning-customers).\n\nMerchant API keys list their own instruments. Partner API keys must\ninclude `merchant_id` for a linked merchant.", "type": "text/plain" }, "url": { "path": [ "api", "v1", "payment-instruments" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "key": "status", "value": "active", "description": "Filter by status." }, { "disabled": false, "key": "merchant_id", "value": "123", "description": "Required for partner API keys. Must be a merchant linked to the authenticated partner." }, { "disabled": false, "key": "per_page", "value": "25", "description": "Number of instruments per page (1-100, default 25)." }, { "disabled": false, "key": "page", "value": "1", "description": "Page number (1+)." } ], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "auth": null }, "response": [ { "id": "dc2e0e56-cc3d-4dff-acb8-941c3e2b4d95", "originalRequest": { "url": { "path": [ "api", "v1", "payment-instruments" ], "host": [ "{{baseUrl}}" ], "query": [ { "key": "status", "value": "active" }, { "key": "merchant_id", "value": "123" }, { "key": "per_page", "value": "25" }, { "key": "page", "value": "1" } ], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"message\": \"Payment instruments retrieved\",\n \"code\": \"\",\n \"data\": {\n \"payment_instruments\": [\n {\n \"payment_instrument_id\": \"pi_01k24d5re8xh1v0c9jc0m8w3ns\",\n \"vault_token\": \"8ac7a4a29852f6f101985300a1b41c2f\",\n \"type\": \"card\",\n \"status\": \"active\",\n \"card_brand\": \"visa\",\n \"card_last_four\": \"1111\",\n \"card_expiry_month\": 12,\n \"card_expiry_year\": 2030,\n \"created_at\": \"2026-08-01T09:18:47.000000Z\",\n \"updated_at\": \"2026-08-01T09:18:47.000000Z\"\n },\n {\n \"payment_instrument_id\": \"pi_01k1zx9v2m5re8ah3t6wd0q7bc\",\n \"vault_token\": \"5fb2c8d10474e2a90198a3f2b17d33aa\",\n \"type\": \"card\",\n \"status\": \"revoked\",\n \"card_brand\": \"mastercard\",\n \"card_last_four\": \"4444\",\n \"card_expiry_month\": 6,\n \"card_expiry_year\": 2028,\n \"created_at\": \"2026-07-14T15:02:10.000000Z\",\n \"updated_at\": \"2026-07-30T11:41:05.000000Z\"\n }\n ],\n \"pagination\": {\n \"current_page\": 1,\n \"last_page\": 1,\n \"per_page\": 25,\n \"total\": 2\n }\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "0b6d6288-eba3-4f0e-a1d6-a706273c00a1", "name": "A partner API key omitted `merchant_id` or referenced a merchant that is not linked to it.", "originalRequest": { "url": { "path": [ "api", "v1", "payment-instruments" ], "host": [ "{{baseUrl}}" ], "query": [ { "key": "status", "value": "active" }, { "key": "merchant_id", "value": "123" }, { "key": "per_page", "value": "25" }, { "key": "page", "value": "1" } ], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Bad Request", "code": 400, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"message\": \"merchant_id is required for partner transactions. Please specify which merchant account to use.\",\n \"code\": \"ERR_AUTH_FAILED\",\n \"data\": \"string\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "abd4ae8e-0139-4da5-a65c-b73c9b26da21", "originalRequest": { "url": { "path": [ "api", "v1", "payment-instruments" ], "host": [ "{{baseUrl}}" ], "query": [ { "key": "status", "value": "active" }, { "key": "merchant_id", "value": "123" }, { "key": "per_page", "value": "25" }, { "key": "page", "value": "1" } ], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"message\": \"Authentication failed\",\n \"code\": \"ERR_AUTH_FAILED\",\n \"data\": \"string\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "c5e6cce5-c618-4372-8fd5-7605c3c19d25", "name": "Rate limit exceeded. See [rate limits](/api-basics/rate-limits).", "originalRequest": { "url": { "path": [ "api", "v1", "payment-instruments" ], "host": [ "{{baseUrl}}" ], "query": [ { "key": "status", "value": "active" }, { "key": "merchant_id", "value": "123" }, { "key": "per_page", "value": "25" }, { "key": "page", "value": "1" } ], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Too Many Requests", "code": 429, "header": [ { "disabled": false, "description": "Seconds until the current rate limit window frees up.", "key": "Retry-After", "value": "1749" }, { "disabled": false, "description": "Requests left in the current 60 second window. Sent on every response and 0 here.", "key": "X-RateLimit-Remaining", "value": "1749" }, { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"message\": \"Too many requests\",\n \"code\": \"ERR_RATE_LIMITED\",\n \"data\": \"string\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "0358ee38-a1eb-4811-bf36-5e5c0ba141e6", "name": "Revoke a payment instrument", "request": { "name": "Revoke a payment instrument", "description": { "content": "Revoke a stored card so its vault token can no longer initiate\ntransactions. Revocation is idempotent: revoking an already revoked\ninstrument succeeds without changing anything. If the same card is\nstored again later, the instrument reactivates with the same token.\n\nMerchant API keys revoke their own instruments. Partner API keys can\nrevoke instruments of linked merchants.", "type": "text/plain" }, "url": { "path": [ "api", "v1", "payment-instruments", ":paymentInstrument_public_id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "pi_01k24d5re8xh1v0c9jc0m8w3ns", "key": "paymentInstrument_public_id", "description": "(Required) The payment instrument id." } ] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "DELETE", "auth": null }, "response": [ { "id": "9738d8dc-35a5-488e-ad4c-925ae6cce3b3", "originalRequest": { "url": { "path": [ "api", "v1", "payment-instruments", ":paymentInstrument_public_id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "pi_01k24d5re8xh1v0c9jc0m8w3ns", "key": "paymentInstrument_public_id", "description": "(Required) The payment instrument id." } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "key": "Accept", "value": "application/json" } ], "method": "DELETE", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"message\": \"Payment instrument revoked\",\n \"code\": \"\",\n \"data\": {\n \"payment_instrument\": {\n \"payment_instrument_id\": \"pi_01k24d5re8xh1v0c9jc0m8w3ns\",\n \"vault_token\": \"8ac7a4a29852f6f101985300a1b41c2f\",\n \"type\": \"card\",\n \"status\": \"revoked\",\n \"card_brand\": \"visa\",\n \"card_last_four\": \"1111\",\n \"card_expiry_month\": 12,\n \"card_expiry_year\": 2030,\n \"created_at\": \"2026-08-01T09:18:47.000000Z\",\n \"updated_at\": \"2026-08-08T10:22:31.000000Z\"\n }\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "e20e28e2-cc34-4e5b-ae42-6b006de9888c", "originalRequest": { "url": { "path": [ "api", "v1", "payment-instruments", ":paymentInstrument_public_id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "pi_01k24d5re8xh1v0c9jc0m8w3ns", "key": "paymentInstrument_public_id", "description": "(Required) The payment instrument id." } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "key": "Accept", "value": "application/json" } ], "method": "DELETE", "body": {} }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"message\": \"Authentication failed\",\n \"code\": \"ERR_AUTH_FAILED\",\n \"data\": \"string\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "0c4e4324-ae8b-4bf5-96ae-0a39a9c8c391", "name": "The instrument belongs to a merchant this API key cannot access.", "originalRequest": { "url": { "path": [ "api", "v1", "payment-instruments", ":paymentInstrument_public_id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "pi_01k24d5re8xh1v0c9jc0m8w3ns", "key": "paymentInstrument_public_id", "description": "(Required) The payment instrument id." } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "key": "Accept", "value": "application/json" } ], "method": "DELETE", "body": {} }, "status": "Forbidden", "code": 403, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"message\": \"Access denied: Resource not accessible\",\n \"code\": \"ERR_AUTH_FAILED\",\n \"data\": \"string\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "186dbaf8-fabe-43c0-8e0b-a106218ff9be", "name": "No payment instrument with this id exists. See the [error catalogue](/api-basics/errors).", "originalRequest": { "url": { "path": [ "api", "v1", "payment-instruments", ":paymentInstrument_public_id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "pi_01k24d5re8xh1v0c9jc0m8w3ns", "key": "paymentInstrument_public_id", "description": "(Required) The payment instrument id." } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "key": "Accept", "value": "application/json" } ], "method": "DELETE", "body": {} }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"message\": \"PaymentInstrument not found\",\n \"code\": \"ERR_NOT_FOUND\",\n \"data\": \"string\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "14c187ad-af09-4d27-9b40-5f60f75ec063", "name": "Rate limit exceeded. See [rate limits](/api-basics/rate-limits).", "originalRequest": { "url": { "path": [ "api", "v1", "payment-instruments", ":paymentInstrument_public_id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "pi_01k24d5re8xh1v0c9jc0m8w3ns", "key": "paymentInstrument_public_id", "description": "(Required) The payment instrument id." } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "key": "Accept", "value": "application/json" } ], "method": "DELETE", "body": {} }, "status": "Too Many Requests", "code": 429, "header": [ { "disabled": false, "description": "Seconds until the current rate limit window frees up.", "key": "Retry-After", "value": "1749" }, { "disabled": false, "description": "Requests left in the current 60 second window. Sent on every response and 0 here.", "key": "X-RateLimit-Remaining", "value": "1749" }, { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"message\": \"Too many requests\",\n \"code\": \"ERR_RATE_LIMITED\",\n \"data\": \"string\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } } ], "event": [] }, { "id": "9e16bcf3-a024-4f36-9939-6a33def118bc", "name": "API Operations", "description": { "content": "", "type": "text/plain" }, "item": [ { "id": "1127de3b-2cdc-4738-9874-101e149bd4c6", "name": "Get API Key Information", "request": { "name": "Get API Key Information", "description": { "content": "Returns information about the API key being used to authenticate the request.\nAPI keys are provisioned by SoftLemon admins for merchants and partners.\nSelf-service onboarding and API key generation are not currently available.", "type": "text/plain" }, "url": { "path": [ "api", "v1", "key-info" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "auth": null }, "response": [ { "id": "75bb9fd3-137a-4573-8854-98b695666ea2", "originalRequest": { "url": { "path": [ "api", "v1", "key-info" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"message\": \"API key information retrieved successfully\",\n \"code\": \"\",\n \"data\": {\n \"key_identifier\": \"sl_20250411105714_TTwbAVtw\",\n \"name\": \"Partner production key\",\n \"status\": \"active\",\n \"entity_type\": \"partner\",\n \"entity_id\": 7,\n \"entity_name\": \"Acme Payments Partner\",\n \"created_at\": \"2025-04-11T10:57:14.000000Z\",\n \"last_used_at\": \"2025-05-20T09:18:47.000000Z\",\n \"expires_at\": \"string\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "bc6ce6f8-5279-46c2-987d-3c446ca50410", "originalRequest": { "url": { "path": [ "api", "v1", "key-info" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"message\": \"Authentication failed\",\n \"code\": \"ERR_AUTH_FAILED\",\n \"data\": \"string\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "ff9d9ea6-cd42-4476-bef3-4d3baa04e6d0", "name": "Rate limit exceeded. See [rate limits](/api-basics/rate-limits).", "originalRequest": { "url": { "path": [ "api", "v1", "key-info" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Too Many Requests", "code": 429, "header": [ { "disabled": false, "description": "Seconds until the current rate limit window frees up.", "key": "Retry-After", "value": "1749" }, { "disabled": false, "description": "Requests left in the current 60 second window. Sent on every response and 0 here.", "key": "X-RateLimit-Remaining", "value": "1749" }, { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"message\": \"Too many requests\",\n \"code\": \"ERR_RATE_LIMITED\",\n \"data\": \"string\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } } ], "event": [] } ], "event": [], "variable": [ { "type": "string", "value": "https://api.sandbox.softlemons.com", "key": "baseUrl" } ], "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{bearerToken}}" } ] }, "info": { "_postman_id": "a7933d78-fd82-4e84-99b6-ef0deedb3b88", "name": "Softlemon Partner API", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json", "description": { "content": "Production-ready partner integration endpoints for admin-provisioned API keys.\n\n**Base URL:** `https://api.sandbox.softlemons.com/`\n\nThis documentation covers the partner integration surface for admin-provisioned API keys.\n\nUse these endpoints when a partner is managing linked merchants and accessing partner-facing operational resources.\n\nAPI keys are created by your SoftLemon admin team and delivered securely. Self-service onboarding and API key generation are not currently available.\n\nThe gateway also sends signed outbound webhooks on transaction state changes. See the Webhooks section below and the [webhook integration guide](/guides/webhooks) for signature verification examples and retry semantics.\n\n## Authenticating requests\n\nTo authenticate requests, include an **`Authorization`** header with the value **`Bearer {YOUR_API_KEY}`**. Use the API key provisioned by your SoftLemon admin team.\n\n## Integration guides\n\nThe [partner integration guide](/guides/partner-integration) walks through the full flow step by step: confirming your key's scope, listing linked merchants, reviewing their transactions and processing payments on a merchant's behalf with `merchant_id`. The same `merchant_id` rules apply to [alternative payments](/guides/accept-an-alternative-payment) through payment sessions and to the stored cards covered in the [returning customers guide](/guides/returning-customers). The [webhook integration guide](/guides/webhooks) covers event delivery and signature verification.\n\nPrefer exploring in Postman? Download the [Partner API Postman collection](/collections/softlemon-partner-api.postman_collection.json) and set your API key as the Bearer token on the collection.", "type": "text/plain" } } }