Individual Iframe (Button URLs)

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

👍

Supported APMs

To set up button iframes, follow these steps:

  1. Configure Your Account

    Contact Integrations Support to enable the desired APM on your merchant account.

    📘

    Note

    Some APMs require additional configuration steps. For additional information, see the Configuring APMs topic.

  2. Create Necessary Payment Flow Pages

    Generally, a merchant site has the following pages:

    • Shopping Cart
    • Confirm/Place Order
    • Checkout
    • Receipt

  3. Configure the Shopping Cart Page

    This page displays all items in the cart and has a button for going to the Checkout page.

    You can also offer alternative payment options (APMs), such as PayPal, as buttons on the page. The purpose of having these buttons at the Shopping Cart level is to have greater conversion before the customer goes to the checkout page.

    a. Add an iframe for each APM you plan to offer to your shoppers. The ID for the iframe is optional (except for Apple Pay). Use it with your own CSS.

    Apple Pay only: Assign the iframe that is used for Apple Pay an ID of nexioApplePayApmIframe (other, less common options, are nexio-apm-iframe or nexio-applePayAuthNet-apm-iframe).

    <iframe id='nexioApplePayApmIframe'> <!-- Apple Pay Iframe Option 1 -->
</iframe>
<iframe> <!- Any other APM iframe->
</iframe>

    <iframe id='nexio-paypal-iframe'> <!-- PayPal Iframe. ID only needed for your CSS. -->
