Pre-requisites #
1. Create an Account and Validate #
To create an account on Payunit as a merchant. Click to create an account.
2. Create an Application #
By default all merchants have an application, to create a new application, go to your dashboard in the section All application > create application, enter all information of your application and validate
3. Get your credentials #
3.1 Api Username and Api Password #
Get the merchant Api User, merchant API key, and merchant API Password from the merchant dashboard under the settings >ApiKeys List section
3.2 Application key #
To get the keys of your application, go to the dashboard of the merchants, and display the list of your application ( Applications > all applications ) then select the application you want, then click on the tab application details ( Application detail )
The PayUnit REST API provides a restful interface for developers to make direct API calls to the PayUnit payment aggregator.
The PayUnit REST-API requires the developer to have a server setup. This server is expected to implement and expose a notify endpoint which will receive and handle the payment transaction responses submitted by PayUnit. PayUnit expects that this endpoint receives a POST request with the payload shown below.
{
"status": "SUCCESS",
"statusCode": 200,
"message": "Your transaction detail",
"data": {
"transaction_amount": "100.00000",
"transaction_status": "SUCCESSFUL",
"transaction_id": "pu-734098-197530",
"purchaseRef": null,
"callback_url": "https://www.website.com"
}
}
Making the API calls #
Specifications HTTP headers for all the API calls
Http header | Description |
---|
Content-Type | Content type supported is : application/json |
Authorization | Http basic Auth encoded in Base 64 and formatted as follow : Basic Base64(apiUser:apiPassword) |
x-api-key | Your application Token |
mode | The current mode operation. Can either be “test” when testing in sandbox or “live” when ready for production. |
1. Request to initialization a transaction on PayUnit #
- End point: {BASE_URL}/gateway/initialize
- Request method: POST
Request body :
Parameter | Mandatory | Description |
total_amount | yes | The amount to be paid |
transaction_id | yes | This transaction should be unique per request and it should be a string . This id should be alphanumeric and less than 20 characters |
currency | yes | The currency you want to use: XAF |
return_url | yes | The url or endpoint to be called upon payment completion |
notify_url | no | Payment result notification to your server |
Example:
curl -X POST \
'{BASE_URL}/gateway/initialize' \
-H 'Authorization: Basic cGF5dW5pdF9UU5LTg1MjMtZTEwZDZmMDg1ODk3' \
-H 'Content-Type: application/json' \
-H 'x-api-key: your_api_key' \
-H 'mode: test' \
-d '{
"total_amount" : "amount_to_be_pay",
"currency" : "XAF",
"transaction_id" : "unique_id_in_your_system",
"return_url" : "https://my.website.com/payunit/return",
}'
Response body :
Parameter | Description |
t_id | The transaction id that has been encrypted |
t_sum | The amount that has been encrypted |
t_url | The return url that has been encrypted |
transaction_id | This transaction should be unique per request and it should be a string. This id should be alphanumeric and less than 20 characters |
transaction_url | The return url that takes a user to the payment platform |
Example:
{
"status": "SUCCESS",
"statusCode": 200,
"message": "Transaction created!",
"data": {
"t_id": "YTQxZjc5YTM2MmJhNGQ3OWVjYTgxMjUxZTg0ZjZjZDQwMw==",
"t_sum": "ZTU1YTY0",
"t_url": "YmMxZTIwZTMyMGIyNTc2ZWIxZjk1YTRkYTk0ZDI1OTQ1NTMwNDM5MGJlYmRiNzZjNTIwMjA3ZTMxZWM5OTg4Njc5MjVhMTcyM2FjMDEyN2I5OWRjMzQxNjM4Mjk0ZTYz",
"transaction_id": "pu-01258-0121c058",
"transaction_url": "https://pay.payunit.net/#/hostedPayment/payment?t_id=YTQxZjc5YTM2MmJhNGQ3OWVjYTgxMjUxZTg0ZjZjZDQwMw==&t_sum=ZTU1YTY0&t_url=YmMxZTIwZTMyMGIyNTc2ZWIxZjk1YTRkYTk0ZDI1OTQ1NTMwNDM5MGJlYmRiNzZjNTIwMjA3ZTMxZWM5OTg4Njc5MjVhMTcyM2FjMDEyN2I5OWRjMzQxNjM4Mjk0ZTYz",
"providers": []
}
}
2 – Making payments on PayUnit #
2.1 Using Hosted Pages #
Use the link available in the transaction_url response to be redirected to the PayUnit payment interface. The interface is shown below.
2.2 Continuous using Rest API ( Working only for the following PSP : Orange , Mtn, Express Union) #
2.2.1 Get all PSP on PayUnit #
- End point: {BASE_URL}/gateway/gateways?t_url=””&t_id=””&t_sum=””
- Request method: GET
Request parameter :
Parameter | Mandatory | Description |
t_id | yes | The transaction id that has been encrypted |
t_sum | yes | The amount that has been encrypted |
t_url | yes | The return url that has been encrypted |
Example:
curl -X GET \
'{BASE_URL}/gateway/gateways?t_url=tyty*****&t_id=ytyy*****&t_sum=ytyty*****' \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic cGF5dW5pdF9UU5LTg1MjMtZTEwZDZmMDg1ODk3' \
-H 'x-api-key: your_api_key' \
-H 'mode: test'
Response body :
Parameter | Description |
statusCode | The statusCode of the request: – 20x for success – 400 or 500 for failed |
message | The message sent back by the system |
created_at | creation date |
updated_at | updated date |
privider_id | id of the provider |
provider_name | name of the provider |
privider_logo | logo of the provider |
provider_short_tag | provider short tag |
provider_status | status of the provider |
Example
{
"status": "SUCCESS",
"statusCode": 200,
"message": "subscribe provider",
"data": [
{
"id": 2,
"created_at": "2022-10-15T08:57:00.918Z",
"updated_at": "2022-10-15T08:57:00.918Z",
"deleted_at": null,
"shortcode": "CM_ORANGE",
"name": "ORANGE MONEY",
"logo": "https://payunit-paymentlinks-imgs.s3.us-west-2.amazonaws.com/psps/orange.png",
"balance": "0",
"status": "ACTIVE",
"country": {
"id": 8,
"created_at": "2022-10-15T08:57:00.881Z",
"updated_at": "2022-10-15T08:57:00.881Z",
"deleted_at": null,
"country_name": "Cameroon",
"country_code": "CM"
}
},
{
"id": 1,
"created_at": "2022-10-15T08:57:00.918Z",
"updated_at": "2022-10-15T08:57:00.918Z",
"deleted_at": null,
"shortcode": "CM_MTNMOMO",
"name": "MTN MOMO",
"logo": "https://payunit-paymentlinks-imgs.s3.us-west-2.amazonaws.com/psps/mtn.png",
"balance": "0",
"status": "ACTIVE",
"country": {
"id": 8,
"created_at": "2022-10-15T08:57:00.881Z",
"updated_at": "2022-10-15T08:57:00.881Z",
"deleted_at": null,
"country_name": "Cameroon",
"country_code": "CM"
}
}
]
}
2.2.2 Make payment on PayUnit #
- End point: {BASE_URL}/gateway/makepayment
- Request method : POST
Request Body :
Parameter | Mandatory | Description |
gateway | yes | provider short tag |
amount | yes | The amount to be pay |
transaction_id | yes | This transaction should be unique per request |
notify_url | no | Payment result notification to your server |
phone_number | yes | The phone number of you customer |
currency | yes | The currency you want to use: XAF |
paymentType | yes | Payment Type |
Example
curl -X POST \
'{BASE_URL}/gateway/makepayment' \
-H 'Authorization: Basic cGF5dW5pdF9UU5LTg1MjMtZTEwZDZmMDg1ODk3' \
-H 'Content-Type: application/json' \
-H 'x-api-key: your_api_key' \
-H 'mode: test' \
-d '{
"gateway" : "mtnmomo",
"amount" : 15000,
"transaction_id" : "unique_id_in_your_system",
"return_url" : "https://my.website.com/payunit/return",
"phone_number" : "655487***",
"currency" : "XAF",
"paymentType": "button"
}'
Response body :
Parameter | Description |
payment_ref | Reference of the Payment |
transaction_id | Id of the transaction |
transaction_amount | Amount wil be pay |
Example
{
"status": "SUCCESS",
"statusCode": 200,
"message": "Sandbox payment successful",
"data": {
"create_time": "2022-10-27T12:03:37.644Z",
"update_time": "2022-10-27T12:03:37.644Z",
"delete_time": null,
"id": 3295,
"transaction_id": "pu-01258-0121c058",
"transaction_amount": 100,
"transaction_real_amount": null,
"transaction_url": "https://pay.payunit.net/#/hostedPayment/payment?t_id=YTQxZjc5YTM2MmJhNGQ3OWVjYTgxMjUxZTg0ZjZjZDQwMw==&t_sum=ZTU1YTY0&t_url=YmMxZTIwZTMyMGIyNTc2ZWIxZjk1YTRkYTk0ZDI1OTQ1NTMwNDM5MGJlYmRiNzZjNTIwMjA3ZTMxZWM5OTg4Njc5MjVhMTcyM2FjMDEyN2I5OWRjMzQxNjM4Mjk0ZTYz",
"transaction_status": "INITIATE",
"transaction_currency": "XAF",
"return_url": "https://website.com/d457b2f3-dd71-4f04-9af5-e2fcf3be8f34",
"transaction_description": null,
"purchaseRef": null,
"transaction_name": null,
"transaction_notify_url": "https://website.com/d457b2f3-dd71-4f04-9af5-e2fcf3be8f34",
"provider_id": null,
"transaction_gateway": null,
"transaction_callback": "https://website.com/d457b2f3-dd71-4f04-9af5-e2fcf3be8f34",
"transaction_response_data": null,
"transaction_request_data": {},
"provider_transaction_key": null,
"transaction_fee": "0.000",
"user_id": "c7fc3c2e-a2fe-4da8-880a-8de32fbbc610",
"username": "payunit_q7QlcNVe8",
"transaction_mode": "SANDBOX",
"transaction_type": "PAYMENTS_COLLECTION",
"application_id": "17fe16e5-34c0-4d69-b62b-36d81d26bfdb",
"receiver_id": null
}
}
3. Getting the payment transaction status on PayUnit #
- End point: {BASE_URL}/gateway/paymentstatus?transaction_id={transaction_id}
- Request method: GET
Request parameter :
Parameter | Mandatory | Description |
transaction_id | yes | Transaction id |
Example
curl -X GET \
'{BASE_URL}/gateway/paymentstatus?transaction_id=pu-734098-197530'\
-H 'Content-Type: application/json' \
-H 'x-api-key: your_api_key' \
-H 'Authorization: Basic cGF5dW5pdF9UU5LTg1MjMtZTEwZDZmMDg1ODk3' \
-H 'mode: test'
Response body :
Parameter | Description |
transaction_id | Id of the transaction |
transactions | the transaction |
status | Transaction Status: -SUCCESS/SUCCESSFUL/SUCCESSFULL for Payment successful – FAILED for Payment failed |
callback_url | The url or endpoint to be called upon payment completion |
transaction_amount | Amount of the transactions |
statusCode | The statusCode of the request: – 20x for success – 400 or 500 for failed
|
Response Example:
{
"status": "SUCCESS",
"statusCode": 200,
"message": "Your transaction detail",
"data": {
"transaction_amount": "10.00000",
"transaction_status": "SUCCESSFUL",
"transaction_id": "pu-734098-197530",
"purchaseRef": null,
"callback_url": "https://website.com/d457b2f3-dd71-4f04-9af5-e2fcf3be8f34"
}
}
POSTMAN DOCUMENTATION #
click here to download the postman collection