☰

API Reference

All API calls provided below, are accesible on HTTP Authentication basis, Scheme: Bearer.

The OviPay API is organized around REST. Has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

You can get your Public and Secret Keys in the Developers field on your OviPay Merchants Dashboard


Here you can Download our PHP Master.

Checkout Page

Custom Integration allows you to redirect your customer directly to the OviPay Checkout Page. It is a browser to browser call where on selecting OviPay option on the checkout page of your website the customer is redirected to the OviPay Checkout Page.

Checkout Page Integration Parameters

Name Description
amount
required
string		 The amount is always given as an integer number of cents, so if you’d like to run a purchase of $83.45, you’d pass an amount of 8345.
order_id
required
string		 Provide a merchant order id related to this transaction.
description
required
string		 Product description
email
required
string		 Customer Email
isTest
required
string		 Set isTest = 1 if you want to test your integration in Test Environment, Switch it to isTest = 0 to accept live payments.
Test cards:
In order to test your integration, you can use following credit cards numbers:
4111 1111 1111 1111 / 12/23 / 123 for a success transaction;
4000 0000 0000 9995 / 12/23 / 123 for a declined one, with insuficient_funds decline code.

Endpoint

POST https://secure.ovipay.net/api/checkout

Sample Request


require_once('path/to/ovipay-php-master/lib/autoload.php');

$gateway = new OviPay\Gateway([
    'publicKey' => 'Your Public Key',
    'privateKey' => 'Your Private Key', 
]);

$form = $gateway->paymentForm()->buildForm(
    [
      
        'amount' => '1000',
        'order_id' => '123',
        'description' => 'Order description',
        'email'=>'[email protected]',
        'isTest' => 1
    ],
    [
        'autoSubmit' => true,
        'hidePayButton' => true
    ]
);

echo $form;

Endpoint

POST https://secure.ovipay.net/api/checkout

Sample Request

from OviPay import Gateway
import random

if __name__ == "__main__":
    gateway = Gateway("<your private key>", "<your public key>", True)

    parameters = {
        "payload": {
            "description": "Golden Ticket",
            "amount": "0.01",
            "currency": "EUR",
            "merchant_order_id": random.randint(1000, 9999),
            "success_url": "https://example.com/success",
        },
        "auto_submit_form": True
    }

    paymentForm = gateway.payment_form().build_form(parameters)

    print paymentForm

Endpoint

POST https://secure.ovipay.net/api/checkout

Sample Request

public class TransactionServlet extends HttpServlet {

    private Gateway gateway = Gateway.builder()
        .publicApi("<your public key>")
        .privateApi("<your private key>")
        .build();

    @Override
    protected void doPost(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException {
        PrintWriter writer = resp.getWriter();

        Form form = gateway.paymentForm()
            .amount("5.00")
            .currency("USD")
            .description("Golden ticket")
            .merchantOrderId(UUID.randomUUID().toString())
            .sign_version(SignVersion.VERSION_2)
            .isAutoSubmit(true);

        writer.println("<html><body>");
        writer.println(form.build());
        writer.println("</body></html>");
    }
}

Endpoint

POST https://secure.ovipay.net/api/checkout

Sample Request

class MainActivity : AppCompatActivity() {

    val OviPay: OviPay by lazy {
        OviPay("<your public key>", true)
    }

    private fun requestPayment() {
        val form = gateWay.form()
            .amount("0.5")
            .currency("USD")
            .description("Golden Ticket")
            .merchantOrderId(UUID.randomUUID().toString())
            .successUrl("<your definition url>")

        startActivity(gateWay.prepareCheckout(this, form))
    }
}

Endpoint

POST https://secure.ovipay.net/api/checkout

Sample Request

curl https://secure.ovipay.net/api/checkout \
-d "api_token: [YOUR_PUBLIC_KEY]" \
-d "order_id=12345" \
-d "amount=999" \
-d "isTest=1" \
-d "[email protected]" \
-d "description=Order Description" \
-d "hash=<hash generated using the combination of amount post param and merchant private key>"

WebHooks

Pingback is a HTTP POST Request from OviPay to the Merchant’s Webhook URL. The Webhook contains parameters related to the Payment Transaction Details.


Following are the list of parameters received by the merchant in a Webhook.

Name Description
transaction.amount
double		 Transaction Amount.
transaction.status
string		 Transaction Status (succeeded / failed).
transaction.customer_id
int		 Customer ID related to this transaction in OviPay System.
transaction.transaction_id
string		 Transaction ID
transaction.method
string		 Payment Method (def: credit_card)
transaction.card_type
string		 Credit Card Type (Visa / Mastercard ...)
transaction.last_4
string		 Credit Card's last 4
transaction.card_year
int		 Credit Card's expire date (year)
transaction.card_month
int		 Credit Card's expire date (month)
transaction.type
string		 Transaction Type (def: Purchase)
transaction.currency
string		 Transaction Currency
transaction.order
string		 Transaction Order ID sent by merchant on checkout.
transaction.order_description
string		 Transaction Order Description sent by merchant on checkout.
transaction.ip_address
string		 IP address from which was made the transaction.
transaction.environment
string		 Environment on which was made the transaction ( Live / Test )
transaction.updated_at
string		 Transaction timestamp.
customer.email
string		 Customer's email sent by merchant on checkout.
customer.country
string		 Customers Country Code
customer.id
string		 Ovipay's Customer ID related to this transaction

Pingbacks should be validated by calculating signature on the merchant end and comparing it with header X-OviPay-Signature.

Example:


require_once('path/to/ovipay-php-master/lib/autoload.php');

$gateway = new OviPay\Gateway([
    'publicKey' => 'Your Public Key',
    'privateKey' => 'Your Private Key', 
]);

$pingbackData = null;
$validationParams = [];

