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
- This service is not compatible with embedded browsers in apps.
- Google Pay and PayPal (with Braintree) are not currently supported through Express APM.
To integrate with Express APM, follow the steps below.
-
Configure Your Account
Contact Integrations Support to enable any desired APMs on your merchant account.
-
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.
-
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 theexpressIFrameUrl
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" } ] }
-
Redirect the Shopper to the Select APM Page
Assign the
expressIframeUrl
from the previous step to your iframe'ssrc
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.
-
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.
-
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 6 months ago