</iframe>
<iframe id='[unique-iframe-id]'> <!-- Any other APM iframe. ID only needed for your CSS. -->
</iframe>
<!- Add more as needed. ->

    b. To generate these buttons, send a POST request to the Create APM one-time-use token endpoint.

    Include the required parameters (and any desired optional parameters) for the payment method or methods. For information about the required and optional parameters, see the appropriate integration guide:

    curl -X POST https://api.nexiopaysandbox.com/apm/v3/token \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic [Base64_encoded_login]'
  -d '{
  "data": {
    "amount": 29.99,
    "currency": "USD",
    "customer": {
      "firstName": "Maria",
      "lastName": "Velasquez",
      "email": "[email protected]",
      "orderNumber": "210058A"
    }
  },
  "customerRedirectUrl": "https://[your-ecommerce-website]"
}'

    A successful request returns an array of buttonIFrameUrls. This array is a list of all APMs currently enabled on your merchant account. Copy the url of the desired APM from the buttonIFrameUrls array for use in the next steps.

    Apple Pay only: Also copy the scriptUrl value for use in the next steps.

    {
  "expiration": "2018-09-18T15:43:05.664Z",
  "token": "830d36f6-a5e3-4455-9600-3a55b63e2fc2",
  "asyncTraceId": "830d36f6-a5e3-4455-9600-3a55b63e2fc2",
  "expressIFrameUrl": "https://www.api.nexiopaysandbox.com/v3?token=830d36f6-a5e3-4455-9600-3a55b63e2fc2",
  "redirectUrls": [...],
  "buttonIFrameUrls": [
    {
      "paymentMethod": "nihaoPayAliPay",
      "url": "https://api.nexiopaysandbox.com/apm/v3?token=830d36f6-a5e3-4455-9600-3a55b63e2fc2&paymentMethod=nihaoPayAliPay"
    },
    {
      "paymentMethod": "nihaoPayWechatPay",
      "url": "https://api.nexiopaysandbox.com/apm/v3?token=830d36f6-a5e3-4455-9600-3a55b63e2fc2&paymentMethod=nihaoPayWechatPay"
    },
    {
      "paymentMethod": "payPal",
      "url": "https://api.nexiopaysandbox.com/apm/v3?token=830d36f6-a5e3-4455-9600-3a55b63e2fc2&paymentMethod=payPal"
    },
    {
      "paymentMethod": "braintreePayPal",
      "url": "https://api.nexiopaysandbox.com/apm/v3?token=830d36f6-a5e3-4455-9600-3a55b63e2fc2&paymentMethod=braintreePayPal"
    },
    {
      "paymentMethod": "nihaoPayUnionPay",
      "url": "https://api.nexiopaysandbox.com/apm/v3?token=830d36f6-a5e3-4455-9600-3a55b63e2fc2&paymentMethod=nihaoPayUnionPay"
    },
    {
      "paymentMethod": "applePayAuthNet",
      "url": "https://api.nexiopaysandbox.com/apm/v3?token=830d36f6-a5e3-4455-9600-3a55b63e2fc2&paymentMethod=applePayAuthNet"
    },
    {
      "paymentMethod": "googlePayAuthNet",
      "url": "https://api.nexiopaysandbox.com/apm/v3?token=830d36f6-a5e3-4455-9600-3a55b63e2fc2&paymentMethod=googlePayAuthNet"
    }
  ]
}

    c. Add each url to the src tag of each iframe you created in step 3a, if applicable.

    Apple Pay only: Copy the scriptUrl to the src of a script tag in the body tag of your checkout page. (If you add the script to the wrong tag on the page, the page loads but the script does not work.)

    Now, when the page loads, the customer sees a button for each APM iframe you added to the page.

    If the APM supports it, you can also include Pay Later messaging.

    d. When they click a button (on your own external button or the iframe button, depending on the page configuration) they are sent to the appropriate APM page to complete payment (either redirected to the page or a popup window opened).

    Apple Pay or Google Pay: The customer is not redirected. Rather, a popup window opens in which the shopper can complete payment.

    PayPal (with Braintree) only: A popup window opens for the customer to log in. After setting an address (can be passed in the one-time-use token request and displayed to the customer as a default option) and payment method, the customer clicks Agree and Continue. The customer gets redirected to the Confirm/Place Order page.

  4. Configure the Confirm/Place Order Page

    The Confirm/Place Order page is used to calculate taxes and shipping cost after gathering address information from the customer.

    This page is important for PayPal (with Braintree). The customer gets redirected here after clicking the PayPal button on the Shopping Cart page, going through the PayPal login, and selecting their payment options.

    a. In the response from PayPal (with Braintree), you get the address information and a token for completing the payment in the full amount (with shipping and tax included).

    b. Based on the address returned, calculate the taxes and shipping cost as you normally would and display that on the page.

    c. Use the token returned from step 3b with the Pay button to send the full payment amount to PayPal.

    d. After the customer clicks the button, they are redirected to the page you specified in your PayPal configuration (such as a Receipt page).

  5. Configure the Checkout Page

    The Checkout page gives the customer the opportunity to make address and payment information, and for the page to calculate and display tax and shipping cost.

    In addition to a Pay button, you can also offer alternative payment options (APMs), such as PayPal, as buttons on the page so consumers have more options for payment. (For more information about creating a checkout page, see the steps in Creating a card checkout page with the iframe.)

    a. Add an iframe for each APM you plan to offer to your shoppers. The ID for the iframe is optional (except for Apple Pay, where it is required). Use it with your own CSS.

    Apple Pay only: Assign the iframe that is used for Apple Pay an ID of nexioApplePayApmIframe (other, less common options, are nexio-apm-iframe or nexio-applePayAuthNet-apm-iframe).

    <iframe id='nexioApplePayApmIframe'> <!-- Apple Pay Iframe Option 1 -->
</iframe>
<iframe> <!- Any other APM iframe->
</iframe>

    <iframe id='nexio-paypal-iframe'> <!-- PayPal Iframe. ID only needed for your CSS. -->
