Get started

Main API URL : 
https://www.howtopay.com/api/v2/

HowToPay API provides an interface for businesses to connect with our system and automated the payment services by calling from their websites

To use this API, you'll required an API key and API Secret Key which you can obtain from Dashboard API Page.

What is new in API v2

With API V2, we made major changes for requests, responses and notifications.

  • API requests made more secure with signature validations
  • Improved end point for payment requests
  • Improved end point for check transaction status
  • Improved callback notifications
  • New notification url parameter to receive transaction changes
  • New API end points
    • Customer payout end point
    • Refund end point.
    • Single Transaction history end point
  • New direct payment links and sends in response to merchant
  • QR code for payment requests for wallet payments

Request Headers

HEADER PARAMETERS

Field Value Description
Content-Type application/json Request must be sent in JSON format
htp-apiversion HTPAPIv2 API Version Name
htp-authorization HTPAPIv2Auth [YOUR PUBLIC KEY]:[REQUEST SIGNATURE] Request Authorization Header
htp-timestamp UNIX TIMESTAMP Local server time in UNIX format

Content-Type must be application/json

htp-apiversion must to be HTPAPIv2

htp-authorization Signature of data array in the request

htp-timestamp must to be UNIX TIMESTAMP of your server time


Request Parameters

# PHP example for generate base64 encoded request
json_encode(array(
    "api_mode" => "live | demo",
    "parameter1" => base64_encode("value 1"),
    "parameter2" => base64_encode("value 2"),
    ...
));

With every request api_mode parameter must be send and every other parameter in the reques should be base64 encoded.

The request parameters must be in JSON format

Request Signature

# PHP example for generate request signature
$json_string = json_encode(array(
    'api_mode' => 'demo',
    'parameter1' => base64_encode("value 1"),
    'parameter2' => base64_encode("value 2")
    ...
));

//signature
$StringToSign = md5($json_string);

$signature = hash_hmac('sha256', $StringToSign, $_YOUR_PRIVATE_KEY);

echo $signature;

With every request HowToPay expect to receive a signature for data that is being sent in the request in the header parameter htp-authorization

The value of htp-authorization should as follows
HTPAPIv2Auth [YOUR PUBLIC KEY]:[REQUEST SIGNATURE]

Steps to Generate Request Signature

  • Generate JSON String with base64 encoded parameters. "api_mode" shouldn't be base64 encoded
  • Generate md5 hash from that JSON String
  • Generate keyed hash value of md5 string, using the HMAC method and using your private key

Response Signature

# Example for a response, sent back with signature
{
    "type": "success",
    "message": "Sample text message",
    "signature": "47533cbae75bf257cd14ccca50e7eb3038af79e64c3a7e1843eca15e7340e1c7",
    "api_version": "HTPAPIv2",
    "data": {
        "payment_id": "",
        "crn": "",
        "trn": "",
        "status": "",
        "amount_requested": "",
        "currency_requested": "",
        .....
    }
}

# PHP example to Validate Response Signature
$response = '{
    "type": "success",
    "message": "Sample text message",
    "signature": "47533cbae75bf257cd14ccca50e7eb3038af79e64c3a7e1843eca15e7340e1c7",
    "api_version": "HTPAPIv2",
    "data": {
        "payment_id": "",
        "crn": "",
        "trn": "",
        "status": "",
        "amount_requested": "",
        ...
    }
}';

//Get data element
$json_resonse = json_decode($response);
$data = $json_resonse->data;

$json_string = json_encode($data);

//signature
$StringToSign = md5($json_string);
$signature = hash_hmac('sha256', $StringToSign, $_YOUR_PRIVATE_KEY);

$response_signature = $json_resonse->signature;

if( $response_signature == $signature ) {
    echo TRUE;
}

For some results we sent back from end points such as "add payment requests", "transaction status/history check", etc we send a data signature back to business side so the business can validate the signature and make sure data are originated from HowToPay servers and untouched while it transmitted.

The signature HowToPay generates is always for the data parameter in the response

Steps to Validate Response Signature

  • Decode the JSON results we sent so you can access data parameter in the array
  • Encode the results in data parameter again with JSON encoding
  • Generate md5 hash from that JSON String
  • Generate keyed hash value of md5 string, using the HMAC method and using your private key
  • Compare the signature just generated with the signature we sent, if the both signatures matched then the data are correct and untouched

Add Payment Request

# PHP Example for Payment Request 

