Creating an echeck checkout page with the iframe
Background |
---|
Before starting this tutorial, make sure you understand the following topics from the Quick start section:
|
Create a checkout page for e-check (ACH) transactions, either by using the Nexio iframe or with your own form.
Note
Echeck transactions cannot be voided or refunded.
To create an echeck checkout page that uses the Nexio iframe, do the following:
-
Add an iframe to the body of your web page where you want the checkout form to display.
<html> <body> <iframe id="myIframe" src=""> </iframe> </body> </html>
-
Create an event listener to monitor actions in the iframe. This listener keeps your code updated on what is happening inside the iframe. You handle the success, error, and loading states here.
See our Iframe events table for a list of possible events.
The following is an example of how to add an event listener with JavaScript:
window.addEventListener('message', function messageListener(event) { if (event.origin === iframeUrl) { // switch on event.data properties // (e.g. loaded, formValidations, error) } });
-
On page load, request a one-time-use token by sending a
POST
request to the Create one-time-use token endpoint.Note
Any iframe
uiOptions
orprocessingOptions
must be included in this request. For more information about these objects and parameters, see the API Reference for the "Create one-time-use token" endpoint.The minimally required field is
data.amount
, but you can add any other supported parameters: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" } }'
{ "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 steps.Try it out . . .
- Go to the Create one-time-use token endpoint.
- In the main content area, click the "RUN ECHECK TRANSACTION IFRAME" option.
- Click the
DATA
object (or the plus sign for it). - Type
29.99
for the 'amountand
USDfor the
currency`. - In the right pane, type your API username and password.
- Select the coding language you want to use (or leave the default selection).
- Click the Try It! button.
See thetoken
in the Response area.
-
Copy or store the
token
value 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.
-
Assign the
src
value of the iframe.a. Set the start of the iframe's URL to the Run echeck 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/processECheck"; var oneTimeUseToken = "?token=" + token; var returnHtml = "&shouldReturnHtml=true"; var url = iframeBaseUrl + oneTimeUseToken + returnHtml; window.document.getElementById('myIframe').src = url;
Try it out . . .
- Go to the Run echeck transaction with iframe endpoint.
- Using the token you got from step 3 above, in the "Authentication" area, paste the
token
text. - Click the Try It! button.
The response shows the HTML returned to the iframe.
-
Add an event listener to your form's submit button that triggers a
POST
request inside the iframe.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 });
Now when a user clicks submit 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.
-
Finally, 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 thetransactionId
. You can only get this parameter after the transaction runs. You get it in the webhook with thetransactionId
(note that this parameter is not returned for legacy webhooks) or in theid
returned in any of the following endpoints:
Updated 17 days ago