Guides

Multi Iframe (Express APM)

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

Nexio's Express APM service allows shoppers to run transactions through many of our supported alternative payment methods (APMs) with a single integration. When you integrate with Express APM, shoppers see a list of all available APMs (as images) with a radio button selector and, after selection, they are redirected to the payment provider to complete payment.

👍

Supported APMs

📘

Notes

To integrate with Express APM, follow the steps below.

  1. Configure Your Account

    Contact Integrations Support to enable any desired APMs on your merchant account.

  2. Create a Checkout Page

    Create a checkout page with an iframe. For more information, see the steps in Creating a card checkout page with the iframe.

  3. Request an Express Iframe URL

    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:

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

    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"
    }
  },
  "uiOptions": {
    "displaySubmitButton": true
  },
  customerRedirectUrl: "https://[your-ecommerce-website]"
}'

    A successful response includes the expressIFrameUrl. Copy or store the expressIFrameUrl value for use in step 4.

    {
  "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": [
    {
      "paymentMethod": "payPal",
      "url": "https://www.api.nexiopaysandbox.com/v3/popup?token=830d36f6-a5e3-4455-9600-3a55b63e2fc2&paymentMethod=payPal"
    }
  ],
  "buttonIFrameUrls": [
    {
      "paymentMethod": "applePayAuthNet",
      "url": "https://api.nexiopaysandbox.com/apm/v3?token=830d36f6-a5e3-4455-9600-3a55b63e2fc2&paymentMethod=applePay"
    }
  ]
}

  4. Redirect the Shopper to the Select APM Page

    Assign the expressIframeUrl from the previous step to your iframe's src tag.

    If using your own external button, you can style the button and create custom actions that run when the consumer clicks it (in addition to going to the APM payment page).

    var url = "https://www.api.nexiopaysandbox.com/v3?token=54a0106y-7750-45b1-961e-29ad95763a23";
window.document.getElementById('myIframe').src = url;

    All APMs: When your iframe loads, shoppers are prompted to select from a list of configured APMs. The shopper makes their selection, clicks 'Submit' (on your own external button or the iframe button, depending on your choice), then is redirected to their chosen APM to complete payment.

  5. Shopper Completes Payment

    This step varies slightly depending on the APM.

    • Voucher payments (Paynet): Users are prompted to print or close the voucher page.
    • All other APMs: Users are prompted to complete the transaction.

    Afterward, they will be redirected back to the merchant site.

    • 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.

  6. Create a Receipt for the Shopper

    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 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"
    }
  }
}

    Example URL query string parameters response (for customerRedirectUrl):

    https://www.your-ecommerce-website.example.com?id=eyJuYW1lIjoicGF5UGFsIiwibWVyY2hhbnRJZCI6IjEwMDAzOSIsInJlZk51bWJlciI6IjlLQTI2NzUwSEs5NzM2OTNBIiwicmFuZG9tIjowLCJjdXJyZW5jeSI6InVzZCJ9&status=success&orderNumber=054204daf0f7456bac59a014e952fb33

Updated 7 months ago