</iframe>
<iframe id='[unique-iframe-id]'> <!-- Any other APM iframe. ID only needed for your CSS. -->
</iframe>
<!- Add more as needed. ->

    b. To generate these buttons, send a POST request to the Create APM one-time-use token endpoint.

    Include the required parameters (and any desired optional parameters) for the payment method or methods. For information about the required and optional parameters, see the appropriate integration guide:

    curl -X POST https://api.nexiopaysandbox.com/apm/v3/token \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic [Base64_encoded_login]'
  -d '{
  "data": {
    "amount": 29.99,
    "currency": "USD",
    "customer": {
      "firstName": "Maria",
      "lastName": "Velasquez",
      "email": "[email protected]",
      "orderNumber": "210058A"
    }
  },
  "customerRedirectUrl": "https://[your-ecommerce-website]"
}'

    A successful request returns an array of buttonIFrameUrls. This array is a list of all APMs currently enabled on your merchant account. Copy the url of the desired APM from the buttonIFrameUrls array for use in the next steps.

    Apple Pay only: Copy the scriptUrl value as well for use in the next steps.

    {
  "expiration": "2018-09-18T15:43:05.664Z",
  "token": "830d36f6-a5e3-4455-9600-3a55b63e2fc2",
  "asyncTraceId": "830d36f6-a5e3-4455-9600-3a55b63e2fc2",
  "expressIFrameUrl": "https://www.api.nexiopaysandbox.com/v3?token=830d36f6-a5e3-4455-9600-3a55b63e2fc2",
  "redirectUrls": [...],
  "buttonIFrameUrls": [
    {
      "paymentMethod": "nihaoPayAliPay",
      "url": "https://api.nexiopaysandbox.com/apm/v3?token=830d36f6-a5e3-4455-9600-3a55b63e2fc2&paymentMethod=nihaoPayAliPay"
    },
    {
      "paymentMethod": "nihaoPayWechatPay",
      "url": "https://api.nexiopaysandbox.com/apm/v3?token=830d36f6-a5e3-4455-9600-3a55b63e2fc2&paymentMethod=nihaoPayWechatPay"
    },
    {
      "paymentMethod": "payPal",
      "url": "https://api.nexiopaysandbox.com/apm/v3?token=830d36f6-a5e3-4455-9600-3a55b63e2fc2&paymentMethod=payPal"
    },
    {
      "paymentMethod": "braintreePayPal",
      "url": "https://api.nexiopaysandbox.com/apm/v3?token=830d36f6-a5e3-4455-9600-3a55b63e2fc2&paymentMethod=braintreePayPal"
    },
    {
      "paymentMethod": "nihaoPayUnionPay",
      "url": "https://api.nexiopaysandbox.com/apm/v3?token=830d36f6-a5e3-4455-9600-3a55b63e2fc2&paymentMethod=nihaoPayUnionPay"
    },
    {
      "paymentMethod": "applePayAuthNet",
      "url": "https://api.nexiopaysandbox.com/apm/v3?token=830d36f6-a5e3-4455-9600-3a55b63e2fc2&paymentMethod=applePayAuthNet"
    },
    {
      "paymentMethod": "googlePayAuthNet",
      "url": "https://api.nexiopaysandbox.com/apm/v3?token=830d36f6-a5e3-4455-9600-3a55b63e2fc2&paymentMethod=googlePayAuthNet"
    }
  ]
}

    c. Add each url to the src tag of each iframe you created in step 5a, if applicable.

    Apple Pay only: Copy the scriptUrl to the src of a script tag in the body tag of your checkout page. (If you add the script to the wrong tag on the page, the page loads but the script does not work.)

    var url = "https://api.nexiopaysandbox.com/apm/v3?token=830d36f6-a5e3-4455-9600-3a55b63e2fc2&paymentMethod=klarna";
