Receiving Payments

Create Transaction

You can tailor your application to collect payments in diffenrent ways. Bekonta has provide you with an easy way to implement pay with crypto.

Html Form

You can collect payment by simply adding the form on your website page with the neccesary checkout parameters of the user.

Form Sample:

<form method="POST" action="https://cloud.bitpezapro.com/api/pay">
    <!-- Merchant Info -->
      <input type="hidden" name="merchant" value="" />
    <!-- Customer Info -->
       <input type="hidden" name="cust_name" value="">
    <!-- customers full name -->
       <input type="hidden" name="cust_email" value="">
       <input type="hidden" name="cust_phone" value="">
    <!-- customers phone number -->
    <!-- Transaction info -->
       <input type="hidden" name="order_ref" value="">
       <input type="hidden" name="item_name" value="" />

       <input type="hidden" name="amount" value="" />
   <!-- in Naira, no decimal, any decimal is rounded up -->

       <input type="hidden" name="amount_currency" value="NGN">
   <!-- this is the currency_id -->
      <input type="hidden" name="description" value="" />
    <!-- Fee info -->
       <input type="hidden" name="fee_taker" value="customer">
    <!-- customer or merchant -->
    <button type="submit" class="btn btn-success">Pay With Crypto - Bekonta</button>
</form>

Form POST Fields

All Data are to be sent via POST : https://cloud.bitpezapro.com/api/pay

REST APIs

Overview

Bekonta provides a standards-based REST interface which enables application developers to interact in a powerful, yet secure way with their Bekonta account. Using the Bekonta API, clients can create and manage invoices, view merchant ledger entries, and much more. Developers may call the API directly over HTTPS using the language of their choice.

Initiate Payment

To make an API request send an HTTP request with a HTTP method to a resource URI and include in the body JSON parameters of the following (plus any additional parameters needed):

POST: https://cloud.bitpezapro.com/api/pay

All data from the checkout should be sent to the POST URL above. developers can use any language to pass the data from the form to the url this will initiate the Bekonta payment module.

Making Requests

Requests to the Bekonta REST API follow a RESTful convention using standard HTTP verbs against various Bekonta resources to return JSON formatted responses.

Payment Verifiation

1. Verify Payment API Service URL: https://cloud.bitpezapro.com/payment/verify
2. Method: GET
3. Required Parameter: 'uuid' (Payment Gateway Reference)
4. Sample Request: https://cloud.bitpezapro.com/payment/verify?uuid=E96BC75FC594AB8

Payment Verification Response

Response format: JSON

Response Method: POST

Sample response payload with  status "Success" :

{
    "status": "Success",
    "payload": {
        "gateway_reference_uuid": "E96BC75FC594AB8",
        "payment_status": "Success",
        "merchant_uuid": "AD524EF97D270",
        "order_ref": "105e9de31945b5b",
        "payment_method": "Bitcoin",
        "coin_code": "BTC",
        "coin_price": "6829.17",
        "coin_amt": "0.00176249",
        "coin_amt_received": "0.00176249",
        "hash": "2ae50178a8d40c82abaf9c6cf6ce2adc07c1261cfd467e47767e9afddb005999",
        "item_name": "Social Media PPC Ads Beginner Course",
        "btc_amt": "0.00176249",
        "usd_amt": "10.55",
        "ngn_amt": "3830.0000",
        "charge_percentage": "70.0000",
        "charge_fixed": "100.0000",
        "fee_taker": "Merchant",
        "total": "4000.0000",
        "amount_currency": "NGN",
        "cust_name": "Customer Name",
        "cust_email": "[email protected]",
        "cust_phone": "08170543327",
        "created_at": "2020-04-20 18:00:54",
        "expire_at": "2020-04-20 18:20:54"
    }
}

Webhook & Callback URLs

What is a Webhook

A WebHook is an HTTP callback: an HTTP POST that occurs when something happens; a simple event-notification via HTTP POST. A web application implementing WebHooks will POST a message to a URL when certain things happen.

Bekonta sends webhooks events that notify your application any time a payment event happens in your account. This is very useful for events - like getting paid via mobile money or USSD where the transaction is completed outside your application- Recurring billing where an API call is not needed for subsequent billings.

In Bekonta you can setup webhooks that would let us notify you anytime events- A user on a subscription is charged, a customer completes a payment, we update a pending payment to successful- happen in your account.

When to use webhooks

Webhooks can be used for all kinds of payment methods, Crypto, card, account, USSD.

