Skip to main content
Sign in

HAPI Payments Implementation Guide

  • Updated

The HAPI Payments API allows ATS users to pay directly to VONQ for their orders.

Introduction

Users are now able to utilize their Credit Card to fund a virtual wallet with VONQ and pay for their campaign orders from this Wallet balance.

The necessary endpoints to implement the feature provide you with a way to:

  • Create a Wallet, if it doesn't exist
  • Retrieve Wallet details, which include the Wallet balance in USD
  • Retrieve a billing portal link that you can display to your users, where they can fill in their billing Details (like email address, TAX ID)
  • Display a Top-Up interface, embeddable in your web pages via an iframe, that can be used to make the actual payments.

Glossary

Wallet

A virtual holder of funds, where a USD balance is kept, based on the various billing operations a user takes.

Billing Portal Link

A direct link to the billing provider's website, where Users can manage their billing details. It expires five minutes after being fetched. If a customer uses it within that time period, then the link expires within one hour of the most recent activity. Each billing portal link can last up to two hours before expiring.

Top-Up Iframe

An iframe displaying the necessary fields for charging a user's Credit Card with the user's specified amount. Note that the fields themselves (for instance Credit Card number), are not hosted on VONQ's domains and are provided by the Billing Provider. Credit Card details never pass through VONQ's systems.

Billing Provider

The third-party billing provider, which is used for the actual charging of Credit Cards or other payment methods.

Top-Up Iframe Event

A custom JavaScript object, JSON serialized, is sent by the Top-Up Iframe to the parent window, i.e., the ATS website, with details about different events happening within the iframe, like payment status updates or error updates.

Partner ID

The unique identifier of the ATS with VONQ.

User/Customer

Utilizer of the ATS software.

Customer ID

The unique identifier of the User in the ATS.

Data Flow

To implement the full flow, a user needs to be able to:

      1. Create a Wallet
      2. Update the billing details
      3. Top Up the Wallet balance
      4. Pay for a campaign from the Wallet balance.
    1.  

Step 1: Create a Wallet

First and foremost, a Wallet needs to be created with VONQ, by providing the Customer ID to the /wallet POST endpoint. There can be only one Wallet per customer. Save the Wallet ID for future requests.

Screen_Shot_2022-09-26_at_11.32.06_AM.png
{
"id": "03c9b80d-64b7-484d-82d3-bc44a835e693",
"balance": {
"USD": 0
},
"created_date": "2022-06-01T14:55:39+00:00",
"has_billing_details": false
}

Step 2: Show the user the billing portal link

After a wallet is created, retrieve the billing portal link and show it to the user. The Wallet details contain ahas_billing_detailsboolean variable that indicates whether the user has the billing details filled in.

Step 3: Retrieve the wallet details to check for billing detail status and balance

The user might have filled in or not the billing details, so you should force retrieval of the Wallet details from/wallet GET every time the user clicks on the Billing Portal Link. One can achieve that by showing a Top Up button, toggling between Top Up and Billing Portal Link:

  • On link click, show button, hide link
  • On button click, get wallet details, and maybe show link again.
Screen_Shot_2022-09-26_at_11.32.06_AM.png
{
"id": "03c9b80d-64b7-484d-82d3-bc44a835e693",
"balance": {
"USD": 0
},
"created_date": "2022-06-01T14:55:39+00:00",
"has_billing_details": true
}

Step 4: Show the Top-Up Iframe

Now that you are sure we have the wallet and the billing details, you can display the Top-Up Iframe, and listen for windowmessageevents on it. You can pass a default amount to be paid, which the User will be able to change once the iframe is loaded.

The iframe should have a minimum height of 600px and a recommended minimum width of 520px.

From this point, the User will attempt to top up their Wallet balance. Depending on the payment method and 3DS settings, when trying to finalize the payment, the user can either:

  • stay within the iframe through the whole credit card charging process or
  • be redirected to an intermediary page (for instance the bank's page) before completing the process; the providedreturnUrlGET parameter will be used as a final landing page in this case.
<iframe src="https://marketplace-sandbox.api.vonq.com/wallet/topup.html?walletId=18043531-0688-5e7e-8d87-7cb5018b7029&partnerId=a6edc906-2f9f-5fb2-a373-efac406f0ef2&amount=100000&returnUrl=https%3A%2F%2Fyourdomain.com%2Fcheckout&successCallbackUrl=https%3A%2F%2Fyourdomain.com%2Fhooks%2Fsuccess" frameborder="0" class="payment-iframe" allow="payment *"></iframe>

Step 6: Make sure you refresh the iframe for each payment attempt

Each iframe load handles one payment attempt. Notice how in our demo we remove the iframe from the page. If a new payment is needed, the iframe should be loaded again.

 

Step 7: Add the wallet information to the campaign order request body

If your partner account is enabled for wallet payments, include thewalletIdparameter in the Order Campaign request body.

Note that if you include thewalletIdand your account is not yet enabled for wallet payments, your campaign order requests will be rejected. Please contact VONQ partnerships team to enable this feature.

Demo

We've put together two video demos where you can see the whole process implemented, as seen by the User, both when the iframe requires parent window redirection and when the payment can be done inside the iframe: https://drive.google.com/drive/folders/10Bc_GInwMFtpwW8Avlb4RbKP2sZ2rnPK

 

Security and data considerations

The user's billing details always remain in the Billing Provider's control. For editing this information, the Billing Portal Linkis provided, and updates must be done from this portal. It is short-lived and generated in real time. The portal is not hosted or operated by VONQ.

All credit card detail elements are served by iframes operated by the Billing Provider and VONQ has no control over them.

Taxes and invoicing

Depending on the customer's location, taxes, if applicable, are automatically calculated by our billing provider and added to the final invoice. Read more here about the way the location is determined.

Examples:

  1. If the customer is from the Netherlands, VAT will be added to the invoice.
  2. If the customer is from an EU country other than the Netherlands, "reverse charge" is added to the invoice.
  3. If the customer is from the United States, the invoice won't contain taxes.

If taxes are added to the invoice, the top-up amount is inclusive of tax.