Merchants seeking to integrate card payments into their checkout process must adhere to the following guidelines to successfully complete the transaction request.
The Request is similar in someway with the Mobile Money Checkout Request/
API
Request URL
{{base_url}}/api/create-order
Request
| Field | Description | Type | Optional/Mandatory |
|---|---|---|---|
| code | Payment code indicating card payments (102) | int | Mandatory |
| merchant_order_id | Unique identifier for the merchant's order | string | Mandatory |
| amount | Amount of the transaction in the specified currency. Minimum is 1000 TZS | int | Mandatory |
| currency | Currency code for the transaction (e.g., "TZS") | string | Mandatory |
| merchant_cancel_url | URL to redirect in case of cancellation (not used) | valid url string | Optional |
| merchant_redirect_url | URL to redirect upon successful transaction (not used) | valid url string | Optional |
| metadata | Additional metadata for the transaction (if applicable) | JSON | Optional |
| billing | Billing information for card payments (see subfields) | JSON | Mandatory |
| merchant_webhook | URL for receiving transaction notifications (webhook) | valid url string | Mandatory |
| product_count | Number of products in the transaction | int | Mandatory |
| customer_email | Customer's email address | valid email string | Mandatory |
| customer_name | Customer's name | string | Mandatory |
| customer_phone | Customer's phone number | string | Mandatory |
| customer_userid | Customer's user ID (if applicable) | string/int maxLength=100 | Optional |
| is_recurring | Flag indicating if the transaction is recurring | bool | Optional |
| shouldFail | Indicates whether the transaction should be processed and succeed or not. Values can be (true) or (false). default is false. This is only important when you set your environment to Playground in your Dashboard. | bool | Optional |
Billing Subfields
| Subfield | Description | Optional/Mandatory | |
|---|---|---|---|
| address | Customer's street address | string | Mandatory |
| state | Customer's state or region | string | Mandatory |
| city | Customer's city | string | Mandatory |
| postcode | Customer's postal code | string | Mandatory |
| country_code | Customer's country (Default "TZ") | string | Optional |
| phone | Customer's phone number | string | Mandatory |
Initiating this request triggers the Card payment process. Upon successful initiation, the merchant receives a payment URL in response. This URL is provided to the customer to facilitate the completion of the transaction.
Sample Request
{
"code": 102, // 102 for Card Payments
"merchant_order_id": "5",
"amount": 10000,
"currency" : "TZS",
"merchant_cancel_url": "https://www.yoursite.com/cancel",
"merchant_redirect_url": "https://www.yoursite.com/success",
"metadata": {
"anykey": "anyvalue",
"another_anyKey": "another_anyvalue"
},
"billing": {
"address": "Kinondoni Moroco",
"state": "Dar es Salaam",
"city": "Dar es Salaam",
"postcode": "00000",
"country_code": "TZ",
"phone": "255789000111"
},
"merchant_webhook": "https://webhook.site/#!/2250a4d1-a6e2-4ac8-97b2-26dda65da334", // mandatory
"product_count": "1",
"customer_email": "[email protected]",
"customer_name": "Johnny Mnemonic",
"customer_phone": "255789000111",
"customer_userid": 2,
"shouldFail" : false
}
Sample Response
Payment Response
Upon initiating a card payment request, the merchant receives a response containing important information regarding the transaction process. Below is an explanation of each field in the response:
- order_id: The unique identifier for the order or transaction initiated by the merchant.
- status: Indicates the outcome of the payment request. In this case, it's set to 203, indicating a successful transaction.
- result: Describes the result of the transaction process. Here, it's set to "dispatched," signifying that the payment notification has been successfully dispatched.
- message: Additional information or notification message related to the payment process. Here, it states that a payment notification has been logged.
- metadata: Optional data provided by the merchant during the payment request. It can include any custom key-value pairs specific to the transaction.
- payment_url: The URL generated by the payment gateway for the customer to proceed with the payment. This URL redirects the customer to the payment page where they can complete the transaction.
{
"order_id": "5",
"status": 203,
"result": "dispatched",
"message": "Payment notification logged",
"metadata": { "anykey": "anyvalue", "another_anyKey": "another_anyvalue" },
"payment_url": "http://example.com/Ahesmey"
}
This response confirms the request has being received and provides the merchant with the necessary information, including the payment URL, to facilitate the customer's payment process.
If the initialisation process fails, the merchant should read what caused the issue and rectify it, otherwise you may get in touch for more assistance
Upon customer payment completion using the URL provided in the previous step, the Merchant will be alerted using the web-hook url they provided in the initial request.