{"openapi":"3.1.0","info":{"title":"Tranzaq API","version":"1.0.0","description":"Pay people in Ghana by mobile money and bank. Test and live use the same address; the credentials decide which one you are in."},"servers":[{"url":"https://api.tranzaq.com"}],"tags":[{"name":"authentication"},{"name":"balance"},{"name":"people"},{"name":"payout-batches"},{"name":"test-mode"}],"paths":{"/oauth/token":{"post":{"operationId":"oauth-token","summary":"Get an access token","description":"Trade your client ID and secret for a bearer token that lasts one hour. Send the credentials in the form body, or as an HTTP Basic header.","tags":["authentication"],"security":[],"requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","required":["grant_type","client_id","client_secret"],"properties":{"grant_type":{"type":"string","description":"Always client_credentials."},"client_id":{"type":"string","description":"Starts with tqz_test_ or tqz_live_. Not needed if you use HTTP Basic."},"client_secret":{"type":"string","description":"Shown once when you create the credentials. Not needed if you use HTTP Basic."},"scope":{"type":"string","description":"Space-separated scopes. Leave out to receive every scope your credentials have; ask for fewer to narrow the token."}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"},"example":{"access_token":"eyJhbGciOiJIUzI1NiIs","token_type":"Bearer","expires_in":3600,"scope":"balance.read payouts.write"}}}},"400":{"description":"unsupported_grant_type: only client_credentials is supported. invalid_scope: you asked for a scope your credentials do not have."},"401":{"description":"invalid_client: the ID or secret is wrong, or the credentials were revoked, expired, or the business is not active."},"429":{"description":"More than 30 token requests a minute from one address."}}}},"/api/v1/balance":{"get":{"operationId":"get-balance","summary":"Get the balance","description":"Your payout balance. Available is what you can pay out now; reserved is locked in approved batches; pending is expected but not yet credited.","tags":["balance"],"security":[{"oauth2":["balance.read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"},"example":{"success":true,"message":"Operation completed","code":200,"result":{"available":75449.74,"reserved":0,"pending":0,"total":75449.74,"currency":"GHS","asOf":"2026-10-18T10:20:00+00:00"}}}}},"401":{"description":"Missing, invalid or expired token."},"403":{"description":"The token does not have the balance.read scope."}}}},"/api/v1/beneficiaries":{"get":{"operationId":"list-beneficiaries","summary":"List people","description":"The people you pay, newest first, with their payout accounts.","tags":["people"],"security":[{"oauth2":["beneficiaries.read"]}],"parameters":[{"name":"search","in":"query","required":false,"description":"Matches name, phone number or your own reference.","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number, starting at 1. Default 1.","schema":{"type":"integer"}},{"name":"pageSize","in":"query","required":false,"description":"Items per page, 1 to 100. Default 20.","schema":{"type":"integer"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"},"example":{"success":true,"message":"Operation completed","code":200,"result":{"items":[],"total":46,"page":1,"pageSize":20}}}}},"401":{"description":"Missing, invalid or expired token."},"403":{"description":"The token does not have the beneficiaries.read scope."}}},"post":{"operationId":"create-beneficiary","summary":"Add a person","description":"Add someone you pay, with a mobile money or bank account. We look up the name on the account and mark it Verified or not.","tags":["people"],"security":[{"oauth2":["beneficiaries.write"]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"8 to 150 characters. A repeat with the same key returns the first answer.","schema":{"type":"string","minLength":8,"maxLength":150}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"name: Up to 200 characters.\nemail: Optional.\nphoneNumber: Optional.\nexternalReference: Your own id for this person, such as an employee number. Up to 100 characters.\ndestination.type: MobileMoney or Bank.\ndestination.accountNumber: The phone number or bank account number.\ndestination.accountName: The name on the account, as you know it.\ndestination.network: Mobile money only: MTN, TELECEL or AIRTELTIGO.\ndestination.bankCode: Bank only: the bank's code."},"example":{"name":"Ama Owusu","phoneNumber":"0241234567","externalReference":"EMP-0042","destination":{"type":"MobileMoney","accountNumber":"0241234567","accountName":"Ama Owusu","network":"MTN"}}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object"},"example":{"success":true,"message":"Beneficiary created","code":201,"result":{"id":"8d2f6f40-5e7a-4b0e-b1a1-2f4c9d7e1a33","name":"Ama Owusu","email":null,"phoneNumber":"0241234567","externalReference":"EMP-0042","status":"Active","createdAt":"2026-10-18T10:10:00+00:00","destinations":[{"id":"e0a1b2c3-d4e5-4f60-8a7b-9c8d7e6f5a4b","type":"MobileMoney","maskedAccountNumber":"024****567","accountName":"Ama Owusu","network":"MTN","isDefault":true,"verificationStatus":"Verified"}]}}}}},"400":{"description":"A field is missing or not valid, or the Idempotency-Key header is missing."},"409":{"description":"The same Idempotency-Key was used for a different request that is still running."}}}},"/api/v1/beneficiaries/{id}":{"get":{"operationId":"get-beneficiary","summary":"Get a person","description":"One person and their accounts.","tags":["people"],"security":[{"oauth2":["beneficiaries.read"]}],"parameters":[{"name":"id","in":"path","required":true,"description":"The person's id.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"},"example":{"success":true,"message":"Beneficiary created","code":201,"result":{"id":"8d2f6f40-5e7a-4b0e-b1a1-2f4c9d7e1a33","name":"Ama Owusu","email":null,"phoneNumber":"0241234567","externalReference":"EMP-0042","status":"Active","createdAt":"2026-10-18T10:10:00+00:00","destinations":[{"id":"e0a1b2c3-d4e5-4f60-8a7b-9c8d7e6f5a4b","type":"MobileMoney","maskedAccountNumber":"024****567","accountName":"Ama Owusu","network":"MTN","isDefault":true,"verificationStatus":"Verified"}]}}}}},"404":{"description":"No such person in your business."}}}},"/api/v1/payout-batches":{"get":{"operationId":"list-batches","summary":"List payout batches","description":"Your batches, newest first, without their items.","tags":["payout-batches"],"security":[{"oauth2":["payouts.read"]}],"parameters":[{"name":"status","in":"query","required":false,"description":"Draft, PendingApproval, Approved, Rejected, Processing, PartiallySuccessful, Successful, Failed or Cancelled.","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number, starting at 1. Default 1.","schema":{"type":"integer"}},{"name":"pageSize","in":"query","required":false,"description":"Items per page, 1 to 100. Default 20.","schema":{"type":"integer"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"},"example":{"success":true,"message":"Operation completed","code":200,"result":{"items":[],"total":22,"page":1,"pageSize":20}}}}},"401":{"description":"Missing, invalid or expired token."},"403":{"description":"The token does not have the payouts.read scope."}}},"post":{"operationId":"create-batch","summary":"Create a payout batch","description":"Save a draft batch of payments. Nothing is sent yet: submit the draft when you are ready. Sending the same Idempotency-Key again returns the same batch.","tags":["payout-batches"],"security":[{"oauth2":["payouts.write"]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"8 to 150 characters. A repeat with the same key returns the first answer.","schema":{"type":"string","minLength":8,"maxLength":150}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"name: A name for the batch, up to 200 characters.\nspeed: Instant (default), SameDay, NextDay or ManualReview.\nitems: The payments. Up to 1,000 per batch.\nitems[].beneficiaryId: A person you added.\nitems[].amount: In cedis, at most 2 decimal places.\nitems[].destinationId: Which of the person's accounts. Leave out to use their default.\nitems[].reference: Your own note or id for this payment, up to 100 characters."},"example":{"name":"October salaries","speed":"Instant","items":[{"beneficiaryId":"8d2f6f40-5e7a-4b0e-b1a1-2f4c9d7e1a33","amount":1850,"reference":"SAL-1"}]}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object"},"example":{"success":true,"message":"Draft saved","code":201,"result":{"id":"3f9c1c9e-6b1a-4d6f-9a77-0f6f3f3c2a10","batchReference":"PB-20261018-0007","batchName":"October salaries","status":"Draft","speed":"Instant","currency":"GHS","totalAmount":1850,"totalFees":9.25,"itemCount":1,"createdBy":"Tranzaq API","createdAt":"2026-10-18T10:15:00+00:00","submittedAt":null,"approvedAt":null,"completedAt":null,"items":[{"id":"b3c5f0a2-3d1e-4a71-8f0e-1c2d3e4f5a6b","reference":"SAL-1","amount":1850,"feeAmount":9.25,"currency":"GHS","destinationType":"MobileMoney","maskedAccountNumber":"024****567","accountName":"Ama Owusu","network":"MTN","status":"Pending","failureCode":null,"failureReason":null}],"approvals":[]}}}}},"400":{"description":"A row is wrong (the message says which: “Row 3: …”), or the Idempotency-Key header is missing."},"403":{"description":"The business has not been approved for live payouts yet. Test mode is not affected."}}}},"/api/v1/payout-batches/{id}":{"get":{"operationId":"get-batch","summary":"Get a payout batch","description":"One batch with every payment, its status and failure reason, and the approval steps. Poll this, or use webhooks.","tags":["payout-batches"],"security":[{"oauth2":["payouts.read"]}],"parameters":[{"name":"id","in":"path","required":true,"description":"The batch id.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"},"example":{"success":true,"message":"Operation completed","code":200,"result":{"id":"3f9c1c9e-6b1a-4d6f-9a77-0f6f3f3c2a10","batchReference":"PB-20261018-0007","batchName":"October salaries","status":"Draft","speed":"Instant","currency":"GHS","totalAmount":1850,"totalFees":9.25,"itemCount":1,"createdBy":"Tranzaq API","createdAt":"2026-10-18T10:15:00+00:00","submittedAt":null,"approvedAt":null,"completedAt":null,"items":[{"id":"b3c5f0a2-3d1e-4a71-8f0e-1c2d3e4f5a6b","reference":"SAL-1","amount":1850,"feeAmount":9.25,"currency":"GHS","destinationType":"MobileMoney","maskedAccountNumber":"024****567","accountName":"Ama Owusu","network":"MTN","status":"Pending","failureCode":null,"failureReason":null}],"approvals":[]}}}}},"404":{"description":"No such batch in your business."}}}},"/api/v1/payout-batches/{id}/submit":{"post":{"operationId":"submit-batch","summary":"Submit a batch","description":"Send a draft for approval. The money is reserved once the required people have approved it on the website. Submitting is safe to repeat: a batch that is no longer a draft answers 409.","tags":["payout-batches"],"security":[{"oauth2":["payouts.write"]}],"parameters":[{"name":"id","in":"path","required":true,"description":"The batch id.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"},"example":{"success":true,"message":"Submitted","code":200,"result":{"id":"3f9c1c9e-6b1a-4d6f-9a77-0f6f3f3c2a10","batchReference":"PB-20261018-0007","batchName":"October salaries","status":"PendingApproval","speed":"Instant","currency":"GHS","totalAmount":1850,"totalFees":9.25,"itemCount":1,"createdBy":"Tranzaq API","createdAt":"2026-10-18T10:15:00+00:00","submittedAt":null,"approvedAt":null,"completedAt":null,"items":[{"id":"b3c5f0a2-3d1e-4a71-8f0e-1c2d3e4f5a6b","reference":"SAL-1","amount":1850,"feeAmount":9.25,"currency":"GHS","destinationType":"MobileMoney","maskedAccountNumber":"024****567","accountName":"Ama Owusu","network":"MTN","status":"Pending","failureCode":null,"failureReason":null}],"approvals":[]}}}}},"400":{"description":"A batch needs at least one payment."},"403":{"description":"The business is not active."},"404":{"description":"No such batch."},"409":{"description":"Only a draft can be submitted."}}}},"/api/v1/payout-batches/{id}/cancel":{"post":{"operationId":"cancel-batch","summary":"Cancel a batch","description":"Cancel a batch that has not been sent yet. Reserved money returns to your available balance.","tags":["payout-batches"],"security":[{"oauth2":["payouts.write"]}],"parameters":[{"name":"id","in":"path","required":true,"description":"The batch id.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"},"example":{"success":true,"message":"Batch cancelled","code":200,"result":{"id":"3f9c1c9e-6b1a-4d6f-9a77-0f6f3f3c2a10","batchReference":"PB-20261018-0007","batchName":"October salaries","status":"Cancelled","speed":"Instant","currency":"GHS","totalAmount":1850,"totalFees":9.25,"itemCount":1,"createdBy":"Tranzaq API","createdAt":"2026-10-18T10:15:00+00:00","submittedAt":null,"approvedAt":null,"completedAt":null,"items":[{"id":"b3c5f0a2-3d1e-4a71-8f0e-1c2d3e4f5a6b","reference":"SAL-1","amount":1850,"feeAmount":9.25,"currency":"GHS","destinationType":"MobileMoney","maskedAccountNumber":"024****567","accountName":"Ama Owusu","network":"MTN","status":"Pending","failureCode":null,"failureReason":null}],"approvals":[]}}}}},"404":{"description":"No such batch."},"409":{"description":"A batch that is already processing or finished can no longer be cancelled."}}}},"/api/v1/sandbox/fund":{"post":{"operationId":"sandbox-fund","summary":"Add test money","description":"Add fake money to your test balance so you can try payouts. Only test credentials can call this; with live credentials it answers 404.","tags":["test-mode"],"security":[{"oauth2":["sandbox.fund"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"amount: From 1 to 100,000, at most 2 decimal places."},"example":{"amount":5000}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"},"example":{"success":true,"message":"Test money added","code":200,"result":{"available":5000,"reserved":0,"pending":0,"total":5000,"currency":"GHS","asOf":"2026-10-18T10:12:00+00:00"}}}}},"400":{"description":"The amount is out of range."},"404":{"description":"These are live credentials."}}}}},"components":{"securitySchemes":{"oauth2":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"https://api.tranzaq.com/oauth/token","scopes":{"balance.read":"Read the balance","beneficiaries.read":"List and read people","beneficiaries.write":"Add people","payouts.read":"List and read payout batches","payouts.write":"Create, submit and cancel batches","sandbox.fund":"Test mode only: add fake money"}}}}}}}