Quick start

Introduction

The Senfenico API offers two integration methods for payment processing: with redirection and without redirection, catering to diverse application needs.

With Redirection

Advantage: Streamlined user flow 🚀; users are redirected to Senfenico's secure payment page.
Disadvantage: Potential disruption in user experience as users exit the native application or website.
Workflow:
Initialize Checkout: Start the payment process by calling the designated endpoint.
Redirect the Customer: Send users to the provided authorization URL.

Without Redirection

Advantage: Complete control over the user experience, with all steps handled within your application or website.
Disadvantage: Increased complexity as you have to handle all the payment steps, including OTP (One-Time Password) submission if required.
Workflow:
Create a Charge: Set up the payment details.
Customer Action: Prompt users to approve the transaction via their mobile device.
Submit OTP: Submit the OTP received by the client.

Accepting Payment with Redirection

1️⃣ First Step: Initialize Checkout

cUrljavanodejsphppython

POST /v1/payment/checkouts/initialize/

curl --location 'https://api.senfenico.com/v1/payment/checkouts/initialize/' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'X-API-KEY: sk_test_...' \
--data '{
    "email": "customer@mail.com",
    "amount": 600,
    "success_url": "https://example.com/sucess",
    "cancel_url": "https://example.com/cancel"
}'

POST /v1/payment/checkouts/initialize/

OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n  \"email\": \"customer@mail.com\",\n  \"amount\": 600,\n  \"success_url\": \"https://example.com/sucess\",\n  \"cancel_url\": \"https://example.com/cancel\"\n}");
Request request = new Request.Builder()
.url("https://api.senfenico.com/v1/payment/checkouts/initialize/")
.method("POST", body)
.addHeader("Content-Type", "application/json")
.addHeader("Accept", "application/json")
.addHeader("X-API-KEY", "sk_test_...")
.build();
Response response = client.newCall(request).execute();

POST /v1/payment/checkouts/initialize/

var https = require('follow-redirects').https;
var fs = require('fs');

var options = {
    'method': 'POST',
    'hostname': 'api.senfenico.com',
    'path': '/v1/payment/checkouts/initialize/',
    'headers': {
        'Content-Type': 'application/json',
        'Accept': 'application/json',
        'X-API-KEY': 'sk_test_...'
    },
    'maxRedirects': 20
};

var req = https.request(options, function (res) {
    var chunks = [];

    res.on("data", function (chunk) {
        chunks.push(chunk);
    });

    res.on("end", function (chunk) {
        var body = Buffer.concat(chunks);
        console.log(body.toString());
    });

    res.on("error", function (error) {
        console.error(error);
    });
});

var postData = JSON.stringify({
    "email": "customer@mail.com",
    "amount": 600,
    "success_url": "https://example.com/sucess",
    "cancel_url": "https://example.com/cancel"
});

req.write(postData);

req.end();

POST /v1/payment/checkouts/initialize/

$senfenico = new \Senfenico\Senfenico('sk_test_...');
$senfenico->checkout->initialize([
    'amount' => 1000,
    'success_url' => 'https://yourwebsite.com/success',
    'cancel_url' => 'https://yourwebsite.com/cancel',
]);

POST /v1/payment/checkouts/initialize/

import senfenico
senfenico.api_key = 'sk_test_...'

senfenico.Checkout.initialize(
    amount=100, 
    success_url='http://website.com/success', 
    cancel_url='http://www.website.com/cancel')

Parameter	Type	Optional	Description
email	string	Yes	Customer's email address
amount	int	No	Amount to charge
success_url	string	No	URL to redirect on success
cancel_url	string	No	URL to redirect if the customer cancels

Sample Response

200 OK

Checkout initialized

{
    "status": true,
    "message": "Checkout initialized",
    "data": {
        "reference": "chk_de1ca053573c40a29a9fe95e7ad91d7e",
        "authorization_url": "https://api.senfenico.com/v1/checkout_payment/payment_page/chk_de1ca053573c40a29a9fe95e7ad91d7e/",
        "live_mode": false
    }
}

Response Element	Type	Description
reference	string	Unique reference for the checkout
authorization_url	string	URL to redirect the user to proceed with the payment

2️⃣ Second Step: Redirect the User

Direct the user to the authorization_url to complete the payment process.

Accepting Payment Without Redirection

1️⃣ First Step: Create a Charge

cUrljavanodejsphppython

POST /v1/payment/charges/

