Collect (Hosted Page)

Notch Pay Collect is our default payment flow, which directs your customer to a Notch Pay-hosted payments page.

Here's how it functions:

1. Call our API initialize payment endpoint with the payment details from your server.
2. We'll provide a link to a payment page. Redirect your customer to this link to proceed with the payment.
3. Upon completion of the transaction, we'll redirect the customer back to you (to the callback you provided) along with the payment details.

Step 1: Collect payment information

In order to commence the transaction, certain information such as email, phone, name, amount, reference, etc., must be queued. Customer details may be obtained from a pre-existing database, session/cookie or form submission, as demonstrated in the example below.

    <form action="/process-payment" method="POST"> 
        <input type="hidden" name="user_email" value="hello@notchpay.co"> 
        <input type="hidden" name="amount" value="1000"> 
        <input type="hidden" name="cart_reference" value="cart_12dh3ds6hs2s8sha"> 
        <button type="submit" name="make_payment" id="make-payment" title="Make payment">Make payment</button>
    </form>

Step 2: Initialize payment

Upon a customer selecting the payment action button, initiate a transaction through submission of a POST request to our API, specifically directed to the Initialize Notch Pay Payment API endpoint, which should include relevant parameters such as email, amount, currency and any additional requisite parameters.

Important notes

1. The amount field must be consistent with the currency you wish to use. If for example you use XAF, this value must not contain a decimal value
2. The cart_reference obtained from the aforementioned form served as our reference for the transaction. It is recommended that a unique transaction identifier from your system is utilized as the reference instead.
3. The callback was established within the payment data array.
4. In the event that a callback URL is not specified on the dashboard or within the code, users will not be redirected to your site subsequent to payment.
5. Test transactions may employ test callback URLs, while live transactions can utilize live callback URLs.

Example request

    $url = "https://api.notchpay.co/payments/initialize";

    $fields = [
        'email' => "customer@email.com",
        'amount' => "1000",
        'currency' => "XAF",
        'description' => "Payment description", // this field is optional
        'reference' => 'your_unique_reference' // this param is optional but recommended
        'callback' => 'your_callback_url'
    ];

    //open connection
    $ch = curl_init();
    
    //set the url, number of POST vars, POST data
    curl_setopt($ch,CURLOPT_URL, $url);
    curl_setopt($ch,CURLOPT_POST, true);
    curl_setopt($ch,CURLOPT_POSTFIELDS, $fields);
    curl_setopt($ch, CURLOPT_HTTPHEADER, array(
        "Authorization: PUBLIC_KEY",
        "Cache-Control: no-cache",
    ));
    
    //So that curl_exec returns the contents of the cURL; rather than echoing it
    curl_setopt($ch,CURLOPT_RETURNTRANSFER, true); 
    
    //execute post
    $result = curl_exec($ch);
    echo $result;

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",
    "reference": "trx.DzoxEW60jLOfd9eB8sb43r1z",
    "status": "pending",
    "currency": "XAF",
    "callback": "https://notchpay.co",
    "geo": "129.0.189.24",
    "created_at": "2024-04-25T04:04:22.000000Z",
    "updated_at": "2024-04-25T04:04:22.000000Z"
  },
  "authorization_url": "https://pay.notchpay.co/l5v1X6gfxTnbHC3DvQAaACiemgsZzfw9Css6Nzozq44aW4nXkO5Lix7qiKPYkEulnWTOCemfaEnZZprWszZvxOnp42hSJA6tAIkRiewFisEp1AiUwDdhCM5EBOrNbRLojUFpQpnj1iDfFoiTWhw614kR3rZaRbPj41tNtC9aUA6ZRd4jQM0Tr8bQPPvL2z4O"
}

Step 3: Redirect your user to our Hosted Payment Page

All you need to do is redirect your customer to the link returned in authorization_url. We will present our payment interface to the customer for payment processing.

Step 4: After Payment

Once the payment is completed, whether successful or failed, several actions will take place:

1. We redirect to your callback_url with the status, reference, trxref, and status included in the query parameters.
2. If you have activated webhooks, we will send you a webhook notification. For more details on webhooks and examples, please refer to our webhooks guide.
3. An acknowledgment email will be sent to your customer if the payment was successful, unless you have disabled this feature.
4. You will receive an email notification, unless you have opted out.

On the server side, it's essential to handle the redirection and always verify the final status of the transaction.

If webhooks are enabled, we'll send you a notification for each failed payment attempt. This feature is particularly useful if you need to follow up with customers who encountered payment issues. Refer to our webhooks guide for an example.