Direct charge

On certain occasions, it may be necessary to obtain increased authority or a personalized strategy that aligns with your application. This is where the option of "Direct" becomes relevant.

We offer APIs for customer billing, however, it is incumbent upon you to retrieve their payment information and determine your own user interface and payment process. This approach grants you the ability to create tailor-made customer experiences that fulfill your vision.

How does it operate?

Direct charge involves three core stages:

1. First, initialize the payment through submitting the payment and customer details to the relevant complete endpoints.
2. Secondly, complete the charge by obtaining the customer's consent through their payment provider, such as a bank, mobile money or card issuer, which allows the charge to be completed.
3. Lastly, as a precautionary measure, make use of the verify payment endpoint or listen Webhooks notification if enabled for confirmation that the payment has been successful prior to providing value.

Step 1: Collect payment details

To begin, you'll need to compile payment details into a JSON object that will be transmitted to your API.

Here are the details you'll need to gather:

• amount: Numeric, required. The payment amount.
• currency: String, required. The currency of the payment.
• description: String, optional. Description of the payment.
• reference: String, optional. Your unique reference of the payment.
• callback: String, optional. Return URL where your customer will be redirected after payment.
• customer: (Array, required. customer information)

  • customer.email: String, required if customer.phone is null. Customer's email address.
  • customer.name: String, optional. Customer's name.
  • customer.phone: String, required if customer.email is null. Customer's phone number.
  • customer.address: String, optional. Customer's address.
  • customer.city: String, optional. Customer's city.
  • customer.state: String, optional. Customer's state.
  • customer.country: String, optional. Customer's country.
  • customer.zip_code: String, optional. Customer's zip code.
• metadata: Array, optional. Additional data for the payment.

Step 2: Initiate payment

After collecting the payment details, proceed to initiate the payment by calling our API. Ensure to include the collected payment details in the request body and authorize the request using your public key.

Example request

$curl = curl_init();

$fields = [
    'customer' => [
      'email' => "customer@email.com",
    ],
    'amount' => "1000",
    'currency' => "XAF",
    'description' => "My first payment"
  ];

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.notchpay.co/payments",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => $fields,
  CURLOPT_HTTPHEADER => [
    "Authorization: YOUR_PUBLIC_KEY",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

Example response

{
  "status": "Accepted",
  "message": "Payment initialized",
  "code": 201,
  "transaction": {
    "amount": 1000,
    "amount_total": 1000,
    "sandbox": false,
    "fee": 0,
    "converted_amount": 1000,
    "customer": "cus.40jRRfanz7tKgZrl",
    "description": "My first payment",
    "reference": "trx.1OFePHllHoeNSL1qfsWUV1l1",
    "status": "pending",
    "currency": "XAF",
    "geo": "129.0.189.24",
    "created_at": "2024-04-25T21:39:21.000000Z",
    "updated_at": "2024-04-25T21:39:21.000000Z"
  },
  "authorization_url": "https://pay.notchpay.co/phUSV2AyUiFTeKU7O2TKxpAN04g9lyqc5zp2aSVz0ZNQYNhJroNOIhlNi8aRnKYQiANLhM51eRqZbuDX6xRAlfkFUYwZngf1pSe4MYYSnzFOzY1u3vf9hxUum69QNmPFwaNvTK9bluTPMZZAcR9KosCH52xeHAyiiz0WlovcRg7wOAkZWOVYSPXOrCRTmYUI"
}

Step 3: Initiate Charge

This operation initiates payment at your customer's operator. Depending on the operator, you will be asked to complete the payment.

To perform Direct Charge operation you need to specify the means by which the customer will make the transaction. Below are the payment methods available.

Charges options

Below are the available methods for receiving payments through e2e. Each form of e2e necessitates distinctive prerequisites and an authorization process.

Parameters according to channel

Data parameters according to channel

Example request

curl --location -g --request PUT 'https://api.notchpay.co/payments/cTXHSX223NhUzjgxAJoRAzVFGwBIn0Kv' \
--header 'Authorization: PUBLIC_KEY' \
--header 'Accept: application/json' \
  --data '{
  "channel": "cm.orange",
  "data" : {
    "phone": "+237656019261"
  }
}'

Example response

{
  "message": "Confirm your transaction by dialing #150#",
  "code": 202,
  "status": "Accepted",
  "action": "confirm"
}

Webhooks

To effectively manage Direct charge scenarios, webhooks can be valuable assets in receiving prompt notifications of customer-authorized charges. Reviewing our comprehensive webhooks guide will provide useful insights and knowledge on how to efficiently incorporate them into your operations.