Welcome to TurboPay Merchant API Integration Guide where you’ll learn how to make integration of your website or application with the REST API of our payment gateway quick and easy. Our gateway will allow you to use different deposit and withdrawal payment methods, as well as other services and features to successfully collect payments from your customers, disburse payments to them, and manage your payment transparently and easily.
\nTo complete successful integration, and testing and go live aside from the current Merchant API Integration Guide you would need:
\nTest* merchant account integration credentials and setup details:
\nTest merchant back office login and password
\nInformation about available methods, currencies, base URL, and transaction limits
All of the above are indicated in the setup sheet, provided by our tech team.
Test API and Webhook keys for authentication of requests
These should be generated by the merchant in their back office.
Integration group chat with our technical team
Will be created by our account management team.
Get your IPs whitelisted on our server
This is done by our tech team through the tech group chat.
Setup your server’s webhooks and redirect URL(s) for your merchant account:
\nStatus URL, where we send you webhooks about order statuses
\nReturn URL, where your customer is redirected to after payment
\n\n\n*A test merchant account allows you to test most of the features including receiving failed and success responses from the gateway without involving real money. They are meant for emulating transactions and responses by software and quality assurance engineers. To perform live transactions in a production mode for test purposes you may need to find a local wallet and/or account and perform these tests with a live merchant account.
\n
It is recommended to complete integration in the following steps:
\nGet all the details mentioned in the Prerequisites section
\nComplete integration with a test merchant account
\nTest integration with simulated transactions
\nGet live account credentials and connect them to your production server
\nTest integration to your live account
\nHave your live account fully switched to live mode*
\nOur account management, customer support, and technical teams will gladly assist you on every step of your integration and going live processes.
\nEach API request that you make to our gateway must be authenticated. Authenticate them by including your API key in the Authorization header.
\nYou can generate your API key as well as the webhook key for validating webhooks directly from the back office.
\n\n\nSecure your API keys - do not commit your API keys to git, do not store in Jira or other project management software, or use them in client-side JavaScript code. It can perform any action on your account without restriction. It should be kept confidential and only stored on your servers, preferably as an environment variable.
\n
API requests made without authentication will fail with the status code 401: Unauthorized. All API requests must be made over HTTPS. Do not set VERIFY_PEER to FALSE.
\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[{"content":"🚀 Introduction","slug":"introduction"},{"content":"⚙️ Prerequisites","slug":"prerequisites"},{"content":"⚙️ Integration steps","slug":"integration-steps"},{"content":"🔐 Authentication","slug":"authentication"}],"owner":"47990315","collectionId":"50330b5f-b2db-4477-bcaf-3bc87ab9e937","publishedId":"2sB3HonygQ","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"228B22"},"publishDate":"2025-09-11T11:47:52.000Z"},"item":[{"name":"📥 Deposit (Hosted page)","item":[{"name":"Create Deposit Order","event":[{"listen":"test","script":{"id":"373cd0f8-11b0-4027-8f7e-e2abe3056208","exec":[""],"type":"text/javascript","packages":{}}}],"id":"996d6b87-7217-40ca-bf03-e116aae07508","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"POST","header":[{"key":"Accept","value":"application/json","type":"text"},{"key":"Authorization","value":"{{merchant_api_token}}","type":"text"},{"key":"Content-Type","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{\n \"method\": \"upi\",\n \"amount\": 2000,\n \"currency\": \"INR\",\n \"customer_email\": \"peter-pen@gmail.com\",\n \"customer_phone\": \"+919876543210\",\n \"customer_name\": \"Peter Pen\",\n \"merchant_order_id\": \"0b087635-f4af-4df3-963f-b9dc3b465f9e\",\n \"merchant_customer_id\": \"ee24d065-5d91-4397-8820-60cb98f6ba42\",\n \"status_url\": \"https://webhook.site/cc6a5b7c-330b-4a2f-a90e-3cdc8cdaf8df\",\n \"redirect_url\": \"https://merchant-website.com\",\n \"traffic\": \"ftd\"\n}","options":{"raw":{"language":"json"}}},"url":"https://api.turbopay.com/api/deposit/new","urlObject":{"path":["deposit","new"],"host":["https://api.turbopay.com/api"],"query":[],"variable":[]}},"response":[{"id":"3c89f624-8146-41ef-9bc2-bd7b99a5ae9f","name":"201 UPI Created successfuly","originalRequest":{"method":"POST","header":[{"key":"Accept","value":"application/json","type":"text"},{"key":"Authorization","value":"{{merchant_api_token}}","type":"text"},{"key":"Content-Type","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{\n \"method\": \"upi\",\n \"amount\": 2000,\n \"currency\": \"INR\",\n \"customer_email\": \"peter-pen@gmail.com\",\n \"customer_phone\": \"+919876543210\",\n \"customer_name\": \"Peter Pen\",\n \"merchant_order_id\": \"5313a2d0-cd01-4669-a4c2-59b89b97b09a\",\n \"merchant_customer_id\": \"4e8fcdb7-2546-4b0e-8766-a2a3b46cfe61\",\n \"status_url\": \"https://webhook.site/cc6a5b7c-330b-4a2f-a90e-3cdc8cdaf8df\",\n \"redirect_url\": \"https://merchant-website.com\",\n \"traffic\": \"ftd\"\n}","options":{"raw":{"language":"json"}}},"url":"https://api.turbopay.com/api/deposit/new"},"status":"Created","code":201,"_postman_previewlanguage":null,"header":[{"key":"Date","value":"Mon, 01 Sep 2025 09:18:56 GMT"},{"key":"Content-Type","value":"application/json"},{"key":"Transfer-Encoding","value":"chunked"},{"key":"Connection","value":"keep-alive"},{"key":"Server","value":"cloudflare"},{"key":"Cache-Control","value":"no-cache, private"},{"key":"vary","value":"Origin"},{"key":"cf-cache-status","value":"DYNAMIC"},{"key":"Nel","value":"{\"report_to\":\"cf-nel\",\"success_fraction\":0.0,\"max_age\":604800}"},{"key":"Report-To","value":"{\"group\":\"cf-nel\",\"max_age\":604800,\"endpoints\":[{\"url\":\"https://a.nel.cloudflare.com/report/v4?s=9bHXb6FIttaKIOYxQknZzTdqESDKs8fjh46fMpYYJs56Vn8X%2BPMNdqglauc1n2OIibzxsom7AnxrxJurhHU4Eln9LB8qesxtFTxurvXcFg%3D%3D\"}]}"},{"key":"CF-RAY","value":"9783aee08ebd41d6-LHR"},{"key":"alt-svc","value":"h3=\":443\"; ma=86400"}],"cookie":[],"responseTime":null,"body":"{\n \"form_url\": \"https://linestrack.com/wire?hash=f16f937b-dbac-48dc-b2b2-a7630e98e903\",\n \"order_id\": \"e7d414e6-81b6-4dd9-a785-d19cb315c118\",\n \"status\": \"new\"\n}"},{"id":"dfd96233-0a95-4f7b-a494-6df78726ff8b","name":"401 Wrong API Key","originalRequest":{"method":"POST","header":[{"key":"Accept","value":"application/json","type":"text"},{"key":"Authorization","value":"","type":"text"},{"key":"Content-Type","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{\n \"method\": \"upi\",\n \"amount\": 200,\n \"currency\": \"INR\",\n \"customer_email\": \"peter-pen@gmail.com\",\n \"customer_phone\": \"+919876543210\",\n \"customer_name\": \"Peter Pen\",\n \"merchant_order_id\": \"a07c1e32-e506-4f0e-a1d1-b61c6ab99aa7\",\n \"merchant_customer_id\": \"328ccfb8-cdd9-4321-bdee-27d6c912b49e\",\n \"status_url\": \"https://webhook.site/cc6a5b7c-330b-4a2f-a90e-3cdc8cdaf8df\",\n \"redirect_url\": \"https://merchant-website.com\",\n \"traffic\": \"ftd\"\n}","options":{"raw":{"language":"json"}}},"url":"https://api.turbopay.com/api/deposit/new"},"status":"Unauthorized","code":401,"_postman_previewlanguage":"json","header":[{"key":"Date","value":"Wed, 22 Jan 2025 10:40:06 GMT"},{"key":"Content-Type","value":"application/json"},{"key":"Transfer-Encoding","value":"chunked"},{"key":"Connection","value":"keep-alive"},{"key":"Cache-Control","value":"no-cache, private"},{"key":"vary","value":"Origin"},{"key":"cf-cache-status","value":"DYNAMIC"},{"key":"Report-To","value":"{\"endpoints\":[{\"url\":\"https:\\/\\/a.nel.cloudflare.com\\/report\\/v4?s=FsllWSedNUnPxpOdfaBPF9cVLIrfPgVVQz4Y%2BDvwH7ziL%2BhvrF1c%2FKMi0032zhoTKv6Q1G2eKdNrmwWzmbuHnSXun3tJxU6Ckc2nNgpQgYcTujMwH3VIyZDozFhapKdl%2B6%2B3A6cd\"}],\"group\":\"cf-nel\",\"max_age\":604800}"},{"key":"NEL","value":"{\"success_fraction\":0,\"report_to\":\"cf-nel\",\"max_age\":604800}"},{"key":"Server","value":"cloudflare"},{"key":"CF-RAY","value":"905eec8528ef3607-MAN"},{"key":"alt-svc","value":"h3=\":443\"; ma=86400"},{"key":"server-timing","value":"cfL4;desc=\"?proto=TCP&rtt=19958&min_rtt=16855&rtt_var=10899&sent=46&recv=45&lost=0&retrans=1&sent_bytes=4307&recv_bytes=2273&delivery_rate=164181&cwnd=253&unsent_bytes=0&cid=447e84a3da709309&ts=41315&x=0\""}],"cookie":[],"responseTime":null,"body":"{\n \"message\": \"Unauthorized\"\n}"}],"_postman_id":"996d6b87-7217-40ca-bf03-e116aae07508"}],"id":"9fa9115c-ac4b-4f52-a900-a9dde754c94a","description":"A deposit process facilitates transferring funds securely and efficiently. This requires creating an order, showing a payment form, and updating order status in your system. Each step ensures accurate processing and status tracking, safeguarding the integrity of the deposit transaction.
\nDescription: Initiate the deposit by running Create Deposit Order endpoint using the API. To use UPI (Unified Payments Interface) as the payment method, specify upi. For bank transfers, specify bank_transfer.
UPI (Unified Payments Interface): A real-time payment system that enables instant money transfers between banks using a mobile number or a virtual payment address (VPA).
\nBank Transfers: A method of transferring funds directly between bank accounts. Supported methods may include IMPS (Immediate Payment Service), which enables instant, 24/7 bank-to-bank transfers within supported networks.
\nAction: Submit a request with the required details, ensuring the use of the correct API key for authorization.
\nResponse: A successful response includes an order_id, form_url, and the transaction status.
Important: Store the order_id , amount and status securely for further processing.
Example of request body:
\n{\n \"method\": \"upi\",\n \"amount\": 200,\n \"currency\": \"INR\",\n \"customer_email\": \"peter-pen@gmail.com\",\n \"customer_phone\": \"+919876543210\",\n \"customer_name\": \"Peter Pen\",\n \"merchant_order_id\": \"e8a5c596-ff82-4529-9b56-ecac6a061c91\",\n \"merchant_customer_id\": \"995e2bae-dbcc-4549-88d0-73e8a7f74fc3\",\n \"status_url\": \"https://webhook.site/cc6a5b7c-330b-4a2f-a90e-3cdc8cdaf8df\",\n \"redirect_url\": \"https://merchant-website.com\",\n \"traffic\": \"ftd\"\n}\n\nRequest parameters:
\nExample of succesful response:
\n{\n \"form_url\": \"https://base_url.com/deposit?hash=v7f0f71f-f896h-kk898f-ff6b0f34cbd0\",\n \"order_id\": \"c2f0f71a-6f3f-4d65-be01-aa6b0f86cbe1\",\n \"status\": \"new\"\n}\n\n\n\nFor security reasons, please keep
\norder_idprivate and do not make it available neither to the public nor to end customers.
Response parameters:
\nStep 2: Show Payment Form
\nDescription: Redirect the customer to the payment form containing the transaction details.
\nAction: All you need to do that is redirect your customer to the link returned in form_url, and we'll display our hosted payment page for them to complete the payment. You can show form by redirecting on our form page or you can show this form using iframe.
Example: Use the form_url to open deposit form:
https://base_url.com/deposit?hash=v7f0f71f-f896h-kk898f-ff6b0f34cbd0
Iframe integration
\nTo integrate our desktop and mobile-friendly hosted payment page directly into your website using an iframe, simply include the following tag on the relevant webpage:
\ninsert iframe tag with folowing params
:src=\"<form_url>\"\n allow=\"clipboard-write\"\n height=\"800\"\n width=\"100%\"\n frameborder=\"0\"\n\nThe iframe triggers a close event when the close or return button is pressed. You can handle this event to close the iframe using the following approach:
\nconst listener = event => {\n if (event.data === 'close') {\n Implement here logic to close the iframe.\n }\n}\n if (window.addEventListener) {\n window.addEventListener(\"message\", listener);\n } else {\n window.attachEvent(\"onmessage\", listener);\n }\n\nDescription: Throughout the deposit process, an order transitions through multiple statuses such as new, pending, success, failed, cancelled, refunded or expired. Each status indicates the current state of the order.
Action: Use webhooks or periodic API calls to monitor order status updates. Handle each status appropriately in your system:
\nSuccess: Mark the order as successful and proceed with delivering goods or services.
\nFailed: Mark the order as unsuccessful and inform the customer.
\nCancelled or Expired: Wait for possible transitions to failed or success before finalizing the order status.
Note that success status is final for deposit order and transition from failed to success is allowed.
\n\nFinal status normally means that it cannot be changed anymore. However, in certain rare cases depending on the payment method and flow, we can change the order status from failed to success, which will be clearly communicated to you each time.
\n
Each change of the order status will trigger a webhook to your designated status_url with the respective order_id and status. Please refer to the Webhooks and Order statuses transitions parts for more information.
\nMake sure to respond to status updates dynamically and adapt your flow according to the allowed status transitions.
\n\n\n","_postman_id":"9fa9115c-ac4b-4f52-a900-a9dde754c94a"},{"name":"📥 Deposit (host-to-host)","item":[{"name":"Create Deposit Order","event":[{"listen":"test","script":{"exec":[""],"type":"text/javascript","packages":{},"id":"6dd97f6a-0d2c-40bb-b1a4-7ed0138dfec0"}}],"id":"16c3d517-33ef-4ace-81bb-97f217b17096","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"POST","header":[{"key":"Accept","value":"application/json","type":"text"},{"key":"Authorization","value":"{{merchant_api_token}}","type":"text"},{"key":"Content-Type","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{\n \"method\": \"upi\",\n \"amount\": 2000,\n \"currency\": \"INR\",\n \"customer_email\": \"peter-pen@gmail.com\",\n \"customer_phone\": \"+919876543210\",\n \"customer_name\": \"Peter Pen\",\n \"merchant_order_id\": \"82ddd757-fc1e-4b73-8dcc-1a9294ff9797\",\n \"merchant_customer_id\": \"cfeb6282-e23d-431e-a548-97606104bc69\",\n \"status_url\": \"https://webhook.site/cc6a5b7c-330b-4a2f-a90e-3cdc8cdaf8df\",\n \"redirect_url\": \"https://merchant-website.com\",\n \"traffic\": \"ftd\"\n}","options":{"raw":{"language":"json"}}},"url":"https://api.turbopay.com/api/s2s/deposit/new","urlObject":{"path":["s2s","deposit","new"],"host":["https://api.turbopay.com/api"],"query":[],"variable":[]}},"response":[{"id":"d1649930-be5e-4bc6-9ecf-c504ae66cfd8","name":"201 UPI Success","originalRequest":{"method":"POST","header":[{"key":"Accept","value":"application/json","type":"text"},{"key":"Authorization","value":"{{merchant_api_token}}","type":"text"},{"key":"Content-Type","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{\n \"method\": \"upi\",\n \"amount\": 226,\n \"currency\": \"INR\",\n \"customer_email\": \"peter-pen@gmail.com\",\n \"customer_phone\": \"+919876543210\",\n \"customer_name\": \"Peter Pen\",\n \"merchant_order_id\": \"3b17c84d-8b08-4c00-a105-3a8d18d6cbf8\",\n \"merchant_customer_id\": \"8f66f8b8-46f7-4b5b-a099-f840bebdfb32\",\n \"status_url\": \"https://webhook.site/cc6a5b7c-330b-4a2f-a90e-3cdc8cdaf8df\",\n \"redirect_url\": \"https://merchant-website.com\",\n \"traffic\": \"ftd\"\n}","options":{"raw":{"language":"json"}}},"url":"https://api.turbopay.com/api/s2s/deposit/new"},"status":"Created","code":201,"_postman_previewlanguage":null,"header":[{"key":"Date","value":"Tue, 28 Apr 2026 09:21:37 GMT"},{"key":"Content-Type","value":"application/json"},{"key":"Transfer-Encoding","value":"chunked"},{"key":"Connection","value":"keep-alive"},{"key":"Server","value":"cloudflare"},{"key":"Cache-Control","value":"no-cache, private"},{"key":"vary","value":"Origin"},{"key":"x-envoy-upstream-service-time","value":"678"},{"key":"cf-cache-status","value":"DYNAMIC"},{"key":"Nel","value":"{\"report_to\":\"cf-nel\",\"success_fraction\":0.0,\"max_age\":604800}"},{"key":"Report-To","value":"{\"group\":\"cf-nel\",\"max_age\":604800,\"endpoints\":[{\"url\":\"https://a.nel.cloudflare.com/report/v4?s=mEkrEk8IOW7uxXWiV7i2mLfrXlGWYmZkbEgfwAYIxnCgaNC%2B9nrq7%2FNQiJMse5R%2BpBFjRQbDr2SMLCftenGN0%2FdAkGsTUK9caTLybqImtJ%2F0FVnZz3jVpLAe6zPnS%2B0t4Pnlag%3D%3D\"}]}"},{"key":"CF-RAY","value":"9f34ff6a293fd67f-IAD"},{"key":"alt-svc","value":"h3=\":443\"; ma=86400"}],"cookie":[],"responseTime":null,"body":"{\n \"wallet_address\": \"test@test\",\n \"wallet_name\": \"[TEST] - TEST - TEST-OSTIN - FTD\",\n \"transaction_note\": \"ZJaoS\",\n \"order_expiration_seconds\": \"600\",\n \"order_id\": \"d19da091-098d-49a6-b401-909bcf558a4f\",\n \"status\": \"new\",\n \"qr\": \"iVBORw0KGgoAAAANSUhEUgAAAOEAAADhCAIAAACx0UUtAAAACXBIWXMAAA7EAAAOxAGVKw4bAAAFj0lEQVR4nO3dy24jNxRF0TjI//+yM8moELDB5qO22mtNVSqVpQPCFyQvv76/v/+CsL/ffgD4BRmlTkapk1HqZJQ6GaVORqmTUepklDoZpU5GqZNR6mSUOhmlTkapk1HqZJQ6GaVORqn7Z+XNX19fu55jbLzpavwYj/dOPfPGzV7XPvfxQStf3UYrf5FxlDoZpU5GqZNR6pZqpodrFcbKf/rXel6cq+TOeatGHDOOUiej1MkodTJK3c6a6eHczMrUxSu1y7lXx6bmis55a07uwThKnYxSJ6PUySh1B2uma1aqonMTPG8txhu/+omt5Y2j1MkodTJKnYxS95E108YtO1MV1bWtUVN/4NR01ycyjlIno9TJKHUySt3Bmuncf+sb+xpMVUUrJdRU6TZ2bZlfpN4yjlIno9TJKHUySt3OmulaI4Nz0zDnJpau7ZTauI8qwjhKnYxSJ6PUySh1X5G5hHNWFvKtLHvbWH9sLJI+8ec2jlIno9TJKHUySt3O85muzZ1MPdXUxVNTVmPN+a0pG8vNFcZR6mSUOhmlTkapO7g2b2W7z8YpnHM9vzcWOiufO7YyC7Vxms2ZtvzJZJQ6GaVORqlbWpu38f/ic6cojW+14hOP1j33G42pmfiTySh1MkqdjFJ3bz/TSilzbk/SlJXibGNj8mY3cWvz+LlklDoZpU5Gqav0zds4z7Ri5VbXprs2HvW08SHP/UbGUepklDoZpU5GqdvZA+LhXFuHlU4NkWZ3489965jaa1/OFOModTJKnYxSJ6PULdVMb7VXmLrV+OKHc7u73qogpzifCX6HjFIno9TJKHUHe40/rCz0mvLW0bpTr56bK2qeC7XCOEqdjFIno9TJKHU79zONXStlms3Fz+2UikyznWMcpU5GqZNR6mSUuoN98851ipt679Stpmxso3dtzmZjnXdtD5ZxlDoZpU5GqZNR6ip988a3utZ7+1xj8o2vPkzVLhv3UU29usI4Sp2MUiej1Mkodff2M43fu3Krc0XSSv1xrsnFw1sdwa8t5DOOUiej1MkodTJK3b15pqk+chvX9Y0vvraBaWVb1ZS3Vv2d2yllHKVORqmTUepklLqdNdPGE4mmLj63gm7qMcYXTzm3Nm/jV3etqYdxlDoZpU5GqZNR6nb2gNi4r+hcwfFWZ7xrC/nGmscQjxlHqZNR6mSUOhmlbqlmOrd07doKupWnGntrjdxYs6AcM45SJ6PUySh1Mkrda/uZxq9unKUY29i/bvzeSMOIlYtXfsEVxlHqZJQ6GaVORqlbqpmubeh5q3HcuXmXj9hINHatrjWOUiej1MkodTJKXWVt3vjO4/eeO6Z2yrlef+c0u1o8GEepk1HqZJQ6GaVu5zzTxnmXjYfYrhy59LBxw9a5XVbXFgFe26FlHKVORqmTUepklLqDZ9qeO2TorYNZz81+nZt2WlkiuLGwW2EcpU5GqZNR6mSUup29xq+5Nhu0cbpr7Fyv8Wut/+xn4ueSUepklDoZpW7nfqZzrtUuY5FW3Oeaa2wsN8cXTzGOUiej1MkodTJK3c5e4+eOx5363I0zKysXn6shxreKrAnceGfjKHUySp2MUiej1O2smR7O/fN+bqfUw7kGClM2PvO13ncbvw3jKHUySp2MUiej1B2smc45V2Bda2NxbYvSxrWX1z73wThKnYxSJ6PUySh1H1kzXZvRufYY58qRjScwmWeC/yej1MkodTJK3cGa6a29Mhs7oK+8d2PRcG7H0srhVeaZ4D8ySp2MUiej1O2sma610VuZDjm3gWnqg1Y+d+q9G+u8t0pG4yh1MkqdjFIno9R95PlM/CjGUepklDoZpU5GqZNR6mSUOhmlTkapk1HqZJQ6GaVORqmTUepklDoZpU5GqZNR6mSUOhml7l8Al9EUyCJ8bAAAAABJRU5ErkJggg==\",\n \"deep_links\": {\n \"phonepe\": \"phonepe://native?data=eyJjb250YWN0Ijp7ImNic05hbWUiOiIiLCJuaWNrTmFtZSI6IiIsInR5cGUiOiJWUEEiLCJ2cGEiOiJ0ZXN0QHRlc3QifSwicDJwUGF5bWVudENoZWNrb3V0UGFyYW1zIjp7ImlzQnlEZWZhdWx0S25vd25Db250YWN0Ijp0cnVlLCJlbmFibGVTcGVlY2hUb1RleHQiOmZhbHNlLCJhbGxvd0Ftb3VudEVkaXQiOmZhbHNlLCJzaG93UXJDb2RlT3B0aW9uIjpmYWxzZSwiZGlzYWJsZVZpZXdIaXN0b3J5Ijp0cnVlLCJzaG91bGRTaG93VW5zYXZlZENvbnRhY3RCYW5uZXIiOmZhbHNlLCJpc1JlY3VycmluZyI6ZmFsc2UsImNoZWNrb3V0VHlwZSI6IkRFRkFVTFQiLCJ0cmFuc2FjdGlvbkNvbnRleHQiOiJwMnAiLCJkaXNhYmxlTm90ZXNFZGl0Ijp0cnVlLCJzaG93S2V5Ym9hcmQiOmZhbHNlLCJjdXJyZW5jeSI6IklOUiIsInNob3VsZFNob3dNYXNrZWROdW1iZXIiOnRydWUsIm5vdGUiOiJaSmFvUyIsImluaXRpYWxBbW91bnQiOjIyNjAwfX0%3D&id=p2ppayment\",\n \"paytm\": \"paytmmp://cash_wallet?pa=test%40test&pn=Test%20Merchant%20STR&tn=ZJaoS&am=226&cu=INR&featuretype=money_transfer\"\n }\n}"},{"id":"4fa15fce-7650-4d1a-aacd-2d8c7a4322ca","name":"422 Invalid request","originalRequest":{"method":"POST","header":[{"key":"Accept","value":"application/json","type":"text"},{"key":"Authorization","value":"{{merchant_api_token}}","type":"text"},{"key":"Content-Type","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{\n \"method\": \"bank_transfer\",\n \"amount\": 2000,\n \"currency\": \"INR\",\n \"customer_email\": \"peter-pen@gmail.com\",\n \"customer_phone\": \"+919876543210\",\n \"customer_name\": \"Peter Pen\",\n \"merchant_order_id\": \"fd850e70-ef0f-4f3a-8f6d-bcac96812e4a\",\n \"merchant_customer_id\": \"77c2679e-255f-4936-ad47-64c8b18b2679\",\n \"status_url\": \"https://webhook.site/cc6a5b7c-330b-4a2f-a90e-3cdc8cdaf8df\",\n \"redirect_url\": \"https://merchant-website.com\",\n \"traffic\": \"ftd\"\n}","options":{"raw":{"language":"json"}}},"url":"https://api.turbopay.com/api/s2s/deposit/new"},"status":"Unprocessable Entity","code":422,"_postman_previewlanguage":"json","header":[{"key":"Date","value":"Wed, 25 Jun 2025 14:16:14 GMT"},{"key":"Content-Type","value":"application/json"},{"key":"Transfer-Encoding","value":"chunked"},{"key":"Connection","value":"keep-alive"},{"key":"Server","value":"cloudflare"},{"key":"Cache-Control","value":"no-cache, private"},{"key":"Vary","value":"Origin"},{"key":"Cf-Cache-Status","value":"DYNAMIC"},{"key":"Nel","value":"{\"report_to\":\"cf-nel\",\"success_fraction\":0.0,\"max_age\":604800}"},{"key":"Report-To","value":"{\"group\":\"cf-nel\",\"max_age\":604800,\"endpoints\":[{\"url\":\"https://a.nel.cloudflare.com/report/v4?s=ABPg%2FtofZ5JAP21nfMCnjzaHzridnGa%2Fv2juFxvg8nTaKRjFF11jr6NxrRme1MMcOgbySG1dv%2F9aZTlBo0ptx0fjzcwOeivpdCsGjTCv79%2FRmlvMbLHqCcc%3D\"}]}"},{"key":"CF-RAY","value":"955514d898a5f44b-MAN"},{"key":"alt-svc","value":"h3=\":443\"; ma=86400"}],"cookie":[],"responseTime":null,"body":"{\n \"message\": \"invalid request\",\n \"errors\": {\n \"account\": [\n \"Mid is not configured for method \\\"bank_transfer\\\"\"\n ]\n }\n}"},{"id":"5a9f4310-33eb-4fe7-94f0-ed894dc652d5","name":"401 Wrong API Key","originalRequest":{"method":"POST","header":[{"key":"Accept","value":"application/json","type":"text"},{"key":"Authorization","value":"{{merchant_api_token}}","type":"text"},{"key":"Content-Type","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{\n \"method\": \"bank_transfer\",\n \"amount\": 2000,\n \"currency\": \"INR\",\n \"customer_email\": \"peter-pen@gmail.com\",\n \"customer_phone\": \"+919876543210\",\n \"customer_name\": \"Peter Pen\",\n \"merchant_order_id\": \"b6e7dc45-a336-477f-b707-322087368e5b\",\n \"merchant_customer_id\": \"a207b3de-053f-411f-9156-995c3572526e\",\n \"status_url\": \"https://webhook.site/cc6a5b7c-330b-4a2f-a90e-3cdc8cdaf8df\",\n \"redirect_url\": \"https://merchant-website.com\",\n \"traffic\": \"std\"\n}","options":{"raw":{"language":"json"}}},"url":"https://api.turbopay.com/api/s2s/deposit/new"},"status":"Unauthorized","code":401,"_postman_previewlanguage":"json","header":[{"key":"Date","value":"Wed, 25 Jun 2025 14:19:23 GMT"},{"key":"Content-Type","value":"application/json"},{"key":"Transfer-Encoding","value":"chunked"},{"key":"Connection","value":"keep-alive"},{"key":"Server","value":"cloudflare"},{"key":"Cache-Control","value":"no-cache, private"},{"key":"Vary","value":"Origin"},{"key":"Cf-Cache-Status","value":"DYNAMIC"},{"key":"Nel","value":"{\"report_to\":\"cf-nel\",\"success_fraction\":0.0,\"max_age\":604800}"},{"key":"Report-To","value":"{\"group\":\"cf-nel\",\"max_age\":604800,\"endpoints\":[{\"url\":\"https://a.nel.cloudflare.com/report/v4?s=YqqOuAnsCHT261qm8dA%2BLbXYbuK588alWiUTGpdJoUl4dgCDjbm4CudkUHpLb1Agji8rCUanGWi1xOAHEZ4xydSa%2B%2BFi1hoyUZfDL8AM40fhSA20vTrw0yOsvw%3D%3D\"}]}"},{"key":"CF-RAY","value":"9555197cbe4fd85e-MAN"},{"key":"alt-svc","value":"h3=\":443\"; ma=86400"}],"cookie":[],"responseTime":null,"body":"{\n \"message\": \"Unauthorized\"\n}"}],"_postman_id":"16c3d517-33ef-4ace-81bb-97f217b17096"},{"name":"Confirm UTR","event":[{"listen":"test","script":{"id":"6dd97f6a-0d2c-40bb-b1a4-7ed0138dfec0","exec":[""],"type":"text/javascript","packages":{}}}],"id":"4603303f-748e-4944-bf51-2b2dc4a17950","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"POST","header":[{"key":"Accept","value":"application/json","type":"text"},{"key":"Authorization","value":"{{merchant_api_token}}","type":"text"},{"key":"Content-Type","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{\n \"order_id\": \"e010d12b-570b-417e-a781-c8f4261dcd27\",\n \"customer_transaction_id\": \"409876543210\"\n}\n","options":{"raw":{"language":"json"}}},"url":"https://api.turbopay.com/api/s2s/deposit/confirm","urlObject":{"path":["s2s","deposit","confirm"],"host":["https://api.turbopay.com/api"],"query":[],"variable":[]}},"response":[{"id":"c7caf0e5-4cf2-4630-a34f-b61d6cb6b2a2","name":"200 Success - order confirmed","originalRequest":{"method":"POST","header":[{"key":"Accept","value":"application/json","type":"text"},{"key":"Authorization","value":"{{merchant_api_token}}","type":"text"},{"key":"Content-Type","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{\n \"order_id\": \"3a54ba9d-cf38-4dcb-8478-51afdb77d96e\",\n \"customer_transaction_id\": \"110000000000\"\n}\n","options":{"raw":{"language":"json"}}},"url":"https://api.turbopay.com/api/s2s/deposit/confirm"},"status":"OK","code":200,"_postman_previewlanguage":null,"header":[{"key":"Date","value":"Mon, 01 Sep 2025 10:09:38 GMT"},{"key":"Content-Type","value":"application/json"},{"key":"Transfer-Encoding","value":"chunked"},{"key":"Connection","value":"keep-alive"},{"key":"Server","value":"cloudflare"},{"key":"Cache-Control","value":"no-cache, private"},{"key":"vary","value":"Origin"},{"key":"cf-cache-status","value":"DYNAMIC"},{"key":"Nel","value":"{\"report_to\":\"cf-nel\",\"success_fraction\":0.0,\"max_age\":604800}"},{"key":"Report-To","value":"{\"group\":\"cf-nel\",\"max_age\":604800,\"endpoints\":[{\"url\":\"https://a.nel.cloudflare.com/report/v4?s=v2J3x5iT4D%2FnbM%2F98jghqQHF2jh5SKjdjIAym4xWmH%2B5EVDZqMOsN9T%2F4%2F0vuqJogmlkK63%2Fu63GuhTpclSLL18jzKlmuOKyVvN3eIG6yw%3D%3D\"}]}"},{"key":"Content-Encoding","value":"br"},{"key":"CF-RAY","value":"9783f9207d9fb54c-LHR"},{"key":"alt-svc","value":"h3=\":443\"; ma=86400"}],"cookie":[],"responseTime":null,"body":"{\n \"status\": \"pending\"\n}"},{"id":"fe0edc3d-1c09-42fc-825a-17a9378d3d51","name":"422 Wrong UTR - already taken","originalRequest":{"method":"POST","header":[{"key":"Accept","value":"application/json","type":"text"},{"key":"Authorization","value":"{{merchant_api_token}}","type":"text"},{"key":"Content-Type","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{\n \"order_id\": \"e010d12b-570b-417e-a781-c8f4261dcd27\",\n \"customer_transaction_id\": \"409876543210\"\n}\n","options":{"raw":{"language":"json"}}},"url":"https://api.turbopay.com/api/s2s/deposit/confirm"},"status":"Unprocessable Entity","code":422,"_postman_previewlanguage":null,"header":[{"key":"Date","value":"Mon, 01 Sep 2025 09:52:27 GMT"},{"key":"Content-Type","value":"application/json"},{"key":"Transfer-Encoding","value":"chunked"},{"key":"Connection","value":"keep-alive"},{"key":"Server","value":"cloudflare"},{"key":"Cache-Control","value":"no-cache, private"},{"key":"vary","value":"Origin"},{"key":"cf-cache-status","value":"DYNAMIC"},{"key":"Nel","value":"{\"report_to\":\"cf-nel\",\"success_fraction\":0.0,\"max_age\":604800}"},{"key":"Report-To","value":"{\"group\":\"cf-nel\",\"max_age\":604800,\"endpoints\":[{\"url\":\"https://a.nel.cloudflare.com/report/v4?s=FcJ6kWaQQpkYOvpF42ByJN6jy0TYP%2BCmGpVermyDPeaPns5PFaTTAPsvPqf06ODICmvu%2BXe%2FxDYvIRaBenjIMOVOMul7eV8GzDDni9kl4A%3D%3D\"}]}"},{"key":"CF-RAY","value":"9783dffb0de0cd1c-LHR"},{"key":"alt-svc","value":"h3=\":443\"; ma=86400"}],"cookie":[],"responseTime":null,"body":"{\n \"message\": \"The selected order id is invalid. (and 1 more error)\",\n \"errors\": {\n \"order_id\": [\n \"The selected order id is invalid.\"\n ],\n \"customer_transaction_id\": [\n \"The customer transaction id has already been taken.\"\n ]\n }\n}"}],"_postman_id":"4603303f-748e-4944-bf51-2b2dc4a17950"}],"id":"7c577958-d081-4fe8-9be0-3c5ea253c5db","description":"Please do not fail orders on your side in cases of
\ncancelledorexpiredstatus webhooks, unless you can accept further transition tosuccessstatus.
The Host-to-Host Deposit endpoint allows you to create orders and confirm them by collecting UTR on your own payment page without leaving your website by the end user.
\nDescription: Initiate the deposit by running Create Deposit Order endpoint using the API. Include payment details such as wallet address, wallet name, and a transaction note. To use UPI (Unified Payments Interface) as the payment method, specify upi. For bank transfers, specify bank_transfer.
UPI (Unified Payments Interface): A real-time payment system that enables instant money transfers between banks using a mobile number or a virtual payment address (VPA).
\nBank Transfers: A method of transferring funds directly between bank accounts. Supported methods may include IMPS (Immediate Payment Service), which enables instant, 24/7 bank-to-bank transfers within supported networks.
\nAction: Submit a request with the required details, ensuring the use of the correct API key for authorization.
\nResponse: A successful request returns an HTTP 201 Created status along with a JSON payload containing the order details.
\nImportant: Store the order_id , amount and status securely for further processing.
Example of request body:
\n{\n \"method\": \"upi\",\n \"amount\": 200,\n \"currency\": \"INR\",\n \"customer_email\": \"peter-pen@gmail.com\",\n \"customer_phone\": \"+919876543210\",\n \"customer_name\": \"Peter Pen\",\n \"merchant_order_id\": \"e8a5c596-ff82-4529-9b56-ecac6a061c91\",\n \"merchant_customer_id\": \"995e2bae-dbcc-4549-88d0-73e8a7f74fc3\",\n \"status_url\": \"https://webhook.site/cc6a5b7c-330b-4a2f-a90e-3cdc8cdaf8df\",\n \"redirect_url\": \"https://merchant-website.com\",\n \"traffic\": \"ftd\"\n}\n\nRequest parameters:
\nExample of succesful response:
\n{\n \"wallet_address\": \"username@bankname\",\n \"wallet_name\": \"Company Name\",\n \"order_expiration_seconds\": \"600\",\n \"transaction_note\": \"A1b2c\",\n \"order_id\": \"c2f0f71a-6f3f-4d65-be01-aa6b0f86cbe1\",\n \"status\": \"new\"\n}\n\n\n\nFor security reasons, please keep
\norder_idprivate and do not make it available neither to the public nor to end customers.
Response parameters:
\n\n\nWe recommend that you immediately store order_id, amount, and status parameters at your end.
\n
Description: Present the customer with your own payment form that displays the Virtual Payment Address (VPA / UPI ID) and other transaction details provided in the deposit order response.
\nAction: Collect the UTR (Unique Transaction Reference) from the customer once the deposit is completed. This must be done within the expiration time specified in order_expiration_seconds.
Description: Once the customer has completed the UPI payment and provided the UTR (Unique Transaction Reference), you need to confirm the transaction by submitting the UTR to our system. This step ensures the order can be verified and moved to a final status.
\nAction: Send a POST request to the confirmation endpoint using the order_id received in the deposit order response. Include the UTR in the customer_transaction_id field of the request body.
POST https://api.turbopay.com/api/s2s/deposit/confirm\nContent-Type: application/json\n\nRequest Body Example:
\n{\n \"order_id\": \"abc12345\",\n \"customer_transaction_id\": \"1234567890\"\n}\n\nResponse:
A HTTP 200 OK response indicates successful acceptance of the UTR. As a result, the order status will be updated to either success or pending.
Response example:
\n{\n \"status\": \"success\"\n}\n\nIt is strongly recommended to save the order status and adjust respective order/transaction status in your system to deliver goods, services, airtime, wallet top-up, or digital credit.
\nAt the same time you would receive a separate webhook with order status.
\nIn case of an expired status or other issue you would receive 422 response with respective error message.
\nResponse example (422):
\n{\n \"message\": \"The customer transaction id has already been taken.\",\n \"errors\": {\n \"customer_transaction_id\": [\n \"The customer transaction id has already been taken.\"\n ]\n }\n}\n\nPlease refer to the Order statuses transitions parts for more information.
\n","_postman_id":"7c577958-d081-4fe8-9be0-3c5ea253c5db"},{"name":"📤 Withdraw","item":[{"name":"Create Withdraw Order","id":"8d40712f-c25e-46f1-b715-186d7a8fa6cb","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"POST","header":[{"key":"Accept","value":"application/json"},{"key":"Authorization","value":"{{merchant_api_token}}"},{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"method\": \"bank_transfer\",\n \"amount\": 11.0,\n \"currency\": \"INR\",\n \"merchant_order_id\": \"0d37d396-ab6b-4daf-94c4-aca08c2c50df\",\n \"merchant_customer_id\": \"44e81f82-5b4d-4815-935a-bc03f56526bc\",\n \"customer_destination_account\": \"05010041281109\",\n \"bank_code\": \"HDFC0000240\",\n \"account_name\": \"Peter Pen\",\n \"customer_name\": \"Peter Pen\",\n \"customer_email\": \"peter-pen@gmail.com\",\n \"customer_phone\": \"+919811000088\",\n \"status_url\": \"https://webhook.site/96543a6e-31c6-4fc7-b8d4-21c9058ce5d5\",\n \"traffic\": \"std\"\n}","options":{"raw":{"language":"json"}}},"url":"https://api.turbopay.com/api/withdraw/new","urlObject":{"path":["withdraw","new"],"host":["https://api.turbopay.com/api"],"query":[],"variable":[]}},"response":[{"id":"55665f18-d3a1-47a5-a7fc-055274652692","name":"201 Success","originalRequest":{"method":"POST","header":[{"key":"Accept","value":"application/json"},{"key":"Authorization","value":""},{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"method\": \"bank_transfer\",\n \"amount\": 500.00,\n \"currency\": \"INR\",\n \"traffic\": \"std\",\n \"customer_email\": \"name@mail.com\",\n \"customer_phone\": \"+919876543210\",\n \"customer_name\": \"Raj Singh\",\n \"merchant_order_id\": \"30bfbb2b-f74a-4330-b419-327d1f4d50f9\",\n \"merchant_customer_id\": \"79c56284-e27f-4fd0-bb77-61b4a9881cc7\",\n \"customer_bank_account\": \"065432123456789\",\n \"bank_code\": \"HDFC0000053\",\n \"status_url\": \"https://merchant.com/status\"\n}\n","options":{"raw":{"language":"json"}}},"url":"https://api.turbopay.com/api/withdraw/new"},"status":"Created","code":201,"_postman_previewlanguage":"json","header":[{"key":"Date","value":"Wed, 25 Jun 2025 14:23:43 GMT"},{"key":"Content-Type","value":"application/json"},{"key":"Transfer-Encoding","value":"chunked"},{"key":"Connection","value":"keep-alive"},{"key":"Server","value":"cloudflare"},{"key":"Cache-Control","value":"no-cache, private"},{"key":"Vary","value":"Origin"},{"key":"Cf-Cache-Status","value":"DYNAMIC"},{"key":"Nel","value":"{\"report_to\":\"cf-nel\",\"success_fraction\":0.0,\"max_age\":604800}"},{"key":"Report-To","value":"{\"group\":\"cf-nel\",\"max_age\":604800,\"endpoints\":[{\"url\":\"https://a.nel.cloudflare.com/report/v4?s=KKAgYz9chVOeaSL7ziOKCi1n1tCHZKLkFbFmRP%2FIFSWm6oz6M8JkYQcAy6FfFleU9JxmlQsli1yU0IR8sszU9YSmrMLjxhlb1DMzBeejlVMSr0D9EsBqK8OUEg%3D%3D\"}]}"},{"key":"CF-RAY","value":"95551fbff88e54d5-MAN"},{"key":"alt-svc","value":"h3=\":443\"; ma=86400"}],"cookie":[],"responseTime":null,"body":"{\n \"order_id\": \"291fe219-af94-4512-8ea5-9efd56bf84c3\",\n \"status\": \"new\"\n}"},{"id":"a992ae72-5682-4f79-8451-4a64afe16a67","name":"422 Error Invalid request","originalRequest":{"method":"POST","header":[{"key":"Accept","value":"application/json"},{"key":"Authorization","value":"{{merchant_api_token}}"},{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"method\": \"bank_transfer\",\n \"amount\": 11.0,\n \"currency\": \"INR\",\n \"merchant_order_id\": \"ba7daff8-1ba3-49da-a06f-0344be9a1bb3\",\n \"merchant_customer_id\": \"1bc8c588-c04d-42ac-9281-04268e3b42b0\",\n \"customer_destination_account\": \"05010041281109\",\n \"bank_code\": \"HDFC0000240\",\n \"account_name\": \"Peter Pen\",\n \"customer_name\": \"Peter Pen\",\n \"customer_email\": \"peter-pen@gmail.com\",\n \"customer_phone\": \"+919811000088\",\n \"status_url\": \"https://webhook.site/96543a6e-31c6-4fc7-b8d4-21c9058ce5d5\",\n \"traffic\": \"std\"\n}","options":{"raw":{"language":"json"}}},"url":"https://api.turbopay.com/api/withdraw/new"},"status":"Unprocessable Entity","code":422,"_postman_previewlanguage":"json","header":[{"key":"Date","value":"Wed, 25 Jun 2025 14:20:14 GMT"},{"key":"Content-Type","value":"application/json"},{"key":"Transfer-Encoding","value":"chunked"},{"key":"Connection","value":"keep-alive"},{"key":"Server","value":"cloudflare"},{"key":"Cache-Control","value":"no-cache, private"},{"key":"Vary","value":"Origin"},{"key":"Cf-Cache-Status","value":"DYNAMIC"},{"key":"Nel","value":"{\"report_to\":\"cf-nel\",\"success_fraction\":0.0,\"max_age\":604800}"},{"key":"Report-To","value":"{\"group\":\"cf-nel\",\"max_age\":604800,\"endpoints\":[{\"url\":\"https://a.nel.cloudflare.com/report/v4?s=4ECmfOC3gHWRzJF4qL6DOJv6mVKKleW6DI0pXBtZA2Akq4GLpAzVHZof39Wr4FPH8zYZ9xVs%2FODeLrNHkR5yOa%2F40Mjgh%2FEyxeVBcpRzE75p%2BFAwEXEgcUSysQ%3D%3D\"}]}"},{"key":"CF-RAY","value":"95551ab60e3ad85e-MAN"},{"key":"alt-svc","value":"h3=\":443\"; ma=86400"}],"cookie":[],"responseTime":null,"body":"{\n \"message\": \"The customer bank account field is required.\",\n \"errors\": {\n \"customer_bank_account\": [\n \"The customer bank account field is required.\"\n ]\n }\n}"},{"id":"fb768624-9c51-435a-8ec3-1aade14dd25a","name":"422 Order already taken","originalRequest":{"method":"POST","header":[{"key":"Accept","value":"application/json"},{"key":"Authorization","value":"{{merchant_api_token}}"},{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"method\": \"bank_transfer\",\n \"amount\": 500.00,\n \"currency\": \"INR\",\n \"traffic\": \"std\",\n \"customer_email\": \"name@mail.com\",\n \"customer_phone\": \"+919876543210\",\n \"customer_name\": \"Raj Singh\",\n \"merchant_order_id\": \"30bfbb2b-f74a-4330-b419-327d1f4d50f8\",\n \"merchant_customer_id\": \"79c56284-e27f-4fd0-bb77-61b4a9881cc7\",\n \"customer_bank_account\": \"065432123456789\",\n \"bank_code\": \"HDFC0000053\",\n \"status_url\": \"https://merchant.com/status\"\n}\n","options":{"raw":{"language":"json"}}},"url":"https://api.turbopay.com/api/withdraw/new"},"status":"Unprocessable Entity","code":422,"_postman_previewlanguage":"json","header":[{"key":"Date","value":"Wed, 25 Jun 2025 14:22:22 GMT"},{"key":"Content-Type","value":"application/json"},{"key":"Transfer-Encoding","value":"chunked"},{"key":"Connection","value":"keep-alive"},{"key":"Server","value":"cloudflare"},{"key":"Cache-Control","value":"no-cache, private"},{"key":"Vary","value":"Origin"},{"key":"Cf-Cache-Status","value":"DYNAMIC"},{"key":"Nel","value":"{\"report_to\":\"cf-nel\",\"success_fraction\":0.0,\"max_age\":604800}"},{"key":"Report-To","value":"{\"group\":\"cf-nel\",\"max_age\":604800,\"endpoints\":[{\"url\":\"https://a.nel.cloudflare.com/report/v4?s=%2FUPj19ktwNCdqrX1aXR2665aYuzQRQ1nkKOw9fOrohWS3qszV1eI0ZRRMJZj9kvFkCzJyI4u%2Fw8Aql4PMCE%2BHAV7bl%2FutspgY%2FeqT2Ufrlj3sM2IQHrr%2FeU%3D\"}]}"},{"key":"CF-RAY","value":"95551dda08c0a935-MAN"},{"key":"alt-svc","value":"h3=\":443\"; ma=86400"}],"cookie":[],"responseTime":null,"body":"{\n \"message\": \"The merchant order id has already been taken.\",\n \"errors\": {\n \"merchant_order_id\": [\n \"The merchant order id has already been taken.\"\n ]\n }\n}"}],"_postman_id":"8d40712f-c25e-46f1-b715-186d7a8fa6cb"}],"id":"94c485e2-d5be-4958-8276-14b6ea923a99","description":"The Withdraw enables you to create a transaction to process payouts to your customers. Each request must be authenticated using your API key, following the same method as with deposit transactions.
\nDescription: Initiate the payout by calling the Create Withdrawal Order endpoint using the API. Include payment details such as the payment method, customer information, and the bank account details of the beneficiary.
Action: Submit a POST request with the required details (e.g., amount, currency, customer_bank_account, etc.), ensuring the use of your API key for authorization.
Response: A successful response includes an order_id and the initial transaction status (new).
Important: Securely store the order_id, amount, and status for future status updates and transaction reconciliation.
Example of request body:
\n{\n \"method\": \"bank_transfer\",\n \"amount\": 500.00,\n \"currency\": \"INR\",\n \"traffic\": \"std\",\n \"customer_email\": \"name@mail.com\",\n \"customer_phone\": \"+919876543210\",\n \"customer_name\": \"Raj Singh\",\n \"merchant_order_id\": \"30bfbb2b-f74a-4330-b419-327d1f4d50f8\",\n \"merchant_customer_id\": \"79c56284-e27f-4fd0-bb77-61b4a9881cc7\",\n \"customer_bank_account\": \"065432123456789\",\n \"bank_code\": \"HDFC0000053\",\n \"status_url\": \"https://merchant.com/status\"\n}\n\nRequest parameters:
\nExample of succesful response:
\n{\n \"order_id\": \"c2f0f71a-6f3f-4d65-be01-aa6b0f86cbe2\",\n \"status\": \"new\"\n}\n\n\n\nFor security reasons, please keep
\norder_idprivate and do not make it available neither to the public nor to end customers.
Response parameters:
\nIn case of an error in the request data, our server will respond with a respective Response code and message.
\nDescription: Track the withdrawal order’s progress as it transitions through statuses (new, pending, success, failed). Each status update is sent to the merchant-hosted status_url provided during order creation.
Action: Use the order_id to monitor the transaction status via webhook callbacks or API queries. Ensure you handle status changes appropriately in your system.
Response: The final status will be either success or failed. Updates will include the order_id and the current status.
Important: Handle the final status (success or failed) carefully, and consider rare cases where a success status may transition to failed.
\n\nFinal status normally means that it cannot be changed anymore. However, in certain rare cases depending on the payment method and flow, we can change the order status from success to failed, which will be clearly communicated to you each time.
\n
Each change of the order status will trigger a webhook to your designated status URL with the respective order_id and status. Please refer to the Webhooks part for more information.
\n","_postman_id":"94c485e2-d5be-4958-8276-14b6ea923a99"},{"name":"Balance","item":[{"name":"Balance check","id":"37b9ec46-2044-416a-b46f-e8f77906dcc6","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"Authorization","value":"{{merchant_api_token}}","type":"text"},{"key":"Accept","value":"application/json","type":"text"}],"url":"https://api.turbopay.com/api/balance?currency=","urlObject":{"path":["balance"],"host":["https://api.turbopay.com/api"],"query":[{"key":"currency","value":""}],"variable":[]}},"response":[{"id":"72044bce-ab93-4995-9d99-ce4e506c3aa8","name":"200 Success","originalRequest":{"method":"GET","header":[{"key":"Authorization","value":"","type":"text"},{"key":"Accept","value":"application/json","type":"text"}],"url":{"raw":"https://api.turbopay.com/api/balance?currency=","host":["https://api.turbopay.com/api"],"path":["balance"],"query":[{"key":"currency","value":""}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Date","value":"Wed, 25 Jun 2025 14:26:56 GMT"},{"key":"Content-Type","value":"application/json"},{"key":"Transfer-Encoding","value":"chunked"},{"key":"Connection","value":"keep-alive"},{"key":"Server","value":"cloudflare"},{"key":"Cache-Control","value":"no-cache, private"},{"key":"Vary","value":"Origin"},{"key":"Cf-Cache-Status","value":"DYNAMIC"},{"key":"Nel","value":"{\"report_to\":\"cf-nel\",\"success_fraction\":0.0,\"max_age\":604800}"},{"key":"Report-To","value":"{\"group\":\"cf-nel\",\"max_age\":604800,\"endpoints\":[{\"url\":\"https://a.nel.cloudflare.com/report/v4?s=Ulhi%2F9AHv%2FQtwpUDxb6VOYwNwXL4fWYHtiDkVHbp6uK%2BKK%2FBeJT6zUbfuQXPDjqYUC6KtNj01arw4PYqX7eFs2VRKEDDKNqyaPe1kYkVal%2F5%2BMxkP7dIOGvcrA%3D%3D\"}]}"},{"key":"Content-Encoding","value":"br"},{"key":"CF-RAY","value":"955524861a7bccb2-MAN"},{"key":"alt-svc","value":"h3=\":443\"; ma=86400"}],"cookie":[],"responseTime":null,"body":"{\n \"account_id\": \"alisa-test\",\n \"currency\": \"INR\",\n \"available_balance\": \"-2.2800\",\n \"total_balance\": \"-2.2800\"\n}"},{"id":"7d7a6254-8e85-4442-98f8-3d4405140e2d","name":"401 Unauthorized","originalRequest":{"method":"GET","header":[{"key":"Authorization","value":"{{merchant_api_token}}","type":"text"},{"key":"Accept","value":"application/json","type":"text"}],"url":{"raw":"https://api.turbopay.com/api/balance?currency=","host":["https://api.turbopay.com/api"],"path":["balance"],"query":[{"key":"currency","value":""}]}},"status":"Unauthorized","code":401,"_postman_previewlanguage":"json","header":[{"key":"Date","value":"Wed, 25 Jun 2025 14:27:46 GMT"},{"key":"Content-Type","value":"application/json"},{"key":"Transfer-Encoding","value":"chunked"},{"key":"Connection","value":"keep-alive"},{"key":"Server","value":"cloudflare"},{"key":"Cache-Control","value":"no-cache, private"},{"key":"Vary","value":"Origin"},{"key":"Cf-Cache-Status","value":"DYNAMIC"},{"key":"Nel","value":"{\"report_to\":\"cf-nel\",\"success_fraction\":0.0,\"max_age\":604800}"},{"key":"Report-To","value":"{\"group\":\"cf-nel\",\"max_age\":604800,\"endpoints\":[{\"url\":\"https://a.nel.cloudflare.com/report/v4?s=ZO7b2gBzW0DMIOw3VeG2pZ%2B7aOg9Pn7AF%2FdDRdHwP62K1C59socmWhi%2BWzq3Mdbo6bKz%2BOkH%2FOZAdJrQ%2BgMM8iL32iTlkqRD3iatH66AMsNktnLregyze9RV8Q%3D%3D\"}]}"},{"key":"CF-RAY","value":"955525c79875ccb2-MAN"},{"key":"alt-svc","value":"h3=\":443\"; ma=86400"}],"cookie":[],"responseTime":null,"body":"{\n \"message\": \"Unauthorized\"\n}"}],"_postman_id":"37b9ec46-2044-416a-b46f-e8f77906dcc6"}],"id":"58f5e838-b115-4fea-a0a4-e264b510cff3","description":"The Balance endpoint provides access to both your total and available balance. Please remember to authenticate each request with the API key in the same way as Deposits.
\n\n\n","_postman_id":"58f5e838-b115-4fea-a0a4-e264b510cff3"},{"name":"🪝Webhooks","item":[],"id":"1a91eb14-42ca-4d0f-b658-63dbe62b02ff","description":"The default balance endpoint returns INR currency if not specified. To specify currency, use the param in the request.
\n
You should provide a webhook URL (called status_url) with each deposit or withdrawal request you make. This will ensure that we send a webhook with order status to the most up-to-date and correct address.
Due to the specific nature of some of our payment methods and flows, each order can change its status and amount within time and may not possess final status (success or failed) immediately. Thus maintaining a webhook URL is vital to efficiently process payments for your customers. We recommend that you save and update your records with all the information received.
A webhook URL is simply a POST endpoint that our server sends updates to.
\nThe URL needs to parse a JSON request and return a 200 OK in the HTTP header.
\n{\n \"order_id\": \"849655cf-ceba-49bc-951a-cbfbf8d63274\",\n \"merchant_order_id\": \"O_XVajPtgGFk173LluM5oKb\",\n \"status\": \"success\",\n \"reason\": \"some reason\",\n \"amount\": \"200.00\",\n \"utr\": \"409876543210\",\n \"target_upi_id\": \"deposit@test\",\n \"merchant_customer_id\": \"aaaaaaa99-1290-3e9f-a08e-c03aedc68b35\"\n}\n\n{\n \"order_id\": \"c2f0f71a-6f3f-4d65-be01-aa6b0f86cbe2\",\n \"merchant_order_id\": \"ABC00001\",\n \"status\": \"failed\",\n \"reason\": \"some reason\",\n \"amount\": \"300\",\n \"utr\": \"409876543210\",\n \"error_code\": \"ERR_001\",\n \"error_message\": \"Payout service under maintenance. Try again later.\"\n}\n\n⚠️ Note:
\nFields error_code and error_message are present only if \"status\": \"failed\".
If \"status\": \"success\", these fields will not be included.
utr → Unique transaction reference received from the bank.
\nreason → Short description of a failed order reason.
\nmerchant_order_id → The order/transaction reference of the merchant provided during the initial create order request.
\nThe system will automatically retry sending the webhook 3 times.
\nIf delivery still fails, we recommend manually resend it from the Back Office and verify that your server is able to receive it.
\nSignature validation
\nSince your webhook URL is publicly available and sensitive data about order ID and its status is transmitted, you need to keep your webhook URL confidential and verify that events originate from our server and not from a bad actor.
\n\n\nWe may not accept responsibility for non-validated webhooks. If you do not perform validation you’re accepting the risks of malicious order statuses.
\n
Events sent from KarmaPe carry the x-pay-signature header. The value of this header is an HMAC SHA256 signature of the event payload (JSON string) signed using your webhook key.
\n\n\nVerifying the header signature should be done before processing the event. As a reference you can use this sandbox: https://www.devglan.com/online-tools/hmac-sha256-online
\n
Each change of the order status will trigger a webhook to your status URL with the respective order_id, amount, and status.
Once we proceed to processing of an order, you will get a pending order status notification:
\nExample body (JSON string) :
\n{\"order_id\":\"849655cf-ceba-49bc-951a-cbfbf8d63274\",\"merchant_order_id\":\"O_XVajPtgGFk173LluM5oKb\",\"status\":\"pending\",\"reason\":\"some reason\",\"amount\":\"200.00\",\"utr\":\"409876543210\",\"target_upi_id\": \"deposit@test\", \"merchant_customer_id\": \"aaaaaaa99-1290-3e9f-a08e-c03aedc68b35\"}\n\nOnce the payment is completed and we verify it, you will get a successful order status notification.
\nYou can also manually trigger a webhook for an order by using the “Resend callback” button in the back office.
\n\n\nDepending on the payment method and flow an order can change not only its status but also the amount. Your system should be able to receive an order amount different from the amount initially requested and adjust the scope of service or product quantity respectively. You will notice that each order has a requested amount and an actual amount in our back office, but you would receive only one most actual amount in the webhook. In case your system does not accept different requested and actual amounts, please let us know about that during the integration process.
\n
\n\nIf you offer digital value like airtime, wallet top-up, digital credit, etc, always confirm that you have not already delivered value for that transaction to avoid double fulfillments, especially, if you also use webhooks.
\n
It is recommended to store order_id in your system for reconciliation purposes.
To get current order status and initiate a webhook to your server you can use Order status check endpoint. Please make sure that you use the standard authentication with your API key. Keep in mind that the primary method for receiving status updates is through webhooks; this endpoint should only be used in rare cases where the webhook was not received. Please note that this endpoint is rate-limited to 60 requests per minute.
\nRequest: GET https://api.turbopay.com/api/order/status/{{order_id}}
No JSON body is required. Parameter {{order_id}} implies KarmaPe order ID, not merchant’s.
\nResponse
In case of a successful result, you will receive a 200 response and JSON with order details:
{\n \"order_id\": \"c2f0f71a-6f3f-4d65-be01-aa6b0f86cbe2\",\n \"merchant_order_id\": \"ABC00001\",\n \"status\": \"success\",\n \"reason\": \"some reason\",\n \"amount\": \"300\",\n \"utr\": \"409876543210\"\n}\n\nSimultaneously a webhook with order status to your status URL will be initiated.
\nIn case of a failed result, you will receive a 4 response code and JSON with details:
\nRequest: GET https://api.turbopay.com/api/merchantorder/status/{{merchant_order_id}}
No JSON body is required. Parameter {{merchant_order_id}} implies the Merchant’s Order ID, not KarmaPe’s.
\n","_postman_id":"8bda7a6e-1384-439b-a069-b09cf0371975"},{"name":"Response codes","item":[],"id":"82cf251f-6d64-45eb-9a9e-10748c187c97","description":"Our API is RESTful and as such, uses conventional HTTP response codes to indicate the success or failure of requests. Some of the most common response examples include:
\n","_postman_id":"82cf251f-6d64-45eb-9a9e-10748c187c97"},{"name":"Order statuses transitions","item":[],"id":"6f8bbe42-b6e8-415f-8661-7e27a2210785","description":"KarmaPe gateway comes with an order status transition concept that allows a merchant to get information on the current state of a payment, i.e. if funds have been transferred or if a customer canceled the transaction etc.
\nBased on the dedicated status that is always returned through our API, you may take appropriate actions, such as delivering the service, contacting the customer for clarification or similar.
\n","_postman_id":"6f8bbe42-b6e8-415f-8661-7e27a2210785"},{"name":"✅ Go-live checklist","item":[],"id":"170e983c-64ac-465d-a267-d39d01373b2d","description":"Please refer to this checklist to ensure a smooth launch of your live payment processing:
\nComplete and test integration in live mode including edge cases:
\nDeposit order creation
\nWithdrawal order creation
\nIncomplete data
\nInvalid data
\nDuplicate data
\nMake sure your application handles all errors
\nMake sure you have proper logging of requests and responses
\nMake sure your status URL is publicly available
\nMake sure you send the status URL with each order
\nMake sure that you validate our webhook signature
\nMake sure you set respective order (transaction) status and amount on your side once new webhook is received from our server
\nMake sure that you deliver/deduct goods, services, or digital credit once receive a successful order status callback from our server
\nMake sure all your production server’s IPs are whitelisted on our side
\nMake sure all our production server’s IPs are whitelisted on your side (if required)
\nMake sure you have access to our back office and can track all orders and their statuses
\nArrange the time and date of the start of processing with our tech team
\nGet the green light from our tech team that you can start live processing
\nMonitor first live customer transactions in both your and our system
\nWhen a previously successful deposit transaction is identified as a chargeback, the order status is updated as follows:
\nPrevious status: success
New status: chargeback
Reason value - here will be a specific reason for the chargeback
\nWhen the transaction status changes to chargeback, the merchant system receives a webhook notification.
{\n \"order_id\": \"849655cf-ceba-49bc-951a-cbfbf8d63274\",\n \"merchant_order_id\": \"O_XVajPtgGFk173LluM5oKb\",\n \"status\": \"chargeback\",\n \"reason\": \"chargeback\", // ask support for proper resaon if needed\n \"amount\": \"200.00\",\n \"utr\": \"409876543210\",\n \"target_upi_id\": \"deposit@test\",\n \"merchant_customer_id\": \"aaaaaaa99-1290-3e9f-a08e-c03aedc68b35\",\n \"claim_id\": \"<cyber_complaint_id>\"\n}\n\nA complaint is detected for an account.
\nRelated transaction is identified.
\nTransaction data is verified:
\nUTR
\nAmount
\nOrder ID
\nMerchant Customer ID
\nSupporting documents (PDF + screenshot) are attached internally.
\nOrder status is updated:
\nsuccess → chargebackWebhook notification is sent to the merchant system.
\nChargeback events are delivered only via webhook.
\nMerchants should handle chargeback status as a final state.
claim_id can be used for reconciliation and support communication.
Amount value always reflects the original credited deposit amount.
\n