Introduction.
Welcome to the official documentation site for Tranzak
The purpose of this site is to provide an open collection of technical topics and details about Tranzak developer APIs that are frequently requested by developers and IT specialists working within the Tranzak ecosystem.
We have tried to provide as much detail as possible and organize it logically. However, if you are looking for details but can not find them here, please provide feedback related to your documentation needs and we will get back with you shortly.
For an overview of the solution and to learn more about the business applications of Tranzak visit our website https://tranzak.net
For support needs, feel free to drop us an email at support@tranzak.net.
Managing Apps and appKeys
All Tranzak APIs and Keys are linked to an Application. You can create this application from the developer portal or use the default application that is provided to you. You can also create multiple applications and manage theirs app keys separately.
Once your organization has been onboarded to Tranzak, you will be given an account to the developer portal to view your dashboard, manage your apps related keys, as well as key scopes (collection,disbursement or both).
If you enable collections for your key, you will be able to receive money from users. But to send money from your merchant account to a mobile wallet, bank account etc... you will need to manually enable disbursement.
Notes:
Sandbox appKeys are now prefixed with
SAND_(eg.SAND_C1B041767BBA4B5D808D91AFB18002A5) and production appKeys are prefixed withPROD_(eg.PROD_HB2141767BBA4B5D808D91AFB1812H38)
Due to continuous enhancements, some of the functions and screen images might be different than what you see on the current level of Tranzak.
All Endpoints have required Authentication and other headers. See Authentication below.
curl "api_endpoint_here" \
-H "Authorization: Bearer Token"
Auth Header Parameters
| Parameter | required | Description |
|---|---|---|
| Authorization | true | user token. in the format Bearer <Token> where <Token> is the token provided by the /auth/token endpoint as shown Here |
Common Request Parameters
These Headers must be passed in all requests. Regardless of whether Authorization is needed of not. If the value is not available, the default value should be empty string "";
| scope | parameter | location | description | required |
|---|---|---|---|---|
| - | Authorization | header | Authentication token, in the format Bearer ${token}.See token generation |
true |
| - | X-App-ID | header | APPlication's appId | false |
Date and Time
All time and dates are formatted using ISO 8601 format.
e.g. 2022-06-29T21:46:50+00:00
General Response Format
Tranzak API calls return HTTP status codes. In addition, some API calls also return JSON response bodies that include information about the resource. Requests that do not generate error (4xx , 5xx) will generally return HTTP status code 200. HTTP status code is not necessarily indicative that the request execution was success. To verify that the execution completed without any errors, the success flag will be used .
- success = TRUE : Indicates that the execution was successful
- success = FALSE : indicates the request was not successfully execution. An error message (
errorMsg) and occasionally ,errorCodewill provide additional information on the failure reason.
Response Payload
The following JSON snippet displays a typical response for a successful request:
{
"data": {
"response": "pong"
},
"success": true
}
Typical response for a paginated list:
{
"data": [],
"totalItems": 984,
"pageSize": 50,
"currentPage": 3,
"hasMore": true, // whether there are more items in the db form the request
"success": true
}
For a failed request, the response may look like the following
{
"data": {},
"success": false,
"errorMsg": "Invalid or unsupported currency code:XAsF",
"errorCode": 0
}
Recommendation
You are advised to always check the value of success to determine outcome of the execution of a request if the HTTP status code returns 200.
Authentication
Glossary
App ID: App are used to identify the caller of a Tranzak Partner API endpoint. Access the Tranzak developer portal to create an app.
App Key: The key generated from the Tranzak developer portal. It can be either sandbox or production key, and is different for each application.
Bearer token: A token placed in the header of an HTTP request to authenticate and identify the merchant making the request. A Tranzak Merchant obtains a bearer token by call the /auth/token endpoint.
Base URL
| Environment | Base URL |
|---|---|
| PRODUCTION | https://dsapi.tranzak.me |
| SANDBOX | https://sandbox.dsapi.tranzak.me |
Security Consideration
- All Tranzak API endpoints must be accessed via HTTPS. All access via unencrypted HTTP will fail.
- Keep the app key safe as it carries a lot privileges.
- In case you forget an app key, generate a new one.
- Generating a new app key renders existing app keys for the same app ID unusable. Therefore, you should use the app key generation tool with caution.
Generate Token
POST /auth/token
Request Body Parameters
| Parameter | Type | required | Description |
|---|---|---|---|
| appId | String | true | App Id |
| appKey | String | true | The app key generated from the developer portal eg: SAND_C1B041767BBA4B5D808D91AFB18002A5 |
// example request body:
{
"appId": "apabc123abc133",
"appKey": "PROD_91AFB18002A5C1B041767BBA4B5D808D91AFB18MJU89"
}
Response
| Parameter | Type | required | Description |
|---|---|---|---|
| scope | String | true | Comma separated value showing the different scopes of your appKey eg: collections,disbursement |
| token | String | true | The bearer token that will be used as Authorization header for all your requests.In the format Bearer ${token} |
| expiresIn | Integer | true | Number of seconds till the token expires. We recommend caching the token in your systems for at least 3/4 of its validity. That's if the token is valid for two hours, you can store it for at least 1h 30min before you get a new token. The Validity of the token may change. |
Example Response>
// example response
{
"data": {
"scope": "collections",
"appId": "ap6gf77v3tdyq4",
"token": "50E41R0RDEYK1TPWE0MEWX801HM0T42K1TCEMMC0U2E1HR08",
"expiresIn": 7200
},
"success": true
}
Bearer Token
We use a Bearer token for all our API requests that need a token. The token in passed in the Authorization header, in the format:
Authorization: 'Bearer ${yourToken}'
Pagination
Pagination governs how data multi-page result-set shall be presented.
Params
| Parameter | Type | required | Description |
|---|---|---|---|
| page | Integer | false | The page number |
| pageSize | Integer | false | The number of items that can be shown in a "page" . Default = 10, maximum = 50 |
| totalItems | Integer | false | The total number of items in the result-set |
| pageCount | Array | false | (read-only) gives the minimum pageSize and supported maximum value (1 .. 50) |
| currentPage | Integer | false | The current page number |
| hasMore | Boolean | false | whether or not there are more items beyond this page (counting forward) . |
NOTE Use the following formula to calculate the total number of pages : totalItems/pageSize
General Structure
{
"data": {
"list": [
item1,
item2
..
itemN
],
"totalItems": 1012,
"pageCount": [
1,
50
],
"pageSize": 10,
"currentPage": 1,
"hasMore": true
},
"success": true
}
Error Codes
Synopsis
Error codes provide info that may be used diagnose common errors that occur during transaction processing.
Payer-Related errors
| Error Code | String | Description |
|---|---|---|
| 1000 | PAYER_UNDEFINED_ERROR | Unspecified error relating to payer's account. |
| 1001 | PAYER_INSUFF_BALANCE | Insufficient balance in payer's account |
| 1002 | PAYER_PAYMENT_METHOD_ERROR | Invalid payment method selected |
| 1003 | PAYER_PAYMENT_METHOD_UNSPECIFIED | No payment method specified |
| 1004 | PAYER_AUTHORIZATION_REQUIRED | Transaction requires authorization |
| 1010 | PAYER_INVALID_PIN | The payment PIN is not valid |
| 1011 | PAYER_INVALID_RNV_KYC | Payer has not completed KYC checks |
| 1201 | PAYER_SETTLEMENT_AMOUNT_VIOLATION | Settlement amount is not within transaction limits |
Beneficiary/Merchant-Related errors
| Error Code | String | Description |
|---|---|---|
| 2000 | BENE_UNDEFINED_ERROR | Unspecified error relating to beneficiary's account |
| 2001 | BENE_ACCOUNT_INVALID | The destination account is not valid |
| 2002 | BENE_ACCOUNT_NAME_INVALID | The name of the beneficiary is not valid |
Transaction Errors
| Error Code | String | Description |
|---|---|---|
| 3000 | TXN_GENERAL_FAILURE | Transaction general failure. e.g caused by internal technical issues |
| 3001 | TXN_FAILED_OPERATOR_ERROR | The transaction failed due problems encountered on the financial operator's network |
| 3002 | TXN_PIN_AUTHORIZATION_REQUIRED | Payment authorization PIN is required to complete the transaction |
| 3003 | TXN_FAILED_INTERNAL_ERROR | Internal error |
| 3004 | TXN_EXPIRED | The transaction expired |
| 3005 | TXN_UNSUPPORTED_CURRENCY | The transaction currency code is not supported |
| 3007 | TXN_INVALID_AMOUNT | The transaction amount is not within acceptable limits |
| 3008 | TXN_CANCELLED | The transaction is in CANCELLED state and may no longer be processed |
| 3009 | TXN_INVALID_AUTHORIZATION_CODE | (Applicable to merchant payment) - invalid/wrong authorization code was input |
| 3010 | TXN_APPROVAL_REQUIRED | The transaction requires manual approval before it can be processed |
| 3011 | TXN_PAYMENT_METHOD_UNSUPPORTED | The payment method is not supported |
| 3012 | TXN_CROSS_BORDER_PAYMENT_UNSUPPORTED | Cross-border payment has not been abled for the Payer's account |
| 3012 | TXN_CROSS_BORDER_PAYMENT_UNSUPPORTED_CURRENCY | The currency may not be used for cross-border transactions ( for the funding account) |
| 3013 | TXN_LIMIT_EXCEEDED | Transaction limits exceeded |
Authentication/Authorization
| Error Code | String | Description |
|---|---|---|
| 401 | INVALID_ACCESS_TOKEN | The access token is invalid |
| 4001 | AUTH_INVALID_CREDENTIALS | Invalid login credentials provided |
General System Errors
| Error Code | String | Description |
|---|---|---|
| 5001 | SYSTEM_PARSE_ERROR | The data input could not be successfully parsed |
| 5002 | SYSTEM_GENERAL_VALIDATION_ERROR | One or more input parameters is/are not valid |
| 5005 | SYSTEM_EXCEPTION | An internal error occurred |
| 5006 | SYSTEM_ADMIN_RESTRICTED | One of the accounts involved in the transaction has been restricted |
| 5007 | SYSTEM_ADMIN_POLICY_VIOLATION | The transaction violated an internal/regulatory/administrative policy |
| 5008 | SYSTEM_INTERNAL_ERROR | Temporary internally error occurred |
Financial Partner/Operator Errors
| Error Code | String | Description |
|---|---|---|
| 7001 | OPERATOR_COMM_ERROR | The communication channel to the financial operator is not stable |
| 7002 | OPERATOR_PAYER_INSUFF_BALANCE | The operator reported insufficient balance in the payer's wallet |
| 7003 | OPERATOR_INVALID_ACCOUNT_HOLDER | Operator reported that the account is not not valid or has been restricted |
| 7004 | OPERATOR_TXN_FAILED | The transaction failed at the operator's side |
| 7005 | OPERATOR_INTERNAL_TXN_FAILURE | Operator reported that the transaction failed due to an internal error on their system |
| 7006 | OPERATOR_SYSTEM_INTERNAL_ERROR | Operator reported that the transaction failed due to an internal error on their system |
| 7007 | OPERATOR_INVALID_SERVICE_PROVIDER | The requested operator is temporarily not available or not supported |
Account
Account Details
Displays account details. If accountId is not specified, then the primary account details will be shown
URL Endpoint
GET /xp021/v1/account/details?accountId={ACCOUNT_ID}
Response
| Parameter | Type | required | Description |
|---|---|---|---|
| accountId | String | true | account ID |
| name | String | true | |
| description | String | true | custom description provided by the merchant |
| currencyCode | String(3) | true | currency code |
| totalBalance | Number | true | the total balance |
| isActive | bool | true | whether account is active or not |
| type | bool | true | Account type |
| createdAt | String | true | creation time |
{
"data": {
"accountId": "PO648WT786QZ18FETE39",
"name": "payout account",
"description": "",
"currencyCode": "XAF",
"isActive": true,
"type": "payout account",
"totalBalance": 72590411,
"availableBalance": 72590411
},
"success": true
}
List Merchant Sub-Accounts
Displays paginated list of accounts (primary and merchant sub-accounts)
URL Endpoint
GET /mapi/xp021/v1/account/accounts
Response
| Parameter | Type | required | Description |
|---|---|---|---|
| accountId | String | true | account ID |
| name | String | true | the custom name (as set in the merchant dasboard) |
| description | String | true | custom description provided by the merchant |
| currencyCode | String(3) | true | currency code |
| totalBalance | Number | true | the balance |
| isActive | bool | true | whether account is active or not |
| createdAt | String | true | creation time |
[
{
"accountId": "PA00WCE4JFYKHE07D10R",
"name": "",
"description": "",
"currencyCode": "XAF",
"balanceAmount": 129907349,
"isActive": true,
"type": "Primary account"
},
{
"accountId": "MSA9WWLZC808KOGGEZJA",
"name": "Coll for Afriland",
"description": "Party scatter",
"currencyCode": "XAF",
"balanceAmount": 11100,
"isActive": true,
"type": "Merchant account"
},
{
"accountId": "MSAKTY68HKWBBT2KD9H9",
"name": "Coll for Afriland",
"description": "Party scatter",
"currencyCode": "USD",
"balanceAmount": 539.67,
"isActive": true,
"type": "Merchant account"
},
{
"accountId": "PO648WT786QZ18FETE39",
"name": "",
"description": "",
"currencyCode": "XAF",
"balanceAmount": 72590411,
"isActive": true,
"type": "payout account"
}
]
Disbursement Account Balance
Displays account details (e.g. balance) of disbursement account.
URL Endpoint
POST /xp021/v1/account/payout-account-details
Response
See the Account Details section.
Collection Account Details
Displays account details (e.g. balance) of primary collection account.
URL Endpoint
POST /xp021/v1/account/collection-account-details
Response
See the Account Details section.
Authorization Code
AVAILABLE ONLY ON SANDBOX ENVIRONMENT Generates authorization code that may be used for testing in-store (in-person) direct charge. See the Payment Request section to learn more on in-person/in-store direct charge.
URL Endpoint
POST /xp021/v1/account/generate-auth-code
Response
| Parameter | Type | required | Description |
|---|---|---|---|
| authCode | String | true | the authorization code that can be passed to a payment request in case of direct charge |
{
"data": {
"authCode": "316246910952747138393729"
},
"success": true
}
API Activity
These endpoints provide useful information for API-related activities.
Transaction Notifications (TPN)
Displays log of transaction notifications sent out to configured webhook endpoints.
URL Endpoint
GET /xp021/v1/api-activity/notifications
Request Body parameters
| Parameter | Type | required | Description |
|---|---|---|---|
| tpnId | String | true | Unique notification ID |
| customTransactionId | String | false | custom transaction reference |
| parentId | String | false | The parent ID of the notification (if applicable) |
| appId | String | false | The app ID |
| eventType | String | false | The matching webhook event type |
| resourceId | String | false | The resource reference |
| webhookId | String | false | the corresponding webhook ID |
| authKey | String | false | The webhook authentication key |
| url | String | false | The callback URL receiving the notification |
| responseStatusCode | String | false | The HTTP status code |
Response
{
"data": {
"list": [
{
"tpnId": "TPN2ZUOK4UMTQMJCJ9AQVD5TXZH",
"parentId": null,
"appId": "c4jtk945h35i",
"eventType": "REQUEST.COMPLETED",
"resourceId": "REQ2207069IWELNMNVOY",
"webhookId": "WHIDZ00LSVVTGZJO6EN5J2",
"authKey": "x5jxgsBb4cpukKBdwJjjXAN",
"isSuccess": true,
"url": "https://example.com/callback-listener",
"responseStatusCode": "200",
"errorDiagnosis": "SUCCESS",
"dispatchTime": "2022-07-06 10:54:13"
},
{
"tpnId": "TPN2F10QYE05LHWG2I1G6NQRNR5",
"parentId": null,
"appId": "c4jtk945h35i",
"eventType": "REQUEST.COMPLETED",
"resourceId": "REQ2207062Z0ARN7C0VB",
"webhookId": "WHIDZ00LSVVTGZJO6EN5J2",
"authKey": "x5jxgsBb4cpukKBdwJjjXAN",
"isSuccess": false,
"url": "https://example.com/callback-listener",
"responseStatusCode": null,
"errorDiagnosis": "REMOTE_SERVER_TIMEOUT",
"dispatchTime": "2022-07-06 10:49:51"
}
],
"totalItems": 2,
"pageCount": [
1,
50
],
"pageSize": 20,
"currentPage": 1,
"hasMore": false
},
"success": true
}
TPN Details
Displays details of a TPN
URL Endpoint
GET /xp021/v1/api-activity/tpn-details?tpnId={TPN_ID}
Request Body Filters
| Parameter | Type | required | Description |
|---|---|---|---|
| tpnId | String | false | Unique TPN ID |
Response
{
"data": {
"tpnId": "TPNJUPU9U7NF3QQHILHHN61Q3PF",
"parentId": null,
"appId": "c4jtk945h35i",
"eventType": "REQUEST.COMPLETED",
"resourceId": "REQ220706CLWJ6LP8H7Q",
"resource": {
"requestId": "REQ220706CLWJ6LP8H7Q",
"amount": 1000,
"currencyCode": "XAF",
"description": "Merchant Payment",
"transactionStatus": "SUCCESSFUL",
"creationTime": "2022-07-06T11:50:07+00:00",
"mchTransactionRef": "2333333",
"appId": "c4jtk945h35i",
"createdAt": "2022-07-06T11:50:07+00:00",
"transactionId": "TX2207063TBYGMKFY31I",
"transactionTime": "2022-07-06T11:51:32+00:00",
"fee": 29,
"payer": {
"userId": "GUEST_USER",
"name": "GUEST_USER",
"paymentMethod": "Visa/Mastercard",
"currencyCode": "XAF",
"countryCode": "CM",
"accountId": "MASTERCARD **2950",
"accountName": "MASTERCARD *NG",
"email": "dan@gmail.com",
"fee": 29,
"customerId": null
},
"merchant": {
"currencyCode": "XAF",
"amount": 1000,
"fee": 0,
"netAmountReceived": 1000,
"accountId": "PACVUM3QVMD3JFWZK7KF"
},
"links": {
"returnUrl": "https://local-api.tranzak.me/fapi/payment-callback/cmmomo"
}
},
"webhookId": "WHIDZ00LSVVTGZJO6EN5J2",
"authKey": "x5jxgsBb4cpukKBdwJjjXAN",
"isSuccess": true,
"url": "https://example.com/callback-listener",
"responseStatusCode": "200",
"errorDiagnosis": "SUCCESS",
"dispatchTime": "2022-07-06 11:51:32"
},
"success": true
}
Trigger a TPN
This action will cause a TPN to be sent to a configured URL endpoint. It takes a TPN ID as parent TPN and triggers a notification registered webhooks.
URL Endpoint
POST /xp021/v1/api-activity/trigger-tpn
Request body parameters
| Parameter | Type | required | Description |
|---|---|---|---|
| tpnId | String | true | The TPN ID e.g TPNVL1AVLIASS9JQPB6F3YKJV7I |
{
"tpnId": "TPNJUPU9U7NF3QQHILHHN61Q3PF"
}
Response payload
Success or failure message
{
"data": {
"message": "message"
},
"success": true,
}
Api Call History
Displays recent calls made to the merchant API endpoint. All API calls are automatically deleted after 7 days.
URL Endpoint
GET /xp021/v1/api-activity/api-calls
Filters
| Parameter | Type | Required | Description |
|---|---|---|---|
| appId | String | true | The app ID |
Response
| Parameter | Type | Required | Description |
|---|---|---|---|
| id | String | true | request ID |
| appId | String | true | the app ID |
| clientIpAddress | String | true | the client IP address |
| httpMethod | String | true | the HTTP method |
| responseCode | String | true | the HTTP response code e.g 200 |
| requestedUrl | String | true | the requested URL |
| requestedHost | String | true | the requested host endpoint |
| requestPayload | String | true | the submitted payload |
| createdAt | String | true | time of request |
Response
{
"data": {
"list": [
{
"id": "zwltjf1lpk09y6v213klb37h",
"appId": "c4jtk945h35i",
"clientIpAddress": "192.168.137.1",
"httpMethod": "POST",
"responseCode": 200,
"requestedUrl": "/mapi/xp021/v1/api-activity/trigger-tpn?id=TPNVL1AVLIASS9JQPB6F3YKJV7I",
"requestedHost": "https://local-api.tranzak.me",
"requestPayload": "{\r\n \"tpnId\": \"TPNJUPU9U7NF3QQHILHHN61Q3PF\"\r\n}",
"createdAt": "2022-07-06 12:05:11"
},
{
"id": "0lpl12byncdsnkpy95umau5n",
"appId": "c4jtk945h35i",
"clientIpAddress": "192.168.137.1",
"httpMethod": "POST",
"responseCode": 200,
"requestedUrl": "/mapi/xp021/v1/api-activity/trigger-tpn?id=TPNVL1AVLIASS9JQPB6F3YKJV7I",
"requestedHost": "https://local-api.tranzak.me",
"requestPayload": "{\r\n \"tpnId\": \"TPNVL1AVLIASS9JQPB6F3YKJV7I\"\r\n}",
"createdAt": "2022-07-06 12:05:03"
},
],
"totalItems": 219,
"pageCount": [
1,
50
],
"pageSize": 20,
"currentPage": 1,
"hasMore": true
},
"success": true
}
Payment Request (Collection API)
Create and manage payment requests. Payment requests provide trackable means of managing collections via Tranzak merchant API. Payment requests may be invoked as direct charges to valid mobile wallet numbers (e.g MTN Momo or Orange Money) or by redirecting the URL to a web payment endpoint. To prevent abuse, direct charges (to mobile wallets or otherwise ) are monitored closely and access may be revoked without notice if a breach of acceptable terms of use is observed.
Payment Request Status Codes
| Code | Description |
|---|---|
| PENDING | Payment request is pending and may receive payment. |
| SUCCESSFUL | The transaction was successfully completed. |
| CANCELLED | The request is cancelled and may not receive payment. |
| CANCELLED_BY_PAYER | Request was cancelled by payer. |
| FAILED | The resulting transaction failed. The payment request may no longer receive payment. |
| PAYMENT_IN_PROGRESS | Transaction process has been triggered but has not yet completed. |
| CANCELLED/REFUNDED | The transaction was voided. |
| PAYER_REDIRECT_REQUIRED | The payer should be redirected to a web resource ( paymentAuthUrl ). This happens when the payer is required to perform an action due to security restriction or other reasons e.g input an OTP, fill in CAPTCHA, etc. |
Common Attributes that apply when creating Payment Requests
The following parameters are applicable when creating any payment request. Endpoint-specific parameters will be provided based on the type of endpoint being called.
Request body parameters
| Parameter | Type | required | Description |
|---|---|---|---|
| amount | number | true | the amount to charge e.g. 1000 |
| currencyCode | String(3) | true | 3-letter currency code , e.g XAF |
| description | String(255) | true | Description of the transaction as shown to the payer. e.g "A bowl of beef pepper soup" |
| payerNote | String(32) | false | a note that will be displayed to the payer. This message will be shown to payer when authenticating via USSD (for mobile wallets) |
| mchTransactionRef | String(64) | false | Custom transaction reference which is used to prevent duplicate requests for the same resource. It is mandatory for calls that require direct charge. Must be unique per request for a duration of 30 days. e.g order10001 . |
| returnUrl | String(500) | false | URL that the payer shall be redirected to after payment is completed |
| cancelUrl | String(500) | false | URL that the payer shall be redirected to if payment is cancelled or aborted |
| receivingAccountId | String(32) | false | Where funds will be moved into after transaction is completed. The default is the primary account. Only merchant sub-accounts and primary account are accepted. e.g MSA3NS4SUHDKLEQJ46IK |
| serviceDiscountAmount | Number | false | This attribute informs the payer that the merchant had applied a discretional discount equivalent to this amount as part of the transaction. It is for informational purposes only and will not impact the transaction amount. Example: suppose the transaction amount is 1000XAF and the serviceDiscountAmount is 100XAF. It'd mean that the original transaction amount was 1000 + 100 = 1100XAF, thereby implying that the payer has enjoyed a discount of 100XAF. The 100XAF serviceDiscountAmount will NOT be deducted from the transaction amount , i.e. the payer will still be required to authorize 1000XAF . |
| receivingEntityName | string(32) | false | A custom name to identity the entity receiving this payment. This value could be a shop name, office, any thing useful for transaction analytics purposes , e.g Petit Boutique , Shop321 , etc |
| transactionTag | String(32) | false | A custom transaction tag, e.g booking123 that can be used to identify the transaction. Useful for transaction analytics/tracking purposes |
| customization | object | false | See Customization |
| payerFeePercentage | Number | false | The percentage of the fee that will be borne by the payer. Value should be between 0 and 100. A value of 100 would mean the payer will bear all charges while 0 (default) would mean payer bears zero charges. This value will override the default merchant setting. NOTE : To prevent abuse, this capability must first be enabled on the business portal before it can be used. Failure to enable on the portal will cause the setting to be ignored. |
| callbackUrl | String(1000) | false | the URL which be invoked after the request is processed. e.g http://mycallback.com/notification . Optionally , you may set global callback URLs for different events using webhooks. |
Customization
The layout of the payment authorization page can be customized using the following parameters:
| Parameter | Type | required | Description |
|---|---|---|---|
| logoUrl | String | false | the URL of the logo to display on Tranzak Payment Gateway Portal to charge e.g. https://example.com/img/tz-logo.31b9da63.png |
| title | String | false | the caption that will be displayed to the payer e.g. Cool Business Ltd |
Create (web redirect payment)
Creates a payment request. The payer should be redirected to the paymentAuthUrl resource to complete the payment.
Endpoint URL
POST /xp021/v1/request/create
Request body parameters
See the Common Payment Request Parameters
{
"amount": 2000,
"currencyCode": "XAF",
"description": "A plate of fufu and eru",
"mchTransactionRef": "myorder234555666",
"returnUrl": "https://partner.example.com/fapi/order/processOrder?123444"
}
Response
See the Details Section
Create Mobile Money Charge
Creates a direct charge of for a money money number. The request will be pushed directly to the mobile number for authorization.
NOTE : The following services are supported : MTN Cameroon Mobile Money, Orange Money Cameroon. For non-Cameroonian mobile wallet services, use the web redirect option.
Endpoint URL
POST /xp021/v1/request/create-mobile-wallet-charge
Request body parameters
| Parameter | Type | required | Description |
|---|---|---|---|
| mobileWalletNumber | String(255) | true | The mobile wallet number to charge. Must be prefixed with country code. e.g 237680657567 |
| mchTransactionRef | String(32) | true | Custom transaction reference. Must be unique per for the last 30 days and will be used for tracking of the request, e.g order10001 |
{
"amount": 2000,
"currencyCode": "XAF",
"description": "A plate of fufu and eru",
"mchTransactionRef": "myorder234555666",
"mobileWalletNumber": "237680657567",
"returnUrl": "https://partner.example.com/fapi/order/processOrder?123444"
}
Response
See the Details Section
Create Direct Charge via Tranzak QR Code (In-Store Payment)
Creates a direct charge using QR Code obtained from Tranzak mobile app. The request will be pushed directly to the user for authorization. NOTE : To prevent abuse, access to this service will be disabled after 10 failed attempts.
Endpoint URL
POST /xp021/v1/request/create-in-store-charge
Request body parameters
| Parameter | Type | required | Description |
|---|---|---|---|
| authCode | String(255) | true | The authorization code extracted from the payer's QR code via Tranzak mobile app. e.g 318277652078079548470738 |
| mchTransactionRef | String(32) | true | Custom transaction reference. Must be unique per merchant (within 30-day period), e.g order10001 |
{
"amount": 2000,
"currencyCode": "XAF",
"description": "A plate of fufu and eru",
"mchTransactionRef": "myorder234555666",
"authCode": "318277652078079548470738",
"returnUrl": "https://partner.example.com/fapi/order/processOrder?123444"
}
Response
See the Details Section
Request Details
Displays payment request details.
Endpoint URL
GET /xp021/v1/request/details?requestId={REQUEST_ID}
Request body parameters
| Parameter | Type | required | Description |
|---|---|---|---|
| requestId | String | true | the request ID. Used for tracking the request throughout the payment cycle. |
| amount | Number | true | the transaction amount , e.g 1000 |
| currencyCode | String(3) | true | The 3-letter currency code, e.g XAF |
| description | String | true | Transaction description |
| status | String | true | the transaction status |
| mchTransactionRef | String | true | merchant customer reference number |
| appId | String | true | the app ID that created the request |
| serviceDiscountAmount | String | true | The discount applied by merchant for this transaction |
| createdAt | String | true | Date/time the request was created |
| links | object | true | links object (see links below) |
Links
| Parameter | Type | required | Description |
|---|---|---|---|
| returnUrl | String(500) | false | the URL that the payer shall be returned to upon completion of transaction |
| paymentAuthUrl | String(500) | false | the payment authorization URL. The payer shall be redirected to this URL to authorize the payment. |
Response
PENDING
{
"data": {
"requestId": "REQ220705LXLDET890D9",
"amount": 1000,
"currencyCode": "XAF",
"description": "Merchant Payment",
"status": "PENDING",
"creationTime": "2022-07-05T16:15:35+00:00",
"mchTransactionRef": "2333333",
"appId": "c4jtk945h35i",
"createdAt": "2022-07-05T16:15:35+00:00",
"links": {
"returnUrl": "https://local-api.tranzak.me/fapi/order/processOrder?123444",
"paymentAuthUrl": "https://pay.tranzak.me/flow/REQ220705LXLDET890D9"
}
},
"success": true
}
SUCCESSFUL STATUS
| Parameter | Type | required | Description |
|---|---|---|---|
| requestId | String | true | the request ID. Used for tracking the request throughout the payment cycle. |
| amount | Number | true | the transaction amount , e.g 1000 |
| currencyCode | String(3) | true | The 3-letter currency code, e.g XAF |
| description | String | true | Transaction description |
| status | String | true | the transaction status |
| mchTransactionRef | String | true | merchant customer reference number |
| appId | String | true | the app ID that created the request |
| createdAt | String | true | Date/time the request was created |
| links | object | true | links |
| transactionId | String | true | the resulting transaction ID |
| transactionTime | String | true | transaction time |
| fee | String | true | the transaction fee. |
| payer | object | true | json object |
| merchant | object | true | links |
payer
| Parameter | Type | required | Description |
|---|---|---|---|
| userId | String(32) | true | the payer user identifier on Tranzak |
| name | String(32) | true | The payer name |
| paymentMethod | String(32) | true | The payment method , e.g MTN MOMO |
| currencyCode | String(3) | true | The currency, e.g XAF |
| countryCode | String(2) | true | The country code of payer, e.g CM . See Country codes for list of countries and their ISO 3166 codes |
| accountId | String(32) | true | Payment account reference e.g 237680657567 for mobile money payment |
| accountName | String(32) | true | The country code of payer, e.g 237680657567 |
| String(32) | true | The email , e.g 4bracelets@piggymail.com |
|
| fee | String(32) | true | Fee paid by payer (in payer's currency) |
| customerId | String(32) | false | The customer ID of the payer (if the payer is non-guest) |
merchant
| Parameter | Type | required | Description |
|---|---|---|---|
| currencyCode | String(3) | true | the merchant receiving currency code |
| amount | Number | true | the merchant receiving currency code |
| fee | Number | true | The fee deducted |
| netAmountReceived | Number | true | The net amount received by merchant |
| accountId | String(32) | true | The receiving account ID e.g MSA3NS4SUHDKLEQJ46IK |
Foreign Currency Transactions
Applicable for transactions involving foreign more than one currency.
| Parameter | Type | required | Description |
|---|---|---|---|
| rate | decimal | true | The sell rate |
| fromAmount | Number | true | source amount e.g. 100.00 |
| fromCurrencyCode | string(3) | true | The source currency code e.g USD |
| toAmount | Number | true | the destination amount e.g 59831 |
| toCurrencyCode | String(3) | true | The destination currency e.g XAF |
{
"data": {
"requestId": "REQ22070523Y5CN8MXJQ",
"amount": 20000,
"currencyCode": "XAF",
"description": "Merchant Payment",
"status": "SUCCESSFUL",
"creationTime": "2022-07-05T16:21:03+00:00",
"mchTransactionRef": "2333333",
"appId": "c4jtk945h35i",
"createdAt": "2022-07-05T16:21:03+00:00",
"transactionId": "TX2207059FKZNWLOLR1F",
"transactionTime": "2022-07-05T16:21:10+00:00",
"fee": 0,
"payer": {
"userId": "tznzgirh9u9jskm7",
"name": "+237680657567",
"paymentMethod": "MTN Momo",
"currencyCode": "XAF",
"countryCode": "CM",
"accountId": "237680657567",
"accountName": "237680657567",
"email": null,
"fee": 0,
"customerId": "CUSP4IKM9F0PKMZQ"
},
"merchant": {
"currencyCode": "XAF",
"amount": 20000,
"fee": 0,
"netAmountReceived": 20000,
"accountId": "PACVUM3QVMD3JFWZK7KF"
},
"links": {
"returnUrl": ""
}
},
"success": true
}
Example response with currency conversion
{
"data": {
"requestId": "REQ2207059BL9UEYDW5L",
"amount": 100,
"currencyCode": "USD",
"description": "A transaction for the world",
"status": "SUCCESSFUL",
"creationTime": "2022-07-05T16:44:59+00:00",
"mchTransactionRef": "sssssshssssssss",
"appId": "c4jtk945h35i",
"createdAt": "2022-07-05T16:44:59+00:00",
"transactionId": "TX2207050K8GP99V1SY8",
"transactionTime": "2022-07-05T16:44:59+00:00",
"fee": 0,
"payer": {
"userId": "tz29",
"name": "tzid29",
"paymentMethod": "TRANZAK",
"currencyCode": "XAF",
"countryCode": "CM",
"accountId": "tz29",
"accountName": "tzid29",
"email": null,
"fee": 0,
"customerId": "CUSX72M70ZYXLYIB"
},
"merchant": {
"currencyCode": "XAF",
"amount": 59831,
"fee": 0,
"netAmountReceived": 59831,
"accountId": "PACVUM3QVMD3JFWZK7KF"
},
"forex": {
"rate": 598.31,
"fromAmount": 100,
"fromCurrencyCode": "USD",
"toAmount": 59831,
"toCurrencyCode": "XAF"
},
"links": {
"returnUrl": ""
}
},
"success": true
}
Cancel a request
Cancels an unpaid payment request.
Request body params
POST /xp021/v1/request/cancel
| Parameter | Type | required | Description |
|---|---|---|---|
| requestId | String(32) | true | The payment request ID |
{
"requestId": "REQ220705UL6WUKML4QX"
}
Response Body
The payment request details
{
"data": {
"requestId": "REQ220705UL6WUKML4QX",
"amount": 1000,
"currencyCode": "XAF",
"description": "Merchant Payment",
"status": "CANCELLED",
"creationTime": "2022-07-05T16:52:35+00:00",
"mchTransactionRef": "2333333",
"appId": "apc4jtk945h35i",
"createdAt": "2022-07-05T16:52:35+00:00"
},
"success": true
}
Void a request
Cancels an unpaid or paid request. Note: *** If payment had been received, a refund will be triggered. ***
Request body params
POST /xp021/v1/request/void
| Parameter | Type | Required | Description |
|---|---|---|---|
| requestId | String(32) | true | The payment request ID |
{
"requestId": "REQ220705UL6WUKML4QX"
}
Response Body
The payment request details
{
"data": {
"requestId": "REQ220705FBJF5ASFQKO",
"amount": 100,
"currencyCode": "USD",
"description": "A transaction for the world",
"status": "CANCELLED/REFUNDED",
"creationTime": "2022-07-05T17:00:00+00:00",
"mchTransactionRef": "sssssshssssssss",
"appId": "c4jtk945h35i",
"createdAt": "2022-07-05T17:00:00+00:00",
"transactionId": "TX220705NTXSYJPQL5R9",
"transactionTime": "2022-07-05T17:00:00+00:00",
"fee": 0,
"payer": {
"userId": "tz29",
"name": "tzid29",
"paymentMethod": "TRANZAK",
"currencyCode": "XAF",
"countryCode": "CM",
"accountId": "tz29",
"accountName": "tzid29",
"email": null,
"fee": 0,
"customerId": "CUSX72M70ZYXLYIB"
},
"merchant": {
"currencyCode": "XAF",
"amount": 59831,
"fee": 0,
"netAmountReceived": 59831,
"accountId": "PACVUM3QVMD3JFWZK7KF"
},
"forex": {
"rate": 598.31,
"fromAmount": 100,
"fromCurrencyCode": "USD",
"toAmount": 59831,
"toCurrencyCode": "XAF"
},
"links": {
"returnUrl": ""
}
},
"success": true
}
Request History
Display list of requests sorted by the most recent requests.
Request body params
GET /xp021/v1/request/history
Filters
| Parameter | Type | required | Description |
|---|---|---|---|
| requestId | String(32) | true | The request ID |
| invoiceId | String(32) | true | filter by invoice ID |
| receivingAccountId | String(32) | true | reference ID |
| transactionId | String(32) | true | filter by transaction ID |
{
"data": {
"list": [
{
"requestId": "REQ220705FBJF5ASFQKO",
"status": "CANCELLED",
"amount": 100,
"currencyCode": "USD",
"description": "A transaction for the world",
"mchTransactionRef": "sssssshssssssss",
"creationTime": "2022-07-05 17:00:00",
"transactionId": "TX220705NTXSYJPQL5R9",
"status": "REFUNDED",
"transactionTime": "2022-07-05 17:00:00.743840"
},
{
"requestId": "REQ220705UL6WUKML4QX",
"status": "CANCELLED",
"amount": 1000,
"currencyCode": "XAF",
"description": "Merchant Payment",
"mchTransactionRef": "2333333",
"creationTime": "2022-07-05 16:52:35"
},
{
"requestId": "REQ2207059BL9UEYDW5L",
"status": "SUCCESSFUL",
"amount": 100,
"currencyCode": "USD",
"description": "A transaction for the world",
"mchTransactionRef": "sssssshssssssss",
"creationTime": "2022-07-05 16:44:59",
"transactionId": "TX2207050K8GP99V1SY8",
"status": "SUCCESSFUL",
"transactionTime": "2022-07-05 16:44:59.621916"
}
],
"totalItems": 40,
"pageCount": [
1,
50
],
"pageSize": 10,
"currentPage": 1,
"hasMore": true
},
"success": true
}
Refresh Transaction Status
This endpoint is used to refresh a the transaction status of a request. Occasionally, though rarely, some operators such as mobile money providers, might be not send out timely notification when a transaction completes. This endpoint can be called to forcefully obtain the latest transaction status from a third party provider thereby enhancing the payment experience for the payer.
Request body params
POST /xp021/v1/request/refresh-transaction-status
| Parameter | Type | required | Description |
|---|---|---|---|
| requestId | String(32) | true | The payment request ID |
{
"requestId": "REQ220705UL6WUKML4QX"
}
Response Body
See payment request [[details]] section
Webhook Details
Webhooks are sent out during when the payment request reaches any of the following states:
- SUCCESSFUL
- FAILED
Event type
To receive callbacks for payment requests, you should create a webhook and subscribe to the following event type : REQUEST.COMPLETED
Callback Payload
| Parameter | Type | required | Description |
|---|---|---|---|
| name | String | true | the TPN info e.g. Tranzak Payment Notification (TPN) |
| version | String | true | The TPN version , e.g 1.0 |
| eventType | String | true | The event type that triggered the callback, e.g REQUEST.COMPLETED |
| appId | String | true | The appId that created the request |
| resourceId | String | true | Unique identifier of the request, e.g. REQ231121WCZRHH2505D |
| resource | JSON object | true | This parameter contains the API response of the request and provides details about the transaction (whether SUCCESSFUL or FAILED.) |
| webhookId | String | true | The webhook reference that triggered the callback |
| creationDateTime | String | true | The time the request was generated |
| authKey | String | true | The authentication key (if configured by the user). It may be used to verify that the payload originated from Tranzak servers. |
SUCCESSFUL Transaction
{
"name": "Tranzak Payment Notification (TPN)",
"version": "1.0",
"eventType": "REQUEST.COMPLETED",
"merchantId": null,
"appId": "apnz8rfqqsgoai",
"resourceId": "REQ231121CIPGSDPMO6J",
"resource": {
"requestId": "REQ231121CIPGSDPMO6J",
"amount": 1000,
"currencyCode": "XAF",
"description": "API Demo",
"mobileWalletNumber": "237674460261",
"status": "SUCCESSFUL",
"transactionStatus": "SUCCESSFUL",
"createdAt": "2023-11-21T03:09:48+00:00",
"mchTransactionRef": "myorder234555666",
"appId": "apnz8rfqqsgoai",
"payerNote": "",
"serviceDiscountAmount": null,
"payerFeePercentage": 0,
"invoiceId": "11111111",
"receivingAccountId": "MSA49HR76HJZ2FQ812WG",
"transactionId": "TX23112186UW8KNF1T07",
"transactionTime": "2023-11-21T03:09:51+00:00",
"partnerTransactionId": "sb_5751652493",
"payer": {
"userId": "tz8pq60s0o79pzn7",
"name": "TFT Thrift Shop",
"paymentMethod": "MTN Momo",
"currencyCode": "XAF",
"countryCode": "CM",
"accountId": "237674460261",
"accountName": "",
"email": null,
"amount": 1000,
"discount": 0,
"fee": 0,
"netAmountPaid": 1000
},
"merchant": {
"currencyCode": "XAF",
"amount": 1000,
"fee": 20,
"netAmountReceived": 980,
"accountId": "MSA49HR76HJZ2FQ812WG"
},
"links": {
"returnUrl": "https://MY_CALLBACK_URL/tranzak_tpn"
}
},
"creationDateTime": "2023-11-21 03:09:52",
"webhookId": "WHM9G4RW7DDXMLIXU6EBZ5",
"authKey": "jaldfjalsdjkssssssssssssssssssssss"
}
FAILED Transaction
{
"name": "Tranzak Payment Notification (TPN)",
"version": "1.0",
"eventType": "REQUEST.COMPLETED",
"merchantId": null,
"appId": "apnz8rfqqsgoai",
"resourceId": "REQ231121BKKJYX5PLZ8",
"resource": {
"requestId": "REQ231121BKKJYX5PLZ8",
"amount": 1000,
"currencyCode": "XAF",
"description": "API Demo",
"mobileWalletNumber": "237674000000",
"status": "FAILED",
"transactionStatus": "FAILED",
"createdAt": "2023-11-21T03:12:38+00:00",
"mchTransactionRef": "myorder234555666",
"appId": "apnz8rfqqsgoai",
"payerNote": "",
"serviceDiscountAmount": null,
"payerFeePercentage": 0,
"invoiceId": "11111111",
"receivingAccountId": "MSA49HR76HJZ2FQ812WG",
"links": {
"returnUrl": "https://MY_CALLBACK_URL/tranzak_tpn"
},
"errorCode": 5002,
"errorMessage": "SYSTEM_GENERAL_VALIDATION_ERROR"
},
"creationDateTime": "2023-11-21 03:12:39",
"webhookId": "WHM9G4RW7DDXMLIXU6EBZ5",
"authKey": "jaldfjalsdjkssssssssssssssssssssss"
}
Transfer (Disbursement API)
This interface is used to transfer funds from the PAYOUT account to a beneficiary. The beneficiary may be a tranzak user account, a mobile wallet account (MTN MOMO , OM) or bank account Prior to making transfers, the partner must ensure that their PAYOUT account has sufficient usable balance.
Transfer Status Codes
| Code | Description |
|---|---|
| PENDING | Request has not been authorized and pending payment. |
| SUCCESSFUL | The transaction was successfully completed. |
| CANCELLED | The transfer was cancelled |
| FAILED | The transfer failed. |
| PROCESSING | The transfer is being processed by Tranzak internal system. This is applicable only in situations where the beneficiary is a mobile wallet or bank account. |
Common Attributes
The following parameters are applicable when creating any transfer. Endpoint-specific parameters will be provided based on the type of endpoint being called.
Request body parameters
| Parameter | Type | required | Description |
|---|---|---|---|
| amount | number | true | the amount to charge e.g. 1000 |
| currencyCode | String(3) | true | 3-letter currency code , e.g XAF |
| description | String(255) | true | Description of the transaction as shown to the payer. e.g "A bowl of goat pepper soup" |
| customTransactionRef | String(64) | false | Custom transaction reference which is used to prevent duplicate requests for the same resource. It is mandatory since it's used to prevent duplicate transactions. Must be unique per request for a duration of 30 days. e.g order10001 . |
| payeeAccountId | String(100) | true | The payee account ID. For internal (Tranzak) users, this may be the Tranzak ID (e.g tzuo7s3tbyjszfkf ) or the mobile phone number (e.g. +237674460261). For mobile wallet transfers this value will be the beneficiary mobile phone number. For bank account, use the bank account number |
| payeeAccountName | String(100) | false | The payee account name. This is mandatory only for bank account transfers. |
| verifyPayeeName | boolean | false | (For mobile wallet transactions) Whether or not to verify the name of the beneficiary. Default is true . Note: when verification is set to true, the payeeAccountName will be verified with the mobile money operator. In case of mismatch, the transaction will fail. |
| payeeNote | String(100) | false | A message that will be displayed to the payee |
| callbackUrl | String(1000) | false | the URL which will be invoked after the request is processed. e.g http://mycallback.com/notification . Optionally , you may set global callback URLs for different events using webhooks. |
| payeeFeePercentage | float | false | The percentage of the fee that will be borne by the payee. Range 0 =< payeeFeePercentage <= 100 . For example, a value of 100 would mean that the payee bears 100% fee which 0 would mean payee bears 0% fee. Default is null which will use the global value set in the Dashboard. |
| sendSmsToPayee | Boolean | false | Whether to send SMS to recipients. Default is false. e.g. false |
| sms | Object | false | SMS object (see below) |
SMS Body (wrapped inside sms object )
| Parameter | Type | required | Description |
|---|---|---|---|
| mobileNumber | String | true | The mobile number to receive SMS notification (if SMS messaging is enabled). This is optional for mobile money transfers. Example: +237674000000 |
| content | String | true | SMS content (limited to 160 ASCII characters) e.g. "Thank you for your business |
Example
"sms": {
"content": "This is the content for SMS",
"mobileNumber": "+237674888888"
}
Transfer to Tranzak Users
Funds will be transferred to the payee account.
Endpoint URL
POST /xp021/v1/transfer/to-internal-user
Request body parameters
See the Common Parameters
{
"amount": "10000",
"currencyCode": "XAF",
"description": "Supplier payment",
"customTransactionRef": "order123",
"payeeAccountId": "tz8lp20abxqslgqc",
"payeeAccountName": "Ben Orock" ,
"payeeNote" : "Payment for 2 bags of cement"
}
Response
See the details section
Transfer To Mobile Money
Transfers funds from Payout account to mobile wallet.
NOTE : The following services are supported : MTN Cameroon Mobile Money, Orange Money Cameroon.
Endpoint URL
POST /xp021/v1/transfer/to-mobile-wallet
Request body parameters
See common attributes above.
NOTE Test numbers may be used to simulated different outcomes (SUCCESSFUL, FAILED, PROCESSING) .
{
"amount": "10000",
"currencyCode": "XAF",
"description": "Supplier payment",
"customTransactionRef": "order123",
"payeeAccountId": "237674000000",
"payeeAccountName": "Ben Orock",
"payeeNote": "Payment for 2 bags of cement"
}
Response
See the details section
Transfer To CEMAC Bank Account
Transfers funds from Payout account to CEMAC bank account.
NOTE : Only Cameroonian banks are currently supported.
Endpoint URL
POST /xp021/v1/transfer/to-bank-account
Request body parameters
See common attributes above.
NOTE The bank account number must be 23-digit CEMAC bank account type in the format : BBBBBCCCCCAAAAAAAKK Where : BBBBB is the 5-digit bank code , CCCCC is the 5-digit branch code, AAAAAAAAAAA is the 11-digit account number and KK the RIB. Example : 10005000220449496105178
{
"amount": "10000",
"currencyCode": "XAF",
"description": "Bank transfer test",
"customTransactionRef": "testorder123",
"payeeAccountId": "10005000220449496105178",
"payeeAccountName": "Tranzak ACME Corp",
"payeeNote": "Service charge"
}
Response
See the details section
Top-up Payout Account
This endpoint is used to top up the payout (disbursement) account from a collection account. By default, the primary collection account will be used as funding source.
Endpoint URL
POST /xp021/v1/transfer/payout-account-topup
Request body parameters
Request body parameters
| Parameter | Type | required | Description |
|---|---|---|---|
| amount | number | true | the amount to charge e.g. 1000 |
| currencyCode | String(3) | true | 3-letter currency code , e.g XAF |
| description | String(255) | false | Description of the transaction as shown to the payer. e.g "A bowl of goat pepper soup" |
| customTransactionRef | String(32) | false | Custom transaction reference which is used to prevent duplicate requests for the same resource. It is mandatory since it's used to prevent duplicate transactions. Must be unique per request for a duration of 30 days. e.g order10001 . |
| fundingAccountId | String(100) | false | The funding account ID. (e.g PACG50J3D402X9LEXROU ). The default (primary collection) account will be used if fundingAccountId is not specified. |
| payeeNote | String(100) | false | A custom note. |
NOTE By default, the primary collection account will be used to fund the transaction. Ensure the funding account has sufficient balance to fund the transaction. You may specify any collection account (e.g collection sub-account) , by specifying the account ID.
{
"amount": "100",
"currencyCode": "XAF",
"description": "Supplier payment",
"customTransactionRef": "order123",
"payeeNote": "Payout account topup"
}
Response
See the [details] section
{
"data": {
"transferId": "TF230629EEHUFTQDTMTT",
"status": "SUCCESSFUL",
"payeeAccountId": "POT3XUVED48LW0F1PHFB",
"fundingAccountId": "PACG50J3D402X9LEXROU",
"payeeAccountName": "Payout account",
"destinationServiceName": "TRANZAK",
"payeeNote": "Payout account topup",
"description": "Supplier payment",
"amount": 100,
"currencyCode": "XAF",
"fee": 0,
"customTransactionRef": "order123",
"createdByAppId": "apnz8rfqqsgoai",
"type": "payout account top-up",
"transactionId": "TX230629K3VRV0LCMAGR",
"transactionTime": "2023-06-29T13:04:15+00:00",
"createdAt": "2023-06-29T13:04:15+00:00"
},
"success": true
}
Request Details
Displays payment request details.
Endpoint URL
GET /xp021/v1/transfer/details?transferId={TRANSFER_ID}
Request body parameters
| Parameter | Type | required | Description |
|---|---|---|---|
| transferId | String | true | the unique transferId ID. Used for tracking |
| customTransactionRef | String(32) | false | Custom transaction reference which is used to prevent duplicate |
Response
SUCCESSFUL outcome
{
"data": {
"transferId": "TF230510WU42HK62KTR1",
"status": "SUCCESSFUL",
"payeeAccountId": "tz8lp20abxqslgqc",
"payeeAccountName": "Ben Orock",
"destinationServiceName": "TRANZAK ACCOUNT",
"payeeNote": "Payment for 2 bags of cement",
"description": "Supplier payment",
"amount": 10000,
"currencyCode": "XAF",
"fee": 0,
"customTransactionRef": "order123",
"createdByAppId": "apnz8rfqqsgoai",
"type": "internal transfer",
"transactionId": "TX230510WB8UFGSF11QI",
"transactionTime": "2023-05-10T13:10:53+00:00",
"createdAt": "2023-05-10T13:10:53+00:00"
},
"success": true
}
PROCESSING
{
"data": {
"transferId": "TF230510GBYJ7ZERTUB2",
"status": "PROCESSING",
"payeeAccountId": "237674000000",
"payeeAccountName": "Ben Orock",
"destinationServiceName": "MTN Momo",
"payeeNote": "Payment for 2 bags of cement",
"description": "Supplier payment",
"amount": 10000,
"currencyCode": "XAF",
"fee": 130,
"customTransactionRef": "order123",
"createdByAppId": "apnz8rfqqsgoai",
"type": "mobile money transfer",
"createdAt": "2023-05-10T13:13:12+00:00"
},
"success": true
}
FAILED
{
"data": {
"transferId": "TF230510GBYJ7ZERTUB2",
"status": "FAILED",
"payeeAccountId": "237674000000",
"payeeAccountName": "Ben Orock",
"destinationServiceName": "MTN Momo",
"payeeNote": "Payment for 2 bags of cement",
"description": "Supplier payment",
"amount": 10000,
"currencyCode": "XAF",
"fee": 130,
"customTransactionRef": "order123",
"createdByAppId": "apnz8rfqqsgoai",
"type": "mobile money transfer",
"errorMessage": "administratively restricted",
"refundId": "REV230510MWMJSH1",
"createdAt": "2023-05-10T13:13:12+00:00"
},
"success": true
}
Request History
Displays paginated list of transfers sorted by the most recent.
Request body params
GET /xp021/v1/transfer/history
Filters
| Parameter | Type | required | Description |
|---|---|---|---|
| transferId | String(32) | true | The request ID |
| transactionId | String(32) | true | filter by transaction ID |
| refundId | String(32) | true | filter by refund ID |
| description | String(32) | true | description |
| customTransactionRef | String(32) | true | custom transaction reference |
| payeeAccountId | String(32) | true | payerAccountId |
| payeeAccountName | String(32) | true | payeeAccountName |
| payeeNote | String(32) | true | payeeNote |
{
"data": {
"list": [
{
"transferId": "TF230510ADMINJYNCS1E",
"status": "PROCESSING",
"payeeAccountId": "10005000220449496105178",
"payeeAccountName": "Tranzak ACME Corp",
"destinationServiceName": "Afriland First Bank (Cameroon)",
"payeeNote": "Service charge",
"description": "Bank transfer test",
"amount": 10000,
"currencyCode": "XAF",
"fee": 130,
"customTransactionRef": "testorder123",
"createdByAppId": "apnz8rfqqsgoai",
"type": "bank transfer",
"createdAt": "2023-05-10T13:21:21+00:00"
},
{
"transferId": "TF230510GBYJ7ZERTUB2",
"status": "FAILED",
"payeeAccountId": "237674000000",
"payeeAccountName": "Ben Orock",
"destinationServiceName": "MTN Momo",
"payeeNote": "Payment for 2 bags of cement",
"description": "Supplier payment",
"amount": 10000,
"currencyCode": "XAF",
"fee": 130,
"customTransactionRef": "order123",
"createdByAppId": "apnz8rfqqsgoai",
"type": "mobile money transfer",
"errorMessage": "administratively restricted",
"refundId": "REV230510MWMJSH1",
"createdAt": "2023-05-10T13:13:12+00:00"
},
{
"transferId": "TF230510WU42HK62KTR1",
"status": "SUCCESSFUL",
"payeeAccountId": "tz8lp20abxqslgqc",
"payeeAccountName": "Ben Orock",
"destinationServiceName": "TRANZAK ACCOUNT",
"payeeNote": "Payment for 2 bags of cement",
"description": "Supplier payment",
"amount": 10000,
"currencyCode": "XAF",
"fee": 0,
"customTransactionRef": "order123",
"createdByAppId": "apnz8rfqqsgoai",
"type": "internal transfer",
"transactionId": "TX230510WB8UFGSF11QI",
"transactionTime": "2023-05-10T13:10:53+00:00",
"createdAt": "2023-05-10T13:10:53+00:00"
},
],
"totalItems": 40,
"pageCount": [
1,
50
],
"pageSize": 10,
"currentPage": 1,
"hasMore": true
},
"success": true
}
Webhook Details
Webhooks are sent out during when the transfer reaches any of the following states:
- SUCCESSFUL
- FAILED
Event type
To receive callbacks for payment requests, you should create a webhook and subscribe to the following event type : TRANSFER.COMPLETED
Callback Payload
| Parameter | Type | required | Description |
|---|---|---|---|
| name | String | true | the TPN info e.g. Tranzak Payment Notification (TPN) |
| version | String | true | The TPN version , e.g 1.0 |
| eventType | String | true | The event type that triggered the callback, e.g TRANSFER.COMPLETED |
| appId | String | true | The appId that created the request |
| resourceId | String | true | Unique identifier of the request, e.g. TF231121DN4QCAPWNI9D |
| resource | JSON object | true | This parameter contains the API response of the request and provides details about the transaction (whether SUCCESSFUL or FAILED.) |
| webhookId | String | true | The webhook reference that triggered the callback |
| creationDateTime | String | true | The time the request was generated |
| authKey | String | true | The authentication key (if configured by the user). It may be used to verify that the payload originated from Tranzak servers. |
SUCCESSFUL Transaction
{
"name": "Tranzak Payment Notification (TPN)",
"version": "1.0",
"eventType": "TRANSFER.COMPLETED",
"merchantId": null,
"appId": "apnz8rfqqsgoai",
"resourceId": "TF231121DN4QCAPWNI9D",
"resource": {
"transferId": "TF231121DN4QCAPWNI9D",
"status": "SUCCESSFUL",
"payeeAccountId": "237674460261",
"fundingAccountId": "POT3XUVED48LW0F1PHFB",
"payeeAccountName": "Dee",
"destinationServiceName": "MTN Momo",
"payeeNote": "Cheers",
"description": "Transfer test",
"amount": 500,
"currencyCode": "XAF",
"fee": 5,
"customTransactionRef": "test1",
"createdByAppId": "apnz8rfqqsgoai",
"payoutId": null,
"type": "mobile money transfer",
"transactionId": "TX2311212SULTDPCN15R",
"transactionTime": "2023-11-21T03:15:46+00:00",
"partnerTransactionId": "test-4345224539",
"sendSmsToPayee": true,
"smsContent": "This is the content for SMS",
"smsMobileNumber": "+237674460261",
"payeeSmsSuccess": null,
"createdAt": "2023-11-21T03:15:46+00:00"
},
"creationDateTime": "2023-11-21 03:16:21",
"webhookId": "WHM9G4RW7DDXMLIXU6EBZ5",
"authKey": "jaldfjalsdjkssssssssssssssssssssss"
}
FAILED Transaction
{
"name": "Tranzak Payment Notification (TPN)",
"version": "1.0",
"eventType": "TRANSFER.COMPLETED",
"merchantId": null,
"appId": "apnz8rfqqsgoai",
"resourceId": "TF231121DDAJL9ZOJCF0",
"resource": {
"transferId": "TF231121DDAJL9ZOJCF0",
"status": "FAILED",
"payeeAccountId": "237674000000",
"fundingAccountId": "POT3XUVED48LW0F1PHFB",
"payeeAccountName": "Dee",
"destinationServiceName": "MTN Momo",
"payeeNote": "Cheers",
"description": "Transfer test",
"amount": 1,
"currencyCode": "XAF",
"fee": 0,
"customTransactionRef": "test1",
"createdByAppId": "apnz8rfqqsgoai",
"payoutId": null,
"type": "mobile money transfer",
"errorMessage": "administratively restricted",
"refundId": "REV231121J6O5LFO",
"sendSmsToPayee": true,
"smsContent": "This is the content for SMS",
"smsMobileNumber": "+237674460261",
"payeeSmsSuccess": null,
"createdAt": "2023-11-21T03:30:29+00:00"
},
"creationDateTime": "2023-11-21 03:30:30",
"webhookId": "WH8UDGOZ9O5T2PDTIA6CTD",
"authKey": "jaldfjalsdjkssssssssssssssssssssss"
}
Bulk Payment API
This endpoint is used to initiate bulk payment to Tranzak users, mobile money or bank accounts. Payment can be made to a single recipient or many recipients in a single request. Up to 2000 recipients may be specified in a single request. By default, the funding source is the PAYOUT account and this account must have enough balance otherwise the transaction would fail.
NOTE API Payout must be enabled on the merchant portal prior to using this endpoint otherwise all API calls to the payout endpoint will fail.
Status Codes
| Code | Description |
|---|---|
| PENDING | Transfer request has not been authorized and is pending payment. |
| SUCCESSFUL | The payout has been authorized and all transfers have been successfully completed |
| CANCELLED | The request is cancelled and may not be authorized |
| QUEUED | The payout has been authorized. Secondary transactions have been queued waiting to be processed. |
| PROCESSING | The payout has been authorized. Secondary transactions are being processed |
Bulk Payment Types
Internal
Transfer funds to one or more Tranzak users.
Mobile Wallet
Transfer to one or more mobile wallet users. As of February 2023, only MTN MOMO and Orange Money Cameroon are supported.
Bank Account
Transfer to one or more bank accounts. As of February 2023, only banks in Cameroon are supported.
Note on File Upload
Bulk Payment is supported through file upload. Download the template from the business portal for the desired transaction. Upload the file as form-data using uploadedFile as file parameter. Use the Postman configuration provided as example.
Common Attributes that apply when creating Payment Requests
The following parameters are applicable when creating any payment request. Endpoint-specific parameters will be provided based on the type of endpoint being called.
Request body parameters
| Parameter | Type | required | Description |
|---|---|---|---|
| title | string(100) | true | The title of the request |
| description | string(254) | true | Description of transfer |
| currencyCode | String(3) | true | 3-letter currency code , e.g XAF |
| isPriority | Boolean | false | Whether priority queuing should be used. |
| customTransactionRef | String(32) | false | Custom transfer request reference |
| recipients | Array | true | See recipient object format below |
| verifyPayeeName | Bool | false | Default true, meaning Tranzak will validate the name of the beneficiary with the name provided. If the names do not match, the transaction will be temporarily halted pending manual authorization from the requester. NOTE this service is currently available only for MTN and Orange (CAMEROON) Mobile Money numbers. |
| callbackUrl | String(1000) | false | the URL which will be invoked after the request is processed. e.g http://mycallback.com/notification . Optionally , you may set global callback URLs for different events using webhooks. |
| payeeFeePercentage | float | false | The percentage of the fee that will be borne by the payee. Range 0 =< payeeFeePercentage <= 100 . For example, a value of 100 would mean that the payee bears 100% fee which 0 would mean payee bears 0% fee. Default is null which will use the global value set in the Dashboard. |
| sendSmsToPayee | Boolean | false | Whether to send SMS to recipients. Default is false. e.g. false |
| sms | Object | false | SMS object (see below) |
SMS Body (wrapped inside sms object )
| Parameter | Type | required | Description |
|---|---|---|---|
| mobileNumber | String | true | The mobile number to receive SMS notification (if SMS messaging is enabled). This is optional for mobile money transfers. Example: +237674000000 |
| content | String | true | SMS content (limited to 160 ASCII characters) e.g. "Thank you for your business |
Recipients
The recipient payload is similar to the [[Transfer]] request payload
| Parameter | Type | required | Description |
|---|---|---|---|
| payeeAccountId | String | true | This is the beneficiary unique identifier. For internal users, this attribute can be tranzak ID, or email, or registered phone number; for mobile money transfer, this attribute will be the mobile wallet number (e.g. +237674xxxxxx) ; for bank transfers, use the 23-digit CEMAC bank account format e.g 1000500022044949610XXXX. |
| mobileNumber | String | false | Required for mobile money transfer type. Possible values are : 237674000009 |
| payeeAccountName | String | false | Required only for bank transfers. The IBAN 23-digit bank Bank account number . e.g 1000500002070197910XXXX |
| amount | number | true | the amount to that recipient shall receive e.g. 1000 |
| payeeNote | String(20) | true | Narration e.g. Delivery fee |
| description | String(32) | true | a custom narration transfer to customer ABC |
| customTransactionRef | String | true | a custom reference to identify this transaction e.g. transaction123 |
| smsMobileNumber | String | false | The mobile number to receive SMS notification (if SMS messaging is enabled) +237674000000 |
Bulk Transfer to Internal Tranzak Users
This endpoint is used to make transfers to users users on Tranzak platform. The beneficiaries can be identified using their their registered phone number, email or Tranzak ID e.g TZ1234566666 .
Endpoint URL
POST /xp021/v1/payout/transfer
Request body parameters
See the Common Parameters
{
"title": "Demo transfer",
"currencyCode": "XAF",
"feeIsPaidByPayee": true,
"isPriority": 1,
"mchTransactionRef": "ref12345566666",
"recipients": [
{
"payeeAccountId": "tzuo7s3tbyjszfkf",
"payeeAccountName": "Lucien Bara",
"amount": 1000,
"payeeNote": "Test",
"description": "Transfer to user",
"customTransactionRef": "111111"
},
{
"payeeAccountId": "cus22@gmail.com",
"payeeAccountName": "Dan Internal",
"amount": 1000,
"payeeNote": "test",
"description": "Transfer to user",
"customTransactionRef": "222222"
},
{
"payeeAccountId": "+237674111111",
"payeeAccountName": "Dan Internal",
"amount": 1000,
"payeeNote": "test",
"description": "Transfer to user",
"customTransactionRef": "33333"
}
]
}
Response
See the details section
Internal Transfer Via File Upload
Bulk payment to Tranzak users via file upload.
Endpoint URL
POST /xp021/v1/payout/upload-transfer-file
Response
See the details section
Mobile Wallet Bulk File Upload
Transfer money to one or more mobile money users.
TIP: You are encouraged to call this endpoint using the different test numbers provided to get different outcomes.
Endpoint URL
POST /xp021/v1/payout/transfer-to-mobile-wallet
Request body parameters
See the Common Parameters
{
"title": "Demo transfer",
"currencyCode": "XAF",
"feeIsPaidByPayee": 1,
"isPriority": 1,
"mchTransactionRef": "ref1234s5566666s",
"recipients": [
{
"payeeAccountId": "+237670000009",
"payeeAccountName": "Victor Iyansel",
"amount": 1000,
"payeeNote": "Thank you!",
"description": "Tip",
"customTransactionRef": "1234"
},
{
"payeeAccountId": "+237670000009",
"payeeAccountName": "Iya Safo",
"amount": 1000,
"payeeNote": "Thank you!",
"description": "Tip",
"customTransactionRef": "2222"
},
{
"payeeAccountId": "+237690000009",
"payeeAccountName": "Victor Iyansel",
"amount": 1000,
"payeeNote": "Thank you!",
"description": "Tip",
"customTransactionRef": "33333"
}
]
}
Response
See the details section
Mobile Wallet Transfer via File Upload
Disburses funds to one or more mobile wallet users in a file
Endpoint URL
POST /xp021/v1/payout/upload-mobile-wallet-file
Response
See the details section
Bank Transfer
Disburses funds to one or more bank accounts
Endpoint URL
POST /xp021/v1/payout/transfer-to-bank-account
Request body parameters
{
"title": "Invoice Payment",
"currencyCode": "XAF",
"feeIsPaidByPayee": 0,
"isPriority": 1,
"mchTransactionRef": "ref12345566666",
"recipients": [
{
"payeeAccountId": "1000500022044949610AAAA",
"payeeAccountName": "Victor Nji",
"amount": 1000,
"payeeNote": "Invoice payment",
"description": "Invoice 1111",
"customTransactionRef": "Inv1111"
},
{
"payeeAccountId": "1000500022044949610BBBB",
"payeeAccountName": "Rolla Ayuk",
"amount": 10000,
"payeeNote": "Invoice payment",
"description": "INV102",
"customTransactionRef": "22222"
}
]
}
Response
See the details section
Bank Transfer File Upload
Disburses funds to one or more bank accounts saved in a file
Endpoint URL
POST /xp021/v1/payout/upload-bank-transfer-file
View Details of Bulk Payment
Displays bulk payment details
The recipient payload is similar to the [[Transfer]] request payload
| Parameter | Type | required | Description |
|---|---|---|---|
| payoutId | String | true | the bulk payment reference ID |
| withRecipients | Boolean | false | if set, the recipients will be displaed together with the payload |
Endpoint URL
GET /xp021/v1/payout/details?payoutId={ID}
Details without beneficiary info
{
"data": {
"payoutId": "BP2307036WA1PVL2",
"title": "Invoice Payment",
"currencyCode": "XAF",
"mchTransactionRef": "ref12345566666",
"description": "",
"feeIsPaidByPayee": false,
"isPriority": true,
"totalNumberOfRecipients": 2,
"totalNumberFailedTransactions": 0,
"totalFailedTransactionAmount": 0,
"transactionId": "TX230703AA6NP3N49EBG",
"transactionTime": "2023-07-03 08:30:29",
"isCreatedViaFileUpload": false,
"appId": "apnz8rfqqsgoai",
"fundingAccountId": "POT3XUVED48LW0F1PHFB",
"status": "FAILED",
"totalAmount": 11000,
"priorityFee": 200,
"totalRecipientFee": 132,
"totalFee": 332,
"type": "bank transfer",
"reportFile": "https://example.com/payout/download-report?_id=64a287259a68f01a3f0ca7be",
"createdAt": "2023-07-03T08:30:29+00:00",
"completedAt": "2023-07-03T08:30:29+00:00"
},
"success": true
}
Details with recipients
{
"data": {
"payoutId": "BP2307036WA1PVL2",
"title": "Invoice Payment",
"currencyCode": "XAF",
"mchTransactionRef": "ref12345566666",
"description": "",
"feeIsPaidByPayee": false,
"isPriority": true,
"totalNumberOfRecipients": 2,
"totalNumberFailedTransactions": 0,
"totalFailedTransactionAmount": 0,
"transactionId": "TX230703AA6NP3N49EBG",
"transactionTime": "2023-07-03 08:30:29",
"isCreatedViaFileUpload": false,
"appId": "apnz8rfqqsgoai",
"fundingAccountId": "POT3XUVED48LW0F1PHFB",
"status": "FAILED",
"totalAmount": 11000,
"priorityFee": 200,
"totalRecipientFee": 132,
"totalFee": 332,
"type": "bank transfer",
"reportFile": "https://example.com/payout/download-report?_id=64a287259a68f01a3f0ca7be",
"createdAt": "2023-07-03T08:30:29+00:00",
"completedAt": "2023-07-03T08:30:29+00:00",
"recipients": [
{
"payeeAccountId": "1000500022044949610AAAA",
"payeeAccountName": "Victor Nji",
"amount": 1000,
"payeeNote": "Invoice payment",
"description": "Invoice 1111",
"customTransactionRef": "Inv1111"
},
{
"payeeAccountId": "1000500022044949610BBBB",
"payeeAccountName": "Rolla Ayuk",
"amount": 10000,
"payeeNote": "Invoice payment",
"description": "INV102",
"customTransactionRef": "22222"
}
]
},
"success": true
}
List Bulk Payment History
View history of bulk payment transfers
Endpoint URL
GET /xp021/v1/payout/history
Request Filters
Filters (partial search available)
| Parameter | Type | required | Description |
|---|---|---|---|
| payoutId | String | false | the payout reference |
| title | String | false | Filter by title |
| mchTransactionRef | String | false | search by custom reference |
| description | String | false | Description of the bulk payment request |
Response
{
"data": {
"list": [
{
"payoutId": "BP2307031VEHHT29",
"title": "Demo transfer",
"currencyCode": "XAF",
"mchTransactionRef": "ref12345566666",
"description": "",
"feeIsPaidByPayee": true,
"isPriority": true,
"totalNumberOfRecipients": 3,
"transactionId": null,
"transactionTime": null,
"isCreatedViaFileUpload": false,
"appId": null,
"fundingAccountId": null,
"status": "PENDING",
"totalAmount": 3000,
"priorityFee": 200,
"totalRecipientFee": 0,
"totalFee": 200,
"type": "internal transfer",
"reportFile": "https://example.com/payout/download-report?_id=64a28cfe2abef23146084963",
"createdAt": "2023-07-03T08:55:26+00:00",
"completedAt": null
},
{
"payoutId": "BP230703ZSAIVI9E",
"title": "Payout cool title",
"currencyCode": "XAF",
"mchTransactionRef": "ref1234s5566666s",
"description": "",
"feeIsPaidByPayee": true,
"isPriority": true,
"totalNumberOfRecipients": 3,
"transactionId": "TX230703JOE7C3DOMC9N",
"transactionTime": "2023-07-03 08:47:08",
"isCreatedViaFileUpload": false,
"appId": "apnz8rfqqsgoai",
"fundingAccountId": "POT3XUVED48LW0F1PHFB",
"status": "COMPLETED",
"totalAmount": 3000,
"priorityFee": 200,
"totalRecipientFee": 0,
"totalFee": 200,
"type": "mobile money transfer",
"reportFile": "https://example.com/payout/download-report?_id=64a28b0cd1f66f1e025c5c1e",
"createdAt": "2023-07-03T08:47:08+00:00",
"completedAt": "2023-07-03T08:47:20+00:00"
},
{
"payoutId": "BP230703AM6EFFXC",
"title": "Something new",
"currencyCode": "XAF",
"mchTransactionRef": "",
"description": "",
"feeIsPaidByPayee": false,
"isPriority": false,
"totalNumberOfRecipients": 3,
"transactionId": null,
"transactionTime": null,
"isCreatedViaFileUpload": false,
"appId": null,
"fundingAccountId": null,
"status": "PENDING",
"totalAmount": 5000,
"priorityFee": 0,
"totalRecipientFee": 60,
"totalFee": 60,
"type": "mobile money transfer",
"reportFile": "https://example.com/payout/download-report?_id=64a28aa79a68f01a3f0ca7c3",
"createdAt": "2023-07-03T08:45:27+00:00",
"completedAt": null
},
...
],
"totalItems": 96,
"pageCount": [
1,
50
],
"pageSize": 10,
"currentPage": 1,
"hasMore": true
},
"success": true
}
List Transfers in a Payout Request
Displays paginated list of transfers
Endpoint URL
GET /xp021/v1/payout/transfers
Request Filters
Partial search available
| Parameter | Type | required | Description |
|---|---|---|---|
| payoutId | String | false | the payout reference |
| transferId | String | false | transfer reference |
| payeeAccountId | String | false | beneficiary account number |
| payeeAccountName | String | false | beneficiary account name |
| payeeNote | String | false | beneficiary account name |
| description | String | false | note |
| customTransactionRef | String | false | custom reference |
{
"data": {
"list": [
{
"transferId": "TF2307034P9O1TSXG56L",
"status": "SUCCESSFUL",
"payeeAccountId": "+237690000009",
"fundingAccountId": "ACEMC43VU23S2ZEXCQXR",
"payeeAccountName": "Victor Iyansel",
"destinationServiceName": "Orange Money",
"payeeNote": "",
"description": "",
"amount": 1000,
"currencyCode": "XAF",
"fee": 0,
"customTransactionRef": "",
"feeIsPaidByPayee": false,
"createdByAppId": "apnz8rfqqsgoai",
"payoutId": "BP23070333CZMAXF",
"type": "mobile money transfer",
"partnerTransactionRefId": "test-725751792",
"transactionId": "TX2307034S9IYKWO1GML",
"transactionTime": "2023-07-03T09:17:36+00:00",
"createdAt": "2023-07-03T09:17:17+00:00"
},
{
"transferId": "TF2307031ZIJUVSGFJQ4",
"status": "SUCCESSFUL",
"payeeAccountId": "+237670000009",
"fundingAccountId": "ACEMC43VU23S2ZEXCQXR",
"payeeAccountName": "Iya Safo",
"destinationServiceName": "MTN Momo",
"payeeNote": "",
"description": "",
"amount": 1000,
"currencyCode": "XAF",
"fee": 0,
"customTransactionRef": "",
"feeIsPaidByPayee": false,
"createdByAppId": "apnz8rfqqsgoai",
"payoutId": "BP23070333CZMAXF",
"type": "mobile money transfer",
"partnerTransactionRefId": "test-3233046844",
"transactionId": "TX230703LMF2MD9YKMQ1",
"transactionTime": "2023-07-03T09:17:36+00:00",
"createdAt": "2023-07-03T09:17:17+00:00"
}
....
],
"totalItems": 118,
"pageCount": [
1,
50
],
"pageSize": 10,
"currentPage": 1,
"hasMore": true
},
"success": true
}
View Details of Transfer Job
Displays single job with details
Endpoint URL
GET /xp021/v1/payout/transfer-details?id={TRANSFER_ID}
{
"data": {
"transferId": "TF2307034P9O1TSXG56L",
"status": "SUCCESSFUL",
"payeeAccountId": "+237690000009",
"payeeAccountName": "Victor Iyansel",
"destinationServiceName": "Orange Money",
"payeeNote": "",
"description": "",
"amount": 1000,
"currencyCode": "XAF",
"fee": 0,
"customTransactionRef": "",
"feeIsPaidByPayee": false,
"createdByAppId": "apnz8rfqqsgoai",
"payoutId": "BP23070333CZMAXF",
"type": "mobile money transfer",
"partnerTransactionRefId": "test-725751792",
"transactionId": "TX2307034S9IYKWO1GML",
"transactionTime": "2023-07-03T09:17:36+00:00",
"createdAt": "2023-07-03T09:17:17+00:00"
},
"success": true
}
Refreshes (stalled) jobs
This is endpoint provides a means to "refresh" or "relaunch" transfer jobs in case they got stalled.
Endpoint URL
POST /xp021/v1/payout/refresh-jobs
Request Body Parameters
| Parameter | Type | required | Description |
|---|---|---|---|
| payoutId | String | false | the payout reference |
{
"payoutId": "PO230301M1VAU9OG"
}
Webhook Details
Webhooks are sent out during when the transfer reaches any of the following states:
- SUCCESSFUL
- FAILED
Event type
To receive callbacks for payment requests, you should create a webhook and subscribe to the following event type : BULK_PAYMENT.COMPLETED
Callback Payload
| Parameter | Type | required | Description |
|---|---|---|---|
| name | String | true | the TPN info e.g. Tranzak Payment Notification (TPN) |
| version | String | true | The TPN version , e.g 1.0 |
| eventType | String | true | The event type that triggered the callback, e.g BULK_PAYMENT.COMPLETED |
| appId | String | true | The appId that created the request |
| resourceId | String | true | Unique identifier of the request, e.g. BP2311210IV6FKVA |
| resource | JSON object | true | This parameter contains the API response of the request and provides details about the transaction (whether SUCCESSFUL or FAILED.) |
| webhookId | String | true | The webhook reference that triggered the callback |
| creationDateTime | String | true | The time the request was generated |
| authKey | String | true | The authentication key (if configured by the user). It may be used to verify that the payload originated from Tranzak servers. |
SUCCESSFUL Transaction
{
"name": "Tranzak Payment Notification (TPN)",
"version": "1.0",
"eventType": "BULK_PAYMENT.COMPLETED",
"merchantId": null,
"appId": "apnz8rfqqsgoai",
"resourceId": "BP231121G4ER6MCL",
"resource": {
"payoutId": "BP231121G4ER6MCL",
"title": "Demo transfer",
"currencyCode": "XAF",
"mchTransactionRef": "ref1234s5566666s",
"description": "",
"feeIsPaidByPayee": true,
"isPriority": false,
"totalNumberOfRecipients": 2,
"totalNumberFailedTransactions": 1,
"totalFailedTransactionAmount": 1,
"transactionId": "TX2311212RRQFDVPRKIG",
"transactionTime": "2023-11-21 03:48:23",
"isCreatedViaFileUpload": false,
"appId": "apnz8rfqqsgoai",
"fundingAccountId": "POT3XUVED48LW0F1PHFB",
"status": "COMPLETED",
"totalAmount": 2,
"priorityFee": 0,
"totalRecipientFee": 0,
"totalFee": 0,
"type": "mobile money transfer",
"reportFile": "https://example.com/download-report?_id=BP231121G4ER6MCL",
"createdAt": "2023-11-21T03:48:23+00:00",
"completedAt": "2023-11-21T03:48:25+00:00",
"sendSmsToPayee": true,
"smsContent": "Thank you for patronizing us",
"refundId": "REF231121NH2X0EB",
"totalRefundedAmount": 1
},
"creationDateTime": "2023-11-21 03:48:25",
"webhookId": "WH8UDGOZ9O5T2PDTIA6CTD",
"authKey": "jaldfjalsdjkssssssssssssssssssssss"
}
SMS and Bulk SMS API
This endpoint is used to send SMS to one or multiple phone numbers. All networks in Cameroon are supported. A single SMS length is 160 regular characters. You can send bulk SMS to up to 500 numbers in a single API call. Every account is given free SMS balance for testing purpose. You can top up SMS balance for your organization at: https://messaging.tranzak.me
NOTE
- Some symbols like emojis count as two characters in a message
- For more security control, we recommend having different apps(hence different apiKeys) for Payment and SMS. You can create a different developer APP for SMS purpose from our developer portal: https://developer.tranzak.me, then use the corresponding appId and apiKey to send SMS.
Endpoint URL.
POST /dn088/v1/sms/api/send
Request Header parameters
| Parameter | Type | required | Description |
|---|---|---|---|
| Authorization | string | true | Your API token generated as described Here in the format Bearer ${token}. |
Request body parameters
| Parameter | Type | required | Description |
|---|---|---|---|
| phones | string | true | Comma separated phone numbers. eg: "+23767xxxxxxx,+23769xxxxxxx,+23768xxxxxxx. Max: 500 numbers per API call |
| msg | string | true | The SMS content to send |
| senderId | string | false | The name to display as sender for each SMS. The name should be 11 characters Max, including white space. Contact support to register a new senderId support@tranzak.net. Unregistered senderId won't work. |
Response
| Parameter | Type | required | Description |
|---|---|---|---|
| msg | string | true | The SMS content sent |
| results | Array | true | Different phone numbers and their reception status |
| total | int | true | The Total number of SMS sent (total of phone numbers * total SMS count). |
Below is a sample response for a successful call.
{
"data": {
"msg": "New promotion going on for all special users. Please login to our application and claim yours.",
"results": [
{
"msisdn": "+2376719xxxx3",
"smscount": "3",
"code": "0",
"reason": "ACCEPTED",
"ticket": "711af4b1-a994-11ee-af6c-00000a148c01"
},
{
"msisdn": "+237692xxxx1",
"smscount": "3",
"code": "0",
"reason": "ACCEPTED",
"ticket": "711b69e1-a994-11ee-af6c-00000a148c01"
}
],
"total": 2
},
"success": true,
"errorMsg": "",
"errorCode": 0
}
Refunds
Interface to create and manage refund requests
Refund Status Codes
| Code | Description |
|---|---|
| PENDING | Refund request is pending approval |
| APPROVED | The refund has been approved (by merchant) |
| REJECTED | The refund request was rejected |
| ON_HOLD | Request is on hold - pending investigation |
| SUCCESSFUL | The refund has been successfully completed |
| CANCELLED | The request for refund was cancelled (by payer) |
| FAILED | The refund request failed |
Create (web redirect)
Creates and automatically approves a refund. The funding account must have adequate balance otherwise the refund request will fail.
Endpoint URL
POST /xp021/v1/refund/create
Request body parameters
| Parameter | Type | required | Description |
|---|---|---|---|
| refundedTransactionId | String | true | The transaction to be refunded |
| amount | number | false | the amount to refund. If not set, then full refund will be issued. e.g. 1000 |
| reasonCode | integer | true | Reason code ( see reason codes section for list of supported codes) |
| mchTransactionRef | String(32) | true | Custom refund reference e.g mchRefund123333 |
| note | String(500) | false | Merchant note to payer |
{
"refundedTransactionId": "TX2207063QEV4E6A64Q6",
"reasonCode": 2,
"merchantRefundNumber": "mchRefund123333",
"note": "Sorry for the inconvenience",
"amount": 1
}
Refund Details
Displays details of a refund
Endpoint URL
GET /xp021/v1/refund/details?refundId={REFUND_ID}
Request body parameters
| Parameter | Type | required | Description |
|---|---|---|---|
| refundId | String | true | Refund ID |
{
"data": {
"refundId": "REFKYAVGDV257LVZY7U5",
"refundedTransactionId": "TX2207063QEV4E6A64Q6",
"amount": 1,
"currencyCode": "USD",
"status": "COMPLETED",
"type": "REFUND",
"merchantRefundRef": "mchRefund123333",
"reasonDescription": "la commande n'était pas conforme à l'accord de transaction",
"isInitiatedByText": "marchand",
"isCancelledByText": "",
"isApprovedByText": "marchand",
"note": "Sorry for the inconvenience",
"reasonCode": 2,
"createdAt": "2022-07-06T10:01:18+00:00",
"approvedAt": "2022-07-06T10:01:18+00:00"
},
"success": true
}
Response
See the details
Approve
Approves a request for refund submitted by payer.
Endpoint URL
POST /xp021/v1/refund/approve
Request body parameters
| Parameter | Type | required | Description |
|---|---|---|---|
| refundId | number | true | The refund reference e.g. REFKYAVGDV257LVZY7U5 |
| note | String(3) | true | Custom message to payer |
{
"refundId": "REFKYAVGDV257LVZY7U5",
"note" : "Thank you for your business."
}
Response
See the response details section
Reject
Rejects a request submitted by payer.
Endpoint URL
POST /xp021/v1/refund/reject
Request body parameters
| Parameter | Type | required | Description |
|---|---|---|---|
| refundId | number | true | The refund reference e.g. REFKYAVGDV257LVZY7U5 |
| note | String(3) | true | Custom message to payer |
{
"refundId": "REFV1OWJQCT2OQ16L8P9" ,
"note" : "Fully compliant transaction"
}
Response
See the response details
List Request Codes
Request reason codes
Endpoint URL
GET /xp021/v1/refund/reason-codes
Request body parameters
N/A
Response
{
"data": {
"1": "mutual agreement between buyer and seller",
"2": "the order did not match the transaction agreement",
"3": "suspicious transaction",
"4": "disputed transaction",
"5": "other reasons",
"6": "Deficient product/service",
"7": "Duplicate transaction",
"8": "Purchased item not delivered by merchant"
},
"success": true
}
List Request Codes
Lists reject reason codes
Endpoint URL
GET /xp021/v1/refund/reject-codes
Request body parameters
N/A
Response
{
"data": {
"1": "insufficient evidence",
"2": "mutual agreement"
},
"success": true
}
History
Displays paginated list of refunds
Endpoint URL
GET /xp021/v1/refund/history
Request body parameters
N/A
Response
{
"data": {
"list": [
{
"refundId": "REF2208186Y48CTRFACZ",
"refundedTransactionId": "TX220818D3FQFN4OD0VQ",
"amount": 1,
"currencyCode": "USD",
"status": "SUCCESSFUL",
"type": "REFUND",
"merchantRefundRef": null,
"reasonDescription": "the order did not match the transaction agreement",
"isInitiatedByText": "merchant",
"isCancelledByText": "",
"isApprovedByText": "merchant",
"note": "Sorry for the inconvenience",
"reasonCode": "2",
"createdAt": "2022-08-18T15:43:14+00:00",
"approvedAt": "2022-08-18T15:43:14+00:00"
},
{
"refundId": "REF220818HGLQOVLIA86",
"refundedTransactionId": "TX220818D3FQFN4OD0VQ",
"amount": 1,
"currencyCode": "USD",
"status": "SUCCESSFUL",
"type": "REFUND",
"merchantRefundRef": null,
"reasonDescription": "the order did not match the transaction agreement",
"isInitiatedByText": "merchant",
"isCancelledByText": "",
"isApprovedByText": "merchant",
"note": "Sorry for the inconvenience",
"reasonCode": "2",
"createdAt": "2022-08-18T15:43:12+00:00",
"approvedAt": "2022-08-18T15:43:12+00:00"
},
....
],
"totalItems": 1,
"pageCount": [
1,
50
],
"pageSize": 10,
"currentPage": 1,
"hasMore": false
},
"success": true
}
Webhook Details
Webhooks are sent out during when the payment request reaches any of the following states:
- SUCCESSFUL
- FAILED
Event type
To receive callbacks for payment requests, you should create a webhook and subscribe to the following event type : REFUND.COMPLETED
Callback Payload
| Parameter | Type | required | Description |
|---|---|---|---|
| name | String | true | the TPN info e.g. Tranzak Payment Notification (TPN) |
| version | String | true | The TPN version , e.g 1.0 |
| eventType | String | true | The event type that triggered the callback, e.g REFUND.COMPLETED |
| appId | String | true | The appId that created the request |
| resourceId | String | true | Unique identifier of the request, e.g. REF231121REIF5J2 |
| resource | JSON object | true | This parameter contains the API response of the request and provides details about the transaction (whether SUCCESSFUL or FAILED.) |
| webhookId | String | true | The webhook reference that triggered the callback |
| creationDateTime | String | true | The time the request was generated |
| authKey | String | true | The authentication key (if configured by the user). It may be used to verify that the payload originated from Tranzak servers. |
SUCCESSFUL Transaction
{
"name": "Tranzak Payment Notification (TPN)",
"version": "1.0",
"eventType": "REFUND.COMPLETED",
"merchantId": null,
"appId": "apnz8rfqqsgoai",
"resourceId": "REF231121VJK2G57",
"resource": {
"refundId": "REF231121VJK2G57",
"refundedTransactionId": "TX231121OLN76RPLMWFJ",
"serviceId": "REQ231121XEBWWKWY8HT",
"amount": 1,
"currencyCode": "XAF",
"status": "SUCCESSFUL",
"type": "REFUND",
"merchantRefundRef": null,
"reasonDescription": "the order did not match the transaction agreement",
"isInitiatedByText": "merchant",
"isCancelledByText": null,
"isApprovedByText": "merchant",
"note": "Sorry for the inconvenience",
"reasonCode": 2,
"reason": "the order did not match the transaction agreement",
"createdAt": "2023-11-21T04:22:32+00:00",
"approvedAt": "2023-11-21T04:22:32+00:00"
},
"creationDateTime": "2023-11-21 04:22:34",
"webhookId": "WH8UDGOZ9O5T2PDTIA6CTD",
"authKey": "jaldfjalsdjkssssssssssssssssssssss"
}
Real Name Verification
Synopsis
The name verification endpoint is for verifying the name of mobile money account holders. Developers can pass the phone numbers of an account to obtain the account holder information.
Supported Services
The following operators are supported:
- MTN MOMO - Cameroon
- Orange Money - Cameroon
Restriction
Access to this API is restricted on production environment but open for testing on Sandbox environment. Contact support@tranzak.net to enable access for your account on production environment.
Create A Verification Request
The following endpoint is used to create a verification request:
POST /xp021/v1/name-verification/create
Request Parameters
| Parameter | Type | required | Description |
|---|---|---|---|
| accountHolderId | String | true | The mobile money number being queried e.g +237674460261 |
| customTransactionId | String | false | a custom order reference |
Response
| Parameter | Type | required | Description |
|---|---|---|---|
| requestId | String | true | The mobile money number e.g NV2411285ZC9OE |
| accountHolderId | String | true | The mobile money number |
| customTransactionId | String | false | a custom order reference |
| verifiedName | String | false | The verified name |
| operatorName | String | false | The operator name |
| status | String | false | Status . Possible values : PENDING, COMPLETED , FAILED |
| errorCode | String | false | error code - in case of failure |
| errorMessage | String | false | error message |
{
"data": {
"requestId": "NV2411285ZC9OE",
"customTransactionId": "123444",
"accountHolderId": "+237674460261",
"verifiedName": "Tranzak Random Name",
"operatorName": "MTN MOMO (CM)",
"status": "COMPLETED",
"createdAt": "2024-11-28T09:26:30+00:00",
"errorCode": null,
"errorMessage": null
},
"success": true
}
Query Request Status
Query the status of a request
URL Endpoint
GET /xp021/v1/name-verification/details?requestId={{REQUEST_ID}}
Response
The request may be queried using any of the following parameters
| Parameter | Type | required | Description |
|---|---|---|---|
| requestId | String | true | account ID |
| customTransactionId | String | true | the custom name (as set in the merchant dasboard) |
{
"data": {
"requestId": "NV2411285ZC9OE",
"customTransactionId": "123444",
"accountHolderId": "+237674460261",
"verifiedName": "Tranzak Random Name",
"operatorName": "MTN MOMO (CM)",
"status": "COMPLETED",
"createdAt": "2024-11-28T09:26:30+00:00",
"errorCode": null,
"errorMessage": null
},
"success": true
}
Test Data
Test Mobile Numbers
Mobile wallet numbers not mentioned below will always return status SUCCESSFUL . Note that the returned status is applicable when the mobile numbers are used as payment methods and also when they are used as beneficiary (e.g during mass payment).
FAILED status
| Number | Operator | Final Status |
|---|---|---|
| 237674000000 | Momo Cameroon | FAILED |
| 237690000000 | Orange Money | FAILED |
| 237674000001 | MOMO Cameroon | PAYMENT_IN_PROGRESS |
| 237690000001 | Orange Money | PAYMENT_IN_PROGRESS |
| 237674000002 | MOMO Cameroon | PAYER_REDIRECT_REQUIRED |
| 237690000002 | Orange Money | PAYER_REDIRECT_REQUIRED |