README

A PHP API wrapper for Notch Pay.

Requirements

Curl 7.34.0 or more recent (Unless using Guzzle)
PHP 5.4.0 or more recent
OpenSSL v1.0.1 or more recent

Install

Via Composer

    $ composer require notchpay/php-sdk

Via download

Download a release version from the releases page. Extract, then:

    require 'path/to/src/autoload.php';

Usage

Do a redirect to the authorization URL received from calling the payments/initialize endpoint. This URL is valid for one time use, so ensure that you generate a new URL per payment.

When the payment is successful, we will call your callback URL (as setup in your dashboard or while initializing the transaction) and return the reference sent in the first step as a query parameter.

If you use a test public key, we will call your test callback url, otherwise, we'll call your live callback url.

0. Prerequisites

Confirm that your server can conclude a TLSv1.2 connection to Notch Pay's servers. Most up-to-date software have this capability. Contact your service provider for guidance if you have any SSL errors. Don't disable SSL peer verification!

1. Prepare your parameters

email, amount and currency are the most common compulsory parameters. Do send a unique email per customer. The amount accept numeric value value. The currency accept currency ISO 3166. For instance, to accept For US Dollar, please send USD as the currency.

2. Initialize a onetime payments

Initialize a payment by calling our API.

    $notchpay = new NotchPay\NotchPay(PUBLIC_KEY);
    try
    {
      $tranx = $notchpay->payment->initialize([
        'amount'=>$amount,       // according to currency format
        'email'=>$email,         // unique to customers
        'currency'=>$currency,         // currency iso code
        'callback'=>$callback,         // optional callback url
        'reference'=>$reference, // unique to transactions
      ]);
  } catch(\NotchPay\NotchPay\Exception\ApiException $e){
      print_r($e->getResponseObject());
      die($e->getMessage());
    }

    // store transaction reference so we can query in case user never comes back

    // redirect to page so User can pay
    header('Location: ' . $tranx->authorization_url);

When the user enters their payment details, NotchPay will validate and charge the card. It will do all the below:

Send a payment.complete event to your Webhook URL set at: https://business.notchpay.co/settings/developer

If receipts are not turned off, an HTML receipt will be sent to the customer's email.

Before you give value to the customer, please make a server-side call to our verification endpoint to confirm the status and properties of the payment.

3. Verify Transaction

After we redirect to your callback, please verify the transaction before giving value.

    $reference = isset($_GET['reference']) ? $_GET['reference'] : '';
    if(!$reference){
      die('No reference supplied');
    }

    // initiate the Library's NotchPay Object
    $notchpay = new NotchPay\NotchPay(PUBLIC_KEY);
    try
    {
      // verify using the library
      $tranx = $notchpay->payment->verify([
        'reference'=>$reference, // unique to transactions
      ]);
    } catch(\NotchPay\NotchPay\Exception\ApiException $e){
      print_r($e->getResponseObject());
      die($e->getMessage());
    }

    if ('complete' === $tranx->status) {
      // transaction was successful...
      // please check other things like whether you already gave value for this ref
      // if the email matches the customer who owns the product etc
      // Give value
    }

5. Closing Notes

Generally, to make an API request after constructing a notchpay object, Make a call to the resource/method thus: $notchpay->{resource}->{method}(); for gets, use $notchpay->{resource}(id) and to list resources: $notchpay->{resource}s().

Currently, we support: 'customer', 'payment'. To specify parameters, send as an array.

Check SAMPLES for more sample calls

Change log

Please see CHANGELOG for more information what has changed recently.

Contributing

Please see CONTRIBUTING and CONDUCT for details.

Security

If you discover any security related issues, please email hello@notchpay.co instead of using the issue tracker.

License

The MIT License (MIT). Please see License File for more information.

notchpay / php-sdk

Maintainers

Details