API Guide

EthPay API lets you integrate EthPay with your website, web application or any other application at the code level. To start a payment request and send your customer to the EthPay Payment Gateway to complete the payment, it provides a straightforward HTML Form-based POST API. When a payment is accepted, a server callback with a checksum to validate the response parameters notifies the specified URL (notify_url) of the payment status. Based on the payment status, you can update and verify your system using those response parameters & checksum.

*You need your EthPay Client ID & Client Secret to integrate with API. To enable API access, visit the homepage.

1. Inputs - POST Send

Redirecting Client to EthPay Payment Gateway

You can easily use an HTML Form to submit the below POST parameters to EthPay Payment Gateway, regardless of your scripting language. When you submit the form, your client will be securely redirected to the EthPay Payment Gateway.

Action URL: https://ethpay-server.herokuapp.com/api/v1/pay

Required POST Parameters:

client_id - EthPay Client ID
return_url - URL to redirect users when success
cancel_url - URL to redirect users when cancelled
notify_url - URL to callback the status of the payment (Needs to be a URL accessible on a public IP/domain)
currency - ETH (We currently only support ETH payments)
amount - Total Payment Amount

Code Sample

<html>
<body>
<form method="post" action="https://ethpay-server.herokuapp.com/api/v1/pay">   
    <input type="hidden" name="client_id" value="YOUR_CLIENT_ID">
    <input type="hidden" name="return_url" value="https://sample.com/return">
    <input type="hidden" name="cancel_url" value="https://sample.com/cancel">
    <input type="hidden" name="notify_url" value="https://sample.com/notify">  
    <input type="text" name="currency" value="ETH">
    <input type="text" name="amount" value="0.02">  
    <input type="submit" value="Buy Now">   
</form> 
</body>
</html>

2. Outputs - POST Retrieve

Listening to Payment Notification

As soon as the payment is processed, EthPay sends the payment status to the notify URL you specified in the API as a server callback and redirects the customer to the return URL on your website. The payment notification will include the following data as POST parameters, so you must host a script on your notify URL to retrieve and update your database accordingly.

Output POST Parameters:

transaction_id - EthPay Transaction ID
tx_hash - Transaction hash (Txn hash)
from_wallet - Transaction from wallet address
to_wallet - Transaction to (your) wallet address
currency - ETH (We currently only support ETH payments)
amount - Total Payment Amount
block_number - Transaction mined block
sha256sig - Encrypted signature to verify the payment

The request parameters are encoded in the application/x-www-form-urlencoded format. (not ~~application/json~~)
The payment notification cannot be tested on localhost. For EthPay to directly notify your server, you must submit a publicly accessible IP or domain-based URL as your notify url.
When redirecting the customer back to your website, no payment status parameters are passed to the return url. You must update your database after your script retrieves the payment status on notify url and then show the payment status to your customer in the page on return url by retrieving the status from your database.

3. Verify

Verifying the Payment Status

Before acting on the payment response, it is critical to verify the Payment Notification. You can perform the verification using the sha256sig checksum parameter generated and sent by EthPay along with the payment notification as shown below.

Node.js

const sha256sig = 
crypto.createHash('sha256').update(
   txHash + crypto.createHash('sha256').update(
       secret
   ).digest('hex')
).digest('hex').toString().toUpperCase();

PHP

$sha256sig = strtoupper(
    hash('sha256', (
        $tx_hash .
        hash('sha256', 'Vf2yyEAj6PBXQ7IhO1VTWPd5039px9t1E0vVx6') // hex
    ))
);

Once you have received the payment status parameters from EthPay, you can generate this checksum locally using the client_id, wallet and transaction_hash sent by the payment notification, as well as the client_secret you have on hand. If the payment notification is valid, your locally generated checksum should match the sha256sig sent by EthPay.

You can host below script at your notify_url

Code Sample (Node.js + Express.js)

const crypto = require('crypto');

router.route('notify_url').get((req, res, next) => {
    const transaction_id = req.body.transaction_id;
    const tx_hash = req.body.tx_hash;
    const from_wallet = req.body.from_wallet;
    const to_wallet = req.body.to_wallet;
    const currency = req.body.currency;
    const amount = req.body.amount;
    const blockNumber = req.body.blockNumber;
    const sha256sig = req.body.sha256sig;

    const local_sha256sig = crypto.createHash('sha256').update(
       tx_hash + crypto.createHash('sha256').update(
           secret
       ).digest('hex')
    ).digest('hex').toString().toUpperCase();

    if (local_sha256sig.toString() === local_sha256sig.toString()) {
        // Update your database as payment success
    }
});

Code Sample (PHP)

<?php
$transaction_id = $_POST['transaction_id'];
$tx_hash = $_POST['tx_hash'];
$from_wallet = $_POST['from_wallet'];
$to_wallet = $_POST['to_wallet'];
$currency = $_POST['currency'];
$amount = $_POST['amount'];
$blockNumber = $_POST['blockNumber'];
$sha256sig = $_POST['sha256sig'];

$local_sha256sig = strtoupper(
    hash('sha256', (
        $tx_hash .
        hash('sha256', 'Vf2yyEAj6PBXQ7IhO1VTWPd5039px9t1E0vVx6') // hex
    ))
);
if ($local_sha256sig == $sha256sig) {
        //TODO: Update your database as payment success
}
?>