Welcome to the Waza payouts API documentation. This API provides a suite of services designed for businesses who want to make local currency payouts to our supported countries. This API follows the RESTful HTTP design pattern, ensuring ease of use, scalability, and compatibility.
\nTo ensure that the requests made to our endpoints are both secure and authenticated, we use API key-based authentication. Every request made to this API requires an API key to be included in the request header (x-waza-key). Please contact us to have a sandbox account and API keys created for you.
\nFor detailed information on our API endpoints, request/response formats, status codes, and examples, please navigate to the respective sections in this documentation. All successful 2XX responses are wrapped in a data object.
Errors are an inevitable part of any system. At Waza, we believe in providing clear, actionable error feedback to help our customers diagnose and easily resolve issues. Our API follows standard HTTP error codes and provides a consistent error body format.
\nWhen an error occurs, the API will return an error response in the following format:
\n{\n \"error\": {\n \"message\": \"Human-readable message detailing the error.\",\n \"code\": \"Unique error code for reference and programmatic handling.\",\n \"description\": \"Short description categorising the nature of the error.\",\n }\n}\n\nmessage: A user-friendly message explaining the error. This can be displayed directly to the end-users or used for debugging purposes.
\ncode: A unique error code that can be used for reference. If you're contacting support regarding an issue, providing this code can expedite the troubleshooting process. This is also useful for programmatically handling errors in your application.
\ndescription: A brief description categorising the nature of the error.
\nfield_errors (optional): A list of failed validation when making resource changing requests, specifies the field and error message. Example below
\n{\n \"error\": {\n \"message\": \"Invalid request in body\",\n \"code\": \"400\",\n \"description\": \"INVALID_REQUEST\",\n \"field_errors\": [\n {\n \"field\": \"url\",\n \"message\": \"URL must not be localhost or 127.0.0.1.\"\n },\n {\n \"field\": \"enabled_events.0\",\n \"message\": \"\\\"enabled_events[0]\\\" must be one of [transaction.created, transaction.processing, transaction.completed, transaction.failed]\"\n },\n {\n \"field\": \"enabled_events.0\",\n \"message\": \"\\\"enabled_events[0]\\\" is not allowed to be empty\"\n }\n ]\n }\n}\n\nResponses from paginated endpoints are structured as follows:
\n{\n \"data\": {\n \"items\": [], // The actual data items for the current page\n \"total_items\": 0, // The total number of items across all pages\n \"page\": 1, // The current page number\n \"limit\": 10, // The number of items per page (page size)\n \"total_pages\": 1 // The total number of pages available\n }\n}\n\nitems: An array containing the actual data items for the current page.
\ntotal_items: The total number of items across all pages.
\npage: The current page number.
\nlimit: The number of items per page, also referred to as the page size.
\ntotal_pages: The total number of pages available given the current page size.
\nTo request a specific page or change the page size (limit), use the page and limit query parameters, respectively.
page (optional): Specifies which page number you want to retrieve. If not provided, defaults to the first page.
\nlimit (optional): Defines how many items you want to retrieve per page. If not provided, a default size (e.g., 10 items) is used.
\nNavigating through Pages: Begin with page=1 and incrementally adjust the page number until the returned total_pages value is met.
Tailoring Page Size: If dealing with numerous minor entries or if bandwidth isn't a concern, consider amplifying the limit. In contrast, reduce the limit if data items are extensive or bandwidth is constrained.
Managing Extensive Datasets: Constantly monitor total_items and total_pages. With significantly large datasets in view, employ strategies like filtering or sorting to minimize the items you need to process.
If you have any queries or issues, our support team is always here to help. Reach out to us at support@waza.co
NG for Nigeria.The response is structured as an array of payout methods available for the specified country.
\nEach payout method contains
\ncountry: The country code.
\ntype: The type of payout method.
\nbeneficiary_requirements: A list of requirements for the beneficiary.
\nEach requirement within beneficiary_requirements has:
description: A textual description of the requirement.
\nfield: The name of the field as it should be used in API requests.
\ntype: The data type of the field.
\nrequired: A boolean indicating whether this field is mandatory.
\nmetadata (optional): Additional information about the requirement.
\nThis endpoint provides a list of available payout methods for a given country. It's designed to aid developers in understanding the requirements for performing a payout in a specific region.
\n","_postman_id":"f65e9ccf-728b-44f5-a45c-afb6c7bce819","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"x-waza-key"},{"key":"value","value":"3PuDo1xS6akdBwAyczyOOVznUChK6ITD"}]},"isInherited":true,"source":{"_postman_id":"7eb6cb17-d551-4ed0-9224-d17b4990f8f7","id":"7eb6cb17-d551-4ed0-9224-d17b4990f8f7","name":"Vanir API","type":"collection"}}},{"name":"Data","item":[{"name":"NG","item":[{"name":"Banks List","id":"29de5634-bcd1-44ef-8702-a4e5b33ea0ab","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"https://api.sandbox.waza.co/payouts/v1/ng/banks","description":"This endpoint provides a list of available banks for Nigeria. This list aids developers in understanding the available banks they can make payouts.
\nThe response returns a list of banks available in Nigeria. Each bank contains:
\nbank_code: A unique code that identifies the bank. This code is used in API requests when specifying a bank.
\nbank_name: The official name of the bank.
\nThis endpoint is especially useful in conjunction with the /payouts/v1/payout-methods endpoint. When making a payout to a bank account in Nigeria, use the bank_code from this endpoint to specify the bank in your payout request.
The account name enquiry endpoint provides a way to confirm the name associated with a bank account number in Nigeria. This is crucial for verification purposes before initiating payouts to ensure the legitimacy and accuracy of the destination bank account.
\naccount_number: The bank account number you wish to look up. It should be a valid account number for the bank specified by bank_code.
bank_code: The unique code that identifies the bank. You can obtain valid bank_code values from the /payouts/v1/ng/banks endpoint.
The response returns details about the queried bank account:
\naccount_name: The name associated with the queried bank account number.
\naccount_number: The bank account number you looked up.
\nbank_code: The bank's unique identification code.
\nbank_name: The official name of the bank.
\nThis endpoint is valuable when you need to verify the name associated with a bank account before making a payout. It can help prevent mistaken transfers and give an added layer of trust and confidence in the transaction process.
\nIf errors (e.g., invalid bank code, non-existent account number) occur, the API will return a structured error message detailing the issue. For a detailed understanding of error formats and resolutions, refer to the \"Error Handling\" section of this documentation.
\n","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"x-waza-key"},{"key":"value","value":"3PuDo1xS6akdBwAyczyOOVznUChK6ITD"}]},"isInherited":true,"source":{"_postman_id":"7eb6cb17-d551-4ed0-9224-d17b4990f8f7","id":"7eb6cb17-d551-4ed0-9224-d17b4990f8f7","name":"Vanir API","type":"collection"}},"urlObject":{"path":["ng","accounts","lookup"],"host":["https://api.sandbox.waza.co/payouts/v1"],"query":[{"key":"account_number","value":"0127909007"},{"key":"bank_code","value":"1"}],"variable":[]}},"response":[{"id":"d683c531-d429-469e-ad0b-2a43ee927020","name":"[200] Name Enquiry","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://api.sandbox.waza.co/payouts/v1/ng/account/lookup?account_number=12229&bank_code=008","host":["https://api.sandbox.waza.co/payouts/v1"],"path":["ng","account","lookup"],"query":[{"key":"account_number","value":"12229"},{"key":"bank_code","value":"008"}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"X-Powered-By","value":"Express"},{"key":"X-Frame-Options","value":"DENY"},{"key":"Content-Type","value":"application/json; charset=utf-8"},{"key":"Content-Length","value":"105"},{"key":"ETag","value":"W/\"69-EURJOmjrQWfLXsG/69TCRY72IYA\""},{"key":"Date","value":"Fri, 14 Jul 2023 12:47:43 GMT"},{"key":"Connection","value":"keep-alive"},{"key":"Keep-Alive","value":"timeout=5"}],"cookie":[],"responseTime":null,"body":"{\n \"data\": {\n \"account_name\": \"John Doe\",\n \"account_number\": \"12229\",\n \"bank_code\": \"008\",\n \"bank_name\": \"Access Bank\"\n }\n}"},{"id":"9fc9327f-86b4-40ad-976b-66740ebdb620","name":"[400] Name Enquiry","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://api.sandbox.waza.co/payouts/v1/ng/account/lookup?account_number=12229&bank_code=","host":["https://api.sandbox.waza.co/payouts/v1"],"path":["ng","account","lookup"],"query":[{"key":"account_number","value":"12229"},{"key":"bank_code","value":""}]}},"status":"Bad Request","code":400,"_postman_previewlanguage":"json","header":[{"key":"X-Powered-By","value":"Express"},{"key":"X-Frame-Options","value":"DENY"},{"key":"Content-Type","value":"application/json; charset=utf-8"},{"key":"Content-Length","value":"140"},{"key":"ETag","value":"W/\"8c-hhqieSZSn9VEHXLrzYx/o+zo8iA\""},{"key":"Date","value":"Fri, 14 Jul 2023 12:48:19 GMT"},{"key":"Connection","value":"keep-alive"},{"key":"Keep-Alive","value":"timeout=5"}],"cookie":[],"responseTime":null,"body":"{\n \"error\": {\n \"message\": \"Invalid request in query\",\n \"field_errors\": [\n {\n \"field\": \"bank_code\",\n \"message\": \"\\\"bank_code\\\" is not allowed to be empty\"\n }\n ]\n }\n}"},{"id":"a8a128bc-1b2b-4c81-8bd5-961c10b61607","name":"[404] Name Enquiry","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://api.sandbox.waza.co/payouts/v1/ng/account/lookup?account_number=0000000000&bank_code=009","host":["https://api.sandbox.waza.co/payouts/v1"],"path":["ng","account","lookup"],"query":[{"key":"account_number","value":"0000000000"},{"key":"bank_code","value":"009"}]}},"status":"Not Found","code":404,"_postman_previewlanguage":"json","header":[{"key":"X-Powered-By","value":"Express"},{"key":"X-Frame-Options","value":"DENY"},{"key":"Content-Type","value":"application/json; charset=utf-8"},{"key":"Content-Length","value":"115"},{"key":"ETag","value":"W/\"73-OOq5G7vsOw+EhH5b94lwr9poBIs\""},{"key":"Date","value":"Fri, 14 Jul 2023 12:54:00 GMT"},{"key":"Connection","value":"keep-alive"},{"key":"Keep-Alive","value":"timeout=5"}],"cookie":[],"responseTime":null,"body":"{\n \"error\": {\n \"message\": \"No account found for bank_code 009 and account_number 0000000000\",\n \"code\": \"ACCOUNT_NOT_FOUND\"\n }\n}"}],"_postman_id":"c27f40cb-24db-40ce-9ebd-7d270b5c6d77"}],"id":"53090477-6f7d-4b55-8419-6f0f314b03fe","description":"Requests specific to Nigeria
\n","_postman_id":"53090477-6f7d-4b55-8419-6f0f314b03fe","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"x-waza-key"},{"key":"value","value":"3PuDo1xS6akdBwAyczyOOVznUChK6ITD"}]},"isInherited":true,"source":{"_postman_id":"7eb6cb17-d551-4ed0-9224-d17b4990f8f7","id":"7eb6cb17-d551-4ed0-9224-d17b4990f8f7","name":"Vanir API","type":"collection"}}}],"id":"a957bd65-01fb-4ce9-89fa-8f420a0fe4d2","description":"Contains endpoints to provide supporting information for creating payouts
\n","_postman_id":"a957bd65-01fb-4ce9-89fa-8f420a0fe4d2","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"x-waza-key"},{"key":"value","value":"3PuDo1xS6akdBwAyczyOOVznUChK6ITD"}]},"isInherited":true,"source":{"_postman_id":"7eb6cb17-d551-4ed0-9224-d17b4990f8f7","id":"7eb6cb17-d551-4ed0-9224-d17b4990f8f7","name":"Vanir API","type":"collection"}}},{"name":"Balances","item":[{"name":"List Balances","id":"6a41cdda-499f-4418-bbb8-04fbf46343f6","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"https://api.sandbox.waza.co/payouts/v1/balances","description":"The balances endpoint provides an overview of your available funds in various currencies and countries. This is especially useful for businesses operating across multiple regions, enabling a comprehensive view of available resources for making payouts or other transactions.
\nThe response will return a list of available balances:
\nid: A unique identifier for the balance record.
\ncurrency: The currency code of the balance, e.g., \"NGN\" for Nigerian Naira.
\ncountry: The ISO country code indicates the country associated with this balance.
\namount: The available balance amount in the smallest currency unit (e.g., for NGN, this would represent kobo). Ensure to handle conversions correctly in your application.
\ntimestamp: The datetime when the balance was last updated, in ISO 8601 format.
\nmetadata: Any additional information or data related to the balance. This field can be empty.
\nYou can use this endpoint to:
\nMonitor available funds: Before making a payout or any other transaction, you can check the available balance in the desired currency and country.
\nReconciliation: Match and reconcile balance amounts with your internal records to ensure consistency and catch any discrepancies.
\nReporting: Generate financial reports on available funds for internal or regulatory purposes.
\nThe /transactions endpoint facilitates the initiation of funds transfer to beneficiaries. By providing details about the amount, beneficiary, sender, and other optional metadata, you can execute payouts seamlessly through this endpoint.
Upon a successful transaction initiation, the API will return the transaction details:
\nid: A unique identifier for the transaction.... [other fields similar to the request body]
\nstate: The current status of the transaction. E.g., \"PENDING\". (states are PENDING, PROCESSING, COMPLETED, FAILED)
created_date: Timestamp indicating when the transaction was initiated.
balance_before: Balance before the transaction in the smallest unit.
balance_after: Balance after the transaction in the smallest unit.
completion_date: Optional date of transaction completion (Available only for completed transfers)
... [and other transaction details]
\n","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"x-waza-key"},{"key":"value","value":"3PuDo1xS6akdBwAyczyOOVznUChK6ITD"}]},"isInherited":true,"source":{"_postman_id":"7eb6cb17-d551-4ed0-9224-d17b4990f8f7","id":"7eb6cb17-d551-4ed0-9224-d17b4990f8f7","name":"Vanir API","type":"collection"}},"urlObject":{"path":["transactions"],"host":["https://api.sandbox.waza.co/payouts/v1"],"query":[],"variable":[]}},"response":[{"id":"874c0306-b84b-4918-8f0e-999015da2fdb","name":"400 Insufficient Balance","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"amount\": 72000000,\n \"currency\": \"NGN\",\n \"country\": \"NG\",\n \"beneficiary\": {\n \"type\": \"BANK_ACCOUNT\",\n \"account_name\": \"James Blunt\",\n \"account_number\": \"12349999\",\n \"bank_code\": \"090365\",\n \"bank_name\": \"Access Bank\"\n },\n \"customer_reference\": \"1234ab\",\n \"metadata\": {\n \"reason\": \"Payment from APP\"\n },\n \"sender\": {\n \"name\": \"Emmanuel Igbodudu\"\n }\n}","options":{"raw":{"language":"json"}}},"url":"https://api.sandbox.waza.co/payouts/v1/transactions"},"status":"Bad Request","code":400,"_postman_previewlanguage":"json","header":[{"key":"Date","value":"Mon, 17 Jul 2023 00:14:56 GMT"},{"key":"Content-Type","value":"application/json; charset=utf-8"},{"key":"Content-Length","value":"140"},{"key":"Connection","value":"keep-alive"},{"key":"X-Powered-By","value":"Express"},{"key":"waza-request-id","value":"7f34f77a-af24-453d-ac1a-14cb931d4509"},{"key":"X-Frame-Options","value":"DENY"},{"key":"ETag","value":"W/\"8c-rcxyCuK5qrWzLY75++hfzZPy86M\""}],"cookie":[],"responseTime":null,"body":"{\n \"error\": {\n \"message\": \"Insufficient Balance of ₦940000.00, requires ₦35060000.00 more\",\n \"code\": \"012\",\n \"description\": \"INSUFFICIENT_BALANCE\"\n }\n}"},{"id":"6c798b24-731c-4d8c-9e18-6177dc7546f8","name":"409 Exisgin customer reference","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"amount\": 18000,\n \"currency\": \"NGN\",\n \"country\": \"NG\",\n \"beneficiary\": {\n \"type\": \"BANK_ACCOUNT\",\n \"account_name\": \"James Blunt\",\n \"account_number\": \"12349999\",\n \"bank_code\": \"090365\",\n \"bank_name\": \"Access Bank\"\n },\n \"customer_reference\": \"1234a\",\n \"metadata\": {\n \"reason\": \"Payment from APP\"\n },\n \"sender\": {\n \"name\": \"Emmanuel Igbodudu\"\n }\n}","options":{"raw":{"language":"json"}}},"url":"https://api.sandbox.waza.co/payouts/v1/transactions"},"status":"Conflict","code":409,"_postman_previewlanguage":"json","header":[{"key":"Date","value":"Mon, 17 Jul 2023 00:17:00 GMT"},{"key":"Content-Type","value":"application/json; charset=utf-8"},{"key":"Content-Length","value":"146"},{"key":"Connection","value":"keep-alive"},{"key":"X-Powered-By","value":"Express"},{"key":"waza-request-id","value":"2568d0d5-fabb-421b-b72e-c25201c46b48"},{"key":"X-Frame-Options","value":"DENY"},{"key":"ETag","value":"W/\"92-m6hPJEuvnUoQNNdh38a/I9AJY/c\""}],"cookie":[],"responseTime":null,"body":"{\n \"error\": {\n \"message\": \"Transfer with customer reference 1234a already exists\",\n \"code\": \"014\",\n \"description\": \"EXISTING_TRANSACTION_CUSTOMER_REFERENCE\"\n }\n}"},{"id":"518c578b-4132-408f-86f8-048fd4f940ae","name":"400 Account Lookup Failure","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"amount\": 18000,\n \"currency\": \"NGN\",\n \"country\": \"NG\",\n \"beneficiary\": {\n \"type\": \"BANK_ACCOUNT\",\n \"account_name\": \"James Blunt\",\n \"account_number\": \"12340000\",\n \"bank_code\": \"090365\",\n \"bank_name\": \"Access Bank\"\n },\n \"customer_reference\": \"1234a\",\n \"metadata\": {\n \"reason\": \"Payment from APP\"\n },\n \"sender\": {\n \"name\": \"Emmanuel Igbodudu\"\n }\n}","options":{"raw":{"language":"json"}}},"url":"https://api.sandbox.waza.co/payouts/v1/transactions"},"status":"Bad Request","code":400,"_postman_previewlanguage":"json","header":[{"key":"Date","value":"Mon, 17 Jul 2023 00:17:27 GMT"},{"key":"Content-Type","value":"application/json; charset=utf-8"},{"key":"Content-Length","value":"140"},{"key":"Connection","value":"keep-alive"},{"key":"X-Powered-By","value":"Express"},{"key":"waza-request-id","value":"b2e06ad3-e4c5-4a7f-bd12-e576bfc21c66"},{"key":"X-Frame-Options","value":"DENY"},{"key":"ETag","value":"W/\"8c-jGnK9RSoFe+QRzmzTRzRTFnLdLA\""}],"cookie":[],"responseTime":null,"body":"{\n \"error\": {\n \"message\": \"No account found for bank_code 090365 and account_number 12340000\",\n \"code\": \"011\",\n \"description\": \"ACCOUNT_LOOKUP_FAILED\"\n }\n}"},{"id":"d4e7e599-8af0-4bab-a21d-1ac3a7996f9c","name":"400 Unsupported Country","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"amount\": 18000,\n \"currency\": \"NGN\",\n \"country\": \"US\",\n \"beneficiary\": {\n \"type\": \"BANK_ACCOUNT\",\n \"account_name\": \"James Blunt\",\n \"account_number\": \"123400001\",\n \"bank_code\": \"090365\",\n \"bank_name\": \"Access Bank\"\n },\n \"customer_reference\": \"1234a\",\n \"metadata\": {\n \"reason\": \"Payment from APP\"\n },\n \"sender\": {\n \"name\": \"Emmanuel Igbodudu\"\n }\n}","options":{"raw":{"language":"json"}}},"url":"https://api.sandbox.waza.co/payouts/v1/transactions"},"status":"Bad Request","code":400,"_postman_previewlanguage":"json","header":[{"key":"Date","value":"Mon, 17 Jul 2023 00:18:01 GMT"},{"key":"Content-Type","value":"application/json; charset=utf-8"},{"key":"Content-Length","value":"106"},{"key":"Connection","value":"keep-alive"},{"key":"X-Powered-By","value":"Express"},{"key":"waza-request-id","value":"782aeb4e-f670-48dc-8886-0623dd7bc557"},{"key":"X-Frame-Options","value":"DENY"},{"key":"ETag","value":"W/\"6a-aRjdEkiAbudYVN0xP7OVrrDVuDs\""}],"cookie":[],"responseTime":null,"body":"{\n \"error\": {\n \"message\": \"Only Nigerian transfers are supported\",\n \"code\": \"013\",\n \"description\": \"INVALID_REQUEST\"\n }\n}"},{"id":"910da5d2-882d-44cd-9ff7-8156f2ac9545","name":"200 Successful","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"amount\": 18000,\n \"currency\": \"NGN\",\n \"country\": \"NG\",\n \"beneficiary\": {\n \"type\": \"BANK_ACCOUNT\",\n \"account_name\": \"James Blunt\",\n \"account_number\": \"123400001\",\n \"bank_code\": \"090365\",\n \"bank_name\": \"Access Bank\"\n },\n \"customer_reference\": \"1234ab\",\n \"metadata\": {\n \"reason\": \"Payment from APP\"\n },\n \"sender\": {\n \"name\": \"Emmanuel Igbodudu\"\n }\n}","options":{"raw":{"language":"json"}}},"url":"https://api.sandbox.waza.co/payouts/v1/transactions"},"status":"Created","code":201,"_postman_previewlanguage":"json","header":[{"key":"Date","value":"Mon, 17 Jul 2023 00:18:28 GMT"},{"key":"Content-Type","value":"application/json; charset=utf-8"},{"key":"Content-Length","value":"474"},{"key":"Connection","value":"keep-alive"},{"key":"X-Powered-By","value":"Express"},{"key":"waza-request-id","value":"b25b4052-ab7e-4329-b947-830ff5a3d9f6"},{"key":"X-Frame-Options","value":"DENY"},{"key":"ETag","value":"W/\"1da-yEeo6YhuTL2Swo7/Z/KmGoZ/qmQ\""}],"cookie":[],"responseTime":null,"body":"{\n \"data\": {\n \"id\": \"waza_trf_LHg8_1689553108124\",\n \"amount\": 18000,\n \"currency\": \"NGN\",\n \"country\": \"NG\",\n \"beneficiary\": {\n \"type\": \"BANK_ACCOUNT\",\n \"account_name\": \"Frank Sani\",\n \"account_number\": \"123400001\",\n \"bank_code\": \"090365\",\n \"bank_name\": \"CORESTEP MICROFINANCE BANK\"\n },\n \"state\": \"PENDING\",\n \"created_date\": \"2023-07-17T00:18:28.124Z\",\n \"completion_date\": \"2023-07-17T00:18:28.125Z\",\n \"customer_reference\": \"1234ab\",\n \"metadata\": {\n \"reason\": \"Payment from APP\"\n },\n \"balance_before\": 1880000,\n \"balance_after\": 1862000\n }\n}"}],"_postman_id":"b29939b9-1d21-451a-9acc-e926ee515aaf"},{"name":"Get by ID","id":"830a4e26-7357-4ab9-ac4c-7ea35976c419","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"https://api.sandbox.waza.co/payouts/v1/transactions/:id","description":"The /transactions/:id endpoint allows clients to retrieve details of a specific transaction by its unique identifier. This is particularly useful when you want to query the status or details of a transaction that was previously initiated.
Upon successful retrieval, the API will return the transaction details:
\nid: A unique identifier for the transaction.
amount: The transaction amount in the smallest unit of the currency.
... [other fields similar to the POST /transactions response]
state: The current status of the transaction. E.g., \"PENDING\".
created_date: Timestamp indicating when the transaction was initiated.
... [and other transaction details]
\n","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"x-waza-key"},{"key":"value","value":"3PuDo1xS6akdBwAyczyOOVznUChK6ITD"}]},"isInherited":true,"source":{"_postman_id":"7eb6cb17-d551-4ed0-9224-d17b4990f8f7","id":"7eb6cb17-d551-4ed0-9224-d17b4990f8f7","name":"Vanir API","type":"collection"}},"urlObject":{"path":["transactions",":id"],"host":["https://api.sandbox.waza.co/payouts/v1"],"query":[],"variable":[{"type":"any","value":"wz_trsf_nlxX_1699010105788","key":"id"}]}},"response":[{"id":"0f04375b-ba95-4467-b8b7-913975fa480c","name":"[200] Get by ID","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://api.sandbox.waza.co/payouts/v1/transactions/:id","host":["https://api.sandbox.waza.co/payouts/v1"],"path":["transactions",":id"],"variable":[{"key":"id","value":"wz_trsf_qYvR_1690198508263"}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"X-Powered-By","value":"Express"},{"key":"waza-request-id","value":"bcc0751c-56bc-498b-bf6e-199a1746831f"},{"key":"X-Frame-Options","value":"DENY"},{"key":"Content-Type","value":"application/json; charset=utf-8"},{"key":"Content-Length","value":"724"},{"key":"ETag","value":"W/\"2d4-Oe7YzUw32xPkycD0duJ6LExTQIQ\""},{"key":"Date","value":"Thu, 10 Aug 2023 09:46:32 GMT"},{"key":"Connection","value":"keep-alive"},{"key":"Keep-Alive","value":"timeout=5"}],"cookie":[],"responseTime":null,"body":"{\n \"data\": {\n \"id\": \"wz_trsf_qYvR_1690198508263\",\n \"amount\": 590000,\n \"currency\": \"NGN\",\n \"country\": \"NG\",\n \"beneficiary\": {\n \"type\": \"BANK_ACCOUNT\",\n \"account_name\": \"Test Account\",\n \"account_number\": \"123400001\",\n \"bank_code\": \"000014\",\n \"bank_name\": \"Test Bank\"\n },\n \"state\": \"COMPLETED\",\n \"created_date\": \"2023-07-24T11:35:08.264Z\",\n \"completion_date\": \"2023-07-24T11:35:15.391Z\",\n \"customer_reference\": null,\n \"metadata\": {\n \"invoiceId\": \"Payment from APP\"\n },\n \"balance_before\": 10190000,\n \"balance_after\": 9600000,\n \"sender\": {\n \"dob\": \"2000-01-23\",\n \"name\": \"Emmanuel Igbodudu\",\n \"address\": \"Optional\",\n \"country\": \"US\",\n \"send_amount\": 500,\n \"send_currency\": \"USD\"\n },\n \"response_code\": \"OO\",\n \"response_description\": \"Transfer Completed successfully\",\n \"company_id\": \"af0bbbfe-ff06-434c-bdba-bc962c627546\"\n }\n}"}],"_postman_id":"830a4e26-7357-4ab9-ac4c-7ea35976c419"},{"name":"Cancel Transaction","id":"aa657a91-1f1d-4bf6-843a-ab296d59150c","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"url":"https://api.sandbox.waza.co/payouts/v1/transactions/:id/cancel","description":"The /transactions/:id/cancel endpoint provides functionality to cancel a specific transaction given its unique identifier. Transactions can only be canceled if they are currently in a \"PENDING\" state. Once a transaction has progressed past this state, it cannot be canceled via this endpoint.
Retrieves a list of transactions based on given filters and pagination parameters.
\nfrom (optional): Specifies the start date of the transaction range in the format YYYY-MM-DD.
to (optional): Specifies the end date of the transaction range in the format YYYY-MM-DD.
state (optional, multiple values allowed): Filters the transactions by their current state. Possible values include PENDING, COMPLETED, etc.
currency (optional): Filters transactions based on their currency (e.g., NGN).
country (optional): Filters transactions by originating country (e.g., NG).
page (optional): Indicates which page of results to retrieve. If not provided, defaults to the first page.
\nlimit (optional): Specifies the number of transactions to retrieve per page.
\nTo retrieve transactions from 2023-07-25 to 2023-07-28 that are either in a PENDING or COMPLETED state, use the NGN currency, originate from NG, and display them in the 3rd page with 2 transactions per page:
GET /transactions?from=2023-07-25&to=2023-07-28&state=PENDING&state=COMPLETED¤cy=NGN&country=NG&page=3&limit=2
The response is paginated and will follow the structure:
\n{\n \"data\": {\n \"items\": [...], // Array of transaction data for the current page\n \"total_items\": XX, // Total count of transactions across all pages\n \"page\": X, // Current page number\n \"limit\": X, // Number of transactions per page (page size)\n \"total_pages\": X // Aggregate number of pages available given the page size\n }\n}\n\nitems array will be empty.Retrieves a singular transaction using the unique customer_reference provided by the API user.
customer_reference associated with a specific transaction. This is a mandatory parameter and should be replaced in the URL with the actual reference string you wish to query.The response is similar to the fetch by ID endpoint
\nIf no transaction matches the provided customer_reference, you'll receive an error response indicating that the transaction wasn't found.
It's crucial to use accurate and case-sensitive customer_reference strings when querying to ensure correct results.
Endpoints related to Payouts
\n","_postman_id":"1ed2103b-6e9f-4f5b-a960-d98254654c18","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"x-waza-key"},{"key":"value","value":"3PuDo1xS6akdBwAyczyOOVznUChK6ITD"}]},"isInherited":true,"source":{"_postman_id":"7eb6cb17-d551-4ed0-9224-d17b4990f8f7","id":"7eb6cb17-d551-4ed0-9224-d17b4990f8f7","name":"Vanir API","type":"collection"}}},{"name":"Statements","item":[{"name":"Create Statement","id":"3c800e86-5a42-458d-aec7-8ca4d4c774b9","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"from\": \"2024-01-01\",\n \"to\": \"2024-12-31\",\n \"account_id\": \"4e482830-bb5d-4175-8966-aa7d96f5a34c\"\n}","options":{"raw":{"language":"json"}}},"url":"https://api.sandbox.waza.co/payouts/v1/statements","description":"To request a statement for a specific account and date range, use the account_id retrieved from the balances endpoint. Additionally, specify the from and to date ranges for which the statement should be generated.
Since the statement generation process is asynchronous, you should periodically verify its status, waiting for it to transition from PENDING to COMPLETED.
Returns a paginated list of statements.
\n","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"x-waza-key"},{"key":"value","value":"3PuDo1xS6akdBwAyczyOOVznUChK6ITD"}]},"isInherited":true,"source":{"_postman_id":"7eb6cb17-d551-4ed0-9224-d17b4990f8f7","id":"7eb6cb17-d551-4ed0-9224-d17b4990f8f7","name":"Vanir API","type":"collection"}},"urlObject":{"path":["statements"],"host":["https://api.sandbox.waza.co/payouts/v1"],"query":[],"variable":[]}},"response":[{"id":"29565e96-6aca-4cba-916f-e7ef2621b647","name":"[200] Get All","originalRequest":{"method":"GET","header":[],"body":{"mode":"raw","raw":"{\n \"from\": \"2023-07-15\",\n \"to\": \"2023-08-04\",\n \"account_id\": \"0947445e-333f-4b3b-a5f9-27267429d2b0\"\n}","options":{"raw":{"language":"json"}}},"url":"https://api.sandbox.waza.co/payouts/v1/statements"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"X-Powered-By","value":"Express"},{"key":"waza-request-id","value":"252ee152-e95c-4531-9f08-c13521acf996"},{"key":"X-Frame-Options","value":"DENY"},{"key":"Content-Type","value":"application/json; charset=utf-8"},{"key":"Content-Length","value":"2410"},{"key":"ETag","value":"W/\"96a-pehTyX29i7uW2r6501d3yX/IjoU\""},{"key":"Date","value":"Thu, 10 Aug 2023 09:42:59 GMT"},{"key":"Connection","value":"keep-alive"},{"key":"Keep-Alive","value":"timeout=5"}],"cookie":[],"responseTime":null,"body":"{\n \"data\": {\n \"items\": [\n {\n \"id\": \"f471f115-8e3e-4a99-95e2-142594221122\",\n \"created_at\": \"2023-08-10T09:42:41.775Z\",\n \"updated_at\": \"2023-08-10T09:42:41.775Z\",\n \"state\": \"PENDING\",\n \"from\": \"2023-07-01\",\n \"to\": \"2023-08-07\",\n \"accountId\": \"0947445e-333f-4b3b-a5f9-27267429d2b0\"\n },\n {\n \"id\": \"3ed2794f-eeae-4775-b560-292c5d634681\",\n \"created_at\": \"2023-08-08T13:35:14.657Z\",\n \"updated_at\": \"2023-08-08T13:35:20.075Z\",\n \"state\": \"COMPLETE\",\n \"from\": \"2023-07-01\",\n \"to\": \"2023-08-07\",\n \"accountId\": \"0947445e-333f-4b3b-a5f9-27267429d2b0\"\n },\n {\n \"id\": \"c005e903-2bd7-4f5e-858f-daac61c4b193\",\n \"created_at\": \"2023-08-08T12:48:15.179Z\",\n \"updated_at\": \"2023-08-08T12:48:26.808Z\",\n \"state\": \"COMPLETE\",\n \"from\": \"2023-07-01\",\n \"to\": \"2023-08-07\",\n \"accountId\": \"0947445e-333f-4b3b-a5f9-27267429d2b0\"\n },\n {\n \"id\": \"93ecbcef-b48d-4e1a-91a0-4e951562a6ca\",\n \"created_at\": \"2023-08-08T12:45:58.122Z\",\n \"updated_at\": \"2023-08-08T13:35:13.206Z\",\n \"state\": \"COMPLETE\",\n \"from\": \"2023-07-01\",\n \"to\": \"2023-08-07\",\n \"accountId\": \"0947445e-333f-4b3b-a5f9-27267429d2b0\"\n },\n {\n \"id\": \"b32cfcac-26d6-449a-804d-96385ea46536\",\n \"created_at\": \"2023-08-07T12:29:53.696Z\",\n \"updated_at\": \"2023-08-07T12:29:59.450Z\",\n \"state\": \"COMPLETE\",\n \"from\": \"2023-08-07\",\n \"to\": \"2023-08-07\",\n \"accountId\": \"0947445e-333f-4b3b-a5f9-27267429d2b0\"\n },\n {\n \"id\": \"07f8e7f4-8717-4b02-a3e0-3c9ee6e2f72a\",\n \"created_at\": \"2023-08-07T12:18:02.093Z\",\n \"updated_at\": \"2023-08-07T12:18:04.477Z\",\n \"state\": \"COMPLETE\",\n \"from\": \"2023-08-07\",\n \"to\": \"2023-08-07\",\n \"accountId\": \"0947445e-333f-4b3b-a5f9-27267429d2b0\"\n },\n {\n \"id\": \"ea44ef0e-a29e-4159-bea8-e51527a0d82e\",\n \"created_at\": \"2023-08-07T12:14:20.547Z\",\n \"updated_at\": \"2023-08-07T12:14:33.872Z\",\n \"state\": \"COMPLETE\",\n \"from\": \"2023-08-07\",\n \"to\": \"2023-08-07\",\n \"accountId\": \"0947445e-333f-4b3b-a5f9-27267429d2b0\"\n },\n {\n \"id\": \"874241a5-a52d-41d1-9da5-03d4efa3a656\",\n \"created_at\": \"2023-08-07T12:09:01.519Z\",\n \"updated_at\": \"2023-08-07T12:09:30.769Z\",\n \"state\": \"COMPLETE\",\n \"from\": \"2023-08-07\",\n \"to\": \"2023-08-07\",\n \"accountId\": \"0947445e-333f-4b3b-a5f9-27267429d2b0\"\n },\n {\n \"id\": \"d0f1da75-095c-4bbc-b6fd-9c3c5aaaa554\",\n \"created_at\": \"2023-08-07T12:07:05.987Z\",\n \"updated_at\": \"2023-08-07T12:07:09.680Z\",\n \"state\": \"COMPLETE\",\n \"from\": \"2023-08-07\",\n \"to\": \"2023-08-07\",\n \"accountId\": \"0947445e-333f-4b3b-a5f9-27267429d2b0\"\n },\n {\n \"id\": \"22201136-d836-4a28-b63a-a3b5ff0e0a61\",\n \"created_at\": \"2023-08-07T12:03:08.406Z\",\n \"updated_at\": \"2023-08-07T12:03:18.221Z\",\n \"state\": \"COMPLETE\",\n \"from\": \"2023-07-15\",\n \"to\": \"2023-07-30\",\n \"accountId\": \"0947445e-333f-4b3b-a5f9-27267429d2b0\"\n }\n ],\n \"totalItems\": 23,\n \"page\": 1,\n \"limit\": 10,\n \"totalPages\": 3\n }\n}"}],"_postman_id":"a1dcbdd0-a78d-4ef8-8750-33ce7935c1c9"},{"name":"Download","id":"ed6b5dd4-febc-4225-b24d-1cc3eb824aac","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"body":{"mode":"raw","raw":"{\n \"from\": \"2023-07-15\",\n \"to\": \"2023-08-04\",\n \"account_id\": \"0947445e-333f-4b3b-a5f9-27267429d2b0\"\n}","options":{"raw":{"language":"json"}}},"url":"https://api.sandbox.waza.co/payouts/v1/statements/:id/download","description":"To download the statement
\nOn invoking this endpoint, the server will initiate a file transfer, allowing your system or browser to prompt you to save the file. The statement is delivered as an Excel sheet with the content type set as an attachment, triggering most HTTP clients or browsers to treat it as a file download.
\nHeaders you might see:
\nContent-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
Content-Disposition: attachment; filename=\"XXXXX.xlsx\"
{COMPANY_NAME}__statement_[FROM_DATE]_{TO_DATE}.xlsx. Consider renaming the file upon download if you wish to adhere to specific naming conventions or add more context to the filename.404 Not Found: This could mean that there's no statement with the provided id or it might have been removed.
403 Forbidden: This usually indicates an authentication problem. Verify if you're providing the correct authentication details and have the necessary permissions.
\n412 Precondition Failed: If the statement is not in the COMPLETED state, you might receive this response. Only completed statements are available for download.
Generating accurate and timely statements for accounts is crucial for financial transparency and accountability. Our API provides a powerful feature that allows users to generate statements asynchronously. A webhook can be configured to notify you when the statement is ready to be downloaded.
\n","_postman_id":"fbc73aec-9e06-430d-b25a-3fac8daced22","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"x-waza-key"},{"key":"value","value":"3PuDo1xS6akdBwAyczyOOVznUChK6ITD"}]},"isInherited":true,"source":{"_postman_id":"7eb6cb17-d551-4ed0-9224-d17b4990f8f7","id":"7eb6cb17-d551-4ed0-9224-d17b4990f8f7","name":"Vanir API","type":"collection"}}},{"name":"Webhooks","item":[{"name":"List Webhooks","id":"e1fc2832-8cf6-4ef4-85bb-a5f608950c69","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"https://api.sandbox.waza.co/payouts/v1/webhooks","description":"The /webhooks endpoint provides a list of all the webhooks you've configured within your MyAPI account. This endpoint offers a paginated view, enabling you to retrieve specific pages of webhook configurations as needed.
id: Unique identifier for the webhook.
created_at: Timestamp indicating when the webhook was created.
updated_at: Timestamp indicating the last update to the webhook.
state: Indicates the current state of the webhook (ENABLED or DISABLED).
url: The URL endpoint where the webhook notifications are sent.
secret: The secret used for verifying webhook payloads.
enabled_events: List of events for which the webhook is triggered. A list of this can be gotten from the available-events endpoint
The /webhooks/available-events endpoint provides a list of all the events that can be subscribed to using the webhook functionality.
data: An array containing the event names that can be used in webhook configurations.When creating or updating a webhook using the /webhooks or /webhooks/:id endpoint, ensure that you only specify events from this list.
The events represent various stages or outcomes in the resource lifecycle, enabling you to set up custom listeners for specific events that are relevant to your use-case.
\nurl: The URL endpoint where the webhook notifications are sent. This must be an HTTPS endpoint for security purposes.
secret: A secret string that MyAPI will use to generate a signature for each webhook event. This ensures the authenticity of the events sent to the URL endpoint.
enabled_events: An array of event names that you want to receive notifications for. Possible values include (but are not limited to) transaction.created, transaction.processing, etc.
id: Unique identifier for the webhook configuration.
created_at: Timestamp indicating when the webhook was created.
updated_at: Timestamp indicating the last update to the webhook.
state: The current state of the webhook (ENABLED or DISABLED).
url: The configured URL endpoint where the webhook notifications are sent.
secret: The configured secret used for verifying webhook payloads.
enabled_events: List of events for which the webhook will trigger.
Ensure the URL endpoint you provide is secure, can verify the webhook payload using the secret, and can handle incoming POST requests.
Regularly review the events you've enabled for notifications to ensure they align with your integration requirements.
\nThe secret should be kept confidential and not be exposed.
Update an existing webhook configuration. You can modify the target URL, secret, or change the list of events you're subscribed to.
\n","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"x-waza-key"},{"key":"value","value":"3PuDo1xS6akdBwAyczyOOVznUChK6ITD"}]},"isInherited":true,"source":{"_postman_id":"7eb6cb17-d551-4ed0-9224-d17b4990f8f7","id":"7eb6cb17-d551-4ed0-9224-d17b4990f8f7","name":"Vanir API","type":"collection"}},"urlObject":{"path":["webhooks",":id"],"host":["https://api.sandbox.waza.co/payouts/v1"],"query":[],"variable":[{"type":"any","value":"c639a70e-ac2b-412b-924d-5a0883811d7d","key":"id"}]}},"response":[],"_postman_id":"80f02a37-7334-433c-811a-0736d9f21e59"},{"name":"Disable Webhook","id":"7be6e7d7-c30f-4822-947c-d3fa9eeaebae","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"url":"https://api.sandbox.waza.co/payouts/v1/webhooks/:id/disable","description":"Allows users to disable a specific webhook. Once a webhook is disabled, it will no longer trigger notifications for any event, even if the event is listed as an enabled event for the webhook.
\nPath Parameters
\nDisabling a webhook is a reversible action. If you wish to re-enable the webhook at a later time, you can use the appropriate endpoint to do so (e.g., /webhooks/:id/enable).
While the webhook is disabled, no events will be sent to the webhook's specified URL, regardless of the events listed in its enabled_events array.
Ensure you provide the correct webhook id in the endpoint path. Providing an invalid or nonexistent id will result in an error.
The /webhooks/:id/enable endpoint allows users to re-enable a specific webhook that was previously disabled. Once re-enabled, the webhook will resume sending notifications for any event listed in its enabled_events array.
Enabling a webhook is a reversible action. If you wish to disable the webhook again at a later time, you can use the /webhooks/:id/disable endpoint.
Once the webhook is enabled, it will start sending notifications to the specified URL for events listed in its enabled_events array.
Ensure you provide the correct webhook id in the endpoint path. Providing an invalid or nonexistent id will result in an error.
The /webhooks/:id endpoint allows users to permanently delete a specific webhook from the system. Once a webhook is deleted, it will no longer send any notifications, and it cannot be restored.
Deleting a webhook is a permanent action and cannot be undone. Before deleting a webhook, ensure that it is no longer needed or that you've made appropriate backups or documentation of its details.
\nIf you try to delete a webhook that doesn't exist or provide an invalid id, you will receive an error message.
After deletion, any attempts to interact with the webhook by its id will result in errors as the webhook will no longer exist in the system.
Webhooks allow you to receive real-time notifications of events happening within your account. Instead of making an API request to fetch updates, we push them directly to a URL endpoint you provide. This guide will cover the configuration, security measures, and event handling of webhooks in our system.
\nConfigure Endpoint using the [POST] /webhooks to create webhooks
We allow up to 5 ENABLED webhooks at any given time
\nEnsuring the webhook calls are from Waza API and have not been tampered with is crucial. We employ a mechanism using HMAC with SHA-256 to sign the payload.
\nExtract the Signature: Retrieve the x-waza-signature value from the header of the incoming request.
Generate Expected Signature: Compute an HMAC with SHA-256 on the received payload using your customer secret as the key.
Compare Signatures: Compare the signature from the header to the one you've computed. If they match, the request can be considered legitimate.
\nNote: Never expose your customer secret. Use it server-side exclusively for the verification process.
Not all webhook deliveries are successful on the first attempt. To handle such failures:
\nExponential Backoff: If a webhook delivery fails, we employ an exponential backoff strategy. This means after the first failure, we wait and try again in double the time, then double again if that fails, and so on.
\n72-Hour Window: We persist in our delivery attempts for up to 72 hours. If all retries fail within this time frame, we will cease delivery attempts for that particular event.
\nEndpoint Resilience: Ensure your endpoint is designed to handle volume and is fault-tolerant. It should also promptly acknowledge receipt by returning a 2XX status code.
Idempotence: Ensure your endpoint handles events in an idempotent manner. Since retries can occur, your system should be built to process each event once and only once.
\nStore Events: It's recommended to store received events for future analysis or debugging.
\n