This section describes the Nanfolo Digital Wallet payment gateway API.
Nanfolo Digital Wallet API is easy to implement in your business software. Our API is well formatted URLs, accepts cURL requests, returns JSON responses.
You can use the API in test mode, which does not affect your live data. The API key is use to authenticate the request and determines the request is valid payment or not. For test mode just use the sandbox URL and In case of live mode use the live URL from section Initiate Payment .
This section describes the currencies supported by Nanfolo Digital Wallet
Nanfolo Digital Wallet allows to make transaction with below currencies. Any new currency may update in future.
Currency Name | Currency Symbol | Currency Code |
---|---|---|
United States Dollar | $ | USD |
Franc Guinéen | fg | GNF |
Franc CFA | cfa | CFA |
This section describes how you can get your api key.
Login to your Nanfolo Digital Wallet merchant account. If you don't have any ? Click Here
Next step is to find the Api Key menu in your dashboard sidebar. Click the menu.
The api keys can be found there which is Public key and Secret key. Use these keys to initiate the API request. Every time you can generate new API key by clicking Generate Api Key button. Remember do not share these keys with anyone.
This section describes the process of initaiing the payment.
To initiate the payment follow the example code and be careful with the perameters. You will need to make request with these following API end points.
Live End Point: https://nanfolo.com/payment/initiate
Test End Point: https://nanfolo.com/sandbox/payment/initiate
Test Mode Mail: test_mode@mail.com
Test Mode Verification Code: 222666
Request Method: POST
Request to the end point with the following parameters below.
Param Name | Param Type | Description |
---|---|---|
public_key | string (50) | Required Your Public API key |
identifier | string (20) | Required Identifier is basically for identify payment at your end |
currency | string (4) | Required Currency Code, Must be in Upper Case. e.g. USD,EUR |
amount | decimal | Required Payment amount. |
details | string (100) | Required Details of your payment or transaction. |
ipn_url | string | Required The url of instant payment notification. |
success_url | string | Required Payment success redirect url. |
cancel_url | string | Required Payment cancel redirect url. |
site_logo | string/url | Required Your business site logo. |
checkout_theme | string | Optional Checkout form theme dark/light. Default theme is light |
customer_name | string (30) | Required Customer name. |
customer_email | string (30) | Required Customer valid email. |
<?php
$parameters = [
'identifier' => 'DFU80XZIKS',
'currency' => 'USD',
'amount' => 100.00,
'details' => 'Purchase T-shirt',
'ipn_url' => 'http://example.com/ipn_url.php',
'cancel_url' => 'http://example.com/cancel_url.php',
'success_url' => 'http://example.com/success_url.php',
'public_key' => 'your_public_key',
'site_logo' => 'https://nanfolo.com/assets/images/logoIcon/logo.png',
'checkout_theme' => 'dark',
'customer_name' => 'John Doe',
'customer_email' => 'john@mail.com',
];
//live end point
$url = "https://nanfolo.com/payment/initiate";
//test end point
$url = "https://nanfolo.com/sandbox/payment/initiate";
$ch = curl_init();
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false);
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POSTFIELDS, $parameters);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$result = curl_exec($ch);
curl_close($ch);
//$result contains the response back.
?>
//Error Response.
{
"error": "true",
"message": "Invalid api key"
}
//Success Response.
{
"success": "ok",
"message": "Payment Initiated. Redirect to url.",
"url":"http://example.com/initiate/payment/checkout?payment_id=eJSAASDxdrt4DASDASVNASJA7893232432cvmdsamnvASF"
}
This section describes the process to get your instant payment notification.
To initiate the payment follow the example code and be careful with the perameters. You will need to make request with these following API end points.
End Point: Your business application ipn url.
Request Method: POST
You will get following parameters below.
Param Name | Description |
---|---|
status | Payment success status. |
identifier | Identifier is basically for identify payment at your end. |
signature | A hash signature to verify your payment at your end. |
data | Data contains some basic information with charges, amount, currency, payment transaction id etc. |
<?php
//Receive the response parameter
$status = $_POST['status'];
$signature = $_POST['signature'];
$identifier = $_POST['identifier'];
$data = $_POST['data'];
// Generate your signature
$customKey = $data['amount'].$identifier;
$secret = 'YOUR_SECRET_KEY';
$mySignature = strtoupper(hash_hmac('sha256', $customKey , $secret));
$myIdentifier = 'YOUR_GIVEN_IDENTIFIER';
if($status == "success" && $signature == $mySignature && $identifier == $myIdentifier){
//your operation logic
}
?>
Below is the example to implement it into a flutter mobile app .
class NanfoloPayments extends StatefulWidget {
final String link;
final String successUrl;
final String cancelUrl;
const NanfoloPayments({
Key? key,
required this.link,
required this.successUrl,
required this.cancelUrl,
}) : super(key: key);
@override
State createState() => _NanfoloPaymentsState();
}
class _NanfoloPaymentsState extends State {
bool isLoading = true;
int pressed = 0;
@override
Widget build(BuildContext context) {
return WillPopScope(
onWillPop: () async {
if (pressed < 2) {
setState(() {
pressed++;
});
final snackBar = SnackBar(
content: Text(
'Press back ${3 - pressed} more times to cancel transaction'));
ScaffoldMessenger.of(context).showSnackBar(snackBar);
return false;
} else {
return true;
}
},
child: Scaffold(
body: SizedBox(
child: Stack(
children: [
InAppWebView(
initialUrlRequest: URLRequest(
url: Uri.parse(widget.link),
),
onLoadStart: (controller, url) {},
onLoadError: (controller, url, code, message) {
setState(() {
isLoading = false;
});
},
onLoadStop: (controller, url) {
setState(() {
isLoading = false;
});
},
initialOptions: InAppWebViewGroupOptions(
crossPlatform: InAppWebViewOptions(
useShouldOverrideUrlLoading: true,
),
),
onAjaxReadyStateChange: (controller, ajaxRequest) {
log('onAjaxReadyStateChange: ${ajaxRequest.response}');
log('onAjaxReadyStateChange: ${ajaxRequest.data}');
log('onAjaxReadyStateChange: ${ajaxRequest.status}');
return Future.value();
},
shouldOverrideUrlLoading: (controller, navigationAction) async {
var uri = navigationAction.request.url!;
debugPrint(uri.toString());
log(uri.toString());
//Here we are handling successUrl. Make sure you enter a correct successUrl value from backend and page exists.
if (uri.toString() == widget.successUrl) {
Navigator.pop(context, true);
}
if (uri.toString() == widget.cancelUrl) {
Navigator.pop(context, false);
}
return NavigationActionPolicy.ALLOW;
},
),
if (isLoading)
const Center(
child: CircularProgressIndicator(),
),
// Observer(builder: (context) => LoaderWidget().visible(appStore.isLoading)),
],
),
),
),
);
}
}
//Calling Webview.
final paymentInitResult =
await postRequest(API.nanfoloPaymentInitiate(cartId), {"payment_method_id": "5"}, bearerToken: true);
if (json.decode(paymentInitResult.body)['success'] == false) {
//Some error occured on your backend server API endpoint.
return false;
}
final responseJson = json.decode(paymentInitResult.body);
//We are calling our webview and waiting for response from it.
final res = await Navigator.push(
context,
MaterialPageRoute(
builder: (context) =>
NanfoloPayments(link: responseJson['url'], successUrl: responseJson['success_url'], cancelUrl: responseJson['cancel_url']),
),
);
if (res != null && res) {
checkoutNotifier.paymentStatus = 'PAID';
checkoutNotifier.paymentMeta = {'payBy': 'nanfolo'};
return true;
} else {
//If failed tell server to rollback the order!
final Response cancelResponse = await postRequest(API.nanfoloPaymentCancelled(cartId),
{"order_id": responseJson!["order_id"].toString()}
,bearerToken: true);
debugPrint("Order Cancelled Response: ${cancelResponse.body}");
return false;
}
This section describes the Nanfolo Digital Wallet virtual cards API.
Nanfolo Digital Wallet virtual cards API is easy to implement in your business software. Our API is well formatted URLs, accepts cURL requests, returns JSON responses.
You can use the API in only live mode. The API key is use to authenticate the request and determines the request is valid payment or not. .
This section describes the process of etting list of your virtual card.
You need to send a get request to below link.
Live End Point: https://nanfolo.com/api/cards
Request Method: GET
Request Header: Bearer { your_secret_api_key }
You can use below query params to paginate records.
Param Name | Param Type | Description |
---|---|---|
page | positive integer | Optional Page number |
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => 'https://nanfolo.com/api/cards?page=1',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => '',
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_HTTPHEADER => array(
'Authorization: Bearer {your_secret_key}'
),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
?>
This section describes the process of creating new virtual card.
To create new card you need to send a POST API request to below endpoint.
Live End Point: https://nanfolo.com/api/cards/save
Request Method: POST
Request Header: Bearer { your_secret_api_key }
Request to the end point with the following parameters below.
Param Name | Param Type | Description |
---|---|---|
currency_code | string (3) | Required Currency of virtual card. Must be from active currencies section |
title | string (255) | Required Title to identify card (not name) |
name_on_card | string (255) | Required User name that appear on card. |
string (255) | Required User email. Must be valid email address. | |
amount | decimal | Required Virtual card total amount. |
<?php
$client = new Client();
$headers = [
'Content-Type' => 'application/json',
'Authorization' => 'Bearer {your_secret_key}'
];
$body = '{
"currency_code": "USD",
"title": "Some Title",
"name_on_card": "Nouman Dev",
"email": "dev@dev.com",
"amount": "1000"
}';
$request = new Request('POST', 'https://nanfolo.com/api/cards/save', $headers, $body);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();
?>
This section describes the process of getting single virtual card transactions.
You need to send a get request to below link.
Live End Point: https://nanfolo.com/api/cards/your_card_id
Request Method: GET
Request Header: Bearer { your_secret_api_key }
No param is needed.
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => 'https://nanfolo.com/api/cards/{your_card_id}',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => '',
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_HTTPHEADER => array(
'Authorization: Bearer {your_secret_key}'
),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
?>
This section describes the process of changing status of virtual card.
To update status of virtual card you need to send a PUT API request to below endpoint.
Live End Point: https://nanfolo.com/api/cards/toggle
Request Method: PUT
Request Header: Bearer { your_secret_api_key }
Request to the end point with the following parameters below.
Param Name | Param Type | Description |
---|---|---|
card_id | string (40) | Required Card id |
active | boolean (true,false) | Required If passed true means you want to activate an inactive card. If this parameter is false then you want to block/inactive this card. |
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => 'https://nanfolo.com/api/cards/toggle',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => '',
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => 'PUT',
CURLOPT_POSTFIELDS =>'{
"card_id": "{card_id_here}",
"active": true
}',
CURLOPT_HTTPHEADER => array(
'Content-Type: application/json',
'Authorization: Bearer {your_secret_token}'
),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
?>
This section describes the process of canceling the virtual card.
To cancel a virtual card you need to send a PUT API request to below endpoint.
Live End Point: https://nanfolo.com/api/cards/cancel/your_card_id
Request Method: PUT
Request Header: Bearer { your_secret_api_key }
No parameter is needed.
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => 'https://nanfolo.com/api/cards/cancel/{your_card_id}',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => '',
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => 'PUT',
CURLOPT_HTTPHEADER => array(
'Authorization: Bearer {your_secret_key}'
),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response; ?>
This is the API resource defination for nanfolo virtual card.
{
"id": "nf_egqvyf6v0jwr2p1yv8vx",
"amount": 200,
"charges": 3,
"available_balance": 0,
"title": "Customer 1 Alakba Gift Card",
"masked_card_number": "************6777",
"card_number": "8246695135536777",
"name_on_card": "Customer 1",
"email": "customer123@gmail.com",
"cvc": "473",
"expiry_month": 11,
"expiry_year": "2025",
"status": "canceled",
"created_at": "2023-11-12T11:46:20.000000Z",
"updated_at": "2023-11-12T14:06:51.000000Z",
"currency": "USD"
}
This is the API resource defination for nanfolo virtual card transactions.
{
"id": "XPX1ZGF56AVV4",
"currency_code": "PKR",
"before_charge": 6000,
"amount": 6000,
"charge": 0,
"type": "-",
"details": "Payment successful to Test Merchant",
"remark": "make_payment",
"created_at": "2023-11-12T16:27:53.000000Z",
"updated_at": "2023-11-12T16:27:53.000000Z"
}