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 john.doe@example.com",
      "amount" : 2000,
      "currency" : {"iso" : "XOF"},
      "callback_url" : "https://mywebsite.com/callback",
      "customer" : {
          "firstname" : "John",
          "lastname" : "Doe",
          "email" : "john.doe@example.com",
          "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 john.doe@example.com",
  "amount" => 2000,
  "currency" => ["iso" => "XOF"],
  "callback_url" => "https://mywebsite.com/callback",
  "customer" => [
      "firstname" => "John",
      "lastname" => "Doe",
      "email" => "john.doe@example.com",
      "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: 'john.doe@example.com',
      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 john.doe@example.com",
      "amount" : 2000,
      "currency" : {"iso" : "XOF"},
      "callback_url" : "https://mywebsite.com/callback",
      "customer" : {
          "email" : "john.doe@example.com",
        }
    }'
/* 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 john.doe@example.com",
  "amount" => 2000,
  "currency" => ["iso" => "XOF"],
  "callback_url" => "https://mywebsite.com/callback",
  "customer" => [
    "email" => "john.doe@example.com" /* 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: 'john.doe@example.com' /* 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 redirect($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
The callback_url or return link, allows you to automatically redirect your customer to a specific page of your choice, once he reaches the transaction settlement process end.
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.
Examples
  • 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.

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");
}

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.