Transactions
Create Transactions
Creating a transaction involves several processes.
1 - Request to create the transaction
You must first send a request to create a transaction via the API.
This request must contain parameters such as the amount of the transaction,
its description and the currency to be used for it in addition to the information
of the customer concerned by this operation.
So you have :
description
: to give a brief description of the transaction purposeamount
: specify the transaction amount. This amount should always be an integercurrency
: specify the currency to use for the transactioncallback_url
: to set a return linkcustomer
: specify the customer with whom the transaction must be done
For this attribute, either the ISO number or the ISO must be indicated. Refer to the table of available currencies.
At this step, you have the possibility to create along with the transaction,
a new customer to whom it will be automatically assigned this transaction
if you have not registered him previously.
In this case you must provide last name, first name, e-mail and telephone number.
Use the code below to address your request via the API.
curl -X POST \
https://sandbox-api.fedapay.com/v1/transactions \
-H 'Authorization: Bearer YOUR_API_SECRET_KEY' \
-H 'Content-Type: application/json' \
-d '{
"description" : "Transaction for [email protected]",
"amount" : 2000,
"currency" : {"iso" : "XOF"},
"callback_url" : "https://mywebsite.com/callback",
"customer" : {
"firstname" : "John",
"lastname" : "Doe",
"email" : "[email protected]",
"phone_number" : {
"number" : "+22997808080",
"country" : "bj"
}
}
}'
/* Replace YOUR_API_SECRET_KEY by your API secret key */
\FedaPay\FedaPay::setApiKey("YOUR_API_SECRET_KEY");
/* Specify whenever you are willing to execute your request in test or live mode */
\FedaPay\FedaPay::setEnvironment('sandbox'); //or setEnvironment('live');
/* Create the transaction */
\FedaPay\Transaction::create(array(
"description" => "Transaction for [email protected]",
"amount" => 2000,
"currency" => ["iso" => "XOF"],
"callback_url" => "https://mywebsite.com/callback",
"customer" => [
"firstname" => "John",
"lastname" => "Doe",
"email" => "[email protected]",
"phone_number" => [
"number" => "+22997808080",
"country" => "bj"
]
]
));
const { FedaPay, Transaction } = require('fedapay')
/* Replace YOUR_API_SECRET_KEY by your API secret key */
FedaPay.setApiKey("YOUR_API_SECRET_KEY");
/* Specify whenever you are willing to execute your request in test or live mode */
FedaPay.setEnvironment('sandbox'); //or setEnvironment('live');
/* Create the transaction */
const transaction = await Transaction.create({
description: 'Description',
amount: 2000,
callback_url: 'https://mywebsite.com/callback',
currency: {
iso: 'XOF'
},
customer: {
firstname: 'John',
lastname: 'Doe',
email: '[email protected]',
phone_number: {
number: '97808080',
country: 'BJ'
}
}
});
If your customer is already listed, just give in parameter his identifier (ID) or his email.
Your customer ID and email can be found on your dashboard in customer details.
curl -X POST \
https://sandbox-api.fedapay.com/v1/transactions \
-H 'Authorization: Bearer YOUR_API_SECRET_KEY' \
-H 'Content-Type: application/json' \
-d '{
"description" : "Transaction for [email protected]",
"amount" : 2000,
"currency" : {"iso" : "XOF"},
"callback_url" : "https://mywebsite.com/callback",
"customer" : {
"email" : "[email protected]",
}
}'
/* Replace YOUR_API_SECRET_KEY by your API secret key */
\FedaPay\FedaPay::setApiKey("YOUR_API_SECRET_KEY");
/* Specify whenever you are willing to execute your request in test or live mode */
\FedaPay\FedaPay::setEnvironment('sandbox'); //or setEnvironment('live');
/* Create the transaction */
\FedaPay\Transaction::create(array(
"description" => "Transaction for [email protected]",
"amount" => 2000,
"currency" => ["iso" => "XOF"],
"callback_url" => "https://mywebsite.com/callback",
"customer" => [
"email" => "[email protected]" /* or "id" => 105 */
]
));
const { FedaPay, Transaction } = require('fedapay')
/* Replace YOUR_API_SECRET_KEY by your API secret key */
FedaPay.setApiKey("YOUR_API_SECRET_KEY");
/* Specify whenever you are willing to execute your request in test or live mode */
FedaPay.setEnvironment('sandbox'); //or setEnvironment('live');
/* Create the transaction */
const transaction = await Transaction.create({
description: 'Description',
amount: 2000,
callback_url: 'https://mywebsite.com/callback',
currency: {
iso: 'XOF'
},
customer: {
email: '[email protected]' /* or id: 105 */
}
});
You can specify in this request a return link or callback url that will allow to your customer to be redirected to a specific page once the transaction settlement completed. Otherwise, you can leave this parameter blank.
Unlike the query others parameters that are required for your transaction creation, it's optionnal. Note that in the case where the return link is not indicated, your customer will have to leave the payment page manually at the end of the transaction.
2- Generate the token and the payment link of the transaction
Once the transaction creation request has been submitted, the system will send you a detailed summary of the transaction data with an unique identifier (ID) for it. Send a new request having for only one parameter, the received identifier via the API to generate the link plus a token or unique key for your transaction.
Use this code to send your request via the API.
curl -X POST \
https://sandbox-api.fedapay.com/v1/transactions/ID/token \
-H 'Authorization: Bearer YOUR_API_SECRET_KEY' \
-H 'Content-Type: application/json'
$transaction = \FedaPay\Transaction::create(array(...))
$token = $transaction->generateToken();
return header('Location: ' . $token->url);
const transaction = await Transaction.create({...})
const token = await transaction.generateToken();
return redirect(token.url);
3- Redirection to the payment page
The link allows you to redirect your customer to the secure payment page on which the customer will settle the transaction.
4- Return link
This link will also return you the transaction ID and status. Indicate one if you wish, it is optional. In this case, the customer will have to leave the payment page manually.
- With the return link specified for an approved transaction
https://www.mywebsite.com/?id=258&status=approved
- With the return link specified for a canceled transaction
https://www.mywebsite.com/?id=259&status=canceled
In these two examples, the link by https://www.mywebsite.com/
is the one you specified as
callback_url
when creating your transaction.
And it returns you the ID and status of the transaction made by the customer in parameters as follows
?id=259&status=canceled
.
So, always send a new request directly to the API for the true status of a transaction with the ID for your treatments.
5- Retrieving the details of a transaction
To retrieve the information about a given transaction, and do some treatments with it, proceed as follows.
curl -X GET \
https://sandbox-api.fedapay.com/v1/transactions/ID \
-H 'Authorization: Bearer YOUR_API_SECRET_KEY' \
-H 'Content-Type: application/json'
$transaction = \FedaPay\Transaction::retrieve(ID);
if ($transaction->status == "approved") {
echo "Payment approved";
}
const transaction = await Transaction.retrieve(ID);
if (transaction.status == "approved") {
console.log("Payment approved");
}
Make a payment without redirection
It is possible to be able to make payments without redirecting the user to the payment page, for example, when you want to keep the user on your site or web application without changing their experience. In this case, you will need to implement the payment form yourself in your application.
1- Send a mobile money payment without redirection
You will first have to create a transaction and then obtain your token. Then send a request for one of the following payment methods:
mtn
: for MTN Mobile Money Beninmoov
: for Moov Beninmtn_ci
: for MTN Mobile Money Ivory Coastmoov_tg
: for Moov Togo
Replace YOUR_API_SECRET_KEY by the API secret key of your sandbox or live account. If you are using your live account, you must replace the link by par https://api.fedapay.com/v1/transactions/ID
Replace PAYMENT_METHOD by one of the payment methods mentioned above.
curl -X POST \
https://sandbox-api.fedapay.com/v1/METHODE_PAIEMENT \
-H 'Authorization: Bearer VOTRE_CLE_API_SECRETE' \
-H 'Content-Type: application/json'
-d '{
"token" : "TOKEN_DE_PAIEMENT"
}'
Replace PAYMENT_METHOD by one of the payment methods mentioned above.
$transaction = \FedaPay\Transaction::create(...);
$token = $transaction->generateToken()->token;
$mode = 'METHODE_PAIEMENT'; // 'mtn', 'moov', 'mtn_ci', 'moov_tg'
$transaction->sendNowWithToken($mode, $token);
Replace PAYMENT_METHOD by one of the payment methods mentioned above.
const transaction = await Transaction.create(...);
const token = transaction.generateToken().token;
const mode = 'METHODE_PAIEMENT'; // 'mtn', 'moov', 'mtn_ci', 'moov_tg'
await transaction.sendNowWithToken(mode, token);
2- Retrieve the status of the transaction.
If you send a payment without redirect, there are two ways to retrieve the status of a transaction since it is paid a few seconds later after sending the payment request.
- Send a request to retrieve the details of the transaction. See Step 5.
- Implement webhooks to receive payment notification. See webhooks.
Transactions lifecycle
When you create a transaction, it goes through different states or statuses: that's the life cycle of transactions.
These statuses are :
pending
: Pendingapproved
: Approveddeclined
: Declinedcanceled
: Canceledrefunded
: Refundedtransferred
: Transferred
Initially, when you create a transaction, it is in Pending
.
This is the default status.
The transaction will change to Approved
when the payment will have been successfully completed by your
customer.
It goes to Declined
if at the moment of payment, your customer does not have enough assets on the account
he has chosen to settle the transaction or has a problem with this account.
It is Canceled
when your customer at the moment of payment, cancels the process intentionally or not.
Refunded
when the payment made by your customer has been returned back to him.
Transferred
when the amount of a transaction has been sent by FedaPay to the balance of your merchant account.
Only transactions which have been approved are transferred to your balance.
You can always check the status of each of your transactions on your FedaPay dashboard in the Transactions menu to follow their progress.
However, for security puposes, we recommend you to issue a new request with the identifier(ID) of a transaction to have its real status.