The hosted form solution provided by Paybyrd is an easy-to-use and flexible payment integration option for ecommerce businesses. It allows the customer to embed a secure and customizable payment page directly on their website, without having to worry about the complex underlying payment infrastructure. The hosted form handles all payment method integrations on its own. This eliminates the need for the ecommerce to handle sensitive payment information on their own server and reduces the scope of PCI compliance. The hosted form is fully integrated with Paybyrd Gateway, providing a seamless payment experience for customers and streamlining the payment process for merchants. With this solution, businesses can quickly and easily accept payments from customers while maintaining the highest levels of security and customer experience.


This guide is divided in 3 steps so you will be able to integrate Paybyrd's Hosted Form v2 in your E-Commerce in a very simple way:

  1. Generate an order
  2. Create a Hosted Form instance (iFrame or Standalone URL)
  3. Validate the payment


Migrating from v1 to v2

There are 3 main breakpoints from the v1 to v2:

  1. failureRedirectUrl was removed and now we always use redirectUrl to return success/failed payments.
  2. We are not using the form with submit anymore, we are now using the queryParameters to communicate to the HostedForm embedded iFrame or a new tab to handle payments in new tabs.
  3. Now it is required to provide the checkoutKey which is the field returned by the /orders POST HTTP call and it has to be sent in the queryParams to the HostedForm to work properly.

1. Generate an order

When the shopper proceeds to the checkout page, you need to send the details of his order via API to Paybyrd. The information provided will be used later on to present the hosted form for the payment conclusion.

Please check the request example below:

