Integration Types

What is an integration?

The type of integration refers to the option chosen to integrate our service to your site. Depending on the level of customisation and the level of complexity your business is looking for, you may choose between our code-free solutions or the different API calls we have available.

📘

Every transaction and payout created in our system follows the same flow, regardless of the integration type used. If you want to know more about transaction and payout flow, please navigate to the Transaction Flow Overview and Payout Flow Overview pages.

Coded solutions

There are two main categories of coded solution: you may integrate our service to your website and communicate directly with our servers, or you can integrate us through a gateway that would act as intermediate for any API call.

In both cases you have the choice between three integration types:

• Paywall Integration: The fastest and easiest way to integrate our payment solution;
• Hosted Payment Pages : This solution gives you full control over the payment method selection page.
• Direct API: This solution allows you complete customization of the user experience, from the payment selection to the checkout page.

📘

You can use different types of integration on the same page. For example: hardcoding a PIX button to highlight this payment method, and use the GET Payment Methods call to display a list of other payment methods available. We refer to these as "mixed integrations".

Those three types of integration imply a redirection to the payment method's checkout page to complete the payment after the creation of the transaction.

Checkout Customisation : Direct API

Merchants have the possibility to use the Get Landing Info API call to fetch the elements of the checkout page and reuse them to design their own instead of redirecting the user to the payment method's checkout page. If you want to know more please check the Direct API page.

Code-free solution

Merchant Back Office

The merchant back office is the dashboard from where merchants can manage their shops and transactions. From there merchants can also generate payment links, payment emails, and payouts manually by filling in a form with the corresponding information. After generating the transaction or payout, the URL and details must be forwarded to the user so they can proceed with payment.

For transactions, the URL generated through the back office will be a paywall. To know more about the back office and how to use it please check the Back Office section. If you want to know more about paywalls please navigate to the Paywall Integration page.

❗️

iFrame Incompatibility

Some PayRetailers payment methods are not compatible with iframe-based integrations, particularly on mobile devices where deep linking or secure redirections are required to complete the payment flow.

We recommend using full-page redirects (instead of iframes) for maximum compatibility across all devices and payment methods.

Optional Handling for Deep Link Payment Methods (not recommended)

If using an iframe is unavoidable, you will need to implement logic to intercept deep link triggers inside the iframe and forward them to the parent window.

Example: Deep Link Interception from iFrame to Parent
Inside the iframe (child content):

<a href="#" id="deepLink">Open The App</a>

<script>
  document.getElementById('deepLink').addEventListener('click', function(e) {
    e.preventDefault();
    const deepLinkUrl = 'yourapp://product/123';
    window.parent.postMessage(deepLinkUrl, 'https://your-parent-domain.com');
  });
</script>

In the parent window (hosting the iframe):

<iframe src="https://iframe-content-domain.com"></iframe>

<script>
  window.addEventListener('message', function(event) {
    if (event.origin !== 'https://iframe-content-domain.com') {
      return;
    }
    window.location.href = event.data;
  });
</script>

🔐 Security Note: Always validate event.origin to ensure only trusted sources can send deep link commands.