Unsupported browser

  • OhentPay has very limited support for old browsers, including Internet Explorer versions 9 and lower
  •  
  • To get the best out of our platform, please upgrade your web browser
  • cURL
  • PHP

Integrate with OhentPay

Getting started

We provide robust integration methods you can use to automate your mass payment needs. Our comprehensive API allows you to integrate and automate your payment processes into your business workflow and it's fully compatible with any business software

Most of the functionality that are available in the management dashboard is also available through the API, allowing you to automate every aspect of your business processes with us.

We aim to make our APIs as RESTful as possible without compromising on ease of use, security and extensibility.

API

To get started using our API, you need to generate an API Access key in your account. This will enable you to authenticate your requests to us

  • Our API base
  • All responses from us are JSON formatted

Webhooks

We can post webhook events that notify your application any time an event happens on your account. Merchants can create webhooks on their accounts and subscribe to various events. All webhook notifications are also signed with the signature key generated when the webhook was created. Webhook data is sent as JSON in the POST request body

Webhooks are also asynchronous, their order is not guaranteed, and idempotency might lead to a duplicate notification of the same event type. So you must not rely exclusively to sent webhooks for data reconciliation. You should rather, use the api. All data sent will contain a timestamp that can be used to match for event order. This means that you can check the timestamp against the last received update and discard it if it is older.

The event notification itself will also contain a timestamp of when the notification was sent. In case of delivery failure, this timestamp will be regenerated on every retry, including the signature.

Note: Only secure URLs are allowed, and SSL certificate must be valid. If you're testing on localhost, you can use ngrok to open access to the internet

Acknowledgement

On receipt of a webhook notification, you must respond with a HTTP status code of 2xx. All other response will indicate to us of a failure and the delivery will be retried. We will ignore any other information returned in the request header/body and only act on the HTTP status code

We will attempt to redeliver the message every hour on the hour for 24 hours, after that we'll discard the message permanently. We'll also include a retry count information in the request header X-OhentPay-Retry-Count

Best practices

After setting up your webhook, click the ping button to make sure it works. This will send an instant notification to the endpoint.

On receipt of a notification, you should queue the message in an internal storage and/or immediately acknowledge receipt before continuing processing. We have a 10 seconds timeout for a request to complete and we may further reduce this number in the future.

We advice on verifying the signature sent to make sure the message was truly sent by us.

Events

This is a list of all the events you can currently subscribe to. We will continue adding to this list as our platform expands and you can always request for more and we'll look into it.

Event Description
ping May be sent at any time to check if an endpoint is working
recipient.created A new recipient has been created
recipient.deleted A recipient has been deleted
recurring_payment.created A new recurring payment has been created
recurring_payment.deactivated A recurring payment has been deactivated
transaction.cancelled A transaction has been cancelled
transaction.failed A transaction failed
transaction.initiated A new transaction has been initiated
transaction.paid A transaction has been marked as paid
transaction.pending A transaction has been put on pending
transaction.processed A transaction has been processed
transaction.processing A transaction is being processed
transaction.refunded A transaction has been refunded

Example HTTP request

                            POST /webhook HTTP/1.1
Host: www.example.com
User-Agent: OhentPay (+https://www.ohentpay.com)
Content-Type: application/json
X-OhentPay-Event: ping
X-OhentPay-Signature: f045b9b4586be411b937f76ef940b6c99eeabc65e697f62f5314ba2ec58814b5623c036d681bf24c35e6e0f37f2087acf657ab356f6777988f039e600ad1f680
X-OhentPay-Retry-Count: 0
{
    "event": "ping",
    "created": 2019-03-17T01:25:56+00:00,
    "data": {
        "Message": "Hello World!",
        "created": 2019-03-17T01:25:54+00:00
    }
}
                        

Verifying webhook signature

We generate a Signature Key every time you create a new webhook, and all notifications sent to you will be signed. The signature HMAC is computed with the SHA512 hash algorithm. The computed signature will be passed through the request header X-OhentPay-Signature. The Signature Key, as all other keys, is secret and must only be shared with relevant authorised personnel.

                        define('OHENTPAY_WEBHOOK_SIGNATURE_KEY', 'SECRETKEY');

// Example JSON payload
$payload = file_get_contents('php://input');

// Compute the HMAC using the SHA-512 hash algorithm
$signature = hash_hmac('SHA512', $payload, OHENTPAY_WEBHOOK_SIGNATURE_KEY)

$headers = getallheaders();

// Verify signature
if($headers['X-OhentPay-Signature'] === $signature){
    http_response_code(200);
}