If you use Bekonta to accept alternate payment methods like Bitcoin, Ethereum, USSD, it is best practice to use webhooks so that your integration can be notified about changes the status of the payment once it is completed. This is because these payment methods are asynchronous and responses only come once the customer has completed the payment on their device.

You might also use webhooks to:

• Update a customer's membership record in your database when a subscription payment succeeds.

• Email a customer when a subscription payment fails.

• Update your database when the status of a pending payment is updated to successful.

NB: Not in all cases would you be able to rely completely on webhooks to get notified, an example is if your server is experiencing a downtime and your hook endpoints are affected, some customers might still be transacting independently of that and the hook call triggered would fail because your server was unreachable.

In such cases we advise that developers set up a re-query service that goes to poll for the transaction status at regular intervals e.g. every hour using the Verify Payment endpoint, till a successful or failed response is returned.

Sample Transaction Payload

On Bekonta , Webhooks can be configured for transactions. When a transaction is completed, a POST HTTP request is sent to the URL you have configured. The HTTP payload will contain

Hook Structure

The hook request structure is consistent across the board, but you can differentiate the event type using the event.type parameter returned. See the list of possible values for the parameter below:

Bitcoin Payments: Bitcoin_PAYMENT

Ethereum Payments: Ethereum_PAYMENT

USSD: USSD_TRANSACTION

Card Payments: CARD_TRANSACTION

Added URLs

1. callback_url
2. webhook_url

callback_url: Sets a URL to go to if the buyer does complete payment. (effective if you design your own checkout page, else you can leave it blank).

Webhook_url: URL to which Bekonta sends webhook notifications. HTTPS is mandatory.

Webhook & Callback Response

Sample of Webhook & Callback response payload:

{
    "status": "Success",
    "payload": {
        "gateway_reference_uuid": "E96BC75FC594AB8",
        "payment_status": "Success",
        "merchant_uuid": "AD524EF97D270",
        "order_ref": "105e9de31945b5b",
        "payment_method": "Bitcoin",
        "coin_code": "BTC",
        "coin_price": "6829.17",
        "coin_amt": "0.00176249",
        "coin_amt_received": "0.00176249",
        "hash": "2ae50178a8d40c82abaf9c6cf6ce2adc07c1261cfd467e47767e9afddb005999",
        "item_name": "Social Media PPC Ads Beginner Course",
        "btc_amt": "0.00176249",
        "usd_amt": "10.55",
        "ngn_amt": "3830.0000",
        "charge_percentage": "70.0000",
        "charge_fixed": "100.0000",
        "fee_taker": "Merchant",
        "total": "4000.0000",
        "amount_currency": "NGN",
        "cust_name": "Customer Name",
        "cust_email": "[email protected]",
        "cust_phone": "08170543327",
        "created_at": "2020-04-20 18:00:54",
        "expire_at": "2020-04-20 18:20:54"
    }
}

Receiving a webhook notification

Creating a webhook endpoint on your server is no different from creating any page on your website. With PHP, you might create a new .php file on your server; with a framework like Laravel, Flask, Sinatra, you would add a new route with the desired webhook URL.

Webhook data is sent as JSON by default.

Receiving webhooks with a CSRF-protected server

When using Rails, Django, Laravel, or any other web framework, your site might automatically check that every POST request contains a CSRF token. This is an important security feature that protects you and your users from cross-site request forgery.

However, this security measure might also prevent your site from processing webhooks sent by Bekonta. If so, you might need to exempt the webhooks route from CSRF protection.

Responding to a webhook request

To acknowledge receipt of a webhook, your endpoint should return a 200 HTTP status code. All response codes outside this range, including 3xx codes, will indicate to Bekonta that you did not receive the webhook. This does mean that a URL redirection or a "Not Modified" response will be treated as a failure. Bekonta will ignore any other information returned in the request headers or request body.

If your endpoint does not successfully receive a webhook for any reason, webhooks would not be retried, though you can query for the status using the Verify Payment endpoint to reconcile your data with any missed events.

Best practices

If your webhook script performs complex logic, or makes network calls, it's possible that the script would time out before Bekonta sees its complete execution. For that reason, you might want to have your webhook endpoint immediately acknowledge receipt by returning a 200 HTTP status code, and then perform the rest of its duties.

Webhook endpoints might occasionally receive the same event more than once. We advise you to guard against duplicated event receipts by making your event processing idempotent. One way of doing this is logging the events you've processed, and then checking if the status has changed before processing the identical event. Additionally, we recommend verifying webhook signatures to confirm that received events are being sent from Bekonta.