curl --location 'https://api.senfenico.com/v1/payment/charges/' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'X-API-KEY: sk_test_...' \
--data '{
    "amount": "500",
    "currency": "XOF",
    "payment_method": "mobile_money",
    "payment_method_details": {
        "phone": "76xxxxxx",
        "provider": "orange_bf"
    }
}'

POST /v1/payment/charges/

OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n  \"amount\": \"500\",\n  \"currency\": \"XOF\",\n  \"payment_method\": \"mobile_money\",\n  \"payment_method_details\": {\n    \"phone\": \"76xxxxxx\",\n    \"provider\": \"orange_bf\"\n  }\n}");
Request request = new Request.Builder()
    .url("https://api.senfenico.com/v1/payment/charges/")
    .method("POST", body)
    .addHeader("Content-Type", "application/json")
    .addHeader("Accept", "application/json")
    .addHeader("X-API-KEY", "sk_test_...")
    .build();
Response response = client.newCall(request).execute();

POST /v1/payment/charges/

var https = require('follow-redirects').https;
var fs = require('fs');

var options = {
    'method': 'POST',
    'hostname': 'api.senfenico.com',
    'path': '/v1/payment/charges/',
    'headers': {
        'Content-Type': 'application/json',
        'Accept': 'application/json',
        'X-API-KEY': 'sk_test_...'
    },
    'maxRedirects': 20
};

var req = https.request(options, function (res) {
var chunks = [];

res.on("data", function (chunk) {
    chunks.push(chunk);
});

res.on("end", function (chunk) {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
});

res.on("error", function (error) {
    console.error(error);
});
});

var postData = JSON.stringify({
    "amount": "500",
    "currency": "XOF",
    "payment_method": "mobile_money",
    "payment_method_details": {
        "phone": "76xxxxxx",
        "provider": "orange_bf"
    }
});

req.write(postData);

req.end();

POST /v1/payment/charges/

$senfenico = new \Senfenico\Senfenico('sk_test_...');
$senfenico->charge->create([
    'amount' => 1000,
    'phone' => '76XXXXXX',
    'provider' => 'orange_bf'
]);

POST /v1/payment/charges/

import senfenico
senfenico.api_key = 'sk_test_...'

senfenico.Charge.create(amount=2000, phone='65000000', provider='orange_bf')

Parameter	Type	Optional	Description
amount	int	No	Amount to charge
currency	string	No	Currency code ("XOF")
payment_method	string	No	Payment method ("mobile_money")
payment_method_details	object	No	Details about the payment method
phone	string	No	your client phone number
provider	object	No	the client payment platform operator. Available options: `orange_bf` `moov_bf` `coris_bf` `sank_bf`

Note on Provider Constraints:

For orange_bf: Use an Orange BF phone number (8 digits). Valid prefixes: 04, 05, 06, 07, 54, 55, 56, 57, 64, 65, 66, 67, 74, 75, 76, 77.
For moov_bf: Use a Moov BF phone number (8 digits). Valid prefixes: 70, 71, 72, 73, 60, 61, 62, 63, 50, 51, 52, 53, 01, 02, 03.
For coris_bf: You can use any Burkina-Faso mobile phone number
For sank_bf: You can use any Burkina-Faso mobile phone number

Sample Response

201 provider:orange_bf201 provider:moov_bf

provider:orange_bf sample response

{
    "status": true,
    "message": "Charge attempted",
    "data": {
        "reference": "ch_1ba1b4d1268b41079ee84c777e999f51",
        "status": "send_otp",
        "display_text": "Composez *144*4*6*500# pour obtenir un code OTP, puis entrez-le sur notre plateforme pour finaliser la transaction.",
        "live_mode": false
    }
}

provider:moov_bf sample response

{
    "status": true,
    "message": "Charge attempted",
    "data": {
        "reference": "ch_4f60d14ace534fd19ee3cce88fd6ba73",
        "status": "send_otp",
        "display_text": "Veuillez entrer le code OTP reçu sur votre téléphone pour finaliser la transaction.",
        "live_mode": false
    }
}

Interpretation of Responses:

For orange_bf: The customer must compose the provided USSD code to obtain an OTP and enter it on the platform.
For moov_bf: The customer will receive an OTP that must be entered on the platform in order to complete the payment.
For coris_bf: The customer will receive an OTP that must be entered on the platform in order to complete the payment.
For sank_bf: The customer will receive an OTP that must be entered on the platform in order to complete the payment.

2️⃣ Second Step: Customer Action

Instruct the customer to follow the provided instructions for payment validation.