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 purpose
• amount : specify the transaction amount. This amount should always be an integer
• currency : specify the currency to use for the transaction

For this attribute, either the ISO number or the ISO must be indicated. Refer to the table of available currencies.

• callback_url : to set a return link
• customer : specify the customer with whom the transaction must be done

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

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 Benin
• moov: for Moov Benin
• mtn_ci: for MTN Mobile Money Ivory Coast
• moov_tg: for Moov Togo

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"
}'

$transaction = \FedaPay\Transaction::create(...);
$token = $transaction->generateToken()->token;
$mode = 'METHODE_PAIEMENT'; // 'mtn', 'moov', 'mtn_ci', 'moov_tg'
$transaction->sendNowWithToken($mode, $token);

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: Pending
• approved: Approved
• declined: Declined
• canceled: Canceled
• refunded: Refunded
• transferred: 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.