        $validationParams = [
            'pingbackData' => file_get_contents('php://input'),
            'signature' => $_SERVER["HTTP_X_OVIPAY_SIGNATURE"]
        ];

       


if (!$gateway->pingback()->validate($validationParams)) {
    exit('Not Validated');
}

$pingbackData = json_decode(file_get_contents('php://input'), 1);

print_r($pingbackData);


#TODO: Write your code to deliver contents to the End-User.

echo "Validated";
exit();

Sample Pingback Data



{
  "customer": {
    "email": "[email protected]",
    "id": 11111,
    "country": "US"
  },
  "transaction": {
    "amount": 1000,
    "status": "succeeded",
    "transaction_id": "KEtY0Ud83a48oLXxN3Z1oAf0sDE",
    "method": "credit_card",
    "card_type": "visa",
    "last_4": "5656",
    "card_year": 2023,
    "card_month": 12,
    "type": "Purchase",
    "currency": "EUR",
    "order": "12345",
    "order_description": "Order description",
    "ip_address": "31.125.208.10",
    "environment": "live",
    "updated_at": "2020-06-02T18:59:03.000000Z"
  }
}

Example:

from flask import request
from OviPay.gateway import FP_Gateway

gateway = Gateway("<your private key>", "<your public key>", True)

if gateway.pingback().validate({"apiKey": request.headers.get("X-ApiKey")}) is True:
    print "OK"
else:
    print "NOK"

Sample Pingback Data

{
    "event": "payment",
    "payment_order": {
        "id": 13339,
        "merchant_order_id": "8245",
        "payment_system": 1,
        "status": "successful",
        "paid_amount": 0.01,
        "paid_currency": "EUR",
        "merchant_net_revenue": -0.2608,
        "merchant_rolling_reserve": 0.0005,
        "fees": 0.2703,
        "date": {
            "date": "2019-07-11 10:56:03.000000",
            "timezone_type": 3,
            "timezone": "UTC"
        }
    },
    "user": {
        "firstname": "John",
        "lastname": "Doe",
        "username": "",
        "country": "IN",
        "email": "[email protected]"
    },

Example:

const OviPay = require('OviPay-node');

let gateway = new OviPay.Gateway({
    publicKey: '<your public key>',
    privateKey: '<your private key>',
    isTest: 1 // Use 1 for Test Method
});

app.post("/pingback", (req, res) => {
    let html = 'NOK';
    if(gateway.Pingback().validate(req)){
        html = 'OK';
    }
    res.send(html);
});

Sample Pingback Data

{
    "event": "payment",
    "payment_order": {
        "id": 13339,
        "merchant_order_id": "8245",
        "payment_system": 1,
        "status": "successful",
        "paid_amount": 0.01,
        "paid_currency": "EUR",
        "merchant_net_revenue": -0.2608,
        "merchant_rolling_reserve": 0.0005,
        "fees": 0.2703,
        "date": {
            "date": "2019-07-11 10:56:03.000000",
            "timezone_type": 3,
            "timezone": "UTC"
        }
    },
    "user": {
        "firstname": "John",
        "lastname": "Doe",
        "username": "",
        "country": "IN",
        "email": "[email protected]"
    },
    "with_risk_check": false,
    "pingback_ts": 1562842637
}

Example:

import spark.Service;

public class PingBackRoute implements Routes {

    private PingBack pingBack = new PingBack("<your private key");

    @Override
    public void define(Service service) {
        this.service = service;
        definePingbackRoutes();
    }

    @POST
    public void definePingbackRoutes() {
        service.post(BASE_PATH, ((request, response) -> {
            boolean isValid = pingBack.validation()
                .signVersion(Optional.ofNullable(request.headers(PingBack.X_OviPay_SIGNATURE_VERSION)))
                .apiKey(Optional.ofNullable(request.headers(PingBack.X_API_KEY)))
                .signature(Optional.ofNullable(request.headers(PingBack.X_OviPay_SIGNATURE)))
                .pingBackData(Optional.of(request.body()))
                .execute();
            if (isValid) {
                //process further with pingBack
                response.status(HttpStatus.OK_200);
                return response;
            } else {
                //process with invalid pingBack
                throw halt(HttpStatus.NOT_IMPLEMENTED_501);
            }
        }));
    }
}

Sample Pingback Data

{
    "event": "payment",
    "payment_order": {
        "id": 13339,
        "merchant_order_id": "8245",
        "payment_system": 1,
        "status": "successful",
        "paid_amount": 0.01,
        "paid_currency": "EUR",
        "merchant_net_revenue": -0.2608,
        "merchant_rolling_reserve": 0.0005,
        "fees": 0.2703,
        "date": {
            "date": "2019-07-11 10:56:03.000000",
            "timezone_type": 3,
            "timezone": "UTC"
        }
    },
    "user": {
        "firstname": "John",
        "lastname": "Doe",
        "username": "[email protected]",
        "country": "IN",
        "email": "[email protected]"
    },
    "with_risk_check": false,
    "pingback_ts": 1562842637
}

WHMCS Plugin

If you are looking for a ready to deploy plugin for WHMCS you can download it from our library.


Click to download WHMCS Plugin.