Guides

Creating a card checkout page with the iframe

Background
Before starting this tutorial, make sure you understand the following topics from the Quick start section:

Part of the payment process includes a checkout page. You can create this page using the iframe, using your own form, or through the API.

This topic guides you through the steps for creating a card checkout page using the iframe.

  1. Create an Iframe on Your Web Page

    <html>
    <iframe id="myIframe" src="">
    </iframe>
</html>

  2. Create an Event Listener

    Create an event listener to monitor actions in the iframe.
    This listener will keep your code updated on what is happening inside the iframe.
    You will handle the success, error, and loading states here.
    See our iframe events table for a list of possible events.

    window.addEventListener('message', function messageListener(event) {
    if (event.origin === iframeUrl) {
        // switch on event.data properties
        // (e.g. loaded, formValidations, error)
    }
}

  3. Send a POST request to the ecommerce Create one-time-use token endpoint.
    The minimally required field is data.amount.

    📘

    Note

    If you want to turn off the automatic saving of the card token while running the transaction, include processingOptions.saveCardToken and set it to false.
    In addition, any iframe uiOptions or processingOptions must be included in this request. For example, you may want to set processingOptions.check3ds to true (see 3D Secure overview ), unless you want to run the transaction without 3D Secure. For more information about these objects and parameters, see the API Reference for the "Create one-time-use token" endpoint.

curl -X POST https://api.nexiopaysandbox.com/pay/v3/token \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic [Base64_encoded_login]'
  -d '{
    "data": {
      "amount": 29.99,
      "currency": "USD"
    },
    "processingOptions": {
      "paymentType": "initialUnscheduled"
    }  
  }'


{
  "expiration": "2022-03-14T15:43:05.664Z",
  "fraudUrl": "https://api.nexiopaysandbox.com/pay/v3/fingerprint?token=830d36f6-a5e3-4455-9600-3a55b63e2fc2",
  "token": "830d36f6-a5e3-4455-9600-3a55b63e2fc2"
}

You will use the token in the next set of steps.

👍

Try it out . . .

  1. Go to the Create one-time-use token endpoint.
  2. In the main content area, click the "RUN CARD TRANSACTION IFRAME" option.
  3. Click the DATA object (or the plus sign for it).
  4. Type 29.99 for the 'amountandUSDfor thecurrency`.
  5. In the right pane, type your API username and password.
  6. Select the language you want to use (or leave the default selection).
  7. Click the Try It! button.
    See the token in the Response area.

  1. Copy or Store the Token From the Above Response

    The token is your one-time-use token.

    📘

    Notes

    • Each one-time-use token expires after one hour.
    • Each one-time-use token can only be used to submit a single form.

  2. Load the Iframe

    a. Set the start of the iframe's URL to the Run card transaction with iframe endpoint. (https://api.nexiopaysandbox.com/pay/v3).

    b. Append the one-time-use token to the iframe's URL in a query parameter called token.

    c. Assign the result to your iframe's src tag.

    📘

    Notes

    • If an error occurs while loading an iframe, the endpoint returns a JSON object with the error message.
    • To receive an HTML response instead, include shouldReturnHtml=true as an additional query parameter in the save card token URL.
var iframeBaseUrl = "https://api.nexiopaysandbox.com/pay/v3";
var oneTimeUseToken = "?token=" + token;
var returnHtml = "&shouldReturnHtml=true";
var url = iframeBaseUrl + oneTimeUseToken + returnHtml;
window.document.getElementById('myIframe').src = url;

👍

Try it out . . .

  1. Go to the Run card transaction with iframe endpoint.
  2. Using the token you got from step 3 above, In the "Authentication" area, paste the token text.
  3. Click the Try It! button.
  4. The response shows the HTML returned to the iframe.

  1. Create an Event Listener

    Add an event listener to your form's submit button that will trigger a POST request inside the iframe. Now when a user clicks the submit button on your outer form, the iframe submits itself. Because of the event listener you created in step 2, your code is aware of iframe responses and errors.

    myForm.addEventListener('submit', function processPayment(event) {
    event.preventDefault();
    const url = 'https://api.nexiopaysandbox.com';
    myIframe.contentWindow.postMessage('posted', url);
    return false; // keeps the form from auto submitting
});

  2. Handle the response
    You may want to store the id returned in the response as this is the payment ID and you can use it to query the status of the transaction (using the View transaction by payment ID endpoint) within about a minute. You may also want to store the transactionId. You can only get this parameter after the transaction runs. You get it in the webhook with the transactionId (note that this parameter is not returned for legacy webhooks) or in the id returned in any of the following endpoints:

Updated 6 months ago