{ "info": { "_postman_id": "b30dbad5-be47-5d29-ba9d-49bfdc91090b", "name": "Snap Pay Merchant API v1", "description": "Payouts to mobile money, rates, number checks and transaction status.\n\n1. Import this collection and the Sandbox environment.\n2. Pick **Snap Pay Sandbox** in the environment menu.\n3. Paste your `sk_test_` key into the `apiKey` variable.\n\nFull docs: https://snapcashpay.com/developers", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json" }, "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{apiKey}}", "type": "string" } ] }, "variable": [ { "key": "baseUrl", "value": "https://uat.snapcashpay.com/api/v1" }, { "key": "apiKey", "value": "sk_test_replace_with_your_key" }, { "key": "payoutReference", "value": "SNP-REPLACE" }, { "key": "paymentReference", "value": "SNP-REPLACE" } ], "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "// Remember the last payout / transaction reference so the next requests work straight away.", "try { const j = pm.response.json();", " if (j && j.object === 'payout' && j.reference) { pm.collectionVariables.set('payoutReference', j.reference); }", " if (j && Array.isArray(j.data) && j.data[0] && j.data[0].reference && !j.data[0].object) { pm.collectionVariables.set('paymentReference', j.data[0].reference); }", "} catch (e) {}" ] } } ], "item": [ { "name": "Account", "item": [ { "name": "Balance", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/balance", "host": [ "{{baseUrl}}" ], "path": [ "balance" ] }, "description": "Your business balance in your main currency." }, "response": [ { "name": "200 example", "originalRequest": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/balance", "host": [ "{{baseUrl}}" ], "path": [ "balance" ] }, "description": "Your business balance in your main currency." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"currency\": \"KES\",\n \"balance_minor\": 1250000,\n \"balance\": \"12500.00\"\n}" }, { "name": "401 bad key", "originalRequest": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/balance", "host": [ "{{baseUrl}}" ], "path": [ "balance" ] }, "description": "Your business balance in your main currency." }, "status": "Unauthorized", "code": 401, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": \"unauthenticated\",\n \"message\": \"Invalid, replaced or inactive API key.\"\n}" } ] }, { "name": "Rates (quote)", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/rates?from=KES&to=UGX&amount=1000", "host": [ "{{baseUrl}}" ], "path": [ "rates" ], "query": [ { "key": "from", "value": "KES", "description": "KES or UGX" }, { "key": "to", "value": "UGX", "description": "Recipient currency" }, { "key": "amount", "value": "1000", "description": "Optional" } ] }, "description": "Indicative rate a payout would use now. Not a lock." }, "response": [ { "name": "200 example", "originalRequest": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/rates?from=KES&to=UGX&amount=1000", "host": [ "{{baseUrl}}" ], "path": [ "rates" ], "query": [ { "key": "from", "value": "KES", "description": "KES or UGX" }, { "key": "to", "value": "UGX", "description": "Recipient currency" }, { "key": "amount", "value": "1000", "description": "Optional" } ] }, "description": "Indicative rate a payout would use now. Not a lock." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"from\": \"KES\",\n \"to\": \"UGX\",\n \"rate\": 27.85,\n \"indicative\": true,\n \"note\": \"The rate is applied when the payout is made and is not locked by this quote.\",\n \"quoted_at\": \"2026-10-29T10:15:02+03:00\",\n \"amount\": \"1000.00\",\n \"converted_amount\": \"27850.00\"\n}" } ] } ] }, { "name": "Payouts", "item": [ { "name": "Check a number", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/accounts/lookup", "host": [ "{{baseUrl}}" ], "path": [ "accounts", "lookup" ] }, "description": "Registered name for MTN/Airtel Uganda; format check for Kenya. Needs API payouts enabled.", "body": { "mode": "raw", "raw": "{\n \"phone\": \"256772123456\",\n \"country\": \"UG\",\n \"network\": \"mtn\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "200 example", "originalRequest": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/accounts/lookup", "host": [ "{{baseUrl}}" ], "path": [ "accounts", "lookup" ] }, "description": "Registered name for MTN/Airtel Uganda; format check for Kenya. Needs API payouts enabled.", "body": { "mode": "raw", "raw": "{\n \"phone\": \"256772123456\",\n \"country\": \"UG\",\n \"network\": \"mtn\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"valid\": true,\n \"name\": \"JANE NAKATO\",\n \"name_available\": true,\n \"phone\": \"256772123456\",\n \"country\": \"UG\"\n}" }, { "name": "403 not enabled", "originalRequest": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/accounts/lookup", "host": [ "{{baseUrl}}" ], "path": [ "accounts", "lookup" ] }, "description": "Registered name for MTN/Airtel Uganda; format check for Kenya. Needs API payouts enabled.", "body": { "mode": "raw", "raw": "{\n \"phone\": \"256772123456\",\n \"country\": \"UG\",\n \"network\": \"mtn\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Forbidden", "code": 403, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": \"payouts_not_enabled\",\n \"message\": \"Payouts through the API are not enabled for your account. Contact Snap Pay to enable them.\"\n}" } ] }, { "name": "Create payout", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Idempotency-Key", "value": "{{$guid}}", "description": "Unique per payout. Reuse the SAME value to retry a payout safely." } ], "url": { "raw": "{{baseUrl}}/payouts", "host": [ "{{baseUrl}}" ], "path": [ "payouts" ] }, "description": "Pay a mobile money number from your balance. Requires Idempotency-Key (Postman generates one per Send).", "body": { "mode": "raw", "raw": "{\n \"amount\": 1500,\n \"currency\": \"KES\",\n \"recipient_phone\": \"254712345678\",\n \"recipient_name\": \"John Kamau\",\n \"recipient_country\": \"KE\",\n \"network\": \"mpesa\",\n \"narration\": \"October commission\",\n \"client_reference\": \"INV-10293\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "202 example", "originalRequest": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Idempotency-Key", "value": "{{$guid}}", "description": "Unique per payout. Reuse the SAME value to retry a payout safely." } ], "url": { "raw": "{{baseUrl}}/payouts", "host": [ "{{baseUrl}}" ], "path": [ "payouts" ] }, "description": "Pay a mobile money number from your balance. Requires Idempotency-Key (Postman generates one per Send).", "body": { "mode": "raw", "raw": "{\n \"amount\": 1500,\n \"currency\": \"KES\",\n \"recipient_phone\": \"254712345678\",\n \"recipient_name\": \"John Kamau\",\n \"recipient_country\": \"KE\",\n \"network\": \"mpesa\",\n \"narration\": \"October commission\",\n \"client_reference\": \"INV-10293\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Accepted", "code": 202, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"object\": \"payout\",\n \"reference\": \"SNP-7K2M9QXA\",\n \"client_reference\": \"INV-10293\",\n \"status\": \"processing\",\n \"amount\": \"1500.00\",\n \"currency\": \"KES\",\n \"destination_amount\": \"1500.00\",\n \"destination_currency\": \"KES\",\n \"fx_rate\": 1,\n \"fee\": \"0.00\",\n \"recipient\": {\n \"name\": \"John Kamau\",\n \"phone\": \"254712345678\",\n \"country\": \"KE\",\n \"network\": \"mpesa\"\n },\n \"narration\": \"October commission\",\n \"created_at\": \"2026-10-29T10:16:40+03:00\",\n \"updated_at\": \"2026-10-29T10:16:41+03:00\"\n}" }, { "name": "422 refused", "originalRequest": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Idempotency-Key", "value": "{{$guid}}", "description": "Unique per payout. Reuse the SAME value to retry a payout safely." } ], "url": { "raw": "{{baseUrl}}/payouts", "host": [ "{{baseUrl}}" ], "path": [ "payouts" ] }, "description": "Pay a mobile money number from your balance. Requires Idempotency-Key (Postman generates one per Send).", "body": { "mode": "raw", "raw": "{\n \"amount\": 1500,\n \"currency\": \"KES\",\n \"recipient_phone\": \"254712345678\",\n \"recipient_name\": \"John Kamau\",\n \"recipient_country\": \"KE\",\n \"network\": \"mpesa\",\n \"narration\": \"October commission\",\n \"client_reference\": \"INV-10293\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Unprocessable Entity", "code": 422, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": \"payout_refused\",\n \"message\": \"Insufficient balance for this payout (scheduled payments are held back).\"\n}" }, { "name": "403 not enabled", "originalRequest": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Idempotency-Key", "value": "{{$guid}}", "description": "Unique per payout. Reuse the SAME value to retry a payout safely." } ], "url": { "raw": "{{baseUrl}}/payouts", "host": [ "{{baseUrl}}" ], "path": [ "payouts" ] }, "description": "Pay a mobile money number from your balance. Requires Idempotency-Key (Postman generates one per Send).", "body": { "mode": "raw", "raw": "{\n \"amount\": 1500,\n \"currency\": \"KES\",\n \"recipient_phone\": \"254712345678\",\n \"recipient_name\": \"John Kamau\",\n \"recipient_country\": \"KE\",\n \"network\": \"mpesa\",\n \"narration\": \"October commission\",\n \"client_reference\": \"INV-10293\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Forbidden", "code": 403, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": \"payouts_not_enabled\",\n \"message\": \"Payouts through the API are not enabled for your account. Contact Snap Pay to enable them.\"\n}" } ] }, { "name": "Get payout", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/payouts/{{payoutReference}}", "host": [ "{{baseUrl}}" ], "path": [ "payouts", "{{payoutReference}}" ] }, "description": "Current status of one API payout." }, "response": [ { "name": "200 example", "originalRequest": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/payouts/{{payoutReference}}", "host": [ "{{baseUrl}}" ], "path": [ "payouts", "{{payoutReference}}" ] }, "description": "Current status of one API payout." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"object\": \"payout\",\n \"reference\": \"SNP-7K2M9QXA\",\n \"client_reference\": \"INV-10293\",\n \"status\": \"succeeded\",\n \"amount\": \"1500.00\",\n \"currency\": \"KES\",\n \"destination_amount\": \"1500.00\",\n \"destination_currency\": \"KES\",\n \"fx_rate\": 1,\n \"fee\": \"0.00\",\n \"recipient\": {\n \"name\": \"John Kamau\",\n \"phone\": \"254712345678\",\n \"country\": \"KE\",\n \"network\": \"mpesa\"\n },\n \"narration\": \"October commission\",\n \"created_at\": \"2026-10-29T10:16:40+03:00\",\n \"updated_at\": \"2026-10-29T10:16:41+03:00\"\n}" } ] }, { "name": "List payouts", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/payouts?status=succeeded&per_page=25&page=1", "host": [ "{{baseUrl}}" ], "path": [ "payouts" ], "query": [ { "key": "status", "value": "succeeded", "description": "processing | succeeded | failed | reversed" }, { "key": "per_page", "value": "25", "description": "1-100" }, { "key": "page", "value": "1" } ] }, "description": "Your API payouts, newest first." }, "response": [ { "name": "200 example", "originalRequest": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/payouts?status=succeeded&per_page=25&page=1", "host": [ "{{baseUrl}}" ], "path": [ "payouts" ], "query": [ { "key": "status", "value": "succeeded", "description": "processing | succeeded | failed | reversed" }, { "key": "per_page", "value": "25", "description": "1-100" }, { "key": "page", "value": "1" } ] }, "description": "Your API payouts, newest first." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"data\": [\n {\n \"object\": \"payout\",\n \"reference\": \"SNP-7K2M9QXA\",\n \"client_reference\": \"INV-10293\",\n \"status\": \"succeeded\",\n \"amount\": \"1500.00\",\n \"currency\": \"KES\",\n \"destination_amount\": \"1500.00\",\n \"destination_currency\": \"KES\",\n \"fx_rate\": 1,\n \"fee\": \"0.00\",\n \"recipient\": {\n \"name\": \"John Kamau\",\n \"phone\": \"254712345678\",\n \"country\": \"KE\",\n \"network\": \"mpesa\"\n },\n \"narration\": \"October commission\",\n \"created_at\": \"2026-10-29T10:16:40+03:00\",\n \"updated_at\": \"2026-10-29T10:16:41+03:00\"\n }\n ],\n \"meta\": {\n \"current_page\": 1,\n \"last_page\": 1,\n \"total\": 1\n }\n}" } ] } ] }, { "name": "Transactions", "item": [ { "name": "List transactions", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/transactions?per_page=25&page=1", "host": [ "{{baseUrl}}" ], "path": [ "transactions" ], "query": [ { "key": "per_page", "value": "25" }, { "key": "page", "value": "1" } ] }, "description": "Everything in and out of your business account." }, "response": [ { "name": "200 example", "originalRequest": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/transactions?per_page=25&page=1", "host": [ "{{baseUrl}}" ], "path": [ "transactions" ], "query": [ { "key": "per_page", "value": "25" }, { "key": "page", "value": "1" } ] }, "description": "Everything in and out of your business account." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"data\": [\n {\n \"reference\": \"SNP-4QH2W8LD\",\n \"status\": \"settled\",\n \"amount\": \"2500.00\",\n \"currency\": \"KES\",\n \"fee_minor\": 3750,\n \"buyer_phone\": \"254722000111\",\n \"payment_link\": \"SNAP-PL-8DK2LQ0Z\",\n \"created_at\": \"2026-10-28T16:02:11+03:00\"\n }\n ],\n \"meta\": {\n \"current_page\": 1,\n \"last_page\": 1,\n \"total\": 1\n }\n}" } ] }, { "name": "Payment status", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/payments/{{paymentReference}}", "host": [ "{{baseUrl}}" ], "path": [ "payments", "{{paymentReference}}" ] }, "description": "One transaction by reference (filled from List transactions)." }, "response": [ { "name": "200 example", "originalRequest": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/payments/{{paymentReference}}", "host": [ "{{baseUrl}}" ], "path": [ "payments", "{{paymentReference}}" ] }, "description": "One transaction by reference (filled from List transactions)." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"reference\": \"SNP-4QH2W8LD\",\n \"status\": \"settled\",\n \"amount\": \"2500.00\",\n \"currency\": \"KES\",\n \"fee_minor\": 3750,\n \"buyer_phone\": \"254722000111\",\n \"payment_link\": \"SNAP-PL-8DK2LQ0Z\",\n \"created_at\": \"2026-10-28T16:02:11+03:00\"\n}" } ] } ] }, { "name": "Sandbox only", "description": "These calls exist only on the sandbox (uat.snapcashpay.com).", "item": [ { "name": "Simulate payout outcome", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/sandbox/payouts/{{payoutReference}}/simulate", "host": [ "{{baseUrl}}" ], "path": [ "sandbox", "payouts", "{{payoutReference}}", "simulate" ] }, "description": "Finish a sandbox payout as succeeded or failed and send its webhook now.", "body": { "mode": "raw", "raw": "{\n \"outcome\": \"succeeded\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "200 example", "originalRequest": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/sandbox/payouts/{{payoutReference}}/simulate", "host": [ "{{baseUrl}}" ], "path": [ "sandbox", "payouts", "{{payoutReference}}", "simulate" ] }, "description": "Finish a sandbox payout as succeeded or failed and send its webhook now.", "body": { "mode": "raw", "raw": "{\n \"outcome\": \"succeeded\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"object\": \"payout\",\n \"reference\": \"SNP-7K2M9QXA\",\n \"client_reference\": \"INV-10293\",\n \"status\": \"succeeded\",\n \"amount\": \"1500.00\",\n \"currency\": \"KES\",\n \"destination_amount\": \"1500.00\",\n \"destination_currency\": \"KES\",\n \"fx_rate\": 1,\n \"fee\": \"0.00\",\n \"recipient\": {\n \"name\": \"John Kamau\",\n \"phone\": \"254712345678\",\n \"country\": \"KE\",\n \"network\": \"mpesa\"\n },\n \"narration\": \"October commission\",\n \"created_at\": \"2026-10-29T10:16:40+03:00\",\n \"updated_at\": \"2026-10-29T10:16:41+03:00\",\n \"webhook_delivery\": \"sent\"\n}" } ] } ] } ] }