window.document.getElementById('nexio-klarna-iframe').src = url;

    Now, when the page loads, the customer sees a button for each APM iframe you added to the page.

    d. When they click a button (on your own external button or the iframe button, depending on the page configuration) they are sent to the appropriate APM page to complete payment (either redirected to the page or a popup window opened).

    Apple Pay or Google Pay: The customer is not be redirected. Rather, a popup window opens in which the shopper can complete payment.

    PayPal (with Braintree) only: A popup window opens for the customer to log in. After setting an address (can be passed in the one-time-use token request and displayed to the customer as a default option) and payment method, the customer clicks Agree and Continue. The customer gets redirected to the Confirm/Place Order page.

  6. Shopper Completes Payment

    This step varies slightly depending on the APM.

    • Voucher payments (Paynet and SPEI): Users are prompted to print or close the voucher page.

    • PayPal (with Braintree) only: If the customer checked out using PayPal (with Braintree) and saveRecurringToken was set to true in the one-time-use token request, then the response includes an apm.token parameter. For example: 

      { "apm": { "token": "apm:f58kq4b5-h408-3a29-s07b-c384j3958fkw" } }

    • All other APMs: When a consumer clicks the APM button, a popup window opens (or they are redirected) to the appropriate APM page in which the consumer can complete payment.

      After the consumer completes payment, the popup window closes (if appropriate) and they are redirected back to the merchant website.

    • If you did not send the customerRedirectUrl in the request from step 3, the consumer is redirected to the checkout page. Nexio provides a response as event messages.

    • If you did send the customerRedirectUrl in the request from step 3, the customer is redirected to that URL. Nexio provides a response via query string parameters in the URL.

    If your merchant account is configured to receive webhooks, in addition to one of the above, Nexio provides responses as event messages to the webhook URLs that have been registered.

  7. Shopper Redirected

    After the shopper has completed payment (or payment has failed) Nexio's iframe requests to be closed and sends a message event or redirect URL with the payment information.

    • If the payment was successful, the message includes the status and payment ID. For information about status, see the Status workflows section for the specific payment method.
    • If the payment failed, the message includes the status and an error message. For information about handling errors, see Error handling.

    Use the message information to create a success (such as a receipt) or failure page for the shopper. You may also want to send a receipt to the shopper via email.

    Example URL query string parameters response (for customerRedirectUrl):

    https://your-ecommerce-website.example.com?status=pending&paymentId=eyJuYW1lIjoidXNhZXBheSIsInJlZk51bWJlciI6IjMxMDA5MDc4MTkiLCJtZXJjaGFudElkIjoiMTAwMDM5IiwicmFuZG9tIjoiMzEwMDkwNzgxOSIsImN1cnJlbmN5IjoiVVNEIn0&orderNumber=228c3778fe

    Example URL query string parameters response (for customerRedirectUrl) for a failed payment:

    https://your-ecommerce-website.example.com?status=pending&error=error_message

    Example event message response (for request without customerRedirectUrl or for webhook):

    {
  "id": "eyJuYW1lIjoicGF5UGFsIiwibWVyY2hhbnRJZCI6IjEwMDAzOSIsInJlZk51bWJlciI6IjlLQTI2NzUwSEs5NzM2OTNBIiwicmFuZG9tIjowLCJjdXJyZW5jeSI6InVzZCJ9",
  "merchantId": "100039",
  "transactionDate": "2020-06-29T18:54:01.087Z",
  "transactionStatus": "settled",
  "amount": 1.15,
  "transactionType": "sale",
  "currency": "USD",
  "gatewayResponse": {
    "result": 201,
    "refNumber": "9KA26750HK973693A",
    "gatewayName": "payPal",
    "message": 201
  },
  "data": {
    "amount": 1.15,
    "currency": "USD",
    "settlementCurrency": "USD",
    "customer": {
      "lastName": "Test",
      "shipToAddressOne": "123 Ship St",
      "shipToPhone": "5033335678",
      "orderNumber": "054204daf0f7456bac59a014e952fb33",
      "shipToCountry": "US",
      "shipToAddressTwo": "Warehouse 456",
      "billToState": "UT",
      "billToCity": "Testerville",
      "shipToPostal": "67890",
      "firstName": "Nexio",
      "shipToCity": "Shipperville",
      "billToAddressOne": "123 Test St",
      "billToCountry": "US",
      "billToPostal": "12345",
      "billToAddressTwo": "Suite 123",
      "billToPhone": "8015551234",
      "email": "[email protected]",
      "shipToState": "OR"
    }
  }
}

Updated 10 days ago