Overview

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.

Integration

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';
		}

		container.append(iframe);
		document.body.append(container);
	}
  
  const paybyrd_params = THIS_DATA_SHOULD_BE_DEFINED_BY_THE_SERVER;

	initHostedForm({
		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
	});
})();

📘

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:

// 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'
'