Transactions

Welcome to the authentication page, here you will find all the necessary information to authenticate and obtain an API token and Merchant ID.

1. What is Transaction

A transaction is a record of a financial activity initiated by a user, a system, or external party. It can involve actions such as:

1. Deposit

2. Withdrawal

3. Fund Transfer

4. Payment

Every time one of these actions is initiated, a transaction is created. The transaction contains the following information:

#	Name	Type	Description	Example	Required
1	id	String	An unique autogenerated identifier	209ec2b1-f17d-4715-9791-9ce51bfbe0d8	No
2	merchant_id	String	Your merchant id	134645be-aff6-4275-a1d3-61507648a4b6	Yes
3	transaction_reference	String	The unique reference from merchant	c2bfpvdm1112test0001	Yes
4	amount	String	The transaction amount	100.0	Yes
5	currency	String	The amount currency	usd	Yes
6	customer_number	String	The phone number used for this transaction	+243837334496	Yes
7	service	String	The telecom operator name	vodacom	Yes
8	operation	String	The action you want to perform, debit (deposit) or credit (cashout)	debit	Yes
9	callback_url	String	Your url that will receive the our callback	https://yourdomain.com/callback	Yes
10	transaction_status	String	A Text that indicates the state of the transaction	Success	No
11	transaction_status_code	String	A code that indicates the state of the transaction	200010	No
12	transaction_status_description	String	A detailed description of the transaction status	Successful	No
13	created_at	String	The created at	2023-06-08T12:08:59.000000Z	No

The transaction model has many other fields, but we will talk about them later. for now let's focus on the most important ones and how we can use them to create new transactions.

Required means that the field is required to create a transaction.

2. How to make a transaction

To make a transaction, you need to use our API by following these steps:

1. Endpoint

2. Headers

3. Body

4. Request

5. Response

2.1. Endpoint

An endpoint is a specific URL that is used to access a specific resource or perform a specific action. In our case we will use the following endpoint to make a transaction:

https://apis.payrouter.io/api/payment/transaction/

2.2. Headers

Headers in the context of an API are key-value pairs sent as part of the request or response to provide metadata or additional information about the request or the response.

For our example, we will use the following headers:

{
    'Content-Type': 'application/json',
    'Authorization': 'Token ************',
}

Here we have two headers:

Content-Type: This header specifies the type of data being sent in the request body. In our case, we are sending JSON data, so we set this header to application/json.

Authorization: This header contains the API token that we obtained earlier. It is used to authenticate the request and authorize the user to perform certain actions on the API.

Note that in Authorization you will need to replace the ************ by your API token. But the word Token must be there as shown in the example above 👆.

2.3. Body

The body of the request contains the data that is being sent to the server. In our case, we will send the following data:

{
    "merchant_id": "************",
    "amount": "100.0",
    "currency": "usd",
    "customer_number": "0812345678",
    "operation": "debit",
    "service": "vodacom",
    "transaction_reference": "test0001",
    "callback_url": "https://yourdomain.com/callback"
}

Let's explain each field:

merchant_id: This is the unique identifier of the merchant account. as explained in the authentication page.
amount: This is the money 💰
currency: The money currency like usd or cdf.
customer_number: This is the phone number of the customer.
operation: This is the action that will be performed like debit for deposit or credit for cash out.
service: This is the service provider like vodacom, orange or airtel.
transaction_reference: This is the unique reference of the transaction, it will be used to track the transaction. You must send a unique value for each transaction (example: test0001, test0002, test0003, etc.).
callback_url: This is the URL that will be called when the transaction is completed.

Note that in merchant_id you will need to replace the ************ by your Merchant ID.

2.4. Request

Now that we have the endpoint, headers and body, we can make our first request to create a transaction

As it name suggests, a request is a message sent from a client to a server to ask for information or to perform an action. In our case, we want the server to create a transaction for us. As we ask the server to create a transaction, we will use the POST method.

Now let's put everything together and make our first request.
You will need to replace the ************ by your API token and ************ by your Merchant ID.

Check the example below and choose your favorite language to make the request

const url = "https://apis.payrouter.io/api/payment/transaction/";

const headers = {
    "Content-Type": "application/json",
    "Authorization": "Token ************"
};

const body = {
    merchant_id: "************",
    amount: "100.0",
    currency: "usd",
    customer_number: "0812345678",
    operation: "debit",
    service: "vodacom",
    transaction_reference: "test0001",
    callback_url: "https://yourdomain.com/callback"
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
})
.then(response => response.json())
.then(data => console.log(data))
.catch(err => console.error("Error:", err));

After sending the request, you will get a response from the server. If the request is successful, you will get 201 status code and the creation of the transaction.

If the request is not successful, you will get an error message.

2.5. Response

The response is the data that is sent back to the client after a request has been made. The response will inform you if the request was successful or not.

1. Transaction Error

2.Transaction Created

2.5.1. Transaction Error

Here is an example of an error response:

{
    "status": "Forbidden",
    "status_code": 403,
    "status_description": "Invalid token."
}

This response means that the API token is invalid or not sent correctly in r.

2.5.2. Transaction Created

Here is an example of a successful response, which means that the transaction was created successfully:

{
    "transaction_reference": "c2borm2508test0009",
    "from_wallet": null,
    "to_wallet": null,
    "merchant_id": "134645be-aff6-4275-a1d3-61507648a4b6",
    "amount": "100.00000",
    "reserved_amount": null,
    "currency": "usd",
    "operation": "debit",
    "service": "vodacom",
    "customer_number": "0812345678",
    "transaction_status_description": null,
    "telecom_reference": null,
    "telecom_status_code": null,
    "telecom_status_description": null,
    "callback_url": "https://yourdomain.com/callback"
}

The last thing to note here is, if the transaction is successful and the operation is debit a push notification will be sent to the customer phone number for confirmation, if the transaction operation is credit an SMS will be sent to the customer phone number.

When the transaction is processed, the server will send a callback request containing the transaction details using the callback_url. So be sure to set the callback_url in your request.

2.6. Next Steps

Now that you have successfully created a transaction, you can go to the dashboard to see all your transactions reports.

Authentication

Reports