$json_string = json_encode(array(
    "api_mode" => "demo",
    "order" => array(
        "amount"=>base64_encode(""),
        "currency"=>base64_encode(""), //3 digit currency code
        "note"=>base64_encode(""),
        "merchant_reference_no"=>base64_encode("")
    ),
    "customer" => array(
        "first_name"=>base64_encode(""),
        "middle_name"=>base64_encode(""),
        "last_name"=>base64_encode(""),
        "email"=>base64_encode(""),
        "phone"=>base64_encode(""),
        "gender"=>base64_encode(""), // male | female 
        "dob"=>base64_encode(""), // YYYY-MM-DD format
        "lang"=>base64_encode(""),
        "ip_address"=>base64_encode("")
    ),
    "customer_address" => array(
        "address1" => base64_encode(""),
        "address2" => base64_encode(""),
        "city" => base64_encode(""),
        "state" => base64_encode(""),
        "postcode" => base64_encode(""),
        "country" => base64_encode("") //3 digit country code
    ),
    "customer_shipping_address" => array(
        "shipping_address1" => base64_encode(""),
        "shipping_address2" => base64_encode(""),
        "shipping_city" => base64_encode(""),
        "shipping_state" => base64_encode(""),
        "shipping_postcode" => base64_encode(""),
        "shipping_country" => base64_encode("")
    ),
    "callback_url" => base64_encode(""),
    "notification_url" => base64_encode("")
));

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://www.howtopay.com/api/v2/create/payment_request',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => $json_string,
  CURLOPT_HTTPHEADER => array(
    'cache-control: no-cache',
    'Content-Type: application/json',
    'htp-authorization: HTPAPIv2Auth XXXXX-XXXXX-XXXXX-XXXXX:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX',
    'htp-apiversion: HTPAPIv2',
    'htp-timestamp: 1505325876486',
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

# JSON Response for a successful payment request
{
    "type": "success",
    "signature": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "api_version": "HTPAPIv2",
    "message": "Request created successfully",
    "data": {
        "invoice_no": "XXXXXX-XXXXXXXXXX",
        "type": "gateway",
        "type_note": [
            "GATEWAY 1 NAME",
            "GATEWAY 2 NAME",
            "GATEWAY 3 NAME",
            "GATEWAY 4 NAME"
        ],
        "payment_link": "https://howtopay.com/id/XXXXXXXXXXXX",
        "direct_links": {
            "GATEWAY 4": "https://howtopay.com/id/XXXXXXXXXXXX"
        }
    }
}

END PIONT: /create/payment_request

When a customer placed an order in business website, it should call this API end point to create a payment request ( #invoice ) at HowToPay side and send the payment options to customer

QUERY HEADERS

Field Value Description
Content-Type application/json Request must be sent in JSON format
htp-apiversion HTPAPIv2 API Version Name
htp-authorization HTPAPIv2Auth [YOUR PUBLIC KEY]:[REQUEST SIGNATURE] Request Authorization Header
htp-timestamp UNIX TIMESTAMP Local server time in UNIX format

QUERY PARAMETERS

Field Type Description Required
api_mode String demo/live Yes
order Object
amount String Must encode with base64 Yes
currency String 3 digit country code. (base64 encoded) Yes
merchant_reference_no String Order ID in merchant system. (base64 encoded) No
note String Order Note (Maximum 100 Characters) (base64 encoded) Yes
customer Object Yes
first_name String Customer First name (base64 encoded) Yes
last_name String Customer Last name (base64 encoded) Yes
middle_name String Customer Middle name (base64 encoded) No
email String Customer Email (base64 encoded) Yes
phone String International format with +Country code (base64 encoded) Yes
gender String (Optional) male/female (base64 encoded) No
dob String (Required) YYYY-MM-DD format (base64 encoded) Yes
gender String (Optional) male/female (base64 encoded) No
lang String (Optional) 2 Digit Language code (base64 encoded) No
ip_address String (Optional) Customer IP Address (base64 encoded) No
customer_address Object Yes
address1 String Customer Address 1 (base64 encoded) Yes
address2 String Customer Address 2 (base64 encoded) No
city String Customer City (base64 encoded) Yes
state String Customer State (base64 encoded) Yes
postcode String Customer Zip/Postal code (base64 encoded) Yes
country String Customer country code - 3 Digit (base64 encoded) Yes
customer_shipping_address Object No
shipping_address1 String Customer Shpping address 1 (base64 encoded) No
shipping_address2 String Customer Shpping address 2 (base64 encoded) No
shipping_city String City (base64 encoded) No
shipping_state String State (base64 encoded) No
shipping_postcode String Zip/Postal code (base64 encoded) No
shipping_country String Country code - 3 Digit (base64 encoded) No
callback_url String URL to receive Paid notifications (base64 encoded) No
notification_url String URL to receive other notifications (base64 encoded) No

JSON RESPONSE PARAMETERS

Field Type Description
type String Returns request status (success/error)
signature String Returns the signature of "data" element in the request. Merchant should use this to validate request before insert to their database
api_version String HowToPay API version
message String Detailed message for success or error
data Object Details of the request (Data object)
invoice_no String HowToPay Payment ID of the request
type String (wallet/gateway) "wallet" returns for the requests that can be paid using wallet only. For other requests it returns "gateway"
type_note Array Payment options which user can used to pay this request
payment_link String Link to the payment page which has all options to fulfill the order
direct_links Array Direct links to the payment options ( if live methods included )

Get Eligible Gateways

# PHP Example for Eligible gateway check for an order

$json_string = json_encode(array(
    'api_mode' => 'demo',
    'currency' => base64_encode(''),
    'amount' => base64_encode(''),
    'country' => base64_encode(''),
    'email' => base64_encode(''),
));

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://www.howtopay.com/api/v2/get/eligible_gateways',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => $json_string,
  CURLOPT_HTTPHEADER => array(
    'cache-control: no-cache',
    'Content-Type: application/json',
    'htp-authorization: HTPAPIv2Auth XXXXX-XXXXX-XXXXX-XXXXX:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX',
    'htp-apiversion: HTPAPIv2',
    'htp-timestamp: 1505325876486',
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

# JSON Response for a successful eligible gateway check
{
    "type": "success",
    "message": "Eligible_Gateways",
    "signature": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "api_version": "HTPAPIv2",
    "data": {
        "gateways": [
            "GATEWAY 1 NAME",
            "GATEWAY 2 NAME",
            "GATEWAY 3 NAME",
            "GATEWAY 4 NAME"
        ]
    }
}

END PIONT: /get/eligible_gateways

This end point can used check if HowToPay can issue a payment request to the order based on the customers country and order currency, and show/hide HowToPay payment option in the checkout page appropriately.

QUERY HEADERS

Field Value Description
Content-Type application/json Request must be sent in JSON format
htp-apiversion HTPAPIv2 API Version Name
htp-authorization HTPAPIv2Auth [YOUR PUBLIC KEY]:[REQUEST SIGNATURE] Request Authorization Header
htp-timestamp UNIX TIMESTAMP Local server time in UNIX format

QUERY PARAMETERS

Field Type Description Required
api_mode String demo/live Yes
currency String 3 digit currency code (base64 encoded) Yes
amount String Order amount (base64 encoded) Yes
country String 3 digit country code (base64 encoded) Yes
email String Customer email address (base64 encoded) - If sent would validate against customer email too No

JSON RESPONSE PARAMETERS

Field Type Description
type String Returns request status (success/error)
signature String Returns the signature of "data" element in the request. Merchant should use this to validate request before insert to their database
api_version String HowToPay API version
message String Detailed message for success or error
data Object Details of the request (Data object)
gateways Array Gateways that can be included for the request ( based on customer country, order currency and customer email if sent )

Get Transaction Status

# PHP Example for Invoice / Transaction status check

$json_string = json_encode(array(
    'api_mode' => 'demo',
    'payment_id' => base64_encode(""),
    'trn' => base64_encode("")
));

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://www.howtopay.com/api/v2/get/transaction_status',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => $json_string,
  CURLOPT_HTTPHEADER => array(
    'cache-control: no-cache',
    'Content-Type: application/json',
    'htp-authorization: HTPAPIv2Auth XXXXX-XXXXX-XXXXX-XXXXX:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX',
    'htp-apiversion: HTPAPIv2',
    'htp-timestamp: 1505325876486',
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

# JSON Response for a successful transaction status check
{
    "type": "success",
    "message": "Newest transaction status for # XXXXXX-XXXXXXXXXX",
    "signature": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "api_version": "HTPAPIv2",
    "data": {
        "payment_id": "XXXXXX-XXXXXXXXXX",
        "crn": "XXXXXXXXXX",
        "trn": "XXXXXX-XXXXXX",
        "status": "Approved", // Approved | Refund | Chargeback | Chargeback_NR
        "amount_requested": "",
        "currency_requested": "XXX", // 3 digit currency code
        "amount_paid": "",
        "currency_paid": "XXX", // 3 digit currency code
        "updated_at": "2021-01-18 10:44:54",
        "note": "Transaction notes"
    }
}

END PIONT: /get/transaction_status

This end point returns the latest transaction details for a Payment Id or TRN number sent in the request. If a payment id received multiple transactions this end point returns the latest transaction only

QUERY HEADERS

Field Value Description
Content-Type application/json Request must be sent in JSON format
htp-apiversion HTPAPIv2 API Version Name
htp-authorization HTPAPIv2Auth [YOUR PUBLIC KEY]:[REQUEST SIGNATURE] Request Authorization Header
htp-timestamp UNIX TIMESTAMP Local server time in UNIX format

QUERY PARAMETERS

Field Type Description Required
api_mode String demo/live Yes
payment_id String Payment id which we sent in the response when created the payment request (base64 encoded) Yes
trn String TRN number in HowToPay system(base64 encoded) No

JSON RESPONSE PARAMETERS

Field Type Description
type String Returns request status (success/error)
signature String Returns the signature of "data" element in the request. Merchant should use this to validate request before insert to their database
api_version String HowToPay API version
message String Detailed message for success or error
data Object Details of the request (Data object)
payment_id String Payment Id of the request
crn String Order reference number for customer
trn String Unique transaction id in HowToPay system
status String Approved | Refund | Chargeback | Chargeback_NR ( Chargeback but not refunded to customer)
amount_requested String Original amount requested
currency_requested String Original currency requested
amount_paid String Customer paid amount
currency_paid String Customer paid currency
updated_at String Last status changed time of transaction
note String Transaction Notes

Get Transaction History

# PHP Example for Invoice / Transaction status check

$json_string = json_encode(array(
    'api_mode' => 'demo',
    'payment_id' => base64_encode("")
));

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://www.howtopay.com/api/v2/get/transaction_history',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => $json_string,
  CURLOPT_HTTPHEADER => array(
    'cache-control: no-cache',
    'Content-Type: application/json',
    'htp-authorization: HTPAPIv2Auth XXXXX-XXXXX-XXXXX-XXXXX:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX',
    'htp-apiversion: HTPAPIv2',
    'htp-timestamp: 1505325876486',
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

# JSON Response for a successful transaction status check
{
    "type": "success",
    "message": "Newest transaction status for # XXXXXX-XXXXXXXXXX",
    "signature": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "api_version": "HTPAPIv2",
    "data": [
        {
            "crn": "XXXXXXXXXX",
            "trn": "XXXXXXXXXXXXXXXXXXXXXXX-XXXXXXXXXX",
            "status": "Approved",
            "amount_requested": "51.20",
            "currency_requested": "USD",
            "amount_paid": "51.20",
            "currency_paid": "USD",
            "updated_at": "2020-09-03 14:26:45"
        },
        {
            "crn": "XXXXXXXXXX",
            "trn": "XXXXXXXXXXXXXXXXXXXXXXX-XXXXXXXXXX",
            "status": "Refund",
            "amount_requested": "51.20",
            "currency_requested": "USD",
            "amount_paid": "-51.20",
            "currency_paid": "USD",
            "updated_at": "2020-10-12 11:19:30"
        }
    ]
}

END PIONT: /get/transaction_history

This end point returns the all the transaction details for the Payment ID sent in the request. If the payment id received multiple transactions this end point returns all the transactions as sub arrays in data array

QUERY HEADERS

Field Value Description
Content-Type application/json Request must be sent in JSON format
htp-apiversion HTPAPIv2 API Version Name
htp-authorization HTPAPIv2Auth [YOUR PUBLIC KEY]:[REQUEST SIGNATURE] Request Authorization Header
htp-timestamp UNIX TIMESTAMP Local server time in UNIX format

QUERY PARAMETERS

Field Type Description Required
api_mode String demo/live Yes
payment_id String Payment id which we sent in the response when created the payment request (base64 encoded) Yes

JSON RESPONSE PARAMETERS

Field Type Description
type String Returns request status (success/error)
signature String Returns the signature of "data" element in the request. Merchant should use this to validate request before insert to their database
api_version String HowToPay API version
message String Detailed message for success or error
data Object Data object contain an array with all transactions received for the payment id
crn String Order reference number for customer
trn String Unique transaction id in HowToPay system
status String Approved | Refund | Chargeback | Chargeback_NR ( Chargeback but not refunded to customer)
amount_requested String Original amount requested
currency_requested String Original currency requested
amount_paid String Customer paid amount
currency_paid String Customer paid currency
updated_at String Last status changed time of transaction

Add Customer Payout

# PHP Example for Create customer payout

$_YOUR_API_KEY = ""; 
$_YOUR_PRIVATE_KEY = ""; 

$json_string = json_encode(array(
    "api_mode" => "live",
    "account_no" => base64_encode(''),
    "reference_no" => base64_encode(''),
    "amount" => base64_encode(''),
    "currency" => base64_encode(''),
    "payout_to" => base64_encode(''),
    "customer" => array(
        "email" => base64_encode(''),
        "phone" => base64_encode(''),
        "account_no" => base64_encode(''),
        "bank" => array(
            "bank_name" => base64_encode(''),
            "bank_country" => base64_encode(''),
            "bank_acc_name" => base64_encode(''),
            "bank_iban" => base64_encode(''),
            "bank_acc_number" => base64_encode(''),
            "bank_swift_bic" => base64_encode(''),
            "bank_currency" => base64_encode('')
        )
    ),
    "remark" => base64_encode(''),
    "notification_url" => base64_encode('')
));

//signature
$StringToSign = md5($json_string);

$signature = hash_hmac('sha256', $StringToSign, $_YOUR_PRIVATE_KEY);

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://www.howtopay.com/api/v2/create/payout',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => $json_string,
  CURLOPT_HTTPHEADER => array(
    'cache-control: no-cache',
    'Content-Type: application/json',
    'htp-authorization: HTPAPIv2Auth '.$_YOUR_API_KEY.':'.$signature,
    'htp-apiversion: HTPAPIv2',
    'htp-timestamp: '.strtotime("now"),
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

# Immediate JSON Response for a successful customer payout
{
    "type": "success",
    "message": "Payout created successfully",
    "signature": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "api_version": "HTPAPIv2",
    "data": []
}

# JSON Response after successful customer payout payment
{
  "type": "payout",
  "signature": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "api_version": "HTPAPIv2",
  "data": {
    "trn": "XXXXXXXXXXX-XXXXXXXXXXXXXXXXX",
    "yrn": "",
    "status": "Paid | Canceled | Rejected",
    "amount_requested": "",
    "currency_requested": "",
    "amount_paid": "",
    "currency_paid": "",
    "updated_at": "YYYY-MM-DD HH:MM:SS"
  }
}

END PIONT: /create/payout

This end point enables businesses to directly pay their customer payouts requesting either pay to customer HowToPay wallet or to customer bank account as a wire transfer

The appropriate fees and the payout amount will be deducted from the merchant's account balance

QUERY HEADERS

Field Value Description
Content-Type application/json Request must be sent in JSON format
htp-apiversion HTPAPIv2 API Version Name
htp-authorization HTPAPIv2Auth [YOUR PUBLIC KEY]:[REQUEST SIGNATURE] Request Authorization Header
htp-timestamp UNIX TIMESTAMP Local server time in UNIX format

QUERY PARAMETERS

Field Type Description Required
api_mode String demo/live Yes
account_no String Merchant HowToPay Account Number to deduct payment (base64 encoded) Yes
reference_no String Merchant reference Number (base64 encoded) No
amount String Payout Amount (base64 encoded) Yes
currency String Payout Currency (base64 encoded) Yes
payout_to String (wallet/swift) To customer HowToPay wallet account or Bank Account (base64 encoded) Yes
customer Object Yes
email String Customer Email Address (base64 encoded) Yes
phone String Customer Phone Number (base64 encoded) Yes
account_no String Customer Account Number (If not provided and the payout type is "wallet", the payout will credit to customer main wallet account) (base64 encoded) No
bank Object (Not required if payout type is wallet) No
bank_name String Customer Bank Name (base64 encoded) No
bank_country String Customer Bank Country (base64 encoded) No
bank_acc_name String Customer Bank Account Name (base64 encoded) No
bank_iban String Customer IBAN Number ( if applicable ) (base64 encoded)
bank_acc_number String Customer Bank Account Number (base64 encoded)
bank_swift_bic String Customer Bank SWIFT Code (base64 encoded) No
bank_currency String Customer Bank Account currency (base64 encoded) No
remark String Payout notes (base64 encoded) Yes
notification_url String We will notify the business to this URL when payout is processed (base64 encoded) No

IMMEDIATE JSON RESPONSE PARAMETERS

Field Type Description
type String Returns request status (success/error)
message String Detailed message for success or error
signature String Returns the signature of "data" element in the request.
api_version String HowToPay API version

NOTIFICATION JSON RESPONSE PARAMETERS

Field Type Description
type String Returns notification type (payout)
signature String Returns the signature of "data" element in the request. Merchant should use this to validate request before insert to their database
api_version String HowToPay API version
message String Detailed message for success or error
data Object Data object contain an array with details of the payout
trn String Unique transaction id in HowToPay system
yrn String Merchant reference number sent in the request
status String Paid | Canceled | Rejected
amount_requested String Original amount requested to payout
currency_requested String Original currency requested to payout
amount_paid String Paid amount to customer
currency_paid String Paid currency to customer
updated_at String Last status changed time of transaction

Add Customer Refund

# PHP Example for Create customer refund

$_YOUR_API_KEY = ""; 
$_YOUR_PRIVATE_KEY = ""; 

$json_string = json_encode(array(
        "api_mode" => "live",
        "crn" => base64_encode(''),
        "trn" => base64_encode(''),
        "reference_no" => base64_encode(''),
        "refund_type" => base64_encode(''), //"full/partial"  
        "refund_amount" => base64_encode(''),
        "refund_to" => base64_encode(''), //wallet /swift
        "customer" => array(
            "account_no" => base64_encode(''), //customer acc no ( optional )
            "bank" => array(
                "bank_name" => base64_encode(''),
                "bank_country" => base64_encode(''),
                "bank_acc_name" => base64_encode(''),
                "bank_iban" => base64_encode(''),
                "bank_acc_number" => base64_encode(''),
                "bank_swift_bic" => base64_encode(''),
                "bank_currency" => base64_encode('')
            )
        ),
        "remark" => base64_encode(''),
        "notification_url" => base64_encode('')
    ));

//signature
$StringToSign = md5($json_string);

$signature = hash_hmac('sha256', $StringToSign, $_YOUR_PRIVATE_KEY);

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://www.howtopay.com/api/v2/create/refund',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => $json_string,
  CURLOPT_HTTPHEADER => array(
    'cache-control: no-cache',
    'Content-Type: application/json',
    'htp-authorization: HTPAPIv2Auth '.$_YOUR_API_KEY.':'.$signature,
    'htp-apiversion: HTPAPIv2',
    'htp-timestamp: '.strtotime("now"),
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

# Immediate JSON Response for a successful customer refund
{
    "type": "success",
    "message": "Refund request created successfully",
    "signature": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "api_version": "HTPAPIv2",
    "data": []
}

# JSON Response after successful customer refund payment
{
  "type": "refund",
  "signature": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "api_version": "HTPAPIv2",
  "data": {
    "payment_id": "XXXXX-XXXXXXXXXX",
    "crn": "XXXXXXXXXX",
    "trn": "XXXXXXXX-XXXXXXXXXXXXXXX",
    "yrn": "",
    "status": "Paid | Canceled | Rejected",
    "amount_requested": "",
    "currency_requested": "",
    "amount_paid": "",
    "currency_paid": "",
    "updated_at": "YYYY-MM-DD HH:MM:SS"
  }
}

END PIONT: /create/refund

This end point enables businesses to directly pay their customer payouts requesting either pay to customer HowToPay wallet or to customer bank account as a wire transfer

The appropriate fees and the payout amount will be deducted from the merchant's account balance

QUERY HEADERS

Field Value Description
Content-Type application/json Request must be sent in JSON format
htp-apiversion HTPAPIv2 API Version Name
htp-authorization HTPAPIv2Auth [YOUR PUBLIC KEY]:[REQUEST SIGNATURE] Request Authorization Header
htp-timestamp UNIX TIMESTAMP Local server time in UNIX format

QUERY PARAMETERS

Field Type Description Required
api_mode String demo/live Yes
crn String CRN number that required to be refunded (base64 encoded) Yes
trn String Transaction ID in howtopay system to be refunded (base64 encoded) Yes
reference_no String Merchant Reference Number for refund (base64 encoded) No
refund_type String "full" or "partial" refund (base64 encoded) Yes
refund_amount String This is required if the return type is "partial" (base64 encoded) No
refund_to String (wallet/swift) Refund to customer HowToPay wallet account or Bank Account (base64 encoded) Yes
customer Object Yes
account_no String If refund type is "wallet" and account number defined, we will refund to this account number. Otherwise refunds will process to main wallet account (base64 encoded) No
bank Object (Not required if refund type is wallet) No
bank_name String Customer Bank Name (base64 encoded) No
bank_country String Customer Bank Country No
bank_acc_name String Customer Bank Account Name (base64 encoded) No
bank_iban String Customer IBAN Number ( if applicable ) (base64 encoded) No
bank_acc_number String Customer Bank Account Number (base64 encoded) No
bank_swift_bic String Customer Bank SWIFT Code (base64 encoded) No
bank_currency String Customer Bank Account currency (base64 encoded) No
remark String Refund notes (base64 encoded) No
notification_url String We will notify the business to this URL when refund is processed (base64 encoded) No

IMMEDIATE JSON RESPONSE PARAMETERS

Field Type Description
type String Returns request status (success/error)
message String Detailed message for success or error
signature String Returns the signature of "data" element in the request. Merchant should use this to validate the response before insert to their database
api_version String HowToPay API version

NOTIFICATION JSON RESPONSE PARAMETERS

Field Type Description
type String Returns request status (success/error)
signature String Returns the signature of "data" element in the request. Merchant should use this to validate request before insert to their database
api_version String HowToPay API version
message String Detailed message for success or error
data Object Data object contain an array with all transactions received for the payment id
crn String Order reference number for customer
trn String Unique transaction id in HowToPay system
status String Approved | Refund | Chargeback | Chargeback_NR ( Chargeback but not refunded to customer)
amount_requested String Original amount requested
currency_requested String Original currency requested
amount_paid String Customer paid amount
currency_paid String Customer paid currency
updated_at String Last status changed time of transaction

In our IPN and Other notifications we are sending Paid Amount and Paid Currency which should always use by the businesses to update their systems. Requested Amount and Requested Currency are original values from the payment request which should use for reference purpose only.

Transaction CRN / TRN

CRN (Customer Reference Number) in HowToPay system is the unique invoice number for each payment request we issued to customer. When customer paid for an order should use this CRN number to identify the order that they are paying. A CRN number can be paid multiple times (Even though we are not recommended) and can have multiple transactions for a single transaction due to this reason.

TRN (Transaction Reference Number) is unique transaction id in howtopay system and never duplicates and should use by business to uniquely identify a transaction in our system.

Over and Under Payments

# Example JSON callback for over payment
{
  "type": "success",
  "signature": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "api_version": "HTPAPIv2",
  "data": {
    "payment_id": "XXXXXX-7010123456",
    "invoice_no": "7010123456",
    "trn": "54321-9876543210",
    "status": "Paid",
    "amount_requested": "200.00",
    "amount_paid": "300.00",
    "currency_requested": "AUD",
    "currency_paid": "AUD",
    "yrn": "",
    "payment_method": "",
    "note": ""
  }
}

# Example JSON callback for under payment
{
  "type": "success",
  "signature": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "api_version": "HTPAPIv2",
  "data": {
    "payment_id": "XXXXXX-7010123456",
    "invoice_no": "7010123456",
    "trn": "54321-9876543210",
    "status": "Paid",
    "amount_requested": "200.00",
    "amount_paid": "100.00",
    "currency_requested": "AUD",
    "currency_paid": "AUD",
    "yrn": "",
    "payment_method": "",
    "note": ""
  }
}

As we aware payment requests doesn't always received the exact amount which is requested in original payment request. Due to this in HowToPay callbacks we have Paid Currency and Paid Amount parameters which merchant should use for update their systems as described in Paid Amount / Currency section.

We expect merchant system correctly identify the amount and currency that is paid and update their systems with correct amount and provide services / goods for the customers accordingly.

Handling IPN Notification

# Example JSON callback for a successful payment
{
  "type": "success",
  "signature": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "api_version": "HTPAPIv2",
  "data": {
    "payment_id": "XXXXXX-7010123456",
    "invoice_no": "7010123456",
    "trn": "12345-0123456789",
    "status": "Paid",
    "amount_requested": "200.00",
    "amount_paid": "",
    "currency_requested": "AUD",
    "currency_paid": "",
    "yrn": "",
    "payment_method": "",
    "note": ""
  }
}

When a payment id is paid in our system we triggers an IPN notifications to business side, using the callback url defined in payment request. If the callback url is not sent in payment request we will use the default callback url in business API settings

JSON RESPONSE PARAMETERS

Field Type Description Required
api_mode String demo/live Yes
account_no String Merchant HowToPay Account Number to deduct payment (base64 encoded) Yes
reference_no String Merchant reference Number (base64 encoded) No
amount String Payout Amount (base64 encoded) Yes
currency String Payout Currency (base64 encoded) Yes
payout_to String (wallet/swift) To customer HowToPay wallet account or Bank Account (base64 encoded) Yes
customer Object Yes
email String Customer Email Address Yes
phone String Customer Phone Number Yes
account_no String Customer Account Number (If not provided and the payout type is "wallet", the payout will be credit to customer main wallet account) No
bank Object (Not required if payout type is wallet) No
bank_name String Customer Bank Name No
bank_country String Customer Bank Country No
bank_acc_name String Customer Bank Account Name No
bank_iban String Customer IBAN Number ( if applicable ) No
bank_acc_number String Customer Bank Account Number No
bank_swift_bic String Customer Bank SWIFT Code No
bank_currency String Customer Bank Account currency No
remark String Payout notes No
notification_url String We will notify the business to this URL when payout is processed No

IPN Signature Validation

With our IPN (callback) notification, we send data signature so business can validate the IPN notification is orignated from HowToPay servers and untouched while transmitted

Validation of IPN signature is same as validation of signature in any other request and should follow the same steps mentioned in Response Signature section

Duplicate Payment Identification

# Example JSON callback for a first payment
{
  "type": "success",
  "signature": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "api_version": "HTPAPIv2",
  "data": {
    "payment_id": "XXXXXX-7010123456",
    "invoice_no": "7010123456",
    "trn": "54321-9876543210",
    "status": "Paid",
    "amount_requested": "200.00",
    "amount_paid": "",
    "currency_requested": "AUD",
    "currency_paid": "",
    "yrn": "",
    "payment_method": "",
    "note": ""
  }
}

# Example JSON callback for a second payment (duplicate)
{
  "type": "success",
  "signature": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "api_version": "HTPAPIv2",
  "data": {
    "payment_id": "XXXXXX-7010123456",
    "invoice_no": "7010123456",
    "trn": "12345-0123456789",
    "status": "Paid",
    "amount_requested": "200.00",
    "amount_paid": "",
    "currency_requested": "AUD",
    "currency_paid": "",
    "yrn": "",
    "payment_method": "",
    "note": ""
  }
}

In HowToPay system a payment request can receive multiple transactions. So it is required by merchants to correctly identify duplicate transactions and update the merchant system accordingly.

To identify duplicate payments business need to use both the TRN and CRN in callback notifications. If business website receiving a second callback notification for a CRN number that is received a notification before, the second notification could be for a possible duplicate transaction.

Steps to identify multi payments for a Payment Id

  • Check the CRN number in merchant database and see if it received a transaction before
  • If CRN number has a payment, then compare the TRN number in the previous payment with the TRN in new Payment Notification
  • If the TRN numbers in the previous transaction and the notification are same business should ignore the notification
  • If the TRN numbers in the previous transaction and the notification are different business should treat the second transaction as a duplicate transaction for the same CRN

As in the example for callback notifications, for duplicate transactions the "crn" parameter is same for both callback notifications. However the transaction reference number ( TRN ) is unique for each transaction and is different in each callback.

Also callback notification paid amount can be same or different in each response.

Gateway supported currencies

As HowToPay provides multiple payment methods for merchants not all gateways support for all currencies. Thus you need to make sure to send the payment requests in gateway supported currencies that are activated in your profile.

Example:
iDeal only support for EURO currency. Thus if you need to include iDeal as an payment option for a customer the currency of payment request should be EUR currency.

Payment request currency conversion

If you send a different currency other than the payment methods local currency HowToPay will try to convert the original amount and send the request in gateway local currency using conversation rates at the time of payment request create.

Gateway supported Countries

Some payment methods we provide are local methods which are specific for each country. Thus we don't support customers outside from that country to use local payment options. Due to this you need to make sure to send the payment request's country parameter and must supported by the activated gateways in business profile in order to send local methods as an option for your customers..

Example:
iDeal is a payment method for Netherlands customer. If you need to send iDeal as an option for a customer, payment request's country parameter should be "NLD" (Netherlands)

Integration Testing and Go Live

Upon complete the integration HowToPay team would conduct series of tests to identify each following cases are implemented correctly and verify that merchant's system correctly acknowledge and update customer accounts according to notifications send by HowToPay.

Checklist:

  • Successfully acknowledgedthe callbacks sent from HowToPay and update merchant system
  • Acknowledged HowToPay notifications in real time( more than 5min delaynot acceptable )
  • Correctly identified and used the Paid amountand Paid currencyparameters
  • Correctly identified the duplicate paymentsand update merchant system accordingly
  • Correctly identified over paymentsand update the merchant system with correct amount
  • Correctly identified under paymentsand update the merchant system with correct amount

Wordpress / Woocommerce Plugin

HowToPay WordPress plugin required Woocommerce installed in the system and it works same as any Woocommerce payment plugin. The settings of HowToPay payment plugin can managed from Woocommerce > Settings > Payments Tab.
Download HowToPay WP Plugin - v3.0.9