curl --location -g --request POST '{{paybyrd-gateway}}/api/v2/orders \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'x-api-key: 5E37D19C-F99C-445F-8B77-1463EFC66C7B' \
--data '
     "amount": "5.00",
     "currency": "EUR",
     "orderRef": "ABC123456",
     "expiresIn": 24,
     "shopper": {
          "firstName": "JHOSH",
          "lastName": "JONES",
          "email": "[email protected]",
          "phoneNumber": "+319999999921"
     "orderOptions": {
          "redirectUrl": "https://your-site-url/payment-finished"
     "expiresIn": 5,
     "paymentOptions": {
          "cardOptions": {
               "isPreAuth": false
          "tokenOptions": {
            "customReference": "+319999999921"


The hosted form supports Tokenized Payments

To enable Tokenized Payments, which means that the customer will see a checkbox that allows the storage of the card information for future payments in the store, just include the tokenOptions prop with a customReference (that should be an unique information from the user) in the /orders API call as you can see in the example above.

See the full Reference API here

2. Create a Hosted Form instance (iFrame or Standalone URL)

- Render as iFrame

After creating an order, with the response you will be able to initiate the Hosted Form. We highly recommend to use the snippet below to generate the iFrame, but the only required step is to have an iframe and define the SRC of it with the correct queryParams that you can check in the table below


New URL for Hosted Form v2

The new URL that will be used as src of the iFrame in the new Hosted Form is https://checkout.paybyrd.com, but you should include some required parameters on it

(function() {
   function initHostedForm(data) {
        const configs = btoa(JSON.stringify(data));
    const ENV_URL = 'https://checkout.paybyrd.com/#/payment?checkoutKey=${data.checkoutKey}&orderId=${data.orderId}&configs=${configs}';
        const container = document.createElement('DIV');
        container.style.width = '100%';
        container.style.height = '100vh';

        const iframe = document.createElement('IFRAME');
        iframe.style.width = '100%';
        iframe.style.height = '100%';
        iframe.style.border = 'none';
        iframe.style.position = 'fixed';
        iframe.style.zIndex = 999999;
        iframe.style.top = 0;
        iframe.style.left = 0;
        iframe.id = 'pb-hf-ifrm';
        // Prod
        iframe.src = ENV_URL;
        iframe.onload = function() {
            document.body.style.overflow = 'hidden';


        redirectUrl: paybyrd_params.redirectUrl,
        locale: paybyrd_params.locale,
        orderId: paybyrd_params.orderId,
        checkoutKey: paybyrd_params.checkoutKey,
        theme: {
            backgroundColor: paybyrd_params.theme.hfBackgroundColor,
            formBackgroundColor: paybyrd_params.theme.hfFormBackgroundColor,
            primaryColor: paybyrd_params.theme.hfPrimaryColor,
            textColor: paybyrd_params.theme.hfTextColor,
      effectsBackgroundColor: paybyrd_params.hfEffectsBackgroundColor,
    autoRedirect: true,
    showCancelButton: false,
    skipATMSuccessPage: false,
    compact: false
redirectUrlThis will be used by the hostedform to redirect the user after a succeeded/failed paymentstringYes
orderIdThis info is required to retrieve the order data to render the Hosted FormGUIDYes
checkoutKeyAlso required and used together with the Order ID to render the data in Hosted FormGUIDYes
localeThis property will define the language of the Hosted Formenum k:parame (Default EN)No
themeAn object that can customize the body background, the form background, the color of the text and the backgroundColor of buttonsObject
backgroundColor: #HEX,
formBackgroundColor: #HEX,
primaryColor: #HEX,
textColor: #HEX,
effectsBackgroundColor: #HEX
No (You can set just a part of the object as well, e.g.: {
backgroundColor: #HEX,
} and not set the rest of the properties)
autoRedirectAfter a payment in the Hosted Form (success/failed) you can use our landing page that validates the payment or you can automatically redirect to your redirectUrl and show a customized page for the userboolean (Default true)No
showCancelButtonIn the Hosted Form it's possible to render a "Cancel Payment" button that automatically change the status of that order to Canceled and redirects the user to the redirectUrlboolean (Default false)No
defaultPaymentMethodRedirects the user automatically to a predefined payment method. If the defaultPaymentMethod provided is not in the available payments list, we render the default payment list. If there is only one available payment, it's not necessary to define a defaultPaymentMethod because the Hosted Form redirects the user automatically to this method.

When a defaultPaymentMethod is provided but there are more than one method available, the user is redirected to the defined payment method but the Hosted Form shows a back button so the user can select a different payment method to make the payment.
enum k:parameters]
"data": {
"h-0": (Default undefined)
skipATMSuccessPageRedirects the user to the redirectUrl defined in the order instead of displaying the entity and reference values inside the hosted form so the client can handle this payment process manuallyboolean (Default false)No
compactRemoves body background, margins, paddings and box shadow from the hosted form container, so you can customize the way you preferboolean (Default false)No


Our Hosted Form is fully customizable!

As you could see in the second step (Create a Hosted Form instance), it is possible to define a theme for the Hosted Form. It's possible to set a background for the entire page to match your visual identity, change the color of the text, the background of the form itself and also the background of the action buttons. It's not required and it's also optional to set only one of the properties. For example, you can define a theme like this:

theme: {
backgroundColor: #000,

In this scenario, the background (from purple gradient) will be white, but the form background, buttons and labels will use our default theme.

- Render as Standalone URL (new or self tab)

It is also possible to redirect the user to this URL: https://checkout.paybyrd.com/#/payment?checkoutKey={CHECKOUT_ID}&orderId={ORDER_ID}&configs={CONFIGS}. The difference is that it's possible to open in a new tab when it's needed. It supports the same configurations of the iFrame, so you can check the object that you can send in the configs param in the table above. Check all the available query params below:

orderIdThis info is required to retrieve the order data to render the Hosted FormGUIDYes
checkoutKeyAlso required and used together with the Order ID to render the data in Hosted FormGUIDYes
configsBased on the configurations that we send to the Hosted Form using the iFrame, here the idea is similar. We just need to stringify the object and send as a Base64 like the snippet below.

Then, just send it as an extra parameter in the URL and we take care of the rest!

To check the reference for the content that will be sent to the configs, check this table
Base64(JSON.stringify(data: Object))No
// Configs Parameter Reference

const configs = btoa(JSON.stringify({  
        redirectUrl: "http://redirect.url",  
        locale: "en_US",  
        orderId: "123-123",  
        checkoutKey: "321-321",  
        theme: {  
            backgroundColor: "#F0F0F0",  
            formBackgroundColor: "#3C3C3C",  
            primaryColor: "#CCCCCC",  
            textColor: "#FFFFFF",
      effectsBackgroundColor: #DBDBDB,  
    autoRedirect: true,  
    showCancelButton: false,
    compact: false

3. Validate the payment

When the payment is finished by the user (even succeeded or failed), the user will be redirect to the redirectUrl. It's important that this redirectUrl validates the payment with a GET to the /orders, so it will be possible to change the Order Status in your e-commerce to the correct one. Also, it's important to configure a WebHook in the e-commerce platform to listen to changes in the order that will be sent by Paybyrd API, so if the user closes the page before getting in your Payment Validation Landing Page or if an async payment (Multibanco, MBWay for example) was made, the Paybyrd API will send a POST to this generated Webhook when the status of the order is changed.

To create a webhook and know more about the responses, follow this tutorial.


Are you using webhooks?

It's important to configure a webhook in your e-commerce platform so it will be possible to manage async payments and cases that the user closes the page before being redirect to the redirectUrl. After generating the webhook following the tutorial above, you will be able to receive the paymentId and the transactionId whenever the order has its status changed and check if the payment was made correctly.

To validate sync payments (like credit cards), after being redirected to the redirectUrl (both success/failure scenarios), it's possible to GET the order and verify its response to change the order status. Check cURL below:

curl --request GET '{{paybyrd-gateway}}/api/v2/orders/{ORDERID} \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'x-api-key: 5E37D19C-F99C-445F-8B77-1463EFC66C7B'