hiDocs

© 2015-2026. All rights reserved.

How to request a payment

Create a payment request

Send POST /payment-request with the appropriate parameters.

Properties secret_key and payment_page_id must be pre-configured by the hiqdev/Merchant team.

As a response, you'll get an URL where you can either redirect a user, embed it as an Iframe inside your application.

Work with the Iframe

In order to notify the POS of success payments, we use Cross-Window JS communication.

After embedding the Iframe, you can subscribe to the messages from it:

const frame_url = 'https://url.to.the.payment.page.retured.from.the.API/pay/#pr_naNzb914a'
window.addEventListener('message', (event) => {
	if (frame_url && frame_url.startsWith(event.origin)) { // Make sure event is not a fake
		const data = JSON.parse(event.data);
		if (data.isSuccess) {
		    alert('Success payment!');
		}
	}
});

You should also always check the Payment Request status to make sure the received message is real. See bellow.

Check the Payment Request status

Send GET /payment-request/:pr_id to get status and all the details.

Handling the Payment Confirmation Notification at the notify_url

As soon as the Customer pays a Payment Request, we will send a notification at the URL, you've passed during the Payment Request creation.

Sample request:

POST /merchantPayTransaction HTTP/1.1
Host: hiapi.blazingcdn.com
X-Notification-Id: pnot_GR8Oykh1EqM
Content-Type: application/x-www-form-urlencoded

payment_request_id=preq_z6XJVys8YYr&reference_id=z0xy7yqkt&transaction_id=txn_jY8m79iwjo&state=paid&external_transaction_id=ch_1HFHbcLb0dkY3ky52KC5IhKZ&payment_method=payment_card_token&payment_service=payment_card_token_eur_hpp&payment_provider=stripe&amount=199.00&currency=USD&pay_time=2020-08-12T10%3A54%3A53%2B00%3A00&payer=cus_HovQqlZAHML6ew&description=blazingcdn.com%3A+deposit+test123%40example.com+for+199.00USD&commission=0.00&signature=0932197ff7bcdf2a7103b538d00bf18afaca5e3668fe784f34859fde4ab9da0a

The body parameters are the following:

namedescription
payment_request_idThe Payment Request ID, as received after creation
reference_idID of the Payment Request in the POS database, as passed during Payment Request creation
transaction_idID of the Payment Transaction. May be stored at the POS side to identify the resulting transaction
stateMUST be paid
external_transaction_idID of the Payment Confirmation at the Service Provider side
payment_methodThe effective Payment Method name
payment_serviceThe effective Payment Service name
payment_providerThe effective Payment Provider code
amountHow much money have the user paid, as requested in the Payment Request
currencyThe currency of that amount, as requested in the Payment Request
pay_timeRFC8601 date time in UTC, when the payment actually happened
payerName, email, account number or any other information that identifies a Payer, provided by the Payment Provider with the confirmation
descriptionA payment description, as requested in the Payment Request
commissionAmount of money set by the merchant for the payment processing. May be used to compensate operational spending for a specific payment provider.
signatureA hash, that is calculated based on a secret_key to verify authority of this confirmation

Before accepting this Payment Confirmation Notification you MUST always verify the signature. You can use the following PHP code as an example:

function validate_signature(string $secret_key, array $notification): void
{
    $hash = hash('sha256', json_encode([
        $notification['payment_request_id'],
        $notification['transaction_id'],
        $notification['state'],
        $notification['amount'],
        $secret_key,
    ]));

    if (! hash_equals($notification['signature'], $hash)) {
        throw new Exception('Invalid signature');
    }
}