Embedded page

1. Prerequisites

Before you begin, make sure you have met the following prerequisites:

• You have an account on the Revolv3 portal with merchant and with one or more configured processors
• You already have a generated developer API key
• You have added the hostname of your website, in which you will embed the checkout page, to the Trusted Checkout Hostnames (Merchant Settings -> Integration Profile).

2. Creating a checkout link

If you have fulfilled all the prerequisites, you can now start creating a link that will be embedded in your website using e.g. iframe.

🚧

Origin HTTP header

To ensure that requests are sent from an authorized merchant's API, make sure the HTTP request includes the Origin HTTP header.

❗If it is missing, you will get a 400 HTTP error.

To create a link you need to send a request to the following endpoint:

POST {{Api Root}}/api/Checkout

📘

Api Root

The API Root can be the URL of our Production (https://api.revolv3.com) or Sandbox (https://api-sandbox.revolv3.com) environment.

Sample payload (more information about the endpoint here -> Create Checkout Link Endpoint. A detailed description of the checkout line items value types -> Checkout Line Items Value Types.

{
  "OneTimePayment": {
    "CheckoutLineItems": [
      {
        "Name": "Item 1",
        "Description": "Description",
        "Value": 9.99
      },
      {
        "Name": "Item 2",
        "Description": "Description",
        "Value": 21.99
      }
    ]
  }
}

The response will have the following structure:

{
    "checkoutId": "0584773e-47bf-4822-91de-06acb5de9358",
    "checkoutLink": "https://some-revolv3-url.com/checkout/0584773e-47bf-4822-91de-06acb5de9358"
}

You can get all the checkout information at any time using this endpoint -> Get Complete Checkout Information

3. Embed the checkout page

Now you have a link to the payment page that you can embed into the your website and wait for the payment to complete. Example of how you can embed a page:

<iframe title="Revolv3 Checkout" src="https://some-revolv3-url.com/checkout/0584773e-47bf-4822-91de-06acb5de9358"
        frameborder="0" scrolling="no">
</iframe>

4. Added an event handler to your webpage

To let your website (parent window) know when you can close an Iframe, you need to add an event handler to the web page. Since windows cannot interact with each other directly, they need to communicate using messages (postMessage).

More information about sending and receiving messages can be found here -> https://developer.mozilla.org/ru/docs/Web/API/Window/postMessage

We send this message from our frontend application after the checkout results are uploaded. Handler may look as follows:

addEventListener("message", receiveMessage, false);


function receiveMessage(event: MessageEvent<{ checkoutId: string, checkoutStatus: string }>) {
    if (event.origin === 'https://portal-sandbox.revolv3.com' ||
      event.origin === 'https://portal.revolv3.com') {
      //do something
      //event.origin;  - message sender (schema + hostname)
      //event.type; - message type (will be message)
      //event.data; - message data
    }
    return;
  }

🚧

Check event.origin

Verification that the message came from the revolv3 website (Production or Sandbox) should be mandatory.

The data structure of the Message Event will be as follows, so you can parse it and check the results.

{ checkoutId: string, checkoutStatus: string }

The checkoutId is an unique identifier of the checkout (The string will be in GUID format). Possible values for checkoutStatus:

• Pending (the checkout has been created, the payment has not yet been made),
• PaymentCompleted (A payment attempt was made. The payment result is - Paid),
• PaymentFailed (A payment attempt was made. The payment result is unsuccessful).