Introduction

Welcome to Nexio’s API documentation. From start-ups to enterprise businesses, Nexio will help you manage your customer’s experience from start to finish. The Nexio Hub manages the payment process for credit cards, alternative payment methods, international currencies, fraud mitigation, and more.

In this documentation you will find tutorials and our complete API Reference. To see what's new, check out our release notes. For more code samples (including PHP, Node, C# and plugin examples for WooCommerce and Magento), see our code examples on GitHub. To start sending test requests without writing any code, download and explore our Postman collection using the button below.

Getting Started

Requirements

To get started using the Nexio API you will need:

• Nexio credentials: To request credentials, send us a message at sandbox@nexiopay.com
• An HTTP client: Our API reference includes cURL examples. You can also download our Postman Collection or use your preferred HTTP client

Ready to get started?

Base URLs and Environments

All endpoints are RESTful with the following base URLs:

• Sandbox: https://api.nexiopaysandbox.com

• Production: https://api.nexiopay.com

The sandbox environment allows you to run test transactions without affecting live data.

Once you have integrated with the sandbox environment you are ready to integrate to production with minimal changes. (Required updates include authentication information and encryption keys.)

Your First Request

A good place to start getting familiar with our API is by sending a request to the Who Am I endpoint.

A successful request to this endpoint will return information about the user whose credentials have been used to authenticate the request, including:

• First Name
• Last Name
• Username
• A list of merchants to which the user has access rights

To send a request, follow the steps below:

1. Authenticate via basic authentication.

2. Send a GET request to the Who Am I endpoint.

Example Request

curl -X GET https://api.nexiopaysandbox.com/user/v3/account/whoAmI \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic <Your Basic Auth>'

 Example 200 Response 

{
  "cognitoSub": "g52679a2-tan5-4a56-b6gc-2592aedd373e",
  "firstName": "John",
  "lastName": "Doe",
  "userName": "jdoe@yourwebsite.com",
  "accessRights": {
    "merchantIds": {
      "100039": "A"
    },
    "role": "A"
  },
  "dateLastModified": "2019-03-08T00:58:27.893Z",
  "dateCreated": "2018-09-27T14:27:39.626Z",
  "enabled": true,
  "phone": "15555555555",
  "notifications": false
}

Next steps

Once you have successfully made your first request, you are ready to move on. Depending on your workflow, you may wish to:

• Load a retail iframe
• Load an e-commerce iframe
• Use an alternative payment method
• Configure webhooks to notify you when transaction events take place
• Retrieve a list of transactions
• Dispute a chargeback

Contact Us

If you have additional questions, our integrations team is happy to help:

• Message us on Slack
• Email us at: integrations@nexiopay.com

If you would like to provide feedback on any part of this documentation, please email us at: docs@nexiopay.com

Authentication

Basic Authentication

To authenticate with basic authentication you will need a Nexio username and password. Please contact integration support to create a Nexio account.

1. Encode Your Username and Password

   Base 64 encode your Nexio username and password with no spaces, separated by a colon.

Example

$ echo -n myname@nexiohub.com:mypassword | base64
bXluYW1lQG5leGlvaHViLmNvbTpteXBhc3N3b3Jk

2. Create the Authorization Header

   Prefix the value from step 1 with the string "Basic ".

Example

Authorization: Basic bXluYW1lQG5leGlvaHViLmNvbTpteXBhc3N3b3Jk

3. Send a Request

   Include the string from step 2 in authorization header of your API request.

Example

curl -X get https://api.nexiopaysandbox.com/user/v3/account/whoAmI \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic bXluYW1lQG5leGlvaHViLmNvbTpteXBhc3N3b3Jk'

One-time-use Tokens

E-commerce

You will need a one-time-use token to load any e-commerce iframes or to save a card token via the API.

To get a one-time-use token, send a request to the E-Commerce One-time-use Token endpoint. Authenticate using basic authentication. Include any information you wish to pass along to the applicable iframe or popup in the body of your request. See the E-commerce One-time-use Token API Reference for a complete list of parameters.

Alternative Payment Methods

You will need a one-time-use token to load an Alternative Payment Method (APM) Iframe. To obtain an alternative payment method one-time-use token, send a request to the One-time-use Token (APM) endpoint. Authentication using basic authentication. Include any information you wish to pass along to the iframe in the body of your request. See the retail UI options section for a complete list.

Notes

• CORS requires that every request for a one-time-use token must be sent from a server. If you attempt to send a request a frontend you will receive an error
• One-time-use tokens for e-commerce iframes and alternative payment methods are not interchangeable
• Not all body parameters that may be included in the body of a request for a one-time-use token apply to every iframe or popup
• Each one-time-use token can only be used to submit a single form
• Each one-time-use token expires after one hour

Overview

Getting Started

To get started with our e-commerce API, you will need a Nexio username and password. Contact integrations support to request credentials.

Prior to accessing any endpoint, you will be required to authenticate. Please see our API Reference for more information on the required authentication for each endpoint. The form of authentication required for each endpoint is listed in a yellow box at the top of each section.

Nexio's e-commerce API enables you to:

• Create a checkout page for your e-commerce website
• Create a save card page for your e-commerce website

• Authorize, Capture, Void and Refund card or e-check transactions
• Initiate a transaction using an alternative payment method
• Capture, Void and Refund alternative payment method transactions
• View transaction and chargeback reports, and deposit summaries,
• Dispute Chargebacks
• And more!

You will have hands-on control to:

• Translate iframe labels for localization
• Enable webhook notifications
• Customize the iframe's CSS to match your site's style
• Choose which fields to display or require

You can also choose to enable built-in fraud protection services, including:

• Address Verification Service (AVS)
• Security Code (CVC) Verification
• Kount Verification

Create a Checkout Page

With the Nexio Iframe

1. Create an Iframe on Your Web Page

Example

<html>
    <iframe id="myIframe">
    </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.

Example

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

3. Request a One-time-use Token

   Send a POST request to the E-commerce One-time-use Token endpoint.

Example Request

curl -X POST https://api.nexiopaysandbox.com/pay/v3/token \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic <Your Basic Auth>'
  -d '{
  "data": {
    "amount": 29.99,
    "currency": "USD"
  }
}'

 Example 200 Response 

{
  "expiration": "2018-09-18T15:43:05.664Z",
  "fraudUrl": "https://api.nexiopaysandbox.com/pay/v3/fingerprint?token=01080f80-76b8-4363-845d-67e8623bf170",
  "token": "830d36f6-a5e3-4455-9600-3a55b63e2fc2"
}

4. Copy or Store the Token From the Above Response

   This is your one-time-use token. It will be used in the next step.

   Notes:

   • Each one-time-use token expires after one hour
   • Each one-time-use token can only be used to submit a single form
   • Any iframe uiOptions or processingOptions must be included in this step

5. Load the Iframe

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

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

   Notes:

   • If an error occurs while loading an iframe, the endpoint will return a JSON object with the error message
   • To receive an HTML response instead, include shouldReturnHtml=true as a query parameter, as in the example above

Example

var iframeBaseUrl = "https://api.nexiopaysandbox.com/pay/v3";
var oneTimeUseToken = "?token=ec53cd46-cee5-44db-a20f-f5c373a44fd2";
var returnHtml = "&shouldReturnHtml=true";
var url = iframeBaseUrl + oneTimeUseToken + returnHtml;
window.document.getElementById('myIframe').src = url;

6. 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 submit on your outer form, the iframe will submit itself. Because of the event listener you created in step 2, your code is aware of iframe responses and errors.

Example

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
});

With Your Own Form

1. Save a Card Token

   Before you can run a transaction using your own form you must save a card token.

   You may save a card token with your own form, with the Nexio Save Card Token iframe, or directly through the API.

2. Create a Form on Your Web Page

Example

<html>
    <form id="myForm">
    </form>
</html>

3. Collect Payment Information

   You may collect some information from the user (such as first and last name, address, etc.) through the form you created in step 2. Other information may be predefined by your site (such as amount, currency, etc.).

   The following information is required by Nexio:

   • Amount (data.amount)
   • Currency (data.currency)
   • Card Token (tokenex.token) This is a previously saved card token

   See the Run Card Transaction endpoint reference for a complete list of possible parameters.

4. Send Payment Information to Your Server

5. Post Payment Information to Nexio

   Send a POST request from your server to Nexio's Run Card Transaction API endpoint with the payment information.

   Note: You will be required to authenticate via basic authentication.

Example Request

curl -X POST https://api.nexiopaysandbox.com/pay/v3/process \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic <Your Basic Auth>'
  -d '{
  "data": {},
  "tokenex": {
    "token": "6ee140a0-05d1-4958-8325-b38a690dbb9d"
  }
}'

6. Create a Receipt for the Customer

   Listen for Nexio's response. Use the response to create a success (such as a receipt) or failure page to the customer. You may also wish to send a receipt to the customer via email.

Create a Save Card Page

With the Nexio Iframe

1. Create an Iframe on your Web Page

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.

Example

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

3. Request a One-time-use Token

   Send a POST request to the One-time-use Token (E-commerce) endpoint.

Example Request

curl -X POST https://api.nexiopaysandbox.com/pay/v3/token \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic <Your Basic Auth>'
  -d '{}'

 Example 200 Response 

{
  "expiration": "2018-09-18T15:43:05.664Z",
  "fraudUrl": "https://api.nexiopaysandbox.com/pay/v3/fingerprint?token=01080f80-76b8-4363-845d-67e8623bf170",
  "token": "830d36f6-a5e3-4455-9600-3a55b63e2fc2"
}

4. Copy or Store the Token From the Above Response

   This is your one-time-use token. It will be used in the next step.

   Notes:

   • Each one-time-use token expires after one hour
   • Each one-time-use token can only be used to submit a single form
   • Any iframe uiOptions or processingOptions must be included in this step

5. Load the Iframe

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

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

   Notes:

   • If an error occurs while loading an iframe, the endpoint will return a JSON object with the error message
   • To receive an HTML response instead, include shouldReturnHtml=true as a query parameter, as in the example above

Example

var iframeBaseUrl = "https://api.nexiopaysandbox.com/pay/v3/saveCard";
var oneTimeUseToken = "?token=ec53cd46-cee5-44db-a20f-f5c373a44fd2";
var returnHtml = "&shouldReturnHtml=true";
var url = iframeBaseUrl + oneTimeUseToken + returnHtml;
window.document.getElementById('myIframe').src = url;

6. 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 submit on your outer form, the iframe will submit itself. Because of the event listener you created in step 2, your code is aware of iframe responses and errors.

Example

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
});

With Your Own Form

Please note that although card data never touches your servers, using your own form changes your PCI liability from SAQ A to SAQ A-EP.

1. Create a Form on Your Web Page

Example

<html>
    <form id="myForm">
    </form>
</html>

2. Add Fields to Your Form

   The following fields are required by Nexio:

   • Cardholder name (card.cardHolderName)
   • Expiration month (card.expirationMonth)
   • Expiration year (card.expirationYear)
   • Card number (card.encryptedNumber) (Your form will accept the full credit card number, which you will then encrypt prior to sending it to Nexio—see step 5)

   You may include any fields listed in the Save Card Token endpoint reference.

3. Load the Form

   Load the form on your page and allow the user to enter their information.

4. Validate the Card Number

   Outside of the Nexio Iframe we are unable to validate card numbers for you.

   Use the Luhn algorithm to make sure the user has typed their card number correctly.

5. Encrypt the Card Number

   Prior to sending the card information to Nexio, you must encrypt it using browser-based encryption. To do so, follow the steps below.

   a. Contact us to obtain the public key. While testing in the sandbox environment, you may use the sandbox public key, shown below.

Sandbox Public Key

MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAvWpIQFjQQCPpaIlJKpeg
irp5kLkzLB1AxHmnLk73D3TJbAGqr1QmlsWDBtMPMRpdzzUM7ZwX3kzhIuATV4Pe
7RKp3nZlVmcrT0YCQXBrTwqZNh775z58GP2kZs+gVfNqBampJPzSB/hB62KkByhE
Cn6grrRjiAVwJyZVEvs/2vrxaEpO+aE16emtX12RgI5JdzdOiNyZEQteU6zRBRJE
ocPWVxExaOpVVVJ5+UnW0LcalzA+lRGRTrQJ5JguAPiAOzRPTK/lYFFpCAl/F8wt
oAVG1c8zO2NcQ0Pko+fmeidRFxJ/did2btV+9Mkze3mBphwFmvnxa35LF+Cs/XJHDwIDAQAB

b. Encrypt the card number using the public key and standard RSA encryption. See this JSFiddle for an example of how to encrypt data to be tokenized.

Note: If you want to store the token in your own database you must either use a callback or use the token returned in the event info.

If you do not perform browser-based encryption in the card holder's browser, you have full PCI liability.

6. Send Card Information to Your Server

   Send the encrypted card number and other card information to your server.

7. Post Card Information to Nexio

   a. Request a one-time-use token

   b. Send a POST request from your server to Nexio's Save Card Token API endpoint with the one-time-use token and the card information.

Example Request

curl -X POST https://api.nexiopaysandbox.com/pay/v3/saveCard \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic <Your Basic Auth>'
  -d '{
  "card": {
    "cardHolderName": "John H Doe",
    "encryptedNumber": "cu3yRktaYFK2LUC6DpNK289tYDsGRCi7cO+GeG0hkeYFvT7Y8/oY5r53obMz6Q/BZ38gk2u2Ufwy8ojBcX2sfNjG5jplGTXA4NNlSIUjMFfiHe1sff1JFpThoiW/IIlifGlbWu+S1/9pqWPTzJ2+DcjwohbHzsDahhYewFhXgC8qsK0ypi/Shlp+CwRITyIvbVXESD0xz3YOTRHeZLlChvVqN8z4ZzN8nm0MXkmT1wcpYI73bH4KdnPwNU3s7XxvP/ernQP73SHHAOKSLlz4F6AEHFjJiCoXzeLF7LwEjRdxDJ0sKVXbRk3i9BGh+8Nle2VYgjpUWtk2763QkvZiQQ==",
    "expirationMonth": "12",
    "expirationYear": "20"
  },
  "token": "eb50a022-d6de-4244-a1e6-dcb8522b2d19"
}'

8. Listen for Nexio's Response

   If Nexio returns a 200 status:

   • Display a success page to the customer
   • Save the card token (tokenex.token). You will need this token to run a transaction as well as to view, edit or delete the card token

   If Nexio returns a non-200 status:

   • Display a failure page to the customer
   • Handle the error. See our list of common errors for more information
   • Contact integration support if you need additional help

Create an E-check Checkout Page

Create a checkout page for e-check (ACH) transactions, either by using the Nexio Iframe or with your own form.

Please note that e-check transactions cannot be voided or refunded.

With the Nexio Iframe

1. Create an Iframe on Your Web Page

Example

<html>
    <iframe id="myIframe">
    </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.

Example

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

3. Request a One-time-use Token

   Send a POST request to the E-commerce One-time-use Token endpoint.

Example Request

curl -X POST https://api.nexiopaysandbox.com/pay/v3/token \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic <Your Basic Auth>'
  -d '{
  "data": {
    "amount": 29.99,
    "currency": "USD"
  }
}'

 Example 200 Response 

{
  "expiration": "2018-09-18T15:43:05.664Z",
  "fraudUrl": "https://api.nexiopaysandbox.com/pay/v3/fingerprint?token=01080f80-76b8-4363-845d-67e8623bf170",
  "token": "830d36f6-a5e3-4455-9600-3a55b63e2fc2"
}

4. Copy or Store the Token From the Above Response

   This is your one-time-use token. It will be used in the next step.

   Notes:

   • Each one-time-use token expires after one hour
   • Each one-time-use token can only be used to submit a single form
   • Any iframe uiOptions or processingOptions must be included in this step

5. Load the Iframe

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

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

   Notes:

   • If an error occurs while loading an iframe, the endpoint will return a JSON object with the error message
   • To receive an HTML response instead, include shouldReturnHtml=true as a query parameter, as in the example above

Example

var iframeBaseUrl = "https://api.nexiopaysandbox.com/pay/v3/processECheck";
var oneTimeUseToken = "?token=ec53cd46-cee5-44db-a20f-f5c373a44fd2";
var returnHtml = "&shouldReturnHtml=true";
var url = iframeBaseUrl + oneTimeUseToken + returnHtml;
window.document.getElementById('myIframe').src = url;

6. 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 submit on your outer form, the iframe will submit itself. Because of the event listener you created in step 2, your code is aware of iframe responses and errors.

Example

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
});

With Your Own Form

1. Save an E-check Token (Optional)

   Before you run an e-check transaction using your own form you may save an e-check token or you may accept the bank information in step 3.

   You may save an e-check token with your own form, with the Nexio Save E-check Token iframe, or directly through the API.

2. Create a Form on Your Web Page

Example

<html>
    <form id="myForm">
    </form>
</html>

3. Collect Payment Information

   You may collect some information from the user (such as first and last name, address, etc.) through the form you created in step 2. Other information may be predefined by your site (such as amount, currency, etc.).

   The following information is required by Nexio:

   • Amount (data.amount)
   • Currency (data.currency)

   Either of the following is also required:

   • E-check token (tokenex.token) This is a previously saved e-check token
   • Bank account information:
     • Account holder name (bank.accountHolderName)
     • Routing number (bank.routingNumber)
     • Account number (bank.encryptedBankAccountNumber)

   See the Run E-check Transaction endpoint reference for a complete list of possible parameters.

4. Send Payment Information to Your Server

5. Post Payment Information to Nexio

   Send a POST request from your server to Nexio's Run E-check Transaction API endpoint with the payment information.

   Note: You will be required to authenticate via basic authentication.

Example Request

curl -X POST https://api.nexiopaysandbox.com/pay/v3/processECheck \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic <Your Basic Auth>'
  -d '{
  "data": {
    "amount": 29.99,
    "currency": "USD"
  },
  "tokenex": {
    "token": "aafb1033-599a-4392-859e-f98033fc37f5"
  }
}'

6. Create a Receipt for the Customer

   Listen for Nexio's response. Use the response to create a success (such as a receipt) or failure page to the customer. You may also wish to send a receipt to the customer via email.

Create a Save E-check Page

With the Nexio Iframe

1. Create an Iframe on your Web Page

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.

Example

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

3. Request a One-time-use Token

   Send a POST request to the One-time-use Token (E-commerce) endpoint.

Example Request

curl -X POST https://api.nexiopaysandbox.com/pay/v3/token \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic <Your Basic Auth>'
  -d '{}'

 Example 200 Response 

{
  "expiration": "2018-09-18T15:43:05.664Z",
  "fraudUrl": "https://api.nexiopaysandbox.com/pay/v3/fingerprint?token=01080f80-76b8-4363-845d-67e8623bf170",
  "token": "830d36f6-a5e3-4455-9600-3a55b63e2fc2"
}

4. Copy or Store the Token From the Above Response

   This is your one-time-use token. It will be used in the next step.

   Notes:

   • Each one-time-use token expires after one hour
   • Each one-time-use token can only be used to submit a single form
   • Any iframe uiOptions or processingOptions must be included in this step

5. Load the Iframe

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

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

   Notes:

   • If an error occurs while loading an iframe, the endpoint will return a JSON object with the error message
   • To receive an HTML response instead, include shouldReturnHtml=true as a query parameter, as in the example above

Example

var iframeBaseUrl = "https://api.nexiopaysandbox.com/pay/v3/saveECheck";
var oneTimeUseToken = "?token=ec53cd46-cee5-44db-a20f-f5c373a44fd2";
var returnHtml = "&shouldReturnHtml=true";
var url = iframeBaseUrl + oneTimeUseToken + returnHtml;
window.document.getElementById('myIframe').src = url;

6. 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 submit on your outer form, the iframe will submit itself. Because of the event listener you created in step 2, your code is aware of iframe responses and errors.

Example

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
});

With Your Own Form

Please note that although bank data never touches your servers, using your own form changes your PCI liability from SAQ A to SAQ A-EP.

1. Create a Form on Your Web Page

Example

<html>
    <form id="myForm">
    </form>
</html>

2. Add Fields to Your Form

   The following fields are required by Nexio:

   • Account holder name (bank.accountHolderName)
   • Routing number (bank.routingNumber)
   • Account number (bank.encryptedBankAccountNumber) (Your form will accept the full account number, which you will then encrypt prior to sending it to Nexio—see step 4)

   You may include any fields listed in the Save E-check Token endpoint reference.

3. Load the Form

   Load the form on your page and allow the user to enter their information.

4. Encrypt the Bank Account Number

   Prior to sending the bank information to Nexio, you must encrypt it using browser-based encryption. To do so, follow the steps below.

   a. Contact us to obtain the public key. While testing in the sandbox environment, you may use the sandbox public key, shown below.

Sandbox Public Key

MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAvWpIQFjQQCPpaIlJKpeg
irp5kLkzLB1AxHmnLk73D3TJbAGqr1QmlsWDBtMPMRpdzzUM7ZwX3kzhIuATV4Pe
7RKp3nZlVmcrT0YCQXBrTwqZNh775z58GP2kZs+gVfNqBampJPzSB/hB62KkByhE
Cn6grrRjiAVwJyZVEvs/2vrxaEpO+aE16emtX12RgI5JdzdOiNyZEQteU6zRBRJE
ocPWVxExaOpVVVJ5+UnW0LcalzA+lRGRTrQJ5JguAPiAOzRPTK/lYFFpCAl/F8wt
oAVG1c8zO2NcQ0Pko+fmeidRFxJ/did2btV+9Mkze3mBphwFmvnxa35LF+Cs/XJHDwIDAQAB

b. Encrypt the account number using the public key and standard RSA encryption. See this JSFiddle for an example of how to encrypt data to be tokenized.

Note: If you want to store the token in your own database you must either use a callback or use the token returned in the event info.

If you do not to perform browser-based encryption in the card holder's browser you have full PCI liability.

6. Send Bank Information to Your Server

   Send the encrypted bank account number and other bank information to your server.

7. Post Bank Information to Nexio

   a. Request a one-time-use token

   b. Send a POST request from your server to Nexio's Save E-check Token API endpoint with the one-time-use token and the bank information.

Example Request

curl -X POST https://api.nexiopaysandbox.com/pay/v3/saveECheck \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic <Your Basic Auth>'
  -d '{
  "bank": {
    "accountHolderName": "John Doe",
    "routingNumber": "231375151"
  },
  "token": "830d36f6-a5e3-4455-9600-3a55b63e2fc2"
}'

8. Listen for Nexio's Response

   If Nexio returns a 200 status:

   • Display a success page to the customer
   • Save the e-check token (tokenex.token). You will need this token to run a transaction as well as to view, edit or delete the card token

   If Nexio returns a non-200 status:

   • Display a failure page to the customer
   • Handle the error. See our list of common errors for more information
   • Contact integration support if you need additional help

More

Save a Card Token With the Nexio API

1. Configure your Account

   Contact integrations@nexiopay.com to ensure your merchant ID and account have access to the proper API endpoint. (You may be asked to provide additional information such as Gateway, TokenEx, or Kount credentials.)

2. Request a One-time-use Token

   Send a POST request to the One-time-use Token endpoint. (Do not include any card information or other body parameters—you will do that in step 3.)

   Copy or store the token from Nexio's response. It will be used in the next step.

Example Request

curl -X POST https://api.nexiopaysandbox.com/pay/v3/token \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic <Your Basic Auth>'
  -d '{}'

 Example 200 Response 

{
  "expiration": "2018-09-18T15:43:05.664Z",
  "fraudUrl": "https://api.nexiopaysandbox.com/pay/v3/fingerprint?token=01080f80-76b8-4363-845d-67e8623bf170",
  "token": "830d36f6-a5e3-4455-9600-3a55b63e2fc2"
}

3. Post Card Information to Nexio

   Send a POST request to the Save Card Token endpoint. Include the token from step 2 and the card information in the body of your request.

Example Request

curl -X POST https://api.nexiopaysandbox.com/pay/v3/saveCard \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic <Your Basic Auth>'
  -d '{
  "card": {
    "cardHolderName": "John H Doe",
    "encryptedNumber": "cu3yRktaYFK2LUC6DpNK289tYDsGRCi7cO+GeG0hkeYFvT7Y8/oY5r53obMz6Q/BZ38gk2u2Ufwy8ojBcX2sfNjG5jplGTXA4NNlSIUjMFfiHe1sff1JFpThoiW/IIlifGlbWu+S1/9pqWPTzJ2+DcjwohbHzsDahhYewFhXgC8qsK0ypi/Shlp+CwRITyIvbVXESD0xz3YOTRHeZLlChvVqN8z4ZzN8nm0MXkmT1wcpYI73bH4KdnPwNU3s7XxvP/ernQP73SHHAOKSLlz4F6AEHFjJiCoXzeLF7LwEjRdxDJ0sKVXbRk3i9BGh+8Nle2VYgjpUWtk2763QkvZiQQ==",
    "expirationMonth": "12",
    "expirationYear": "20"
  },
  "token": "eb50a022-d6de-4244-a1e6-dcb8522b2d19"
}'

Run a Transaction With the Nexio API

Authorize and Capture

To authorize and capture a transaction using the API, follow the steps below:

1. Configure Your Account

   Contact integration support to ensure your merchant ID and account have access to the proper API endpoint. (You may be asked to provide additional information such as Gateway, TokenEx, or Kount credentials.)

2. Save a Card Token

   This may be done directly through the API, through your own form, or using the Nexio Save Card iframe.

3. Post Payment Information to Nexio

   Post payment details along with the card token to the Run Card Transaction endpoint.

Example Request

curl -X POST https://api.nexiopaysandbox.com/pay/v3/process \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic <Your Basic Auth>'
  -d '{
  "data": {},
  "tokenex": {
    "token": "6ee140a0-05d1-4958-8325-b38a690dbb9d"
  }
}'

Authorize Only

To authorize a transaction using the API, follow the steps below:

1. Configure Your Account

   Contact integration support to ensure your merchant ID and account have access to the proper API endpoint. (You may be asked to provide additional information such as Gateway, TokenEx, or Kount credentials.)

2. Save a Card Token

   This may be done directly through the API, through your own form, or using the Nexio Save Card iframe.

3. Post Payment Information to Nexio

   Post payment details along with the card token to the Run Card Transaction endpoint.

   Include the parameter isAuthOnly: true in the body of your request.

Example Request

curl -X POST https://api.nexiopaysandbox.com/pay/v3/process \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic <Your Basic Auth>'
  -d '{
  "data": {},
  "tokenex": {
    "token": "6ee140a0-05d1-4958-8325-b38a690dbb9d"
  },
  "isAuthOnly": true
}'

Save an E-check Token With the Nexio API

1. Configure your Account

   Contact integrations@nexiopay.com to ensure your merchant ID and account have access to the proper API endpoint. (You may be asked to provide additional information such as Gateway, TokenEx, or Kount credentials.)

2. Request a One-time-use Token

   Send a POST request to the One-time-use Token endpoint. (Do not include any bank information or other body parameters—you will do that in step 3.)

   Copy or store the token from Nexio's response. It will be used in the next step.

Example Request

curl -X POST https://api.nexiopaysandbox.com/pay/v3/token \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic <Your Basic Auth>'
  -d '{}'

 Example 200 Response 

{
  "expiration": "2018-09-18T15:43:05.664Z",
  "fraudUrl": "https://api.nexiopaysandbox.com/pay/v3/fingerprint?token=01080f80-76b8-4363-845d-67e8623bf170",
  "token": "830d36f6-a5e3-4455-9600-3a55b63e2fc2"
}

3. Post Bank Information to Nexio

   Send a POST request to the Save E-check Token endpoint. Include the token from step 2 and the card information in the body of your request.

Example Request

curl -X POST https://api.nexiopaysandbox.com/pay/v3/saveECheck \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic <Your Basic Auth>'
  -d '{
  "bank": {
    "accountHolderName": "John Doe",
    "routingNumber": "231375151"
  },
  "token": "830d36f6-a5e3-4455-9600-3a55b63e2fc2"
}'

Run an E-check Transaction With the Nexio API

1. Configure Your Account

   Contact integration support to ensure your merchant ID and account have access to the proper API endpoint. (You may be asked to provide additional information such as Gateway, TokenEx, or Kount credentials.)

2. Save an E-check Token

   This may be done directly through the API, through your own form, or using the Nexio Save E-check iframe.

3. Post Payment Information to Nexio

   Post payment details along with the card token to the Run E-check Transaction endpoint.

Example Request

curl -X POST https://api.nexiopaysandbox.com/pay/v3/processECheck \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic <Your Basic Auth>'
  -d '{
  "data": {
    "amount": 29.99,
    "currency": "USD"
  },
  "tokenex": {
    "token": "aafb1033-599a-4392-859e-f98033fc37f5"
  }
}'

Overview

Nexio's Retail platform allows you to seamlessly integrate checkout and save card pages into your company's software, all while limiting your PCI scope.

Nexio's Retail payment forms can be accessed at https://retail.nexiopay.com.

Nexio's Retail iframes enable you to:

• Save Card: Save a credit or debit card token for use in recurring billing or one-time payments
• Run Transaction: Process a credit or debit card transaction by keying in the card number or using a terminal

You can also choose to enable built-in fraud protection services, including:

• Address Verification Service (AVS)
• Security Code (CVC) Verification
• Kount Verification

Authentication

Simple Login

Simple Login allows trusted users to proceed directly to the retail/MOTO Iframe without the necessity of entering a Nexio username and password. This option is useful for cases in which multiple users will be using a single Nexio account. It can also save time for internal users by eliminating the need to enter a username and password upon each login. To use Simple Login:

1. Request a Simple Login Key

   Send a request to the Simple Login endpoint. A successful request will return a response with the following shape:

 Example 200 Response 

{
  "exp": 1550600014,
  "jwt": "t3jraWQiOiI3V2JrOFdSVVliMVljR2p3Mlhwd2swR3lIRWt6THcwVDRqckVhNVVVTjBnPSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiI4YWYzZTQwZC02Y2I0LTQ0ZWQtOWRlZS0yN2Y3NmNmNDc0YmMiLCJlbWFpbF92ZXJpZmllZCI6dHJ1ZSwiaXNzIjoiaHR0cHM6XC9cL2NvZ25pdG8taWRwLnVzLWVhc3QtMS5hbWF6b25hd3MuY29tXC91cy1lYXN0LTFfVlVEN21MeWNqIiwiY3VzdG9tOmFjY291bnRJZCI6ImVjN2NiOWJhLWQwMmQtNDhkYS1hY2I3LWI2ZWQ3YmJiZWQwMiIsImNvZ25pdG86dXNlcm5hbWUiOiJscm9ibGVkb0BjbXNvbmxpbmUuY29tIiwiYXVkIjoiNDBtZWQ2YnNybDZ1aWpnMmpmZzQwcmJzOGkiLCJldmVudF9pZCI6IjE0YmU5MWFjLTM0NjctMTFlOS9iNDZjLWMxMjdjYTkzZjA3NCIsInRva2VuX3VzZSI6ImlkIiwiYXV0aF90aW1lIjoxNTUwNTk1Mjk0LCJleHAiOjE1NTA1OTg4OTRsImN1c3RvbTphY2Nlc3NSaWdodHMiOiJ7XCJtZXJjaGFudElkc1wiOntcIjEwMDAzOVwiOlwiQVwiLFwiMTAwMDQxXCI6XCJBXCIsXCI1MTU3OTQwMDAwMTM1MDRcIjpcIkFcIixcIjkyMzYwMDAwMTEyNDUwM1wiOlwiQVwiLFwiOTIzNTAwMDAxNDMyNzQyXCI6XCJBXCIsXCI1MTM0ODUwMDAwMDAwMThcIjpcIkFcIixcIjkyMzYwMDAwODEyNjYxMFwiOlwiQVwiLFwiOTIzNjAwMDAzMTYzODEwXCI6XCJBXCJ9LFwicm9sZVwiOlwiQVwifSIsImlhdCI6MTU1MDU5NTI5NCwiZW1haWwiOiJscm9ibGVkb0BjbXNvbmxpbmUuY29tIn0.OEEZarSzbSLpxUM55UKmycYtAAWEtm__XUJdqBJ9QPSF_8sdLIL9EXBF8cLarhv3DoLqeWKUpieNgfcME2IsIc8amDXitvJtJe3STQtI_zaJwAibBxJhFKQRLRCrIe3kpslVJPuw3OeST54QcseifLlA64bxNaveXygja7aejwINueE4_Nj0NEzcFGZoYHgNB6br6Ksbjgx-z_SiFIZ1XHS-eOMnBoCIVWjFr3FY9IbfnQf4v0c0AFWKt9mOpjYracSqOHHmSER7GuaMBNrHxfbe0kHVh6hvnrzh10SEnTsF573qbP1R_aZA_Uh80MOLB0UvPWWFzzyP4GniNc3zLw",
  "key": "4f211fde-d135-4c91-afbc-bcdb73c0c504",
  "refreshToken": "t3jjdHkiOiJKV1QiLCJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiUlNBLU9BRVAifQ.CejuLZHvZcrISuiwE7N4xg7EYq6ArivbyNwDVE2X7eTdr7CTO4l5udgc9ZUV1byTe1r3eLN_szbte1nlaimbQj5ZcJpim1zmW5pkk7aFVF-WcnLjIBVPilp6bLW8gsZaB04WErDjwzt4r7Bxnz6YnmLM7e3V15ZVkY6GLFqgrUF9Tb9UOFbCDD_H8qe1AdFktVeeVgefekJew3RuZ8p2BnKWejt1BcyMUnYY-QgaLm3TzUpd14PRbdvOfBG3D9KmJCnZ_6H9sQ5FUirqsF_U6eXNppE1QXZdjhFg4oic791Kq5rXU2xbMI9ggeFoGIjLLP0Keb0iT66NwXpf50-h4w.eUOjohgz3zXTJWHH.IBQMMiNKtbAZ02r0QGXJXw_zM2c3epH5LGtdZxIVUReMRr5CLm-ptE7zaFTK0D1tpUHcVonqiDuXyc09IN0IO4jL32QqQjgeG-V9LBYgpr1xV3qyc5TR-L2VNHjJt3A3SbJsIzxHDqKLucJw2N0WaiOgLb577q8B8lu0pLCpOV_POlUiT4BLAvycMCKkgUCDrejyjzR39ofCUqtZKuMglXanUfVE3hC0OaNOMpl65N_utjuf9vzklyZZRQMTgokQ7V0yp0VSpCC6D_zNBvwTPUKHVFyMrzEC4wJZ9uOtIS9h9rv_HywpwrPqHYajsGYNrv7QvHE1Kg80I73CbL0owW-J5bKEbgImqkahNVhBoFJejnvN3PEr9zthNey15Q_utOUFUkR0Po9GH6fnXFXxQnIC7c2hQ4lgjV2wR3WGzEiE5L0aNLF1Cnjyn-t1VZxQHG2uiyiT1aIUFBPbItTkVPjKhkFKf7AfXqOTAl52VFdBPpFdbG5Ecwfm_4ZGgO_4KJnLcb7qMQuEI6G20xelkPD2NHIpdS9gHx7XIlyfiBPkvq3YEKMtOQQbRAQ_Hcy7leeZnSyPgq65Bnsn22xZ4NG5bSshSEEMlq5lbOV4-dzBGV8SA6dOeNHR7GeQvSr1XQ89sBloJlMKJLe9WL0fYhkY6u-MbmecvMoU1OrC4mvIv-0l53TIeeGDMtn8UkcaSxQG7HBEqcQlvaFAxGaol7kiDPlAMxdp11lnk0ix3G0M74xHRFpZalIFtUAPm2xEVFJLWlwLqalRgJpO70asiw9QJ_pi0HERT5N_wCXraxeQyNrknNmi157ih5yP7SGm7MXrSVUOHu6GIBZktAfP8IURhJNQZfSk3Do_up1vUBPN7yLNumqPq2PWH3CgFXle3nDaQYCVsVkGU-FZTy7KLIbKc2EStkOFOCPiYYSoD8h1-C8kclCeIKFLDFQIo7weJyIGjQqV_pY9HEPQivgXw6X1ti711x0YZ2bhl9tPuUEtXeja7hGAxLnrU4QqHr2iS58J9F5NMVc6LlK_NcExLzrlnQBJws7urmDkV_yoOtCRadxVuAxVCYqfAh8X4gzQ7LQMT27pFeV98iCvAmkhWx4RpAmFYHmacUJIXUVXKe6eTlN27gsYir1H9SrkbFgjOjvoUBj5p-mn-mMathsdAbRtlryJEjfCzAfBWis-7d4GsxCZGQnCJ0NezIP50_2dCPyzpgYcUwt4E4kHIA5-SBOLWneULDPz7VpRJxKv8BaYxOZuotnV2zz2nwB3vlDWK1h6cgRfMT8o8iphcUMxdZdjd-FElzNCdQ.SDQXbyIYZu6_jdCeAzTzoA",
  "username": "youremail@cmsonline.com"
}

2. Load the Retail Iframe

   Take the key from the above response and use it as a query parameter to send a request to Nexio's retail iframe endpoint:

Example

https://retail.nexiopaysandbox.com/?simpleLogin=4f211fde-d135-4c91-afbc-bcdb73c0c504

Notes:

• Each key can only be used once and will expire after one hour
• The iframe may also be used without Simple Login by going to https://retail.nexiopaysandbox.com and logging in with your Nexio username and password

Create a Retail Save Card Page

1. Authenticate

   You may authenticate through either of the following options:

   • By using Simple Login
   • By going to https://retail.nexiopaysandbox.com and entering your Nexio credentials where prompted

2. Load the Iframe

   Append the setting { "uiOptions" : { "saveCard": true } } to Nexio's Retail Iframe URL.

   See the examples below:

Save Card Iframe with Simple Login

https://retail.nexiopaysandbox.com/?simpleLogin=4f211fde-d135-4c91-afbc-bcdb73c0c504&settings={%22uiOptions%22:{%22saveCard%22:true} }

Save Card Iframe without Simple Login

https://retail.nexiopaysandbox.com/?settings={%22uiOptions%22:{%22saveCard%22:true} }

3. Enter the Card Information
4. Click 'Save Card'

Run a Keyed Transaction

1. Authenticate

   You may authenticate through either of the following options:

   • By using Simple Login
   • By going to https://retail.nexiopaysandbox.com and entering your Nexio credentials where prompted

2. Load the Iframe

   • The run transaction iframe will load by default
   • You may also select additional UI options as shown in the table below

   See the examples below:

Run Transaction Iframe with Simple Login

https://retail.nexiopaysandbox.com/?simpleLogin=4f211fde-d135-4c91-afbc-bcdb73c0c504

Run Transaction Iframe without Simple Login

https://retail.nexiopaysandbox.com/

3. Select ‘Card (keyed)’ in the Payment Method Dropdown

   Note: If you do not see the Payment Method dropdown, your account does not yet have a terminal registered. If this is the case, contact Nexio Integrations for help getting registered with a terminal, then continue to step 4.

4. Enter or Confirm the Amount

5. Key in Card Information

6. Click ‘Pay $X.XX’

7. Create a Receipt

   The iframe will display a simple success page—it does not generate a default receipt. Use our response to create a success/confirmation page and your own receipt.

Process a Transaction with a Terminal

Nexio's API allows you to process card present (EMV) transactions using a terminal.
Follow the steps below, depending on your gateway.

• USAePay
• Zeamster

USAePay

In order to process a card present transaction with a terminal through USAePay, you need to set up your terminal and then pair it and process the transaction either via iframe or via API.

Setup Terminal for Pairing

Set up your terminal for pairing.

Note: After you have completed these steps once, you do not need to complete them again unless you want to change the terminal mode or reconfigure the internet connection.

1. Power on the terminal.

   • If the terminal is not connected to the internet and is not paired, the main menu displays
   • If the terminal is connected to the internet and is not paired, the pairing screen displays.
     Exit the pairing screen by pressing the red button until the main menu displays

2. From the main menu, press the correct buttons to go to Settings and then Mode Select. A menu with options for Production and SANDBOX displays.

3. Select the mode.

   • If you are processing test transactions, select SANDBOX. An icon of a flask displays in the upper-left corner of the main menu screen
   • If you are processing live transactions, select Production

   After you select the mode, the system returns you to the Settings menu.

4. From the Settings menu, select Connection Type. A menu with options for WiFi and Ethernet displays.

5. Select WiFi or Ethernet.

   • If you select WiFi, return to the Settings menu by pressing the red button and select Rescan WiFi. When the terminal finds your desired network, select it and type the password. After you have connected to the WiFi, if the terminal is rebooted, it connects to the chosen network automatically
   • If you select Ethernet and the cable is plugged in, the terminal is ready for pairing. Press the red button to get to the main screen

6. From the main screen, press the red button to get to the pairing screen.

You have successfully set up your terminal. Now that your terminal is connected to the internet, you can pair it and process a transaction via iframe or via API.

Pair terminal via iframe

In order to pair your terminal using Nexio's retail iframe, you must have completed setup.

Note: After pairing completes, the connection is permanent until the device is unpaired or the pairing is removed in the USAePay portal.

1. Authenticate through either of the following options:

   • By using Simple Login
   • By going to https://retail.nexiopaysandbox.com and entering your Nexio credentials where prompted

2. Load the retail iframe.

   • The retail iframe loads by default
   • You may also select additional UI options as shown in the UI options table

3. From the Payment Method menu of the iframe, select Card (terminal).

4. Click Add Terminal at the bottom of the iframe to open the Add Terminal dialog.

5. Type the terminal name you want to use. If the name is longer than 12 characters, the terminal only displays 12 characters after the name is saved.

6. Click Submit to save the name and close the dialog.

7. Type the pairing code that appears in the iframe into your terminal.

8. Wait until the iframe displays "Pairing Complete".

Now that you have paired your terminal via iframe, you can process a transaction by following the process below.

Process transaction via iframe

In order to process a transaction via iframe, you must have completed setup and paired your terminal via iframe.

1. Authenticate through either of the following options:
   • By using Simple Login
   • By going to https://retail.nexiopaysandbox.com and entering your Nexio credentials where prompted
2. Load the retail iframe.
   • The retail iframe loads by default
   • You may also select additional UI options as shown in the UI options table
3. From the Processing Account menu of the iframe, select the correct processing account.
4. From the Payment Method menu, select Card (terminal).
5. Select the correct value from the Currency menu.
6. Type the correct value in the Amount field.
7. From the Terminal menu, select the paired terminal you want to use. If the terminal you want to use does not appear in the Terminal menu, it may not be paired.
8. Click Submit to send the payment to the terminal.
9. Complete the transaction at the terminal. The response posts to the iframe.

Pair terminal via API

In order to pair your terminal using Nexio's retail iframe, you must have completed setup.

Note: After pairing completes, the connection is permanent until the device is unpaired or the pairing is removed in the USAePay portal.

1. Send a POST request to the Pair terminal endpoint. A successful request returns a response including a pairingCode.

   Example Request

   curl -X POST https://api.nexiopaysandbox.com/pay/v3/processFromTerminal \
     -H 'Content-Type: application/json' \
     -H 'Accept: application/json' \
     -H 'Authorization: Basic <Your Basic Auth>'
     -d '{
     "data": {
       "merchantId": "100111",
       "terminalName": "FrontDesk1"
   }'
   

   Example 200 Response

   [
     {
       "terminalName": "FrontDesk1",
       "pairingCode": 712677,
       "expirationDate": "2022-01-31T10:09:33.000Z",
       "key": "sa_a04ZF6U2J99wwvAOzHtMOVzOm9WSb",
       "random-4611765": "6fec4a03-3a9f-40de-90bc-23a513ac904c"
     }
   ]
   

   
   

2. Type the pairingCode from the response into the pairing screen of the terminal. If successful, the terminal displays the WELCOME screen and up to 12 characters of the terminalName.

3. Send a GET request to the View terminal list endpoint. A successful request returns an array of terminal objects. These are the terminals currently enabled on your merchant ID.

4. Confirm that the newly paired terminal is in the response.

   Example Request

   curl -X GET https://api.nexiopaysandbox.com/pay/v3/getTerminalList \
     -H 'Accept: application/json' \
     -H 'Authorization: Basic <Your Basic Auth>'
   

   Example 200 Response

   [
     {
       "merchantId": "100111",
       "merchantName": "Merchant Name",
       "gatewayName": "usaepay",
       "gatewayType": 10,
       "gatewayLabel": "...5tjb",
       "terminalName": "FrontDesk1",
       "terminalSerialNumber":"000118205206486",
       "terminalKey": "sa_a04ZF6U2J99wwvAOzHtMOVzOm9WSb",
       "terminalStatus": "connected",
       "terminalId": "eyJtZXJjaGFudElkIjoiMTAwODg4IiwiZ2F0ZXdheUxhYmVsIjoiLi4uNXRqYiIsInRlcm1pbmFsIjp7ImlkIjoic2FfYTA0WkY2VTJKOTl3d3ZBT3pIdE1PVnpPbTlXU2IiLCJsb2NhdGlvbklkIjoiZm40eHJ2YmRyZzNqN3QzMjgifX0="
     }
   ]
   

Process transaction via API

In order to process a transaction via API, you must have completed setup and paired your terminal via API.

1. Send a POST request with the transaction data and terminalId to the Process transaction from terminal endpoint. A successful request returns a terminalRequestStatus of initialized.

   Example Request

   curl -X POST https://api.nexiopaysandbox.com/pay/v3/processFromTerminal \
     -H 'Content-Type: application/json' \
     -H 'Accept: application/json' \
     -H 'Authorization: Basic <Your Basic Auth>'
     -d '{
     "data": {
       "amount": "13.45"
     },
     "terminalId": "eyJtZXJjaGFudElkIjoiMTAxMDM5IiwiZ2F0ZXdheUxhYmVsIjoiLi4uMmUyMSwuLi41ZWU3IiwidGVybWluYWwiOnsiaWQiOiIxMWU5MDIxMGNmZTdmNmFlOWVkNWUwYTgiLCJsb2NhdGlvbklkIjoiMTFlOGNkNmE4YjQ0YzUzZWFkNmFkY2UxIn19"
   }'
   

   Example 200 Response

   {
     "terminalRequestId": "8524beee-70f1-4890-9382-3d5bb8871a4c",
     "terminalRequestStatus": "initialized",
   
   }
   

   
   

2. After submitting the request to process from terminal, the terminal displays the amount that was in the request and an image indicating that it is ready for you to present the card.

3. Complete the transaction at the terminal.

4. Send a request to the View terminal transaction status endpoint as frequently as once per second until the terminalRequestStatus returns as success. You may see a pending status before the success status. This means that it was submitted but the transaction with the gateway is not complete.

Unpair the terminal

1. From the WELCOME screen, navigate to the main menu.
   • For the Vega3000 model, press and hold the 9 button for three seconds
   • For the MP200 model, press and hold the down arrow button for three seconds
2. Go to Settings.
3. Select Unpair Device.
4. Press the green button to confirm.

Zeamster

1. Request a Terminal List

   Send a GET request to the Get Terminal List endpoint. A successful request returns an array of terminal objects. These are the terminals currently enabled on your merchant ID.

   Example Request

   curl -X GET https://api.nexiopaysandbox.com/pay/v3/getTerminalList \
     -H 'Accept: application/json' \
     -H 'Authorization: Basic <Your Basic Auth>'
   

   Example 200 Response

   [
     {
       "gatewayLabel": "...2e21,...5ee7",
       "gatewayName": "yourGateway",
       "gatewayType": 110,
       "merchantId": "103002",
       "merchantName": "Test Merchant",
       "terminalId": "eyJtZXJjaGFudElkIjoiMTAxMDM5IiwiZ2F0ZXdheUxhYmVsIjoiLi4uMmUyMSwuLi41ZWU3IiwidGVybWluYWwiOnsiaWQiOiIxMWU5MDIxMGNmZTdmNmFlOWVkNWUwYTgiLCJsb2NhdGlvbklkIjoiMTFlOGNkNmE4YjQ0YzUzZWFkNmFkY2UxIn19",
       "terminalName": "Terminal 1",
       "terminalSerialNumber": "84937213"
     }
   ]
   

   
   

2. Copy the Terminal ID

   Copy the terminalId from the response above. You will use it in step 3.
   

3. Post Transaction Details

   Send a POST request with the transaction details and terminalId to the Process From Terminal endpoint.

   A successful response returns a terminalRequestId. You can use the terminalRequestId to check the status of the transaction.

   Example Request

   curl -X POST https://api.nexiopaysandbox.com/pay/v3/processFromTerminal \
     -H 'Content-Type: application/json' \
     -H 'Accept: application/json' \
     -H 'Authorization: Basic <Your Basic Auth>'
     -d '{
     "data": {
       "amount": "13.45"
     },
     "terminalId": "eyJtZXJjaGFudElkIjoiMTAxMDM5IiwiZ2F0ZXdheUxhYmVsIjoiLi4uMmUyMSwuLi41ZWU3IiwidGVybWluYWwiOnsiaWQiOiIxMWU5MDIxMGNmZTdmNmFlOWVkNWUwYTgiLCJsb2NhdGlvbklkIjoiMTFlOGNkNmE4YjQ0YzUzZWFkNmFkY2UxIn19"
   }'
   

   Example 200 Response

   {
     "terminalRequestId": "64ea267f-2766-49b8-9e0e-aeb91b2fe722",
     "terminalRequestStatus": "initialized"
   }
   

   
   

4. Check the Transaction Status (Optional)

   Send a GET request with the terminalRequestId to the Terminal Transaction Status endpoint.

   Example Request

   curl -X GET https://api.nexiopaysandbox.com/pay/v3/processFromTerminal/{terminalRequestId} \
     -H 'Accept: application/json' \
     -H 'Authorization: Basic <Your Basic Auth>'
   

   Example 200 Response

   {
     "gatewayResponse": {
       "gatewayName": "yourGateway"
     },
     "terminalRequestId": "64ea267f-2766-49b8-9e0e-aeb91b2fe722",
     "terminalRequestStatus": "initialized"
   }
   

More

Customize the Iframe

To customize the retail/MOTO iframe, include a settings object as a query parameter in your request to https://retail.nexiopaysandbox.com. You can include settings with or without a Simple Login key.

See the examples below:

Save Card Iframe without Simple Login

https://retail.nexiopaysandbox.com/?settings={%22uiOptions%22:{%22saveCard%22:true} }

Run Transaction Iframe with Simple Login and a Default Amount of $20

https://retail.nexiopaysandbox.com/?simpleLogin={key}&settings={%22processingOptions%22:{%22amountDefault%22:"20"} }

UI Options

Name	Description
amountSet	Prepopulates the amount field. User will not be able to change it
amountDefault	Prepopulates the amount field. User will be able to change it
amountMax	The maximum amount the user may enter into the amount field
hideAuthOnly	Hides or display the Auth Only Checkbox (default: true)
hideBilling	Hides or displays all billing fields (default: false)
limitCountriesTo	If this array is nonempty, the Country Dropdown field will be limited to the countries on the list. Note: These must be the two-character (Alpha-2) ISO country codes
merchantIdDefault	Prepopulates the merchant dropdown. User will be able to change it
merchantIdSet	Prepopulates the merchant dropdown. User will not be able to change it

3D Secure

3DS, or three-domain secure, helps prevent fraud by requiring cardholders to authenticate with their issuing bank when making online purchases. To comply with the PSD2’s Strong Customer Authentication (SCA) requirements, especially in regions where mandated, merchants should ensure transactions are properly authenticated prior to being processed with 3DS helping to fulfill those requirements.

Nexio uses 3DS 2.0 protocol whenever possible with 3DS 1.0 fallback enabled for cases where issuers do not yet support 2.0. When a transaction is attempted, card issuers use the transactional data provided to determine whether a challenge is required. If a challenge is issued, additional information from the cardholder will be needed, such as a password or one-time code received via a mobile device.

3DS through Nexio

The 3DS authentication workflow happens through a redirect provided by the cardholder’s issuing bank.

Nexio’s secure e-commerce iframe will prompt shoppers to confirm they are being redirected to their bank's page for authentication. Upon confirmation the iframe will open a new tab in which authentication will be completed.

Merchants using only the Nexio API to process transactions will need to handle the redirect separately. After the shopper completes the authentication, the transaction will be processed.

Use 3D Secure

You can enable 3DS using Nexio's e-commerce iframe or directly through the API.

Use 3D Secure with Nexio's E-commerce Iframe

1. Request a One-time-use Token

   Send a POST request to the E-commerce One-time-use Token endpoint.

Example Request

curl -X POST https://api.nexiopaysandbox.com/pay/v3/token \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic <Your Basic Auth>'
  -d '{
  "data": {
    "amount": 29.99,
    "currency": "USD"
  }
}'

 Example 200 Response 

{
  "expiration": "2018-09-18T15:43:05.664Z",
  "fraudUrl": "https://api.nexiopaysandbox.com/pay/v3/fingerprint?token=01080f80-76b8-4363-845d-67e8623bf170",
  "token": "830d36f6-a5e3-4455-9600-3a55b63e2fc2"
}

2. Load the Iframe

   Use the token from the response above to send a request to the GET Run Card Transaction Iframe endpoint:

Example Request

curl -X GET https://api.nexiopaysandbox.com/pay/v3?token=830d36f6-a5e3-4455-9600-3a55b63e2fc2 \
  -H 'Accept: application/json' \
  -H 'One-time-use Token: API_KEY'

3. Redirect and Complete the Transaction

   If the transaction requires 3DS authentication Nexio’s iframe will prompt shoppers to confirm they are being redirected for authentication. Upon confirmation the iframe will open a new tab in which authentication will be completed.

   Once users have successfully authenticated, the transaction will be attempted. Upon completion, the response will be returned as a message to the browser.

 Example 200 Response 

{
  "amount": 34.25,
  "authCode": "035410",
  "card": {...},
  "currency": "USD",
  "data": {...},
  "gatewayResponse": {...},
  "id": "eyJuYW1lIjoidXNhZXBheSIsInJlZk51bWJlciI6IjMxMDA5MDc4MTkiLCJtZXJjaGFudElkIjoiMTAwMDM5IiwicmFuZG9tIjoiMzEwMDkwNzgxOSIsImN1cnJlbmN5IjoiVVNEIn0=",
  "kountResponse": {...},
  "merchantId": "100039",
  "token": {...},
  "transactionDate": "2019-01-15T13:19:39.329Z",
  "transactionStatus": "pending",
  "transactionType": "sale"
}

Notes:

• The response schema will be the same as that of a standard POST request to the Run Card Transaction endpoint
• The page does not generate a default confirmation page. We recommend using our response to create your own confirmation page

Use 3D Secure with Nexio's API

1. Post Transaction Information

   Send a POST request to the Run Card Transaction endpoint. Include the parameter processingOptions.customerRedirectUrl in the body of your request. This is the URL to which the shopper will be redirected after completing the 3DS authentication.

Example Request

curl -X POST https://api.nexiopaysandbox.com/pay/v3/process \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic <Your Basic Auth>'
  -d '{
  "data": {},
  "tokenex": {
    "token": "6ee140a0-05d1-4958-8325-b38a690dbb9d"
  },
  "processingOptions": {
    "customerRedirectUrl": "https://your-ecommerce-website.example.com"
  }
}'

If the payment requires 3DS authentication, Nexio's response will include a redirectUrl.

Example 200 Response

{
    "status": "redirect",
    "message": "Provide redirect url to shopper to complete 3ds authentication and transaction",
    "redirectUrl": "https://api.nexiopaysandbox.com/pay/v3/threeDS/frame?token=4c0e5734-63f6-4ada-9fc5-e632109e2a77"
}

2. Redirect the User

   Display the redirectUrl from the response above in a browser. Shoppers will be prompted to confirm they are being redirected for authentication.

3. User Authenticates

   Once users have successfully authenticated, the transaction will be attempted. Upon completion, the user will be redirected to the customerRedirectUrl provided in step 1. The transaction id and status will be returned to the browser.

Example 200 Response

{
    "id": "eyJuYW1lIjoidXNhZXBheSIsInJlZk51bWJlciI6IjMxMDA5MDc4MTkiLCJtZXJjaGFudElkIjoiMTAwMDM5IiwicmFuZG9tIjoiMzEwMDkwNzgxOSIsImN1cnJlbmN5IjoiVVNEIn0=",
    "status": "pending"
}

Notes:

• The response schema will be the same as that of a standard POST request to the Run Card Transaction endpoint
• The page does not generate a default confirmation page. We recommend using our response to create your own confirmation page

3DS Requirements

Initial Transactions

Initial or first-time transactions may be subject to cardholder authentication depending on the merchant account and/or region. Nexio will provide transaction information to the gateway and respond to your system with a 3DS redirect URL where required. We recommend, therefore, that your system be equipped to handle any 3DS redirect returned by Nexio.

Nexio’s check3ds flag allows you to indicate whether your system is equipped to handle a 3DS redirect. If set to true, Nexio will return the redirect URL to you or prompt users to continue with the authentication if using the e-commerce iframe. If set to false, Nexio will attempt to process transactions without 3DS. If 3DS is required, Nexio will instead return an error so your system does not get hung up with the 3DS workflow.

Recurring transactions

If you intend to process recurring transactions, you will need to set check3ds: false for any recurring transactions. This indicates to Nexio one of the following:

• The transaction is using a payment token that has been previously authenticated or used for processing a transaction
• Your system is not equipped to handle a 3DS redirect workflow

Do not include check3ds: true in recurring transactions as they are out-of-scope of SCA. Nexio will determine whether to flag transactions as recurring to the gateway. This flag will be determined based on the check3ds value and the token provided at the time of a transaction.

Account Updater

The account updater service allows merchants to automatically update saved cards due to changes in card number or expiration date.

Merchants that process recurring transactions will see fewer declines due to invalid or expired cards by having the most recent card information before the transaction is attempted.

By default, each new card token is tagged for registration with account updater. However, they will not be registered until you have enrolled your merchant account with account updater. We recommend configuring all existing card tokens prior to enrolling your merchant account with account updater.

Contact your Nexio sales agent to enroll your merchant account in account updater.

You may also want to configure webhooks for the various event types that may be returned due to changes or actions from the account updater service. For more information and examples of possible responses, see Event Types in the Webhooks section.

Configure Existing Card Tokens

Prior to enrolling in account updater, we recommend checking the configuration of your existing card tokens. Tag any card you do not wish to be registered with account updater for exclusion. (By default, all cards are tagged for registration.)

If you are already enrolled account updater, you may tag a a card that is currently registered for de-registration or tag a card that is currently not registered for registration.

Check a Card's Enrollment Tag

To check the enrollment tag of an existing card token, send a GET request to the View Card Token endpoint. Replace the {cardToken} in the example below with the card token you wish to view. The response will include a boolean value called shouldUpdateCard. This is the card's enrollment tag. It indicates whether a card will be registered or excluded from account updater.

Note: The card will not be registered until the merchant account is enrolled. See the Account Updater Enrollment Tag table below for more information.

Example Request

curl -X GET https://api.nexiopaysandbox.com/pay/v3/vault/card/{cardToken} \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic <Your Basic Auth>'

 Example 200 Response 

{
  "accountUpdaterStatus": "isExcluded",
  "card": {...},
  "data": {...},
  "dateCreated": "2019-07-31T17:02:39.035Z",
  "dateLastModified": "2019-07-31T18:33:30.660Z",
  "merchantId": "100100",
  "shouldUpdateCard": true,
  "tokenex": {...}
}

Tag an Existing Card For Registration

1. Update the Card's Registration Tag

   Send a PUT request to the Edit Card Token endpoint. Include the parameter shouldUpdateCard: true in the body of your request.

Example Request

curl -X PUT https://api.nexiopaysandbox.com/pay/v3/vault/card/{cardToken} \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic <Your Basic Auth>'
  -d '{
  "shouldUpdateCard": true
}'

2. Check the Card's Status (Optional)

   Send a GET request to the View Card Token endpoint. The response will include a string value called accountUpdaterStatus. This is the card's enrollment status. See the Account Updater Card Status table for more information.

   Note: It usually takes three to four business days for a card token to become registered with account updater.

Example Request

curl -X GET https://api.nexiopaysandbox.com/pay/v3/vault/card/{cardToken} \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic <Your Basic Auth>'

 Example 200 Response 

{
  "accountUpdaterStatus": "isExcluded",
  "card": {...},
  "data": {...},
  "dateCreated": "2019-07-31T17:02:39.035Z",
  "dateLastModified": "2019-07-31T18:33:30.660Z",
  "merchantId": "100100",
  "shouldUpdateCard": true,
  "tokenex": {...}
}

Tag an Existing Card For De-registration

1. Update the Card's Registration Tag

   Send a PUT request to the Edit Card Token endpoint. Include the parameter shouldUpdateCard: false in the body of your request.

Example Request

curl -X PUT https://api.nexiopaysandbox.com/pay/v3/vault/card/{cardToken} \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic <Your Basic Auth>'
  -d '{
  "shouldUpdateCard": false
}'

2. Check the Card's Status (Optional)

   Send a GET request to the View Card Token endpoint. The response will include a string value called accountUpdaterStatus. This is the card's enrollment status. See the Account Updater Card Status table for more information.

   Note: It usually takes three to four business days for a card token to become de-registered with account updater.

Example Request

curl -X GET https://api.nexiopaysandbox.com/pay/v3/vault/card/{cardToken} \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic <Your Basic Auth>'

Example 200 Response

{
  "accountUpdaterStatus": "isRegistered",
  "card": {...},
  "data": {...},
  "dateCreated": "2019-07-31T17:02:39.035Z",
  "dateLastModified": "2019-07-31T18:33:30.660Z",
  "merchantId": "100100",
  "shouldUpdateCard": false,
  "tokenex": {...}
}

Configure New Card Tokens

Tag a New Card for Enrollment

By default, all cards are tagged for enrollment in account updater upon creation.

Tag a New Card for Exclusion

With the Nexio Iframe

1. Prepare the Iframe

   Follow steps 1-2 of the Create a Save Card Page With the Nexio Iframe tutorial or the Create a Checkout Page with the Nexio Iframe tutorial.

2. Request a One-time-use Token

   Request an e-commerce one-time-use token. Include the parameter shouldUpdateCard: false in the body of your request.

Example Request

curl -X POST https://api.nexiopaysandbox.com/pay/v3/token \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic <Your Basic Auth>'
  -d '{
  "shouldUpdateCard": false
}'

3. Load the Iframe

   Follow steps 4-6 of the Create a Save Card Page With the Nexio Iframe or the Create a Checkout Page with the Nexio Iframe tutorial.

   Now, when the iframe is loaded a Kount check will be performed.

   Nexio will return the results back to you in the Kount response.

With Your Own Form

1. Prepare the Iframe

   Follow steps 1-6 of the Create a Save Card Page Using the Iframe tutorial.

2. Request a One-time-use Token

   Request an e-commerce one-time-use token.

   (This is step 7a of the Create a Save Card Page Using the Iframe tutorial.)

Example Request

curl -X POST https://api.nexiopaysandbox.com/pay/v3/token \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic <Your Basic Auth>'
  -d '{}'

4. Post Card Information to Nexio

   Follow step 7b of the Create a Save Card Page Using the Iframe tutorial. Include the parameter shouldUpdateCard: false in the body of your request.

Example Request

curl -X POST https://api.nexiopaysandbox.com/pay/v3/saveCard \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic <Your Basic Auth>'
  -d '{
  "card": {
    "cardHolderName": "John H Doe",
    "encryptedNumber": "cu3yRktaYFK2LUC6DpNK289tYDsGRCi7cO+GeG0hkeYFvT7Y8/oY5r53obMz6Q/BZ38gk2u2Ufwy8ojBcX2sfNjG5jplGTXA4NNlSIUjMFfiHe1sff1JFpThoiW/IIlifGlbWu+S1/9pqWPTzJ2+DcjwohbHzsDahhYewFhXgC8qsK0ypi/Shlp+CwRITyIvbVXESD0xz3YOTRHeZLlChvVqN8z4ZzN8nm0MXkmT1wcpYI73bH4KdnPwNU3s7XxvP/ernQP73SHHAOKSLlz4F6AEHFjJiCoXzeLF7LwEjRdxDJ0sKVXbRk3i9BGh+8Nle2VYgjpUWtk2763QkvZiQQ==",
    "expirationMonth": "12",
    "expirationYear": "20"
  },
  "token": "eb50a022-d6de-4244-a1e6-dcb8522b2d19",
  "shouldUpdateCard": false
}'

5. Listen for Nexio's Response

   Follow step 8 of the Create a Save Card Page Using the Iframe tutorial. See the Kount Response section for more information about the possible results included in the response.

With the API

1. Request a One-time-use Token

   Request an e-commerce one-time-use token.

Example Request

curl -X POST https://api.nexiopaysandbox.com/pay/v3/token \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic <Your Basic Auth>'
  -d '{}'

2. Post Card Information to Nexio

   Send a POST request to the Save Card Token endpoint. Include the token from step 2, the card information and the parameter shouldUpdateCard: false in the body of your request.

Example Request

curl -X POST https://api.nexiopaysandbox.com/pay/v3/saveCard \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic <Your Basic Auth>'
  -d '{
  "card": {
    "cardHolderName": "John H Doe",
    "encryptedNumber": "cu3yRktaYFK2LUC6DpNK289tYDsGRCi7cO+GeG0hkeYFvT7Y8/oY5r53obMz6Q/BZ38gk2u2Ufwy8ojBcX2sfNjG5jplGTXA4NNlSIUjMFfiHe1sff1JFpThoiW/IIlifGlbWu+S1/9pqWPTzJ2+DcjwohbHzsDahhYewFhXgC8qsK0ypi/Shlp+CwRITyIvbVXESD0xz3YOTRHeZLlChvVqN8z4ZzN8nm0MXkmT1wcpYI73bH4KdnPwNU3s7XxvP/ernQP73SHHAOKSLlz4F6AEHFjJiCoXzeLF7LwEjRdxDJ0sKVXbRk3i9BGh+8Nle2VYgjpUWtk2763QkvZiQQ==",
    "expirationMonth": "12",
    "expirationYear": "20"
  },
  "token": "eb50a022-d6de-4244-a1e6-dcb8522b2d19",
  "shouldUpdateCard": false
}'

Account Updater Enrollment Tag

Merchant's Enrollment in Account Updater	shouldUpdateCard	Action
Enrolled	true	The card will be registered with account updater
Enrolled	false	The card will be excluded from account updater. If the card was previously registered it will be de-registered
Not Enrolled	true	The card is tagged for registration. Upon merchant enrollment the card will be registered with account updater
Not Enrolled	false	The card is tagged for exclusion. Upon merchant enrollment the card will be excluded from account updater

Account Updater Card Status

accountUpdaterStatus	Description
isRegistered	Card has been successfully registered. Automatic card updates will occur.
pendingExclusion	Card is in the process of being de-registered (usually takes about three to four business days).
isExcluded	Card is excluded or has been de-registered from the account updater service. (This is the default status before a card is run through the account updater service.)
toDelete	Indicates that Nexio must first de-register the card before deleting the token.
pendingDeletion	Card is in the process of being de-registered. The token will be deleted within three to four business days.

Account Updater Test Cards

Test transactions for Account Updater can be submitted using the following card numbers:

Test Card Number	Response Code	Description
4000200011112222	201	Expiration date has been updated (3 years added to the expiration date)
4000200111112221	201	Expiration date has been updated (3 years added to the expiration date)
4000100011112224	202	Card number updated to 4000100511112229
4000100111112223	202	Card number updated to 4000100611112228
4000600011112223	203	Closed account
4000600111112222	203	Closed account
4000700011112221	204	Contact cardholder
4000700111112220	204	Contact cardholder

Alternative Payment Methods

Nexio's alternative payment method (APM) service allows you to offer shoppers multiple APMs with a single integration. Based on your preferred workflow, you may want to use the Express APM iframe display one or more Nexio-provided APM button iframes or send shoppers directly to your chosen APM using Nexio-provided redirect URLs.

Nexio's Express APM integration allows you to offer shoppers multiple alternative payment methods with a single iframe. Nexio will provide a radio button list of all configured APMs. The shopper will then be redirected to their selected APM where they will complete the payment. Payment response information will be sent to the parent document as a message event. See the Express APM tutorial for integration instructions.

Supported APMs

The table below lists all available APMs and their supported transaction types.

Please note that Braintree PayPal, Apple Pay, and Google Pay are currently only available through Nexio's APM button iframes.

Apple Pay and Google Pay also require additional configuration steps. See the Apple Pay configuration / Google Pay configuration sections for instructions.

APM	Supported Transaction Types	paymentMethod
Alipay	Sale, Refund	nihaoPayAliPay
ApplePay	Sale, Auth only, Capture, Void, Refund	applePayAuthNet applePayCyberSource applePayCheckout
GooglePay	Sale, Auth only, Capture, Void, Refund	googlePayAuthNet googlePayCyberSource
Klarna	Sale, Auth only, Capture, Refund	klarna
Paynet	Sale	paynet
SPEI	Sale	openpaySpei
PayPal	Sale, Auth only, Capture, Void, Refund Sale (Button Iframe URLs only), Merchant-initiated, Auth only, Capture, Void, Refund	payPal braintreePayPal
SEPA	Sale, Auth only, Capture	adyenSepa
UnionPay	Sale, Refund	nihaoPayUnionPay
WeChat Pay	Sale, Refund	nihaoPayWechatPay

Configuration

The following alternative payment methods (APMs) require additional configuration steps:

• Apple Pay
• PayPal (with Braintree)
• Google Pay

Apple Pay

In order to configure your account for use with Apple Pay, you will need the following:

• An Apple computer
• An Apple Developer account
• An Authorize.Net account

Once you have the above, you are ready to follow the configuration steps below:

• Step 1: Create an Apple Pay Merchant ID
• Step 2: Create A Payment Processing Certificate
• Step 3: Create a Merchant Identity Certificate
• Step 4: Verify Your Domain
• Step 5: Provide Your Configuration Settings to Integration Support

Note: When integrating Apple Pay to multiple environments, you will need to complete step 4 for each environment. However, steps 1-3 only need to be completed once.

Step 1: Create an Apple Pay Merchant ID

Follow the steps below to create an Apple Pay Merchant ID.

1. Navigate to the Apple Developer Portal

   Go to the Apple Developer Portal

2. Navigate to Identifiers List

   a. Click on 'Accounts'

   b. Click on 'Certificates, IDs and Profiles'

   c. Click on 'Identifiers'

   d. Click on the '+' sign

3. Create the Merchant ID

   Select the 'Merchant ID' radio button, then click 'Create'. Fill in the required fields. Copy or note the Merchant ID. You will need it when you create the payment processing certificate and the merchant identity certificate.

Step 2: Create A Payment Processing Certificate

Follow the steps below to download a Payment Processing Certificate through Authorize.Net and upload it to Apple Pay.

1. Navigate to Authorize.Net

   Go to the Authorize.Net developer portal

2. Click on 'Digital Payment Solutions'

3. Click on 'Apple Pay'

   Enter the Merchant ID you created in step 1

4. Download the Certificate

   Click the 'Download' button to download the Payment Processing Certificate. You will use this certificate in the next step.

5. Upload the Payment Processing Certificate

   a. Navigate to the Apple Developer Portal

   b. Click the 'Upload' button and upload the Payment Processing Certificate from the previous step.

Step 3: Create a Merchant Identity Certificate

Follow the steps below to create an Apple Pay Merchant Identity Certificate.

1. Create the Certificate Signing Request

   In this step you will create the certificate signing request (CSR) for a Merchant Identity Certificate. (The steps below are adapted from Apple's tutorial on how to create a certificate signing request)

   a. Launch Keychain Access located in /Applications/Utilities

   b. Choose Keychain Access > Certificate Assistant > Request a Certificate from a Certificate Authority

   c. In the Certificate Assistant dialog, enter an email address in the User Email Address field. (Any email address will work)

   d. Enter the Common Name. You may pick a common name of your choice, but for this tutorial we will call it 'Nexio Apple Pay Merchant Cert'

   e. Leave the CA Email Address field empty

   f. Choose 'Saved to disk', and click Continue

   g. The default 'Save As' name will be something like CertificateSigningRequest.certSigningRequest. We will call it NexioApplePayMerchant.certSigningRequest

   Successful completion of the above steps will create the following files:

   • CSR (saved to the location you selected with the name you chose in the step g)
   • A private key (saved to the KeyChain tool, with the same name as the Common Name you chose in step d)
   • A public key (saved to the KeyChain tool, with the same name as Common Name you chose in step d)

2. Upload the CSR to Apple's developer portal

   a. Go to the Apple Developer Portal

   b. Click to expand App IDs dropdown menu (in the top right)

   c. Select merchant IDs

   d. Select the desired merchant ID (If you do not see the merchant ID, create it now)

   e. Under 'Apple Pay Merchant Identity Certificate' click on 'Create Certificate'

   f. Upload the certificate you created in step 1

   g. Download the certificate Name it NexioApplePayMerchant.cer

3. Export the Private Key From Step 1

   a. Go back to the KeyChain tool on your MacBook

   b. Right click on the private key and select Export

   c. Export as NexioApplePayMerchantKey.p12

   Note: If p12 is greyed out you choose the wrong key

4. Convert the Format of the Private Key Convert the format of the private key you downloaded in step 3. Convert it first to a PEM certificate, then to a Base64 string.

   a. Navigate to the directory where the private key is saved (Documents, by default):

   cd Documents

   b. Create the privatePem by typing the following in the terminal:

   openssl pkcs12 -in NexioApplePayMerchantKey.p12 -out NexioApplePayMerchantKey.pem -nodes -clcerts

   c. Convert .pem file to a Base64 string:

   base64 NexioApplePayMerchantCRT.pem

5. Convert the Format of the Apple Pay Certificate Convert the format of the certificate you downloaded in step 2. Convert it first to a PEM certificate, then to a Base64 string.

   a. Navigate to the directory where the private key is saved (Downloads, by default):

   cd Downloads

   b. Create the certPem by typing the following in the terminal:

   openssl x509 -inform DER -outform PEM -in NexioApplePayMerchant.cer -out NexioApplePayMerchantCRT.pem

   c. Convert the files to base64 strings

   base64 NexioApplePayMerchantCRT.pem

Step 4: Verify Your Domain

Follow these steps to verify the domain to be used with Apple Pay. If you have multiple domains (for example, for development environments) repeat these steps for each.

1. Navigate to the Apple Developer Portal

   Go to the Apple Developer Portal

2. Add the Domain

   a. Click on 'Merchant Domains'

   b. Click on 'Add Domain'

   c. Enter the URL of the domain you plan to use. Click 'Save'.

   d. Apple Pay will provide you with a text file to download and a URL. Download the file and copy the URL, you will use both in the next step.

3. Host the Text File at the Proper URL

   Host the text file at the exact URL provided by Apple.

Step 5: Provide Your Configuration Settings to Integration Support

Once you have completed **steps 1-4**,
[contact integration support](#contact-us) to provide them with the following:
- Your [Apple Pay Merchant ID](#create-an-apple-pay-merchant-id)
- Your [Payment Processing Certificate](#create-a-payment-processing-certificate)
- Your [Merchant Identity Certificate](#create-a-merchant-identity-certificate)
- Your Authorize.Net Login ID
- Your Authorize.Net Transaction Key
- The [verified domain](#verify-your-domain) for processing

**Note:** The verified domain you provide to integration support will be used by default to process any Apple Pay transactions on your account.
If you have multiple verified domains for testing purposes,
you can dynamically choose the domain by providing `data.applePayDomain` in the payload when you request a [one-time-use token](#apm-one-time-use-token).
(See **step 4** of the [Button Iframes](#button-iframe-urls) tutorial for more information.)

PayPal (with Braintree)

In order to configure your account for use with PayPal (with Braintree), you will need the following:

• A login for the PayPal developer site
• A Braintree account
• PayPal accounts ready for your different markets

After you have the above, and have worked with integration support to get your PayPal ClientID, you are ready to follow the configuration steps.

Link PayPal Account to Braintree Environment

Integration support helps you complete this step for the Sandbox environment. However, you must do the configuration for your production environment.

Follow these steps to link your PayPal account:

1. Navigate to the Braintree Control Panel

   Go to the Braintree Control Panel and log in.

2. Get the API keys

   Go to Settings > API.

   The system displays all the API keys.

3. Locate the Merchant ID

   The Merchant ID displays at the bottom of the Keys page.

   Make note of this ID because you will use this value in Step 7.

4. Navigate to Processing Options

   Go back to the home screen.

   Go to Settings > Processing > Processing Options.

5. Configure Options

   In the PayPal area, click Options.

   You are prompted to log in with your PayPal account credentials.

   After successfully logging in, the PayPal Accounts page displays. Braintree retrieves the necessary clientID, PayPal email, and Client Secret.

6. Link One or More PayPal Accounts

   Merchant account IDs are created and added to the merchant account by PayPal, after the merchant has signed all the necessary PayPal documentation. Contact PayPal and the merchant to arrange the creation of merchant account IDs. Follow this same process when you need to add new payment methods to the merchant account.

   a. Click the +Link New PayPal Account button.

   b. Provide PayPal account details and URLs for Privacy Policy and Terms and Conditions.

   c. In the new account row (the one that does not show any merchant accounts), click Edit.

   d. Start typing the merchant account name so that the selector displays a list of all potential matches.

   e. If you want to enable PayPal Disputes for this account, select Manage PayPal Disputes in the Braintree Control Panel.

   Note: If you link a merchant account here, any previous links made to that merchant account are removed.

7. Add Merchant Account IDs for Each Currency to Support

   To support multiple currencies, you must have a different merchant account ID for each currency. Work with your PayPal account representative to arrange this, using the value you noted in Step 3.

PayPal (with Braintree) Payment Flow

The following show the general flows for a customer accessing a merchant site through payment using PayPal with Braintree, either from the cart or the checkout page.

Customer adds item to shopping cart and clicks PayPal button to pay

1. The customer adds one or more items to a shopping cart.

2. The customer goes to that cart, the order amount displays, along with a Pay with PayPal button.

3. If the customer clicks that button, they are asked to log in to PayPal and to select their payment options and address information.

4. After making those selections, the customer clicks an Agree & Continue button.

5. The customer is redirected to a Confirm/Place Order page. Based on the address selected, they see tax and shipping costs for this order and are asked to confirm payment.

6. The customer is redirected to a Receipt page.

Customer adds item to cart and clicks Checkout button

1. The customer adds one or more items to a shopping cart.

2. The customer goes to that cart, the order amount displays, along with a Pay with PayPal button.

3. Customer instead clicks the Checkout button and is redirected to a Checkout page with all available payment options (potentially including PayPal). Customer address information is collected (or retrieved) and is used to generate tax and shipping costs.

4. If the customer clicks the PayPal button here, they are asked to log in to PayPal and to select their payment options.

   If the customer clicks a different APM button, the process for that specific APM continues through to confirming the payment options.

   If the customer submits payment for card or ACH, the process continues based on the entered payment options.

5. The customer is redirected to a Receipt page.

Google Pay

In order to configure your account for use with Google Pay, you will need the following:

• A Google Pay Console account
• A Google Pay Console Business Profile
• A Google Pay Console Merchant ID
• An Authorize.Net account

---

Klarna

This section provides the following topics:

• Overview
  • Solution
  • Intended audience
  • Prerequisites
  • Testing Data
• Run a Transaction through Klarna
  • Express APM with Klarna
  • Button Iframe URLs with Klarna
• Response Handling
• Status Workflows
• Error handling
• Troubleshooting

Overview

Klarna is a payment provider allowing consumers to pay using their payment methods saved to their Klarna account. This section is intended to help you implement Klarna based on your preferred integration workflow.

You can offer Klarna as a payment provider for your consumers in any of the following ways:

• In an iframe that displays all payment methods available to the consumer (based on the consumer’s location and the merchant’s configured payment methods)
• In an individual iframe for Klarna
  
  

---

Solution

Regardless of the implementation workflow you implement, consumers will be redirected to Klarna to complete their transactions.

Nexio supports the following transaction types for Klarna:

• Sale
• Auth Only
• Capture
• Refund

Nexio supports the following countries and regions for Klarna:

• United States
• Great Britain
• European Region
• Canada
• Australia
• Sweden
• New Zealand
• Norway
• Denmark
• Switzerland

Nexio currently supports the following processing currencies for Klarna:

• USD
• GDP
• EUR
• CAD
• AUD
• SEK
• NZD
• NOK
• DKK
• CHF

The merchant needs to go through Klarna’s underwriting process and the merchant needs to contract with Klarna directly for them to provision a Production merchant ID (MID) with the payment methods for the region that the merchant wants to process. Only the payment methods approved and contracted with Klarna and the merchant will be the ones available at checkout for the consumer.

Development scope

This guide walks you through the process of getting Klarna set up in the sandbox environment and connecting your website using our API.

Intended audience

This guide is intended for developers looking to allow online consumers to make purchases on a merchant’s website using Klarna.

You should already have experience using the Nexio APIs and understand how to create one-time-use tokens, send and receive requests, and work with the Sale, Auth Only, Capture, and Refund transaction types. If you need more information about these things, see the Getting Started section and work through the concepts and examples in e-Commerce Flows and Operations.

Prerequisites

The following table shows the required and optional fields for Klarna transactions in the APM One-time Use Token request.

Field	Required?	Description
data.amount	Y	The transaction amount. This value must equal data.cart.items[n].quantity times data.cart.items[n].price.
data.currency	Y	The three-character ISO currency code for the transaction. Note: See Solution for the list of supported processing currencies with Klarna.
data.customer.orderNumber	Y	The order number.
data.customer.firstName	Y	The customer's first name, as it appears on the credit card.
data.customer.lastName	Y	The customer's last name, as it appears on the credit card.
data.customer.email	Y	The customer's email address.
data.customer.billToCountry	Y	The two-character (Alpha-2) ISO country code. Note: See Solution for the list of supported countries with Klarna.
data.cart.items[n].description	Y	A description of the item.
data.cart.items[n].price	Y	The price per item.
data.cart.items[n].quantity	Y	The quantity sold.
data.cart.items[n].item	Optional	Item number or code.
data.totalTaxAmount	Optional	Total tax amount.

Testing Data

For testing data, see Klarna’s Testing Environment page.

Use 4.00 as the amount in your request to continue the payment in Klarna.

---

Run a Transaction through Klarna

You can offer Klarna as a payment provider for your consumers in any of the following ways:

• Through Express APM, in an iframe that displays all payment methods available to the consumer, including Klarna
• In an individual iframe for Klarna
  
  

---

Express APM with Klarna

Nexio's Express APM service allows shoppers to run transactions through many of our supported alternative payment methods (APMs) with a single integration, including Klarna. When you integrate with Express APM, shoppers will be shown a list of all available APMs (based on their location and the merchant’s configured payment methods), prompted to select their preference, then be redirected to complete payment.

Notes:

• This service is not compatible with embedded browsers in apps
• For instructions on how to do an auth only transaction with Klarna, see Express APM for Auth Only with Klarna

To integrate with Express APM for Klarna, follow the steps below.

1. Configure Your Account

   Contact integration support to enable Klarna on your merchant account.

2. Create a Checkout Page

   Create a checkout page with an iframe.

3. Request an Express Iframe URL

   Send a POST request to the APM One-time-use Token endpoint.

   Include the following required parameters:

   • data.amount (must equal the price times the quantity)
   • data.currency (see Solution for the list of supported processing currencies with Klarna)
   • data.customer.orderNumber
   • data.customer.firstName
   • data.customer.lastName
   • data.customer.email
   • data.customer.billToCountry (see Solution for the list of supported countries with Klarna)
   • data.cart.items[n].description
   • data.cart.items[n].price
   • data.cart.items[n].quantity
     
     

   In addition, you may include the following optional parameters:

   • data.totalTaxAmount
   • data.cart.items[n].item

   You may choose to have Nexio provide an in-frame submit button or your own external button by setting the displaySubmitButton UI Option to true for an in-frame submit button or false for an external submit button.

   Example Request

   curl -X POST https://api.nexiopaysandbox.com/apm/v3/token \
     -H 'Content-Type: application/json' \
     -H 'Accept: application/json' \
     -H 'Authorization: Basic <Your Basic Auth>'
     -d '{
     "data": {
       "amount": 4.00,
       "currency": "USD",
       "customer": {
         "orderNumber": "12345678",
         "firstName": "John",
         "lastName": "Doe",
         "email": "john@doe.com",
         "billToCountry": "US"
       },
       "totalTaxAmount": 0,
       "cart": {
         "items": [
           {
             "item": "E200",
             "description": "Platinum set",
             "quantity": 2,
             "price": 2
           }
         ]
       }
     }
   }'
   

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

   Example 200 Response

   {
     "expiration": "2021-07-22T20:49:50.000Z",
     "token": "54a0106y-7750-45b1-961e-29ad95763a23",
     "expressIFrameUrl": "https://api.nexiopaysandbox.com/apm/v3?token=54a0106y-7750-45b1-961e-29ad95763a23",
     "redirectUrls": [
       {
         "paymentMethod": "klarnaPayments",
         "url": "https://api.nexiopaysandbox.com/apm/v3/popup?token=54a0106b-7750-45b1-961e-29ad95763a23&paymentMethod=klarnaPayments"
       }
     ],
     "buttonIFrameUrls": [
       {
         "paymentMethod": "klarnaPayments",
         "url": "https://api.nexiopaysandbox.com/apm/v3?token=54a0106b-7750-45b1-961e-29ad95763a23&paymentMethod=klarnaPayments"
       },
       {
         "paymentMethod": "braintreePayPal",
         "url": "https://api.nexiopaysandbox.com/apm/v3?token=54a0106b-7750-45b1-961e-29ad95763a23&paymentMethod=braintreePayPal"
       }
     ],
     "scriptUrl": "https://api.nexiopaysandbox.com/apm/v3/scripts?token=54a0106y-7750-45b1-961e-29ad95763a23"
   }
   

4. Redirect the Shopper to the Selected 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).

   Example

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

   When your iframe loads, shoppers will be prompted to select from a list of configured APMs, including Klarna. The shopper makes their selection of Klarna, clicks 'Submit' (on your button or the iframe button, depending on your choice), then gets redirected to Klarna to complete payment.

   
   

5. Shopper Completes Payment

   Users will be prompted to complete the transaction.

   Afterward they will be redirected back to the merchant website.

   The consumer is redirected to the checkout page. Nexio provides a response as event messages

   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 will request to be closed and send a message event with the payment information.

   • If the payment was successful, the message will include the status and payment ID. For information about status, see Status Workflows
   • If the payment failed, the message will include the status and an error message. For information about handling errors with Klarna, see Error Handling in Klarna

   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:

   Example Sale Response

   {
     "id": "eyJuYW1lIjoia2xhcm5hIiwibWVyY2hhbnRJZCI6IjEwMDI2MCIsInJlZk51bWJlciI6Ijk1M2VmOTFkLTkzNTYtNGRhYi1hZGQ3LTQyOTI0ZGUyNTk3OSIsInJhbmRvbSI6MCwiY3VycmVuY3kiOiJ1c2QifQ==",
     "merchantId": "100260",
     "transactionDate": "2021-07-22T19:54:51.033Z",
     "transactionStatus": "pending",
     "amount": 4,
     "transactionType": "sale",
     "currency": "USD",
     "gatewayResponse": {
       "result": 200,
       "refNumber": "953ef91d-9356-4dab-add7-42924de25979",
       "gatewayName": "klarnaPayments",
       "message": "checkout_complete"
     },
     "data": {
       "amount": 4,
       "currency": "USD",
       "settlementCurrency": "USD",
       "customer": {
         "lastName": "Doe",
         "shipToAddressOne": "123 Ship St",
         "shipToPhone": "5033335678",
         "orderNumber": "7beb71d234c441e5a3c6a475835f8590",
         "shipToCountry": "US",
         "shipToAddressTwo": "Warehouse 456",
         "billToState": "AL",
         "billToCity": "Huntsville",
         "shipToPostal": "67890",
         "firstName": "John",
         "shipToCity": "Shipperville",
         "billToAddressOne": "107 Shoalford Dr",
         "billToCountry": "US",
         "billToPostal": "35806",
         "billToAddressTwo": "Suite 123",
         "billToPhone": "8015551234",
         "email": "nexiotest@example.com",
         "shipToState": "OR"
       },
       "cart": {
         "items": [
           {
             "description": "Platinum set",
             "item": "E200",
             "quantity": 2,
             "type": "sale",
             "price": 2
           }
         ]
       }
     }
   }
   

---

Button Iframe URLs with Klarna

To integrate with Button Iframe URLs with Klarna, follow the steps below.

1. Configure Your Account

   Contact integration support to enable Klarna on your merchant account.

2. Create a Checkout Page

3. Add Iframes to your checkout page

   Add an iframe for Klarna.

   Note: The ID for the iframe is optional. You can use it with your own CSS.

   Example 1: Klarna only

   <iframe id='nexio-klarna-iframe'> <!-- Klarna Iframe Option 1 -->
   </iframe>
   

   Example 2: Klarna plus others

   <iframe id='nexio-klarna-iframe'> <!-- Klarna Iframe with other iframes -->
   </iframe>
   <iframe id='<unique-iframe-id>'> <!-- Any other APM iframe. Add more as needed. -->
   </iframe>
   

4. Request the APM Button Iframe URLs

   Send a POST request to the APM One-time-use Token endpoint.

   Include the following required parameters:

   • data.amount (must equal the price times the quantity)
   • data.currency (see Solution for the list of supported processing currencies with Klarna)
   • data.customer.orderNumber
   • data.customer.firstName
   • data.customer.lastName
   • data.customer.email
   • data.customer.billToCountry (see Solution for the list of supported countries with Klarna)
   • data.cart.items[n].description
   • data.cart.items[n].price
   • data.cart.items[n].quantity
     
     

   In addition, you may include the following optional parameters:

   • data.totalTaxAmount
   • data.cart.items[n].item

   Example Request

   curl -X POST https://api.nexiopaysandbox.com/apm/v3/token \
     -H 'Content-Type: application/json' \
     -H 'Accept: application/json' \
     -H 'Authorization: Basic <Your Basic Auth>'
     -d '{
     "data": {
       "amount": 4.00,
       "currency": "USD",
       "customer": {
         "orderNumber": "12345678",
         "firstName": "John",
         "lastName": "Doe",
         "email": "john@doe.com",
         "billToCountry": "US"
       },
       "totalTaxAmount": 0,
       "cart": {
         "items": [
           {
             "item": "E200",
             "description": "Platinum set",
             "quantity": 2,
             "price": 2
           }
         ]
       }
     }
   }'
   

   A successful request will return an array of buttonIFrameUrls. This array is a list of all APMs currently enabled on your merchant account. Copy the url of the Klarna APM for use in step 5.

   Example 200 Response

   {
     "expiration": "2021-07-22T20:49:50.000Z",
     "token": "54a0106y-7750-45b1-961e-29ad95763a23",
     "expressIFrameUrl": "https://api.nexiopaysandbox.com/apm/v3?token=54a0106y-7750-45b1-961e-29ad95763a23",
     "redirectUrls": [
       {
         "paymentMethod": "klarnaPayments",
         "url": "https://api.nexiopaysandbox.com/apm/v3/popup?token=54a0106b-7750-45b1-961e-29ad95763a23&paymentMethod=klarnaPayments"
       }
     ],
     "buttonIFrameUrls": [
       {
         "paymentMethod": "klarna",
         "url": "https://api.nexiopaysandbox.com/apm/v3?token=54a0106b-7750-45b1-961e-29ad95763a23&paymentMethod=klarnaPayments"
       },
       {
         "paymentMethod": "braintreePayPal",
         "url": "https://api.nexiopaysandbox.com/apm/v3?token=54a0106b-7750-45b1-961e-29ad95763a23&paymentMethod=braintreePayPal"
       }
     ],
     "scriptUrl": "https://api.nexiopaysandbox.com/apm/v3/scripts?token=54a0106y-7750-45b1-961e-29ad95763a23"
   }
   

5. Add the Klarna URL to your Iframe

   Add the url of the Klarna APM to the src tag of the Klarna iframe you created in step 3.

   Example

   var url = "https://api.nexiopaysandbox.com/apm/v3?token=54a0106b-7750-45b1-961e-29ad95763a23&paymentMethod=klarnaPayments";
   window.document.getElementById('nexio-klarna-iframe').src = url;
   

   Now, when the page loads, the shopper will see a button for each APM iframe you added to the page, including Klarna.

   

6. Shopper Completes Payment

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

   Afterward, the popup window will close and they will be redirected back to the merchant website.

   The consumer is redirected to the checkout page. Nexio provides a response as event messages.

   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

   Once the shopper has completed payment (or payment has failed) Nexio's iframe will request to be closed and send a message event with the payment information.

   If the payment was successful, the message will include the status and payment ID. For information about status, see Status Workflows. If the payment failed, the message will include the status and an error message. For information about handling errors with Klarna, see Error Handling in Klarna.

   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:

   Example Sale Response

   {
     "token": "86da4b93-9867-4f30-a99b-c69f96eb801a",
     "id": "eyJuYW1lIjoia2xhcm5hIiwibWVyY2hhbnRJZCI6IjEwMDI2MCIsInJlZk51bWJlciI6Ijk1M2VmOTFkLTkzNTYtNGRhYi1hZGQ3LTQyOTI0ZGUyNTk3OSIsInJhbmRvbSI6MCwiY3VycmVuY3kiOiJ1c2QifQ==",
     "merchantId": "100260",
     "transactionDate": "2021-07-22T19:54:51.033Z",
     "transactionStatus": "pending",
     "amount": 4,
     "transactionType": "sale",
     "currency": "USD",
     "gatewayResponse": {
       "result": 200,
       "refNumber": "953ef91d-9356-4dab-add7-42924de25979",
       "gatewayName": "klarnaPayments",
       "message": "checkout_complete"
     },
     "data": {
       "amount": 4,
       "currency": "USD",
       "settlementCurrency": "USD",
       "customer": {
         "lastName": "Doe",
         "shipToAddressOne": "123 Ship St",
         "shipToPhone": "5033335678",
         "orderNumber": "7beb71d234c441e5a3c6a475835f8590",
         "shipToCountry": "US",
         "shipToAddressTwo": "Warehouse 456",
         "billToState": "AL",
         "billToCity": "Huntsville",
         "shipToPostal": "67890",
         "firstName": "John",
         "shipToCity": "Shipperville",
         "billToAddressOne": "107 Shoalford Dr",
         "billToCountry": "US",
         "billToPostal": "35806",
         "billToAddressTwo": "Suite 123",
         "billToPhone": "8015551234",
         "email": "nexiotest@example.com",
         "shipToState": "OR"
       },
       "cart": {
         "items": [
           {
             "description": "Platinum set",
             "item": "E200",
             "quantity": 2,
             "type": "sale",
             "price": 2
           }
         ]
       }
     }
   }
   

---

Response Handling

Nexio responds with transaction results in one of three ways, depending on your integration workflow:

• Event messages: This applies to all integrations
• Webhook notification: If your merchant account is configured to receive webhooks, in addition to the above, Nexio provides responses to the webhook URLs that have been registered

For information about how to run each of the integration workflows, see Run a Transaction through Klarna.

---

Status Workflows

The status of a successful transaction with Klarna varies, depending on the options you choose.

Sale

When isAuthOnly is false, successful sale transactions will have the following statuses:

• pending (called "authorized" when querying transactions and in Nexio Dashboard)
• settled

When isAuthOnly is true, successful sale transactions will have the following statuses:

• authOnlyPending
• authOnly

Capture

Successful capture transactions will have the following status:

• settled

Refund

Successful refund transactions will have the following status:

• settled
  
  

---

Error handling

For help with errors and declines, see the Handling Errors and Declines topic.

Troubleshooting

If you encounter issues while implementing or testing Klarna, contact integration support.

SEPA

This guide provides the following topics:

• Overview
  • Solution
  • Intended audience
  • Prerequisites
  • Testing Data
• Run a Transaction through SEPA
  • Express APM with SEPA
• Run an Auth Only Transaction through SEPA
• Response Handling
• Status Workflows
• Error handling
• Troubleshooting

---

Overview

The SEPA (Single Euro Payments Area) with Adyen is is a pan-European network that allows consumers to send and receive payments in euros (€) between two cross-border bank accounts in the eurozone. With SEPA, sending money within the eurozone is as easy as making your usual domestic bank transfers.

A SEPA credit transfer is a single transfer of euros from one person or organization to another. For example, this could be to pay the deposit for a holiday rental or to settle an invoice. A SEPA direct debit is a recurring payment. For example, to pay monthly rent or for a service like a mobile phone contract.

This section is intended to help you implement SEPA with Adyen based on your preferred integration workflow.

You can offer SEPA as a payment provider for your consumers only in the following way:

• In an individual iframe for SEPA showing the form fields
  
  

---

Solution

Regardless of the implementation workflow you implement, consumers will be redirected to Adyen to complete their transactions.

Nexio supports the following transaction types for SEPA with Adyen:

• Sale
• Auth Only
• Capture

Nexio currently supports the following currency for SEPA with Adyen:

• EUR

Note: SEPA with Adyen does not support chargebacks.

Development scope

This guide walks you through the process of getting SEPA with Adyen set up in the sandbox environment and connecting your website using our API.

Intended audience

This guide is intended for developers looking to allow online consumers to make purchases on a merchant’s website using SEPA.

You should already have experience using the Nexio APIs and understand how to create one-time-use tokens, send and receive requests, and work with the Sale, Auth Only, Capture, and Refund transaction types. If you need more information about these things, see the Getting Started section of the "Developer Documentation" and work through the concepts and examples in e-Commerce Flows and Operations.

Prerequisites

The following table shows the required and optional fields for SEPA with Adyen transactions in the APM One-time Use Token request.

Field	Required?	Description
isAuthOnly	N	Set to true to run an auth only transaction.
data.amount	Y	The transaction amount.
data.currency	Y	The three-character ISO currency code for the transaction. Note: Nexio only supports EUR with SEPA.
data.paymentMethod	Y	The desired alternative payment method. This value must be adyenSepa.
data.dueDate	N	The date by which the customer must complete the payment.
data.description	N	A description of the transaction.
data.customer.orderNumber	Y	The order number.
data.customer.firstName	Y	The customer's first name, as it appears on the credit card.
data.customer.lastName	Y	The customer's last name, as it appears on the credit card.
data.customer.email	Y	The customer's email address.
data.customer.billToAddressOne	N	The customer's billing street address.
data.customer.billToAddressTwo	N	Additional street address information, if required.
data.customer.city	N	The customer's billing city.
data.customer.billToCountry	N	The two-character (Alpha-2) ISO country code.
data.customer.billToPhone	N	The billing phone number.
data.customer.billToPostal	N	The customer's billing postal code.
data.customer.billToState	N	The state or province on file with the credit card provider.
data.customer.customerRef	N	Customer identifier. You can use this field to pass a customer ID to the gateway or APM or to manage user subscriptions.
data.customer.shipToAddressOne	N	The shipping address, if different from the billing address.
data.customer.shipToAddressTwo	N	Additional shipping address information, if required.
data.customer.shipToCity	N	The shipping city.
data.customer.shipToCountry	N	The two-character (Alpha-2) ISO country code.
data.customer.shipToPhone	N	The shipping phone number.
data.customer.shipToPostal	N	The shipping postal code.
data.customer.shipToState	N	The shipping state or province.
processingOptions.paymentOptionTag	N	A custom value used to route transactions to a specific gateway or merchant account.
processingOptions.merchantId	N	The merchant ID (MID).

Testing Data

Adyen has an extensive list of test accounts. For more information, see SEPA Direct Debit on Adyen's site.

Run a Transaction through SEPA

You can offer SEPA as a payment provider for your consumers in the following way:

• Through Express APM, in an iframe that displays the SEPA form fields and Pay button to the consumer

Express APM with SEPA

Nexio's Express APM service allows shoppers to run transactions through many of our supported alternative payment methods (APMs) with a single integration, including SEPA. When you integrate with Express APM, shoppers will be shown a list of all available APMs (based on their location and the merchant’s configured payment methods), prompted to select their preference, then be redirected to complete payment.

Notes:

• This service is not compatible with embedded browsers in apps
• For instructions on how to do an auth only transaction with SEPA, see Express APM for Auth Only with SEPA

To integrate with Express APM for SEPA, follow the steps below.

1. Configure Your Account

   Contact integration support to enable SEPA with Adyen on your merchant account.

2. Create a Checkout Page

   Create a checkout page with an iframe for SEPA.

3. Request an Express Iframe URL

   Send a POST request to the APM One-time-use Token endpoint.

   Include the following required parameters:

   • data.amount
   • data.currency (EUR is currently the only supported currency for SEPA with Adyen)
   • data.paymentMethod - Use the value of adyenSepa for SEPA with Adyen
   • data.customer.orderNumber
   • data.customer.firstName
   • data.customer.lastName
   • data.customer.email

   In addition, you may include any of the the optional parameters. For the list of optional paramters, see Prerequisites.
   

   Example Request

   curl -X POST https://api.nexiopaysandbox.com/apm/v3/token \
     -H 'Content-Type: application/json' \
     -H 'Accept: application/json' \
     -H 'Authorization: Basic <Your Basic Auth>'
     -d '{
     "data": {
       "amount": 5.00,
       "currency": "EUR",
       "paymentMethod": "adyenSepa",
       "customer": {
         "orderNumber": "7beb71d234c441e5a3c6a475835f8590",
         "firstName": "John",
         "lastName": "Doe",
         "email": "john@doe.com"
       }
     }
   }'
   

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

   Example 200 Response

   {
     "expiration": "2021-07-22T20:49:50.000Z",
     "token": "cb1f6727-f425-4ac9-b958-2b43c8bf7ae8",
     "expressIFrameUrl": "https://api.nexiopaysandbox.com/apm/v3?token=cb1f6727-f425-4ac9-b958-2b43c8bf7ae8",
     "redirectUrls": [
       {
         "paymentMethod": "adyenSepa",
         "url": "https://api.nexiopaysandbox.com/apm/v3/popup?token=cb1f6727-f425-4ac9-b958-2b43c8bf7ae8&paymentMethod=adyenSepa"
       }
     ],
     "buttonIFrameUrls": [
       {
         "paymentMethod": "adyenSepa",
         "url": "https://api.nexiopaysandbox.com/apm/v3?token=cb1f6727-f425-4ac9-b958-2b43c8bf7ae8&paymentMethod=adyenSepa"
       },
       {
         "paymentMethod": "braintreePayPal",
         "url": "https://api.nexiopaysandbox.com/apm/v3?token=cb1f6727-f425-4ac9-b958-2b43c8bf7ae8&paymentMethod=braintreePayPal"
       }
     ],
     "scriptUrl": "https://api.nexiopaysandbox.com/apm/v3/scripts?token=cb1f6727-f425-4ac9-b958-2b43c8bf7ae8"
   }
   

   
   

4. Add the URL to the iframe.

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

   Example

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

   When your iframe loads, SEPA displays a form with fields for Holder Name and Account Number (IBAN), along with a Pay button.
   
   

5. Shopper Completes Payment

   Users type appropriate values and click Pay.

   Nexio provides a response as event messages.
   
   

6. Create a Receipt for the Shopper

   After the shopper has completed payment (or payment has failed), Nexio's iframe sends a message event with the payment information.

   • If the payment was successful, the message includes the status and payment ID. For information about status, see Status Workflows
   • If the payment failed, the message includes the status and an error message. For information about handling errors with SEPA, see Error Handling in SEPA

   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:

   Example Sale Response

   {
     "id": "eyJuYW1lIjoia2xhcm5hIiwibWVyY2hhbnRJZCI6IjEwMDI2MCIsInJlZk51bWJlciI6Ijk1M2VmOTFkLTkzNTYtNGRhYi1hZGQ3LTQyOTI0ZGUyNTk3OSIsInJhbmRvbSI6MCwiY3VycmVuY3kiOiJ1c2QifQ==",
     "merchantId": "100260",
     "transactionDate": "2021-07-22T19:54:51.033Z",
     "transactionStatus": "pending",
     "amount": 5,
     "transactionType": "sale",
     "currency": "EUR",
     "gatewayResponse": {
       "result": "pending",
       "refNumber": "953ef91d-9356-4dab-add7-42924de25979",
       "gatewayName": "adyenSepa",
       "message": "Authorised"
     },
     "data": {
       "amount": 5,
       "currency": "EUR",
       "settlementCurrency": "EUR",
       "customer": {
         "firstName": "John",
         "lastName": "Doe",
         "orderNumber": "7beb71d234c441e5a3c6a475835f8590",
         "email": "john@doe.com"
       }
     }
   }
   

Run an Auth Only Transaction through SEPA

You may wish to authorize a transaction (auth only) and capture it at a later time.

You can run an auth only transaction through SEPA using the following integration method:

• Express APM for Auth Only with SEPA

Express APM for Auth Only with SEPA

To run an auth only transaction through SEPA using Express APM, follow the steps below.

1. Prepare Your Checkout Page

   Follow steps 1-2 of the Express APM with SEPA tutorial.

2. Request an Express Iframe URL

   Follow step 3 of the Express APM with SEPA tutorial.

   Include isAuthOnly: true in the body of your request.

   Example Request

   curl -X POST https://api.nexiopaysandbox.com/apm/v3/token \
     -H 'Content-Type: application/json' \
     -H 'Accept: application/json' \
     -H 'Authorization: Basic <Your Basic Auth>'
     -d '{
     "isAuthOnly": true;
     "data": {
       "amount": 5.00,
       "currency": "EUR",
       "paymentMethod": "adyenSepa",
       "customer": {
         "orderNumber": "7beb71d234c441e5a3c6a475835f8590",
         "firstName": "John",
         "lastName": "Doe",
         "email": "john@doe.com"
       }
     }
   }'
   

   A successful response will include the expressIFrameUrl. Copy or store this for use in step 3.

   Example 200 Response

   {
     "expiration": "2021-07-22T20:49:50.000Z",
     "token": "cb1f6727-f425-4ac9-b958-2b43c8bf7ae8",
     "expressIFrameUrl": "https://api.nexiopaysandbox.com/apm/v3?token=cb1f6727-f425-4ac9-b958-2b43c8bf7ae8",
     "redirectUrls": [
       {
         "paymentMethod": "adyenSepa",
         "url": "https://api.nexiopaysandbox.com/apm/v3/popup?token=cb1f6727-f425-4ac9-b958-2b43c8bf7ae8&paymentMethod=adyenSepa"
       }
     ],
     "buttonIFrameUrls": [
       {
         "paymentMethod": "adyenSepa",
         "url": "https://api.nexiopaysandbox.com/apm/v3?token=cb1f6727-f425-4ac9-b958-2b43c8bf7ae8&paymentMethod=adyenSepa"
       },
       {
         "paymentMethod": "braintreePayPal",
         "url": "https://api.nexiopaysandbox.com/apm/v3?token=cb1f6727-f425-4ac9-b958-2b43c8bf7ae8&paymentMethod=braintreePayPal"
       }
     ],
     "scriptUrl": "https://api.nexiopaysandbox.com/apm/v3/scripts?token=cb1f6727-f425-4ac9-b958-2b43c8bf7ae8"
   }
   

3. Complete the Payment Process

   Follow steps 4-6 of the Express APM with SEPA tutorial.

   A successful auth only transaction will return a status of authOnly.

Response Handling with SEPA

Nexio responds with transaction results with Event messages.

For information about how to run the integration workflow, see Run a Transaction through SEPA.

Status Workflows with SEPA

The status of a successful transaction with SEPA varies, depending on the options you choose.

Sale

When isAuthOnly is false, successful sale transactions will have the following statuses:

• pending (called "authorized" when querying transactions and in Nexio Dashboard)
• settled

When isAuthOnly is true, successful sale transactions will have the following status:

• authOnly

Capture

Successful capture transactions will have the following status:

• settled

Error handling with SEPA

For help with errors and declines, see the Handling Errors and Declines topic in "Developer Documentation".

Troubleshooting with SEPA

If you encounter issues while implementing or testing SEPA with Adyen, contact integration support.

---

Run a Transaction

Express APM

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 will be shown a list of all available APMs, prompted to select their preference, then be redirected to complete payment.

Notes:

• This service is not compatible with embedded browsers in apps
• Apple Pay, Google Pay, and PayPal (with Braintree) are not currently supported through Express APM
• For the Klarna APM, see Express APM with Klarna for specific instructions on running transactions using Express APM
• For the SEPA APM, see Express APM with SEPA for specific instructions on running transactions using Express APM

To integrate with Express APM, follow the steps below.

1. Configure Your Account

   Contact integration support to enable any desired APMs on your merchant account.

2. Create a Checkout Page

   Create a checkout page with an iframe.

3. Request an Express Iframe URL

   Send a POST request to the APM One-time-use Token endpoint. Include the following required parameters:

   • data.amount
   • data.currency
   • data.customer.firstName
   • data.customer.lastName
   • data.customer.email
   • data.customer.orderNumber
   • customerRedirectUrl (only required if you intend to use your own external submit button)

   You may choose to have Nexio provide an in-frame submit button or your own external button by using the displaySubmitButton UI Option.

Example Request

curl -X POST https://api.nexiopaysandbox.com/apm/v3/token \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic <Your Basic Auth>'
  -d '{
  "data": {
    "amount": 29.99,
    "currency": "USD",
    "customer": {
      "firstName": "Maria",
      "lastName": "Velasquez",
      "email": "mvelaquez@fake.email",
      "orderNumber": "210058A"
    }
  },
  "uiOptions": {
    "displaySubmitButton": true
  },
  "customerRedirectUrl": "https://your-ecommerce-website.example.com"
}'

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

 Example 200 Response 

{
  "expiration": "2018-09-18T15:43:05.664Z",
  "token": "830d36f6-a5e3-4455-9600-3a55b63e2fc2",
  "expressIFrameUrl": "https://www.api.nexiopaysandbox.com/v3?token=79001ef6-fb40-4917-b8ae-2294fdfe1cf2",
  "redirectUrls": [
    {
      "paymentMethod": "payPal",
      "url": "https://www.api.nexiopaysandbox.com/v3/popup?token=79001ef6-fb40-4917-b8ae-2294fdfe1cf2&paymentMethod=payPal"
    }
  ],
  "buttonIFrameUrls": [
    {
      "paymentMethod": "applePayAuthNet",
      "url": "https://api.nexiopaysandbox.com/apm/v3?token=b61ca2a9-b804-4a28-a00e-b794c8975dee&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).

Example

var url = "https://www.api.nexiopaysandbox.com/v3?token=79001ef6-fb40-4917-b8ae-2294fdfe1cf2";
window.document.getElementById('myIframe').src = url;

When your iframe loads, shoppers will be prompted to select from a list of configured APMs. The shopper will make their selection, click 'Submit' (on your own external button or the iframe button, depending on your choice), then be redirected to their chosen APM to complete payment.

5. Shopper Completes Payment

   This step varies slightly depending on the APM.

   • Voucher payments (Paynet and SPEI): Users will be prompted to print or close the voucher page
   • All other APMs: Users will be 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

   Once the shopper has completed payment (or payment has failed) Nexio's iframe will request to be closed and send a message event or redirect URL with the payment information. If the payment was successful, the message will include the status and payment ID. If the payment failed, the message will include the status and an error message.

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

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

Example Sale Response

{
  "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": "nexiotest@example.com",
      "shipToState": "OR"
    }
  }
}

Example URL query string parameters response (for customerRedirectUrl):

Successful Payment Redirect

https://www.yourwebsite.com?id=eyJuYW1lIjoicGF5UGFsIiwibWVyY2hhbnRJZCI6IjEwMDAzOSIsInJlZk51bWJlciI6IjlLQTI2NzUwSEs5NzM2OTNBIiwicmFuZG9tIjowLCJjdXJyZW5jeSI6InVzZCJ9&status=success&orderNumber=054204daf0f7456bac59a014e952fb33

Button Iframe URLs

Notes:

• For the Klarna APM, see Button Iframe URLs with Klarna for specific instructions on running transactions using a button iframe URL

1. Configure Your Account

   Contact integration support to enable the desired APM on your merchant account. Note: Apple Pay and Google Pay require additional configuration steps, please see the Apple Pay configuration /Google Pay configuration sections for additional information.

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 will be used for Apple Pay an ID of nexioApplePayApmIframe (other, less common options, are nexio-apm-iframe or nexio-applePayAuthNet-apm-iframe).

Example 1: Apple Pay

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

Example 2: Other APMs

<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 APM One-time-use Token endpoint.

Include the following required parameters:

• data.amount
• data.currency
• data.customer.firstName
• data.customer.lastName
• data.customer.email
• data.customer.orderNumber
• customerRedirectUrl (only required if you intend to use your own external submit buttons)

Apple Pay only: If you wish to run the transaction through a domain other than the one you configured in step 1, include the parameter data.applePayDomain in the body of your request.

Braintree PayPal only: If you want to save a recurring token for a future merchant-initiated transaction, include the parameter processingOptions.saveRecurringToken in the body of your one-time-use token request and set it equal to true. In addition, if the amount to process on the Confirm/Place Order page will be more than the current amount, you must include this parameter so that you can send the payment request (for example, if adding tax and shipping costs to the amount).

Example Request

curl -X POST https://api.nexiopaysandbox.com/apm/v3/token \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic <Your Basic Auth>'
  -d '{
  "data": {
    "amount": 29.99,
    "currency": "USD",
    "customer": {
      "firstName": "Maria",
      "lastName": "Velasquez",
      "email": "mvelaquez@fake.email",
      "orderNumber": "210058A"
    }
  },
  "customerRedirectUrl": "https://your-ecommerce-website.example.com"
}'

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 step 5.

Apple Pay only: Copy the scriptUrl value as well for use in step 5.

Example 200 Response

{
  "expiration": "2018-09-18T15:43:05.664Z",
  "token": "830d36f6-a5e3-4455-9600-3a55b63e2fc2",
  "scriptUrl": "https://api.nexiopaysandbox.com/apm/v3/script?token=b61ca2a9-b804-4a28-a00e-b794c8975dee",
  "expressIFrameUrl": "https://www.api.nexiopaysandbox.com/v3?token=79001ef6-fb40-4917-b8ae-2294fdfe1cf2",
  "redirectUrls": [...],
  "buttonIFrameUrls": [
    {
      "paymentMethod": "nihaoPayAliPay",
      "url": "https://api.nexiopaysandbox.com/apm/v3?token=b61ca2a9-b804-4a28-a00e-b794c8975dee&paymentMethod=nihaoPayAliPay"
    },
    {
      "paymentMethod": "nihaoPayWechatPay",
      "url": "https://api.nexiopaysandbox.com/apm/v3?token=b61ca2a9-b804-4a28-a00e-b794c8975dee&paymentMethod=nihaoPayWechatPay"
    },
    {
      "paymentMethod": "payPal",
      "url": "https://api.nexiopaysandbox.com/apm/v3?token=b61ca2a9-b804-4a28-a00e-b794c8975dee&paymentMethod=payPal"
    },
    {
      "paymentMethod": "braintreePayPal",
      "url": "https://api.nexiopaysandbox.com/apm/v3?token=b61ca2a9-b804-4a28-a00e-b794c8975dee&paymentMethod=braintreePayPal"
    },
    {
      "paymentMethod": "nihaoPayUnionPay",
      "url": "https://api.nexiopaysandbox.com/apm/v3?token=b61ca2a9-b804-4a28-a00e-b794c8975dee&paymentMethod=nihaoPayUnionPay"
    },
    {
      "paymentMethod": "applePayAuthNet",
      "url": "https://api.nexiopaysandbox.com/apm/v3?token=b61ca2a9-b804-4a28-a00e-b794c8975dee&paymentMethod=applePayAuthNet"
    },
    {
      "paymentMethod": "googlePayAuthNet",
      "url": "https://api.nexiopaysandbox.com/apm/v3?token=b61ca2a9-b804-4a28-a00e-b794c8975dee&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 will load but the script will not work.)

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

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 is 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. 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 provide 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.

   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 will be used for Apple Pay an ID of nexioApplePayApmIframe (other, less common options, are nexio-apm-iframe or nexio-applePayAuthNet-apm-iframe).

Example 1: Apple Pay

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

Example 2: Other APMs

<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 APM One-time-use Token endpoint.

Include the following required parameters:

• data.amount
• data.currency
• data.customer.firstName
• data.customer.lastName
• data.customer.email
• data.customer.orderNumber
• customerRedirectUrl (only required if you intend to use your own external submit buttons)

Apple Pay only: If you wish to run the transaction through a domain other than the one you configured in step 1, include the parameter data.applePayDomain in the body of your request.

Braintree PayPal only: If you want to save a recurring token for a future merchant-initiated transaction, include the parameter processingOptions.saveRecurringToken in the body of your one-time-use token request and set it equal to true.

Example Request

curl -X POST https://api.nexiopaysandbox.com/apm/v3/token \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic <Your Basic Auth>'
  -d '{
  "data": {
    "amount": 29.99,
    "currency": "USD",
    "customer": {
      "firstName": "Maria",
      "lastName": "Velasquez",
      "email": "mvelaquez@fake.email",
      "orderNumber": "210058A"
    }
  },
  "customerRedirectUrl": "https://your-ecommerce-website.example.com"
}'

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 step 5.

Apple Pay only: Copy the scriptUrl value as well for use in step 5.

Example 200 Response

{
  "expiration": "2018-09-18T15:43:05.664Z",
  "token": "830d36f6-a5e3-4455-9600-3a55b63e2fc2",
  "scriptUrl": "https://api.nexiopaysandbox.com/apm/v3/script?token=b61ca2a9-b804-4a28-a00e-b794c8975dee",
  "expressIFrameUrl": "https://www.api.nexiopaysandbox.com/v3?token=79001ef6-fb40-4917-b8ae-2294fdfe1cf2",
  "redirectUrls": [...],
  "buttonIFrameUrls": [
    {
      "paymentMethod": "nihaoPayAliPay",
      "url": "https://api.nexiopaysandbox.com/apm/v3?token=b61ca2a9-b804-4a28-a00e-b794c8975dee&paymentMethod=nihaoPayAliPay"
    },
    {
      "paymentMethod": "nihaoPayWechatPay",
      "url": "https://api.nexiopaysandbox.com/apm/v3?token=b61ca2a9-b804-4a28-a00e-b794c8975dee&paymentMethod=nihaoPayWechatPay"
    },
    {
      "paymentMethod": "payPal",
      "url": "https://api.nexiopaysandbox.com/apm/v3?token=b61ca2a9-b804-4a28-a00e-b794c8975dee&paymentMethod=payPal"
    },
    {
      "paymentMethod": "braintreePayPal",
      "url": "https://api.nexiopaysandbox.com/apm/v3?token=b61ca2a9-b804-4a28-a00e-b794c8975dee&paymentMethod=braintreePayPal"
    },
    {
      "paymentMethod": "nihaoPayUnionPay",
      "url": "https://api.nexiopaysandbox.com/apm/v3?token=b61ca2a9-b804-4a28-a00e-b794c8975dee&paymentMethod=nihaoPayUnionPay"
    },
    {
      "paymentMethod": "applePayAuthNet",
      "url": "https://api.nexiopaysandbox.com/apm/v3?token=b61ca2a9-b804-4a28-a00e-b794c8975dee&paymentMethod=applePayAuthNet"
    },
    {
      "paymentMethod": "googlePayAuthNet",
      "url": "https://api.nexiopaysandbox.com/apm/v3?token=b61ca2a9-b804-4a28-a00e-b794c8975dee&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 will load but the script will not work.)

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

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 will be prompted to print or close the voucher page
   • Braintree PayPal only: If the customer checked out using Braintree PayPal 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: Users will be prompted to complete the transaction

   After the consumer completes payment, the popup window closes 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

   Once the shopper has completed payment (or payment has failed) Nexio's iframe will request to be closed and send a message event or redirect URL with the payment information. If the payment was successful, the message will include the status and payment ID. If the payment failed, the message will include the status and an error message.

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

   Example URL query string parameters response (for customerRedirectUrl):

Successful Payment Redirect

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

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

Failed Payment Redirect

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

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

Example Sale Response

{
  "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": "nexiotest@example.com",
      "shipToState": "OR"
    }
  }
}

Redirect URLs

The single APM integration option allows you to send shoppers directly to a single APM to complete payment. Upon completion (payment success or failure) shoppers will be redirected to the customer redirect URL provided in step 3 of the tutorial below.

Notes:

• PayPal (with Braintree) is not currently supported through Redirect URLs
• Klarna is not currently supported through Redirect URLs

To integrate with a single APM, follow the steps below.

1. Configure Your Account

   Contact integration support to enable the desired APM on your merchant account.

2. Create a Checkout Page

   On the page, for each APM you want, include a button, image, link, or similar element that the consumer can click.

3. Request an APM Redirect URL

   Send a POST request to the APM One-time-use Token endpoint. Include the following required parameters:

   • data.amount
   • data.currency
   • data.customer.firstName
   • data.customer.lastName
   • data.customer.email
   • data.customer.orderNumber
   • customerRedirectUrl

Example Request

curl -X POST https://api.nexiopaysandbox.com/apm/v3/token \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic <Your Basic Auth>'
  -d '{
  "data": {
    "amount": 29.99,
    "currency": "USD",
    "customer": {
      "firstName": "Maria",
      "lastName": "Velasquez",
      "email": "mvelaquez@fake.email",
      "orderNumber": "210058A"
    }
  },
  "customerRedirectUrl": "https://your-ecommerce-website.example.com"
}'

A successful request will return an array of redirectUrls. This array is a list of all APMs currently enabled on your merchant account. Copy the url of the desired APM for use in step 4.

Example 200 Response

{
  "expiration": "2018-09-18T15:43:05.664Z",
  "token": "830d36f6-a5e3-4455-9600-3a55b63e2fc2",
  "expressIFrameUrl": "https://www.api.nexiopaysandbox.com/v3?token=79001ef6-fb40-4917-b8ae-2294fdfe1cf2",
  "redirectUrls": [
      {
          "paymentMethod": "nihaoPayAliPay",
          "url": "https://www.api.nexiopaysandbox.com/v3/popup?token=79001ef6-fb40-4917-b8ae-2294fdfe1cf2&paymentMethod=nihaoPayAliPay"
      },
      {
          "paymentMethod": "payPal",
          "url": "https://www.api.nexiopaysandbox.com/v3/popup?token=79001ef6-fb40-4917-b8ae-2294fdfe1cf2&paymentMethod=payPal"
      },
      {
          "paymentMethod": "paynet",
          "url": "https://www.api.nexiopaysandbox.com/v3/popup?token=79001ef6-fb40-4917-b8ae-2294fdfe1cf2&paymentMethod=paynet"
      },
      {
          "paymentMethod": "openpaySpei",
          "url": "https://www.api.nexiopaysandbox.com/v3/popup?token=79001ef6-fb40-4917-b8ae-2294fdfe1cf2&paymentMethod=openpaySpei"
      },
      {
          "paymentMethod": "nihaoPayUnionPay",
          "url": "https://www.api.nexiopaysandbox.com/v3/popup?token=79001ef6-fb40-4917-b8ae-2294fdfe1cf2&paymentMethod=nihaoPayUnionPay"
      },
      {
          "paymentMethod": "nihaoPayWechatPay",
          "url": "https://www.api.nexiopaysandbox.com/v3/popup?token=79001ef6-fb40-4917-b8ae-2294fdfe1cf2&paymentMethod=nihaoPayWechatPay"
      }
  ],
  "buttonIFrameUrls": [...]
}

4. Redirect the Shopper to the APM

   For each APM, add the url copied from step 3 to the appropriate form action, onClick location.url event, link src, and so forth for the element you added in step 2.

   Now, when the page loads, the shopper will see a button, image, and so forth for the APM (or APMs). The shopper clicks the element and then gets redirected (or a popup window opens) to the APM to complete payment.

5. Shopper Completes Payment

   This step varies slightly depending on the APM.

   • Voucher payments (Paynet and SPEI): Users will be prompted to print or close the voucher page
   • All other APMs: Users will be prompted to complete the transaction

   Afterward, the popup window will close and they will be redirected back to the merchant website specified in the customerRedirectUrl from Step 3. Nexio provides a response via query string parameters in the URL.

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

6. Shopper Redirected

   Once the shopper has completed payment (or payment has failed) they will be redirected to the customerRedirectUrl you provided in step 3. If the payment was successful, the redirect URL will include the status, payment ID and order number as query parameters. If the payment failed, the redirect URL will include the status and an error message as query parameters.

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

Successful Payment Redirect

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

Failed Payment Redirect

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

Example response for a webhook:

Example Sale Response

{
  "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": "nexiotest@example.com",
      "shipToState": "OR"
    }
  }
}

Merchant-Initiated Transactions

You may want to support merchant-initiated transactions through PayPal (with Braintree) for your customers, such as for recurring transactions.

To allow for merchant-initiated transactions, follow the steps below.

1. Configure Your Account

   Configure your Nexio account to use Braintree PayPal. If you need to have this done, contact integration support.

2. Create Necessary Payment Flow Pages

   Complete step 2 in Button Iframe URLs to create any needed pages.

3. Configure Pages

   Complete step 3 in Button Iframe URLs to create a Shopping Cart page. Include the URL from the "braintreePayPal" paymentMethod to add that payment option to the checkout page. IMPORTANT: Make sure to include the processingOptions.saveRecurringToken parameter in the body of your one-time-use token request and set it equal to true.

   Complete step 4 in Button Iframe URLs to create a Confirm/Place Order page.

   Complete step 5 in Button Iframe URLs to create a Checkout page. Include the URL from the "braintreePayPal" paymentMethod to add that payment option to the checkout page. IMPORTANT: Make sure to include the processingOptions.saveRecurringToken parameter in the body of your one-time-use token request and set it equal to true.

4. Shopper Completes Payment and You Save APM Token

   If the customer clicks the PayPal (through Braintree) button as the payment method (steps 6-7 in Button Iframe URLs), then, in the event posted to your window, the response includes an apm.token parameter.

   Save the apm.token value somewhere in order to use it again (probably similar to how you save TokenEx tokens already).

   WARNING: This apm.token value cannot be retrieved through the API at any other time.

   By way of example, a response may look like the following. Notice the apm object and its token:

Example Braintree PayPal Sale Response

{
  "id": "eyJuYW1lIjoiYnJhaW50cmVlUGF5UGFsIiwibWVyY2hhbnRJZCI6IjEwMTAzOSIsInJlZk51bWJlciI6InA0NXljeWQ5IiwicmFuZG9tIjowLCJjdXJyZW5jeSI6InVzZCJ9",
  "merchantId": "101039",
  "transactionDate": "2021-07-13T22:12:56.780Z",
  "transactionStatus": "settled",
  "amount": 4,
  "transactionType": "sale",
  "currency": "USD",
  "gatewayResponse": {
    "result": "settling",
    "refNumber": "p45ycyd9",
    "gatewayName": "braintreePayPal",
    "message": "settling"
  },
  "data": {
    "amount": 4,
    "currency": "USD",
    "settlementCurrency": "USD",
    "customer": {
      "lastName": "Test",
      "shipToAddressOne": "123 Ship St",
      "shipToPhone": "5033335678",
      "orderNumber": "1151057c04214a688c382ee1f666e76e",
      "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": "nexiotest@example.com",
      "shipToState": "OR"
    }
  },
  "apm": {
    "token": "apm:66b742ee-7abc-4e36-81ea-0a26d23d2822"
  }
}

5. Run Merchant-Initiated Payment

   Later, when you are ready to initiate another transaction for the customer without their input, use that stored apm.token value from step 4 above to run a payment.

   Send a POST request to the APM Run Transaction endpoint, as in the following example. Notice the inclusion of the apm object with its token in the body of the request:

Example Merchant-Initiated Request

curl -X POST https://api.nexiopaysandbox.com/apm/v3/process \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic <Your Basic Auth>'
  -d '{
  "isAuthOnly": false,
  "apm": {
    "token": "apm:66b742ee-7abc-4e36-81ea-0a26d23d2822"
  },
  "data": {
    "currency":"USD",
    "amount": 9.95,
    "description": "test purchase",
    "customer": {
      "orderNumber": "sdgsrgrsb",
      "firstName":"Joe",
      "lastName":"Brown",
      "billToAddressOne": "123 Street",
      "billToAddressTwo": "Box 232",
      "billToCity": "Narnia",
      "billToState": "TX",
      "billToPostal": "46632",
      "billToCountry": "USA"
    }
  }
}'

You will then get a response, which will be similar to other payment responses that you normally get. On success, the response looks similar to the following:

Example 200 Response

{
    "id": "eyJuYW1lIjoiYnJhaW50cmVlUGF5UGFsIiwibWVyY2hhbnRJZCI6IjEwMTAzOSIsInJlZk51bWJlciI6Ims3ZDN6cDJlIiwicmFuZG9tIjowLCJjdXJyZW5jeSI6InVzZCJ9",
    "merchantId": "101039",
    "transactionDate": "2021-07-13T22:14:03.514Z",
    "transactionStatus": "settled",
    "amount": 9.95,
    "transactionType": "sale",
    "currency": "USD",
    "gatewayResponse": {
        "result": "settling",
        "refNumber": "k7d3zp2e",
        "gatewayName": "braintreePayPal",
        "message": "settling"
    },
    "data": {
        "amount": 88,
        "currency": "USD",
        "settlementCurrency": "USD",
        "customer": {
            "orderNumber": "sdgsrgrsb",
            "firstName": "Joe",
            "lastName": "Brown",
            "billToAddressOne": "123 Street",
            "billToAddressTwo": "Box 232",
            "billToCity": "Narnia",
            "billToState": "TX",
            "billToPostal": "46632",
            "billToCountry": "USA"
        }
    }
}

Run an Auth Only Transaction

You may wish to authorize a transaction (auth only) and capture it at a later time. Please note that auth only transaction(s) are currently only available through the following alternative payment methods:

• PayPal
• PayPal (with Braintree)
• Apple Pay and Google Pay
• Klarna
• SEPA with Adyen

PayPal

To run an auth only transaction through PayPal, follow the steps below.

1. Prepare Your Checkout Page

   Follow steps 1-2 of the Redirect URLs Integration tutorial.

2. Request the APM Redirect URL

   Follow step 3 of the Redirect URLs Integration tutorial. Include isAuthOnly: true in the body of your request.

Example Request

curl -X POST https://api.nexiopaysandbox.com/apm/v3/token \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic <Your Basic Auth>'
  -d '{
  "data": {
    "amount": 29.99,
    "currency": "USD",
    "customer": {
      "firstName": "Maria",
      "lastName": "Velasquez",
      "email": "mvelaquez@fake.email",
      "orderNumber": "210058A"
    }
  },
  "isAuthOnly": true,
  "customerRedirectUrl": "https://your-ecommerce-website.example.com"
}'

Example 200 Response

{
  "expiration": "2018-09-18T15:43:05.664Z",
  "token": "830d36f6-a5e3-4455-9600-3a55b63e2fc2",
  "scriptUrl": "https://api.nexiopaysandbox.com/apm/v3/script?token=b61ca2a9-b804-4a28-a00e-b794c8975dee",
  "expressIFrameUrl": "https://www.api.nexiopaysandbox.com/v3?token=79001ef6-fb40-4917-b8ae-2294fdfe1cf2",
  "redirectUrls": [
      {
          "paymentMethod": "nihaoPayAliPay",
          "url": "https://www.api.nexiopaysandbox.com/v3/popup?token=79001ef6-fb40-4917-b8ae-2294fdfe1cf2&paymentMethod=nihaoPayAliPay"
      },
      {
          "paymentMethod": "payPal",
          "url": "https://www.api.nexiopaysandbox.com/v3/popup?token=79001ef6-fb40-4917-b8ae-2294fdfe1cf2&paymentMethod=payPal"
      }
  ],
  "buttonIFrameUrls": [...]
}

A successful request will return an array of redirectUrls. This array is a list of all APMs currently enabled on your merchant account. Copy the URL associated with the payPal payment method.

3. Complete the Payment Process

   Follow steps 4-6 of the Redirect URLs Integration tutorial. A successful auth only transaction will return a status of success

PayPal (with Braintree)

To run an auth only transaction through PayPal (with Braintree), follow the steps below.

1. Prepare Your Cart or Checkout Page

   Follow steps 1-5 of the Button Iframe URLs tutorial.

   In making the one-time-use token request, include isAuthOnly: true in the body of your request. If you want to save a recurring token for a future merchant-initiated transaction, include processingOptions.saveRecurringToken in the body of your request and set it equal to true.

Example Request

curl -X POST https://api.nexiopaysandbox.com/apm/v3/token \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic <Your Basic Auth>'
  -d '{
  "data": {
    "amount": 29.99,
    "currency": "USD",
    "customer": {
      "firstName": "Maria",
      "lastName": "Velasquez",
      "email": "mvelaquez@fake.email",
      "orderNumber": "210058A"
    }
  },
  "isAuthOnly": true,
  "processingOptions": {
    "saveRecurringToken": true
  },
  "customerRedirectUrl": "https://your-ecommerce-website.example.com"
}'

Example 200 Response

{
  "expiration": "2018-09-18T15:43:05.664Z",
  "token": "830d36f6-a5e3-4455-9600-3a55b63e2fc2",
  "scriptUrl": "https://api.nexiopaysandbox.com/apm/v3/script?token=b61ca2a9-b804-4a28-a00e-b794c8975dee",
  "expressIFrameUrl": "https://www.api.nexiopaysandbox.com/v3?token=79001ef6-fb40-4917-b8ae-2294fdfe1cf2",
  "redirectUrls": [...],
  "buttonIFrameUrls": [
    {
      "paymentMethod": "nihaoPayAliPay",
      "url": "https://www.api.nexiopaysandbox.com/v3/popup?token=79001ef6-fb40-4917-b8ae-2294fdfe1cf2&paymentMethod=nihaoPayAliPay"
    },
    {
      "paymentMethod": "braintreePayPal",
      "url": "https://www.api.nexiopaysandbox.com/v3/popup?token=79001ef6-fb40-4917-b8ae-2294fdfe1cf2&paymentMethod=braintreePayPal"
    },
    {
      "paymentMethod": "payPal",
      "url": "https://www.api.nexiopaysandbox.com/v3/popup?token=79001ef6-fb40-4917-b8ae-2294fdfe1cf2&paymentMethod=payPal"
    }
  ]
}

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 associated with the braintreePayPal payment method.

2. Complete the Payment Process

   Follow steps 6-7 of the Button Iframe URLs tutorial.

   A successful auth only transaction returns a status of success.

   NOTE: If the customer selected PayPal (with Braintree) as the payment method, then, in the event posted to your window, the response includes an apm.token parameter. Save the apm.token value somewhere in order to use it again (probably similar to how you save TokenEx tokens already).

Apple Pay and Google Pay

To run an auth only transaction through Apple Pay or Google Pay, follow the steps below.

1. Prepare Your Checkout Page

   Follow steps 1-3 of the Button Iframe URLs tutorial.

2. Request the APM Button Iframe URLs

   Follow step 4 of the Redirect URLs Integration tutorial. Include isAuthOnly: true in the body of your request.

Example Request

curl -X POST https://api.nexiopaysandbox.com/apm/v3/token \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic <Your Basic Auth>'
  -d '{
  "data": {
    "amount": 29.99,
    "currency": "USD",
    "customer": {
      "firstName": "Maria",
      "lastName": "Velasquez",
      "email": "mvelaquez@fake.email",
      "orderNumber": "210058A"
    }
  },
  "isAuthOnly": true,
  "customerRedirectUrl": "https://your-ecommerce-website.example.com"
}'

Example 200 Response

{
  "expiration": "2018-09-18T15:43:05.664Z",
  "token": "830d36f6-a5e3-4455-9600-3a55b63e2fc2",
  "scriptUrl": "https://api.nexiopaysandbox.com/apm/v3/script?token=b61ca2a9-b804-4a28-a00e-b794c8975dee",
  "expressIFrameUrl": "https://www.api.nexiopaysandbox.com/v3?token=79001ef6-fb40-4917-b8ae-2294fdfe1cf2",
  "redirectUrls": [...],
  "buttonIFrameUrls": [
    {
      "paymentMethod": "applePayAuthNet",
      "url": "https://api.nexiopaysandbox.com/apm/v3?token=b61ca2a9-b804-4a28-a00e-b794c8975dee&paymentMethod=applePayAuthNet"
    },
    {
      "paymentMethod": "googlePayAuthNet",
      "url": "https://api.nexiopaysandbox.com/apm/v3?token=b61ca2a9-b804-4a28-a00e-b794c8975dee&paymentMethod=googlePayAuthNet"
    }
  ]
}

A successful request will return an array of buttonIFrameUrls. This array is a list of all APMs currently enabled on your merchant account. Copy the url associated with the Apple Pay or Google Pay payment method. (Or both the Apple Pay and Google Pay urls.)

3. Complete the Payment Process

   Follow steps 5-7 of the Button Iframe URLs tutorial. A successful auth only transaction will return a status of success

Klarna

You can run an auth only transaction through Klarna using any of these integration methods:

• Express APM for Auth Only with Klarna
• Button Iframe URLs for Auth Only with Klarna

Express APM for Auth Only with Klarna

To run an auth only transaction through Klarna using Express APM, follow the steps below.

1. Prepare Your Checkout Page

   Follow steps 1-2 of the Express APM with Klarna tutorial.

2. Request an Express Iframe URL

   Follow step 3 of the Express APM with Klarna tutorial.

   Include isAuthOnly: true in the body of your request.

Example Request

curl -X POST https://api.nexiopaysandbox.com/apm/v3/token \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic <Your Basic Auth>'
  -d '{
  "data": {
    "amount": 4.00,
    "currency": "USD",
    "customer": {
      "orderNumber": "12345678",
      "firstName": "John",
      "lastName": "Doe",
      "email": "john@doe.com",
      "billToCountry": "US"
    },
    "totalTaxAmount": 0,
    "cart": {
     "items": [
       {
          "item": "E200",
          "description": "Platinum set",
          "quantity": 2,
          "price": 2
        }
      ]
    }
  },
  "customerRedirectUrl": "https://www.yourwebsite.com",
  "uiOptions": {
    "displaySubmitButton": true
  },
  "isAuthOnly": true
}'

A successful response will include the expressIFrameUrl. Copy or store this for use in step 3.

Example 200 Response

{
  "expiration": "2021-07-22T20:49:50.000Z",
  "token": "54a0106y-7750-45b1-961e-29ad95763a23",
  "expressIFrameUrl": "https://api.nexiopaysandbox.com/apm/v3?token=54a0106y-7750-45b1-961e-29ad95763a23",
  "redirectUrls": [
   {
      "paymentMethod": "klarna",
      "url": "https://api.nexiopaysandbox.com/apm/v3/popup?token=54a0106b-7750-45b1-961e-29ad95763a23&paymentMethod=klarna"
    }
  ],
  "buttonIFrameUrls": [
    {
      "paymentMethod": "klarna",
      "url": "https://api.nexiopaysandbox.com/apm/v3?token=54a0106b-7750-45b1-961e-29ad95763a23&paymentMethod=klarna"
    },
    {
      "paymentMethod": "braintreePayPal",
      "url": "https://api.nexiopaysandbox.com/apm/v3?token=54a0106b-7750-45b1-961e-29ad95763a23&paymentMethod=braintreePayPal"
    }
  ],
  "scriptUrl": "https://api.nexiopaysandbox.com/apm/v3/scripts?token=54a0106y-7750-45b1-961e-29ad95763a23"
}

3. Complete the Payment Process

   Follow steps 4-6 of the Express APM with Klarna tutorial.

   A successful auth only transaction will return a status of authOnlyPending or authOnly.

Button Iframe URLs for Auth Only with Klarna

To run an auth only transaction through Klarna using the button iframe URLs, follow the steps below.

1. Prepare Your Checkout Page

   Follow steps 1-3 of the Button Iframe URLs with Klarna tutorial.

2. Request the APM Button Iframe URLs

   Follow step 4 of the Button Iframe URLs with Klarna tutorial. Include isAuthOnly: true in the body of your request.

Example Request

curl -X POST https://api.nexiopaysandbox.com/apm/v3/token \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic <Your Basic Auth>'
  -d '{
  "data": {
    "amount": 4.00,
    "currency": "USD",
    "customer": {
      "orderNumber": "12345678",
      "firstName": "John",
      "lastName": "Doe",
      "email": "john@doe.com",
      "billToCountry": "US"
    },
    "totalTaxAmount": 0,
    "cart": {
      "items": [
        {
          "item": "E200",
          "description": "Platinum set",
          "quantity": 2,
          "price": 2
        }
      ]
    }
  },
  "customerRedirectUrl": "https://www.yourwebsite.com",
  },
  "isAuthOnly": true
}'

A successful request will return an array of buttonIFrameUrls. This array is a list of all APMs currently enabled on your merchant account. Copy the url associated with the klarna payment method.

Example 200 Response

{
  "expiration": "2021-07-22T20:49:50.000Z",
  "token": "54a0106y-7750-45b1-961e-29ad95763a23",
  "expressIFrameUrl": "https://api.nexiopaysandbox.com/apm/v3?token=54a0106y-7750-45b1-961e-29ad95763a23",
  "redirectUrls": [
    {
      "paymentMethod": "klarna",
      "url": "https://api.nexiopaysandbox.com/apm/v3/popup?token=54a0106b-7750-45b1-961e-29ad95763a23&paymentMethod=klarna"
    }
  ],
  "buttonIFrameUrls": [
    {
      "paymentMethod": "klarna",
      "url": "https://api.nexiopaysandbox.com/apm/v3?token=54a0106b-7750-45b1-961e-29ad95763a23&paymentMethod=klarna"
    },
    {
      "paymentMethod": "braintreePayPal",
      "url": "https://api.nexiopaysandbox.com/apm/v3?token=54a0106b-7750-45b1-961e-29ad95763a23&paymentMethod=braintreePayPal"
    }
  ],
  "scriptUrl": "https://api.nexiopaysandbox.com/apm/v3/scripts?token=54a0106y-7750-45b1-961e-29ad95763a23"
}

3. Complete the Payment Process

   Follow steps 5-7 of the Button Iframe URLs with Klarna tutorial.

   A successful auth only transaction will return a status of authOnlyPending or authOnly.

Webhooks For APM Transactions

All of Nexio's available APMs process transactions asynchronously. In order to receive updates about the status of an APM transaction, you must configure webhooks for each expected event type. The table below lists the possible events that can occur for each APM.

For further explanation of the webhook event types, see the Webhook Event Types table.

APM	Possible Webhook Event Types
Alipay	TRANSACTION_SETTLED, TRANSACTION_REFUNDED
Apple Pay	TRANSACTION_SETTLED, TRANSACTION_REFUNDED
Google Pay	TRANSACTION_SETTLED, TRANSACTION_REFUNDED
Klarna	TRANSACTION_AUTHORIZED, TRANSACTION_CAPTURED, TRANSACTION_REFUNDED, TRANSACTION_SETTLED
Paynet	TRANSACTION_SETTLED, TRANSACTION_PENDING
SPEI	TRANSACTION_SETTLED, TRANSACTION_PENDING
PayPal	TRANSACTION_AUTHORIZED, TRANSACTION_CAPTURED, TRANSACTION_REFUNDED, TRANSACTION_SETTLED, TRANSACTION_VOIDED
PayPal (with Braintree)	TRANSACTION_AUTHORIZED, TRANSACTION_CAPTURED, TRANSACTION_REFUNDED, TRANSACTION_SETTLED, TRANSACTION_VOIDED
UnionPay	TRANSACTION_SETTLED, TRANSACTION_REFUNDED
WeChat Pay	TRANSACTION_SETTLED, TRANSACTION_REFUNDED

Pay Later Messaging

You can present customers with Pay Later messaging that provides information about financing options. Depending on the available payment methods, this messaging indicates whether customers can pay later or in installments.

Pay Later messaging is only supported for the following alternative payment methods:

• Klarna
• PayPal (for more information about the messaging, see PayPal Pay Later Messaging)

To enable any desired APMs on your merchant account, contact integration support.

Note: Pay Later messaging can be shown for only one payment method on the merchant account. If you need to change which payment method is enabled for Pay Later messaging, contact integration support.

Use Pay Later Messaging

You can use Pay Later messaging on any relevant page within your workflow, such as the product details or checkout pages.

In order to present customers with Pay Later messaging, complete the following steps:

1. Configure Your Account

   Contact integration support to enable any desired APMs on your merchant account.

   Note: Pay Later messaging can be shown for only one payment method on the merchant account. If you need to change which payment method is enabled for Pay Later messaging, contact integration support.

2. Add DIV to Page

   Add a div tag with a unique class (for example, "nexio-installments-div") to any relevant web pages in your workflow. The value is case-sensitive and cannot contain any spaces.

   You can include multiple different DIV sections and script references on the same page for different Pay Later messaging. This allows the promotion of several products on the same page with differing amounts, so the message is customized to the product amount.

   Put the DIV element where you want the Pay Later messaging to display on the page.

   For example:

<html>
  <body>
    ...
    <div class="nexio-installments-div" />
    ...
  </body>
</html>

3. Add Script to Page

   Add the Pay Later messaging script to any relevant web pages in your workflow.

   The URL for the script must include a Nexio username, the total amount, the three-character ISO currency code, and optionally the DIV class to reference (if left out, the system uses the default of "nexio-installments-div").

   The script takes the following form:

https://{nexio_environment_base_URL}/apm/v3/installment/{username}/{total_amount}/{currency_code}/script.js?divId={unique-div-id}

Substitute the relevant text above with the appropriate values or your own variables. For example, where the environment is the sandbox, the Nexio user is jdoe@example.com, the amount is 104.55, the currency is USD, and the DIV ID is my-div-id, the script would look like the following example:

<script src="https://api.nexiopaysandbox.com/apm/v3/installment/jdoe@example.com/104.55/USD/script.js?divId=my-div-id" />

Use different divIDs in different script tags to reference each unique message you want and which DIV to show it in.

4. Verify

   Open your site in a browser to verify the Pay Later wording displays as expected.

   The exact messaging text varies, depending on the available payment methods.

   Examples:

   • Pay in 4 interest-free payments of $26.14
   • Pay in 4 interest-free payments on qualifying purchases
   • No Interest if paid in full in 6 months

Troubleshooting Klarna Pay Later Messaging

Nexio provides a couple error messages in the response to assist in troubleshooting problems.

Status 400

The 400 message code indicates that the format used for the divId is not valid. For example, if there are spaces in the name.

Remove any spaces or other problem characters and retry the request.

Status 500

The 500 message code indicates that there is no matching DIV on the page with the specified divId.

Change the divId in the script to match one on the page, or add a DIV to the page and use the divId indicated in the script as the ID of the DIV.

Decline Recovery (BETA)

Note: This feature is in beta. Decline Recovery is a dynamic tool that helps ensure you don't lose revenue due to payment declines. When the Decline Recovery service is enabled, Nexio will automatically retry declined transactions at a more desirable date and time or with more complete customer information as available (for example, a billing address). You can use Nexio's Decline Recovery service when running card transactions with the API or card transactions run through the subscription service.

Notes:

• Decline Recovery does not immediately determine whether the payment will go through at a later date. It should not be used for payments for which the customer will be waiting for payment confirmation, such as through the payment iframe or your own form.
• Decline Recovery will not attempt to retry transactions classified as hard declines. In general, hard declines require the issuer or cardholder to rectify outstanding issues. (See FlexPay's documentation for more information regarding hard and soft declines.)

With The API

You may enable Decline Recovery on transactions run directly through the Nexio API.

1. Configure Your Account

   Contact integration support to enable Decline Recovery on your merchant account.

2. Configure Webhooks

   In order to be notified when a previously declined transaction is successfully processed, you must configure webhooks for TRANSACTION_AUTHORIZED, TRANSACTION_CAPTURED and TRANSACTION_SETTLED events. See the Webhooks tutorial for instructions on how to configure and receive webhooks. You may also wish to configure webhooks for other transaction events at this time.

   (Skip this step if you have already configured webhooks for all desired events on your account.)

3. Post Card Information to Nexio

   Post payment details along with a previously saved card token to the Run Card Transaction endpoint. Include the object "processingOptions": { "retryOnSoftDecline": true } in the body of your request.

   If desired you may also choose to run an auth only transaction.

Example Request

curl -X POST https://api.nexiopaysandbox.com/pay/v3/process \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic <Your Basic Auth>'
  -d '{
  "data": {},
  "tokenex": {
    "token": "6ee140a0-05d1-4958-8325-b38a690dbb9d"
  },
  "processingOptions": {
    "retryOnSoftDecline": true
  }
}'

Now, any successful transactions will be run as usual. Soft declines will be scheduled to be rerun at a later time.

4. Await Success Confirmation

   Each time a transaction is retried Nexio will send a webhook (see step 2) with one of the following event types: TRANSACTION_AUTHORIZED, TRANSACTION_CAPTURED and TRANSACTION_SETTLED. The webhook body will include the transaction status (data.transactionStatus), letting you know whether the transaction was successful.

Through the Subscription Service

You may enable Decline Recovery on transactions run through the Nexio Subscription Service.

1. Configure Your Account

   Contact integration support to enable Decline Recovery on your merchant account.

2. Configure Webhooks

   In order to be notified when a previously declined transaction is successfully processed, you must configure webhooks for TRANSACTION_AUTHORIZED, TRANSACTION_CAPTURED and TRANSACTION_SETTLED events. See the Webhooks tutorial for instructions on how to configure and receive webhooks. You may also wish to configure webhooks for other transaction events at this time.

3. Create a Subscription or Pay Plan

   Follow steps 1-2 of the Create a Subscription or Create a Pay Plan tutorial. Set the parameter payment.processingOptions.retryOnSoftDecline to true in the body of your request.

Example Request

curl -X POST https://api.nexiopaysandbox.com/subscription/v3 \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic <Your Basic Auth>'
  -d '{
  "payment": {
    "data": {
      "amount": 19.99,
      "currency": "USD",
      "customer": {
        "customerRef": "RP006"
      }
    },
    "tokenex": {
      "token": "6ee140a0-05d1-4958-8325-b38a690dbb9d"
    },
    "processingOptions": {
      "retryOnSoftDecline": true
    }
  },
  "schedule": {
    "interval": "week",
    "intervalCount": 2
  }
}'

If the initial transaction is declined, the subscription will not be created. It must be re-created with corrected information (such as new card token, corrected billing information, etc.) Any future transactions that are declined will be rerun at a later date and time. (Up to 11 times within a 30 day period.)

Note: Subscriptions run with Decline Recovery have a minimum interval of 29 days.

4. Monitor Webhooks

   Each time a transaction is retried Nexio will send a webhook (see step 2) with one of the following event types: TRANSACTION_AUTHORIZED, TRANSACTION_CAPTURED and TRANSACTION_SETTLED. The webhook body will include the transaction status (data.transactionStatus), letting you know whether the transaction was successful.

Retrieve Transactions from Decline Recovery

You can obtain a list of declined and recovered transactions and their recovery status for a specified date range.

To retrieve transactions by recovery status, do the following:

1. Retrieve recovery status

   Perform a GET request for the declined transactions with the /recovery/v3 endpoint.

   You can specify a start and end date as part of the request. You can also specify to retrieve transactions of a specific recoveryStatus. The following table shows the possibilities for recoveryStatus and what they mean.

   recoveryStatus	Status	Description
   10	Disabled	No retry attempt made. Can be enabled if merchant is configured for Decline Recovery service.
   20	In progress	Transaction request has been sent to the gateway for processing. This is a temporary status.
   30	Scheduled	The retry attempt has been scheduled.
   40	Unrecoverable	The declined transaction cannot be retried.
   50	Recovered	The transaction has been successfully retried.

   For details on other options with this request, see Recovery Status in the Reporting API.

   For example, in the following, the request is to retrieve all declined or recovered transactions regardless of status for the second quarter of 2021, starting with the first one and showing only 10 at a time.

Example Request

curl -X GET 'https://api.nexiopaysandbox.com/recovery/v3?startDate=2021-03-01&endDate=2021-06-30&offset=0&limit=10' \
  -H 'Authorization: Basic <Your Basic Auth>'

2. Note the recoveryStatus of the transactions in the response

   The response includes a rows array with each transaction that matches the request parameters. The information for each item in the array includes a recoveryStatus.

   This example response shows 3 resulting transactions. Note that the first one has a recoveryStatus of 30, indicating that the retry attempt is scheduled. The second one has a recoveryStatus of 50, indicating that the retry of the transaction was successful. The third one has a recoveryStatus of 40, indicating that the declined transaction cannot be retried.

Example 200 Response

{
  "offset": 0,
  "limit": 10,
  "rows": [
    {
      "id": 62641,
      "retryDate": "2021-06-08T19:00:00.000Z",
      "transactionDate": "2021-05-25T14:08:20.000Z",
      "originalAmount": 77.65,
      "originalDeclinePaymentId": "eyJuYW1lIjoiIiwibWVyY2hhbnRJZCI6IjEwMDI2MCIsInJlZk51bWJlciI6IjQwMDY1OTkyNDM3IiwicmFuZG9tIjowLCJjdXJyZW5jeSI6InVzZCJ9",
      "orderNumber": "210058A",
      "recoveryStatus": 30,
      "retryCount": 13,
      "merchantId": "100260",
      "userName": "jbanks@cmsonline.com",
      "isEnabledForRecovery": true,
      "updatedAt": "2021-06-07T19:01:28.000Z",
      "declineMessage": "This transaction has been declined."
    },
    {
      "id": 61829,
      "retryDate": "2021-05-24T15:13:26.000Z",
      "transactionDate": "2021-05-24T21:09:22.000Z",
      "originalAmount": 77.58,
      "originalDeclinePaymentId": "eyJuYW1lIjoiIiwibWVyY2hhbnRJZCI6IjEwMDI2MCIsInJlZk51bWJlciI6IjQwMDY1OTM3MzAyIiwicmFuZG9tIjowLCJjdXJyZW5jeSI6InVzZCJ9",
      "orderNumber": "210058A",
      "recoveryStatus": 50,
      "retryCount": 5,
      "merchantId": "100039",
      "userName": "api-test-sandbox@cmsonline.com",
      "isEnabledForRecovery": true,
      "updatedAt": "2021-05-27T21:15:26.000Z",
      "declineMessage": "This transaction has been declined."
    },
    {
      "id": 35343,
      "retryDate": null,
      "transactionDate": "2021-04-09T16:00:48.000Z",
      "originalAmount": 109.33,
      "originalDeclinePaymentId": "eyJuYW1lIjoiIiwibWVyY2hhbnRJZCI6IjEwMDI2MCIsInJlZk51bWJlciI6ImNoXzFJVDd6SUtHTVRlYmRqQjR2bm5RbkVPWCIsInJhbmRvbSI6MCwiY3VycmVuY3kiOiJhdWQifQ==",
      "orderNumber": "1234567",
      "recoveryStatus": 40,
      "retryCount": 0,
      "merchantId": "100039",
      "userName": "api-test-sandbox@cmsonline.com",
      "isEnabledForRecovery": false,
      "updatedAt": "2021-04-09T16:01:25.000Z",
      "declineMessage": "Your card was declined. This transaction requires authentication."
    }
  ],
  "hasMore": false
}

Address Verification Service

The Address Verifcation Service (AVS) compares the address and postal code provided with the information on file with the credit card issuer. Nexio interprets these results and returns them concisely back to you, making it easy for you to determine which cards to save, giving you greater control over your risk management. You can use AVS while saving a card token with the Nexio iframe, with your own form, or through the API.

Contact Integrations Support if you have questions about address verification.

Enable AVS

With the Nexio Iframe

1. Determine the Correct Setting

   Use the AVS Settings table to determine which AVS setting best suits your needs.

2. Prepare the Iframe

   Follow steps 1-2 of the Create a Save Card Page With the Nexio Iframe tutorial.

3. Request a One-time-use Token

   Request an e-commerce one-time-use token.

   Include the object "processingOptions": { "verifyAvs": <your AVS setting from step 1> } in the body of your request.

Example Request

curl -X POST https://api.nexiopaysandbox.com/pay/v3/token \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic <Your Basic Auth>'
  -d '{
  "processingOptions": {
    "verifyAvs": 3
  }
}'

4. Load the Iframe

   Follow steps 4-6 of the Create a Save Card Page With the Nexio Iframe. Now, when the iframe is loaded an AVS check will be performed.

   Nexio will return the results back to you in the AVS response.

With Your Own Form

1. Determine the Correct Setting

   Use the AVS Settings table to determine which AVS setting best suits your needs.

2. Prepare the Iframe

   Follow steps 1-6 of the Create a Save Card Page With Your Own Form tutorial.

3. Request a One-time-use Token

   Request an e-commerce one-time-use token.

   Include the object "processingOptions": { "verifyAvs": <your AVS setting from step 1> } in the body of your request.

   (This is step 7a of the Create a Save Card Page With Your Own Form tutorial.)

Example Request

curl -X POST https://api.nexiopaysandbox.com/pay/v3/token \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic <Your Basic Auth>'
  -d '{
  "processingOptions": {
    "verifyAvs": 3
  }
}'

4. Post Card Information to Nexio

   Follow step 7b of the Create a Save Card Page With Your Own Form tutorial.

5. Listen for Nexio's Response

   Follow step 8 of the Create a Save Card Page With Your Own Form tutorial. See the AVS Response section for more information about the possible results included in the response.

With the Nexio API

1. Determine the Correct Setting

   Use the AVS Settings table to determine which AVS setting best suits your needs.

2. Request a One-time-use Token

   Request an e-commerce one-time-use token.

   Include the object "processingOptions": { "verifyAvs": <your AVS setting from step 1> } in the body of your request.

Example Request

curl -X POST https://api.nexiopaysandbox.com/pay/v3/token \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic <Your Basic Auth>'
  -d '{
  "processingOptions": {
    "verifyAvs": 3
  }
}'

3. Post Card Information to Nexio

   Follow step 3 of the Save a Card Token with the Nexio API.

The AVS Response

When you check AVS your response will include an object called avsResults. See the example below.

Example 200 Response

{
  "token": {...},
  "card": {...},
  "data": {...},
  "avsResults": {
    "matchAddress": true,
    "matchPostal": true,
    "gatewayResponse": {...}
  },
  "cardType": "visa"
}

Match Address

The results of the address check.

• True: The address provided matches the address on file with the credit card issuer.
• False: The address provided does not match the address on file with the credit card issuer.

(In this case, 'address' refers to the street address portion of the billing address. For example, if the address provided were 123 Sesame St. Manhattan, NY 10128, matchAddress would compare '123 Sesame St.' with the address on file.)

Note: Card issuers may handle address checks differently. For your convenience, Nexio returns a simple true or false regardless of the card issuer.

Match Postal

The results of the postal code check.

• True: The postal code provided matches the postal code on file with the credit card issuer.
• False: The postal code provided does not match the postal code on file with the credit card issuer.

(Using the example address above, matchPostal would compare '10128' with the postal code on file.)

Gateway Response

This part of the response includes raw details from the gateway's response to the AVS check. Format may vary by gateway.

Note: A gateway AVS error will not prevent the card token from being saved. If you received a gateway error during an address verification check, you may wish to delete the card token.

Test AVS

In the sandbox environment you may trigger matchAddress and matchPostal values by using the following postal codes:

Postal Code	matchAddress result	matchPostal result
56649	true	true
39601	true	false
53574	false	true
49802	false	false

Please be sure to use only the test postal codes provided in the table above.

AVS Settings

verifyAvs set to:	Purpose
0	Do not perform AVS check
1	Always save card regardless of result
2	Do not save card if the address match fails
3	Do not save card if the postal code match fails
4	Do not save the card if either the address match fails OR the postal code match fails
5	Do not save the card if both the address match AND the postal code match fail

When verifyAvs is set to 0

You will not receive an avsResponse object.

When verifyAvs is set to 1

addressMatch	postalMatch	What will happen:
true	true	Card will be saved
true	false	Card will be saved
false	true	Card will be saved
false	false	Card will be saved

When verifyAvs is set to 2

addressMatch	postalMatch	What will happen:
true	true	Card will be saved
true	false	Card will be saved
false	true	Card will not be saved
false	false	Card will not be saved

When verifyAvs is set to 3

addressMatch	postalMatch	What will happen:
true	true	Card will be saved
true	false	Card will not be saved
false	true	Card will be saved
false	false	Card will not be saved

When verifyAvs is set to 4

addressMatch	postalMatch	What will happen:
true	true	Card will be saved
true	false	Card will not be saved
false	true	Card will not be saved
false	false	Card will not be saved

When verifyAvs is set to 5

addressMatch	postalMatch	What will happen:
true	true	Card will be saved
true	false	Card will be saved
false	true	Card will be saved
false	false	Card will not be saved

Device Fingerprinting

Device fingerprinting helps detect fraudulent behavior even when a user changes their IP address, device, account information or other identifying information.

You can enable device fingerprinting while saving a card token or running a transaction.

Enable Device Fingerprinting

With the Nexio Iframe

1. Prepare the Iframe

   Follow steps 1-3 of the Create a Save Card Page With the Nexio Iframe or the Create a Checkout Page With the Nexio Iframe tutorial.

   Successful completion of step 3 will return the following:

Example One-time-use Token Response

{
  "expiration": "2018-09-18T15:43:05.664Z",
  "fraudUrl": "https://api.nexiopaysandbox.com/pay/v3/fingerprint?token=01080f80-76b8-4363-845d-67e8623bf170",
  "token": "830d36f6-a5e3-4455-9600-3a55b63e2fc2"
}

2. Add the Device Fingerprinting Script

   a. Copy the fraudUrl from the above response.

   b. Add a script tag to your web page.

   c. Assign the fraudUrl to the script's src tag.

Example

<script type='text/javascript' src='https://api.nexiopaysandbox.com/pay/v3/fingerprint?token=01080f80-76b8-4363-845d-67e8623bf170'></script>

3. Complete the Iframe

   Follow steps 4-6 of the Create a Save Card Page With the Nexio Iframe or the Create a Checkout Page With the Nexio Iframe tutorial. Now, when the form is submitted the user's device will be fingerprinted prior to the transaction being processed or card being saved.

   Note: Enabling device fingerprinting will not affect your UI.

With Your Own Form

While Saving a Card Token

1. Prepare the Form

   Follow steps 1-2 of the Create a Save Card Page With Your Own Form tutorial.

2. Add the Device Fingerprinting Script to Your Web Page

   a. Request a one-time-use token. A successful request will return a response with the following keys:

 Example 200 Response 

{
  "expiration": "2018-09-18T15:43:05.664Z",
  "fraudUrl": "https://api.nexiopaysandbox.com/pay/v3/fingerprint?token=01080f80-76b8-4363-845d-67e8623bf170",
  "token": "830d36f6-a5e3-4455-9600-3a55b63e2fc2"
}

b. Copy the fraudUrl from the above response and add it as a script to your web page.

Example

<script type='text/javascript' src='https://api.nexiopaysandbox.com/pay/v3/fingerprint?token=01080f80-76b8-4363-845d-67e8623bf170'></script>

c. Copy and store the token from the above response, we will use it in step 5.

3. Load the Form

   Because of the script you added in step 2b the user's device will be fingerprinted when your page is loaded. Nexio will return the fingerprint as a browser event called fingerprintPosted.

4. Send Card Data To Your Server

   Follow steps 4-5 of the Create a Save Card Page With Your Own Form tutorial.

5. Post Card Information to Nexio

   POST the token from step 2 and the card information to Nexio.

Example Request

curl -X POST https://api.nexiopaysandbox.com/pay/v3/saveCard \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic <Your Basic Auth>'
  -d '{
  "card": {
    "cardHolderName": "John H Doe",
    "encryptedNumber": "cu3yRktaYFK2LUC6DpNK289tYDsGRCi7cO+GeG0hkeYFvT7Y8/oY5r53obMz6Q/BZ38gk2u2Ufwy8ojBcX2sfNjG5jplGTXA4NNlSIUjMFfiHe1sff1JFpThoiW/IIlifGlbWu+S1/9pqWPTzJ2+DcjwohbHzsDahhYewFhXgC8qsK0ypi/Shlp+CwRITyIvbVXESD0xz3YOTRHeZLlChvVqN8z4ZzN8nm0MXkmT1wcpYI73bH4KdnPwNU3s7XxvP/ernQP73SHHAOKSLlz4F6AEHFjJiCoXzeLF7LwEjRdxDJ0sKVXbRk3i9BGh+8Nle2VYgjpUWtk2763QkvZiQQ==",
    "expirationMonth": "12",
    "expirationYear": "20"
  },
  "token": "eb50a022-d6de-4244-a1e6-dcb8522b2d19"
}'

6. Create a Success or Failure Page for the Customer

   Listen for Nexio's response. Use the response to create a success or failure page to the customer.

While Running a Transaction

There are two options for fingerprinting a device while running a transaction. You may create a new fingerprint at the time of running the transaction, or you may use a saved fingerprint.

If you choose to create a new fingerprint, you will need to perform a few extra steps in addition to what is typically required to create a checkout page With your own form.

Create a New Fingerprint

1. Prepare the Form

   Follow steps 1-2 of the Create a Checkout Page With Your Own Form tutorial.

2. Add the Device Fingerprinting Script to Your Web Page

   a. Request a one-time-use token. Do not include any of the transaction data. This step is only required so that you can get the fraudUrl for use in the next step.

   A successful request will return a response with the following keys:

 Example 200 Response 

{
  "expiration": "2018-09-18T15:43:05.664Z",
  "fraudUrl": "https://api.nexiopaysandbox.com/pay/v3/fingerprint?token=01080f80-76b8-4363-845d-67e8623bf170",
  "token": "830d36f6-a5e3-4455-9600-3a55b63e2fc2"
}

b. Copy the fraudUrl from the above response and add it as a script to your web page.

Example

<script type='text/javascript' src='https://api.nexiopaysandbox.com/pay/v3/fingerprint?token=01080f80-76b8-4363-845d-67e8623bf170'></script>

3. Load the Form

   Because of the script you added in step 2b the user's device will be fingerprinted when your page is loaded. Nexio will return the fingerprint as a browser event called fingerprintPosted.

4. Send Payment Data To Your Server

   Follow steps 4-5 of the Create a Checkout Page With Your Own Form tutorial.

   Send the transaction information to your server.

5. Post Payment Information to Nexio POST the transaction information to Nexio.

Example Request

curl -X POST https://api.nexiopaysandbox.com/pay/v3/process \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic <Your Basic Auth>'
  -d '{
  "data": {
    "amount": 29.99,
    "currency": "USD"
  },
  "tokenex": {
    "token": "6ee140a0-05d1-4958-8325-b38a690dbb9d"
  }
}'

6. Create a Receipt for the Customer

   a. Listen for Nexio's response.

   b. Use the response to create a success (such as a receipt) or failure page to the customer. You may also wish to send a receipt to the customer via email.

Use a Saved Fingerprint

1. Save a Card

   a. Save a card fingerprint while saving a card token. Nexio will store the fingerprint for 12 hours.

   b. By default, the stored fingerprint will be used when the card token is used to run a transaction.

2. Create a Checkout Page Using the API

   Follow steps 1-4 of the Create a Checkout Page With Your Own Form tutorial. Include the card token in the body of your request when you POST payment information to Nexio.

Example Request

curl -X POST https://api.nexiopaysandbox.com/pay/v3/process \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic <Your Basic Auth>'
  -d '{
  "data": {
    "amount": 29.99,
    "currency": "USD"
  },
  "tokenex": {
    "token": "6ee140a0-05d1-4958-8325-b38a690dbb9d"
  }
}'

3. Create a Receipt for the Customer

   a. Listen for Nexio's response.

   b. Use the response to create a success (such as a receipt) or failure page to the customer. You may also wish to send a receipt to the customer via email.

Kount Verification

Nexio utilizes Kount for fraud and risk management. You can enable Kount verification while saving a card token or running a transaction with the Nexio iframe, with your own form, or through the API.

Nexio will run one of two Risk Inquiry Service (RIS) requests depending on whether customer information (customer.customerRef) is provided in the request body:

Information Provided	Inquiry Mode
Customer Ref Provided	Kount Central full inquiry with returned thresholds (Inquiry Mode: W)
Customer Ref Not Provided	Default Inquiry (Inquiry Mode: Q)

(Please see Kount's documentation for more information on Inquiry Modes.)

Contact your CMS sales agent for more information, or if you are interested in using Kount with your Nexio merchant account.

Enable Kount Verification

With the Nexio Iframe

1. Configure Your Account

   Contact integration support to ensure Kount is enabled on your merchant account.

2. Prepare the Iframe

   Follow steps 1-2 of the Create a Save Card Page With the Nexio Iframe tutorial or the Create a Checkout Page with the Nexio Iframe tutorial.

3. Request a One-time-use Token

   Request an e-commerce one-time-use token.

   Include the object "processingOptions": { "checkFraud": true } in the body of your request.

Example Request

curl -X POST https://api.nexiopaysandbox.com/pay/v3/token \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic <Your Basic Auth>'
  -d '{
  "processingOptions": {
    "checkFraud": true
  }
}'

4. Load the Iframe

   Follow steps 4-6 of the Create a Save Card Page With the Nexio Iframe or the Create a Checkout Page with the Nexio Iframe tutorial.

   Now, when the iframe is loaded a Kount check will be performed.

   Nexio will return the results back to you in the Kount response.

With Your Own Form

While Saving a Card Token

1. Configure Your Account

   Contact integration support to ensure Kount is enabled on your merchant account.

2. Prepare the Iframe

   Follow steps 1-6 of the Create a Save Card Page Using the Iframe tutorial.

3. Request a One-time-use Token

   Request an e-commerce one-time-use token.

   (This is step 7a of the Create a Save Card Page Using the Iframe tutorial.)

Example Request

curl -X POST https://api.nexiopaysandbox.com/pay/v3/token \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic <Your Basic Auth>'
  -d '{}'

4. Post Card Information to Nexio

   Follow step 7b of the Create a Save Card Page Using the Iframe tutorial. Include the object "processingOptions": { "checkFraud": true } in the body of your request.

Example Request

curl -X POST https://api.nexiopaysandbox.com/pay/v3/saveCard \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic <Your Basic Auth>'
  -d '{
  "card": {
    "cardHolderName": "John H Doe",
    "encryptedNumber": "cu3yRktaYFK2LUC6DpNK289tYDsGRCi7cO+GeG0hkeYFvT7Y8/oY5r53obMz6Q/BZ38gk2u2Ufwy8ojBcX2sfNjG5jplGTXA4NNlSIUjMFfiHe1sff1JFpThoiW/IIlifGlbWu+S1/9pqWPTzJ2+DcjwohbHzsDahhYewFhXgC8qsK0ypi/Shlp+CwRITyIvbVXESD0xz3YOTRHeZLlChvVqN8z4ZzN8nm0MXkmT1wcpYI73bH4KdnPwNU3s7XxvP/ernQP73SHHAOKSLlz4F6AEHFjJiCoXzeLF7LwEjRdxDJ0sKVXbRk3i9BGh+8Nle2VYgjpUWtk2763QkvZiQQ==",
    "expirationMonth": "12",
    "expirationYear": "20"
  },
  "token": "eb50a022-d6de-4244-a1e6-dcb8522b2d19",
  "processingOptions": {
    "checkFraud": true
  }
}'

5. Listen for Nexio's Response

   Follow step 8 of the Create a Save Card Page Using the Iframe tutorial. See the Kount Response section for more information about the possible results included in the response.

While Running a Transaction

1. Configure Your Account

   Contact integration support to ensure Kount is enabled on your merchant account.

2. Prepare the Iframe

   Follow steps 1-5 of the Create a Checkout Page With Your Own Form tutorial.

3. Post Card Information to Nexio

   Follow step 5 of the Create a Checkout Page With Your Own Form tutorial.

   Include the object "processingOptions": { "checkFraud": true } in the body of your request.

Example Request

curl -X POST https://api.nexiopaysandbox.com/pay/v3/process \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic <Your Basic Auth>'
  -d '{
  "data": {},
  "tokenex": {
    "token": "6ee140a0-05d1-4958-8325-b38a690dbb9d"
  },
  "processingOptions": {
    "checkFraud": true
  }
}'

4. Create a Receipt for the Customer

   Follow step 6 of the Create a Checkout Page With Your Own Form tutorial. See the Kount Response section for more information about the possible results included in the response.

With the Nexio API

While Saving a Card Token

1. Configure Your Account

   Contact integration support to ensure Kount is enabled on your merchant account.

2. Request a One-time-use Token

   Request an e-commerce one-time-use token.

Example Request

curl -X POST https://api.nexiopaysandbox.com/pay/v3/token \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic <Your Basic Auth>'
  -d '{}'

3. Post Card Information to Nexio

   Send a POST request to the Save Card Token endpoint. Include the token from step 2, the card information and the object "processingOptions": { "checkFraud": true } in the body of your request.

Example Request

curl -X POST https://api.nexiopaysandbox.com/pay/v3/process \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic <Your Basic Auth>'
  -d '{
  "data": {},
  "tokenex": {
    "token": "6ee140a0-05d1-4958-8325-b38a690dbb9d"
  },
  "processingOptions": {
    "checkFraud": true
  }
}'

While Running a Transaction

1. Configure Your Account

   Contact integration support to ensure Kount is enabled on your merchant account.

2. Post Card Information to Nexio

   Post payment and the previously saved card token to the Run Card Transaction endpoint.

   Include the object "processingOptions": { "checkFraud": true } in the body of your request.

Example Request

curl -X POST https://api.nexiopaysandbox.com/pay/v3/process \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic <Your Basic Auth>'
  -d '{
  "data": {},
  "tokenex": {
    "token": "6ee140a0-05d1-4958-8325-b38a690dbb9d"
  },
  "processingOptions": {
    "checkFraud": true
  }
}'

The Kount Response

When you perform a Kount verification your response will include an object called kountResponse. It consists of two parts: status and rules.

Kount Response Example

{
  "token": {...},
  "card": {...},
  "data": {...},
  "kountResponse": {
    "status": "success",
    "rules": "{\"VERS\":\"0630\",\"MODE\":\"Q\"}"
  },
  "cardType": "visa"
}

Status

There are three possible statuses. The status indicates what action will be taken. The action will differ based on the endpoint. See below for more information:

• Success:
  • Run Credit Card Transaction: Based on the Kount rule(s) configured, the transaction will be processed with no further action required.
  • Save Card: The card will be saved with no further action required.
• Review:
  • Run Credit Card Transaction: Based on the Kount rule(s) triggered, the transaction has been run as an Auth Only, meaning the transaction has been authorized but is pending further action. You can manually approve or decline these transactions in the Fraud tab of Nexio Dashboard. (Please note that these transactions will auto-approve after 48 hours if no action is taken.)
  • Save Card: A 'Review' status will not prevent the card from being saved.
• Decline:
  • Run Credit Card Transaction: Based on the Kount rule(s) triggered, the transaction will not be processed with no further action required.
  • Save Card: The card will not be saved.
• Error:
  • Run Credit Card Transaction: Based on the Kount rule(s) triggered, the transaction will not be processed with no further action required.
  • Save Card: The card will not be saved.

Rules

This part of the response will include Kount-specific information including Kount version, mode, transaction ID, and a brief description of each rule that was triggered.

Kount Rules Example

"kountResponse": {
    "status": "success",
    "rules": "{
        "VERS": "0630",
        "MODE": "W",
        "TRAN": "79970C4SYHL2",
        "SESS": "61504d7500d44f67bba921474750f90f",
        "ORDR": "456",
        "AUTO": "A",
        "SCOR": "76",
        "RULES_TRIGGERED": 2,
        "RULE_ID_0": "1004064",
        "RULE_DESCRIPTION_0": "Scorecard:  Distance from Device to Billing > 1000km (1)",
        "RULE_ID_1":"1004066",
        "RULE_DESCRIPTION_1":"Scorecard:  Billing Country not equal to BIN Country (Visa/MC)
    }"
}

Test Kount Verification

While testing Kount in your sandbox account you may force a status of review or decline by using the values listed below. Any other combination will result in a status of success.

Value	Result
Address 1 or Address 2 contains '456'	review
Amount between 6.00 and 6.99	review
Amount = 7.00	decline

The examples below show how to test Kount verification on the Run Card Transaction endpoint.

Example Request: Triggers Status of Review

curl -X POST https://api.nexiopaysandbox.com/pay/v3/process \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic <Your Basic Auth>'
  -d '{
  "data": {
    "customer": {
      "billToAddressOne": "456"
    }
  },
  "tokenex": {
    "token": "6ee140a0-05d1-4958-8325-b38a690dbb9d"
  },
  "processingOptions": {
    "checkFraud": true
  }
}'

Example Request: Triggers Status of Decline

curl -X POST https://api.nexiopaysandbox.com/pay/v3/process \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic <Your Basic Auth>'
  -d '{
  "data": {
    "amount": 7
  },
  "tokenex": {
    "token": "6ee140a0-05d1-4958-8325-b38a690dbb9d"
  },
  "processingOptions": {
    "checkFraud": true
  }
}'

To test the Save Card Token endpoint use any of the values listed in the table above in your request for a One-time-use Token (E-commerce), then use the token to request a Save Card Token iframe.

Security Code Verification

The Nexio security code (CVC) verification feature allows you to save only those cards that pass a CVC check, helping you reduce your risk of fraud. You can enable CVC verification while saving a card token with the Nexio iframe, with your own form, or through the API.

Enable Security Code Verification

With the Nexio Iframe

1. Prepare the Iframe

   Follow steps 1-2 of the Create a Save Card Page With the Nexio Iframe tutorial.

2. Request a One-time-use Token

   a. Request an e-commerce one-time-use token.

   Include the object "processingOptions": { "verifyCvc": true } in the body of your request.

   b. Adjust the requireCvc and hideCvc UI options as desired. (Optional)

   See the CVC settings table for an explanation of how changing these settings will affect your iframe. The following will be selected by default:

   • requireCvc: true
   • hideCvc: false

Example Request

curl -X POST https://api.nexiopaysandbox.com/pay/v3/token \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic <Your Basic Auth>'
  -d '{
  "processingOptions": {
    "verifyCvc": true
  }
}'

3. Load the Iframe

   Follow steps 4-6 of the Create a Save Card Page With the Nexio Iframe. Now, when the iframe is loaded, a CVC check will be preformed. Nexio will return the results back to you in the CVC response.

With Your Own Form

1. Prepare the Iframe

   Follow steps 1-6 of the Create a Save Card Page With Your Own Form tutorial.

2. Request a One-time-use Token

   Request an e-commerce one-time-use token. Include the object "processingOptions": { "verifyCvc": true } in the body of your request. (This is part of step 7a of the Create a Save Card Page With Your Own Form tutorial, with the addition of the verifyCvc parameter in the processingOptions object.)

Example Request

curl -X POST https://api.nexiopaysandbox.com/pay/v3/token \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic <Your Basic Auth>'
  -d '{
  "processingOptions": {
    "verifyCvc": true
  }
}'

3. Post Card Information to Nexio

   Follow step 7b of the Create a Save Card Page With Your Own Form tutorial.

   In the request,, be sure to also include the CVC (as the securityCode parameter) as entered by the user.

Example Request

{
  curl -X POST https://api.nexiopaysandbox.com/pay/v3/saveCard \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic <Your Basic Auth>'
  -d '{
  "token": "eb50a022-d6de-4244-a1e6-dcb8522b2d19",
  "card": {
    "cardHolderName": "John H Doe",
    "encryptedNumber": "cu3yRktaYFK2LUC6DpNK289tYDsGRCi7cO+GeG0hkeYFvT7Y8/oY5r53obMz6Q/BZ38gk2u2Ufwy8ojBcX2sfNjG5jplGTXA4NNlSIUjMFfiHe1sff1JFpThoiW/IIlifGlbWu+S1/9pqWPTzJ2+DcjwohbHzsDahhYewFhXgC8qsK0ypi/Shlp+CwRITyIvbVXESD0xz3YOTRHeZLlChvVqN8z4ZzN8nm0MXkmT1wcpYI73bH4KdnPwNU3s7XxvP/ernQP73SHHAOKSLlz4F6AEHFjJiCoXzeLF7LwEjRdxDJ0sKVXbRk3i9BGh+8Nle2VYgjpUWtk2763QkvZiQQ==",
    "expirationMonth": "12",
    "expirationYear": "20",
    "securityCode": 111
  }
}'

4. Listen for Nexio's Response

   Follow step 8 of the Create a Save Card Page With Your Own Form tutorial. See the CVC Response section for more information about the possible results included in the response.

With the Nexio API

1. Request a One-time-use Token

   Request an e-commerce one-time-use token. Include the object "processingOptions": { "verifyCvc": true } in the body of your request.

Example Request

curl -X POST https://api.nexiopaysandbox.com/pay/v3/token \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic <Your Basic Auth>'
  -d '{
  "processingOptions": {
    "verifyCvc": true
  }
}'

2. Post Card Information to Nexio

   Send a POST request to the Run Card Transaction endpoint. Include the token returned from step 1 and the card information (including the CVC securityCode) in the body of your request.

Example Request

curl -X POST https://api.nexiopaysandbox.com/pay/v3/process \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic <Your Basic Auth>'
  -d '{
  "data": {
    "amount": "29.99",
    "currency": "USD"
  },
  "tokenex": {
    "token": "6ee140a0-05d1-4958-8325-b38a690dbb9d"
  },
  "card": {
    "cardHolderName": "John H Doe",
    "encryptedNumber": "cu3yRktaYFK2LUC6DpNK289tYDsGRCi7cO+GeG0hkeYFvT7Y8/oY5r53obMz6Q/BZ38gk2u2Ufwy8ojBcX2sfNjG5jplGTXA4NNlSIUjMFfiHe1sff1JFpThoiW/IIlifGlbWu+S1/9pqWPTzJ2+DcjwohbHzsDahhYewFhXgC8qsK0ypi/Shlp+CwRITyIvbVXESD0xz3YOTRHeZLlChvVqN8z4ZzN8nm0MXkmT1wcpYI73bH4KdnPwNU3s7XxvP/ernQP73SHHAOKSLlz4F6AEHFjJiCoXzeLF7LwEjRdxDJ0sKVXbRk3i9BGh+8Nle2VYgjpUWtk2763QkvZiQQ==",
    "expirationMonth": "12",
    "expirationYear": "20",
    "securityCode": 927
  }
}'

The CVC Response

When you check the CVC your response will include an object called cvcResults. See the examples below.

Note: A gateway error will not prevent the card token from being saved. The only time a card will not be saved is when the matchCvv parameter returns false. If you received a gateway error during a CVC check, you may wish to delete the card token.

Example 200 Response

{
  "token": {...},
  "card": {...},
  "data": {...},
  "cvcResults": {
    "matchCvv": true,
    "error": false,
    "gatewayMessage": {
      "cvvresponse": "M",
      "message": "CVV2/CVC2 match"
    }
  },
  "cardType": "visa"
}

Example 400 Response

{
  "error": 437,
  "message": "Verify CVC Failed",
  "cvcResults": {
    "matchCvv": false,
    "error": false,
    "gatewayMessage": {
      "cvvresponse": "N",
      "message": "CVV2/CVC2 no match"
    }
  }
}

Test Security Code Verification

You can test the CVC Verification Service using the Nexio Sandbox Tester, Postman, or your own code base.

The following values can be used while testing:

Card Number	CVC	Result
Any number provided here	111	Success
Any number provided here	222	Failure

Security Code Verification Settings

verifyCvc	hideCvc	requireCvc	Result
true	false	true	The user will be required to input the CVC field and the card will only be saved if the CVC is verified.
true	false	false	The card will only be saved if the provided CVC is verified, but users will also have the option of ignoring the CVC field.

Please also note the following:

verifyCvc	hideCvc	requireCvc	Result
true	true	true, false	You will receive a 400 error, because the CVC cannot be verified when the field is hidden.

Label Translation

Nexio provides the option to customize the labels on your e-commerce or retail iframe. This feature is particularly helpful for localization, allowing you to translate your checkout or save card page.

You may use this feature in two ways:

• To translate or localize your iframes by using our out of the box translation files
• To translate, localize or customize your iframes by providing your own custom labels

Out of the Box Translations

Nexio currently provides out of the box localization files for the following languages/regional dialects:

• English (Canada): https://customerassets.nexiopay.com/CMSLabels_en_ca.json
• French: https://customerassets.nexiopay.com/CMSLabels_fr.json
• French (Canada): https://customerassets.nexiopay.com/CMSLabels_fr_ca.json
• French (United States): https://customerassets.nexiopay.com/CMSLabels_fr_us.json
• Japanese: https://customerassets.nexiopay.com/CMSLabels_jp.json
• Spanish: https://customerassets.nexiopay.com/CMSLabels_es.json
• Spanish (Mexico): https://customerassets.nexiopay.com/CMSLabels_es_mx.json
• Spanish (United States): https://customerassets.nexiopay.com/CMSLabels_es_us.json
• Turkish: https://customerassets.nexiopay.com/CMSLabels_tr.json

To use our translation files to customize your iframe, follow steps below:

1. Request a One-time-use Token

   Send a POST request for a one-time-use token.

   • Include a uiOptions object in the body of your request
   • Within the uiOptions object, include the key customTextUrl
   • Set the value to the URL of the desired language file listed above

Example Request

curl -X POST https://api.nexiopaysandbox.com/pay/v3/token \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic <Your Basic Auth>'
  -d '{
  "uiOptions": {
    "customTextUrl": "https://customerassets.nexiopay.com/CMSLabels_es.json"
  }
}'

 Example 200 Response 

{
  "expiration": "2018-09-18T15:43:05.664Z",
  "fraudUrl": "https://api.nexiopaysandbox.com/pay/v3/fingerprint?token=01080f80-76b8-4363-845d-67e8623bf170",
  "token": "830d36f6-a5e3-4455-9600-3a55b63e2fc2"
}

2. Request the Iframe

   Use the token from the response in step 1 to send a GET request for the desired iframe. You may wish to customize any of the following:

   • Checkout Page
   • Save Card Token Page
   • Save E-check Token Page

For example, the following request will return the HTML for a save card page, with the labels from the out of the box translation file you specified in step 1.

Example Request

curl -X GET https://api.nexiopaysandbox.com/pay/v3/saveCard?token=830d36f6-a5e3-4455-9600-3a55b63e2fc2 \
  -H 'Accept: application/json' \
  -H 'One-time-use Token: API_KEY'

Custom Labels

If you would like to completely customize your iframe's labels, or if you would like to translate them into a language that is not currently included in Nexio's out of the box translations, follow the steps below:

1. Create a Custom Label File

   Create a JSON file with the same keys as shown below. (Click here to download a copy.)

Custom Text File Example

{
    "Card Information": "",
    "Name": "",
    "as it appears on card": "",
    "Card Number": "",
    "Card number is invalid": "",
    "We only accept": "",
    "Expiration Date": "",
    "Select a date in the future": "",
    "Security Code": "",
    "Security code is invalid, must be 3-4 digits": "",
    "Billing Information": "",
    "Country": "",
    "Address 1": "",
    "Address 2": "",
    "City": "",
    "State / Province": "",
    "Postal Code": "",
    "eCheck Information": "",
    "Routing Number": "",
    "Routing Number is invalid, must be 9 digits": "",
    "Account Number": "",
    "Account number is invalid": "",
    "Submit": "",
    "You are now being redirected to Alipay for payment.": "",
    "Cancel": "",
    "Confirm": "",
    "Required": "",
    "Establishing secure connection to payment engine.": "",
    "Failed to connect to secure server. Please check your internet connection.": ""
}

2. Add the Custom Labels

   Replace any values you would like to customize. If any value is an empty string, or the property is left out, the default value will be used.

3. Host the Custom Label File

   Host the JSON file. This step varies based on the environment:

   • Sandbox: You may host the file anywhere. (For instuctions on how to host your custom JSON file on GitHub, see this FAQ.) Take note of the URL for use in step 4

   • Production: You must send the file to integrations@nexiopay.com for approval. Important: The URL used in sandbox will not be used on the production server

   Once approved, we will host it on our secure servers and provide you with the URL to use in step 4

4. Request a One-time-use Token

   Send a POST request for a one-time-use token.

   • Include a uiOptions object in the body of your request
   • Within the uiOptions object, include the key customTextUrl
   • Set the value to the URL of the JSON file from step 3

Example Request

curl -X POST https://api.nexiopaysandbox.com/pay/v3/token \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic <Your Basic Auth>'
  -d '{
  "data": {
    "amount": 29.99,
    "currency": "USD"
  },
  "uiOptions": {
    "customTextUrl": "https://your-webpage.com/custom-labels.json"
  }
}'

 Example 200 Response 

{
  "expiration": "2018-09-18T15:43:05.664Z",
  "fraudUrl": "https://api.nexiopaysandbox.com/pay/v3/fingerprint?token=01080f80-76b8-4363-845d-67e8623bf170",
  "token": "830d36f6-a5e3-4455-9600-3a55b63e2fc2"
}

5. Request the Iframe

   Use the token from the response in step 4 to send a GET request for the desired iframe. You may wish to customize any of the following:

   • Checkout Page
   • Save Card Token Page
   • Save E-check Token Page

Example Request

curl -X GET https://api.nexiopaysandbox.com/pay/v3?token=830d36f6-a5e3-4455-9600-3a55b63e2fc2 \
  -H 'Accept: application/json' \
  -H 'One-time-use Token: API_KEY'

Once the iframe is loaded, the labels will be replaced with values you provided.

Custom CSS

Nexio provides the option to provide a custom CSS file so that you can match your site's style.

To do so, follow steps below:

1. Host Your CSS File

   Host your CSS file, available publicly.

2. Request a One-time-use Token

   Send a POST request to the E-commerce One-time-use Token. Include the URL of your CSS file as a UI Option in the body of your request. See the example below.

Example Request

curl -X POST https://api.nexiopaysandbox.com/pay/v3/token \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic <Your Basic Auth>'
  -d '{
  "uiOptions": {
    "css": "https://tester.nexiopaysandbox.com/static/ecom-example1.css"
  }
}'

 Example 200 Response 

{
  "expiration": "2018-09-18T15:43:05.664Z",
  "fraudUrl": "https://api.nexiopaysandbox.com/pay/v3/fingerprint?token=01080f80-76b8-4363-845d-67e8623bf170",
  "token": "830d36f6-a5e3-4455-9600-3a55b63e2fc2"
}

3. Load the Iframe

   You may wish to customize a:

   • Checkout Page
   • Save Card Token Page
   • Save E-check Token Page

   For example, the following request will return the HTML for a checkout page, with the style from the CSS file you specified in step 2.

Example Request

curl -X GET https://api.nexiopaysandbox.com/pay/v3?token=830d36f6-a5e3-4455-9600-3a55b63e2fc2 \
  -H 'Accept: application/json' \
  -H 'One-time-use Token: API_KEY'

Lodging Data

Merchants in the lodging industry can pass certain parameters. The entire lodging object is optional. However, the following are all the supported parameters:

• Advanced Deposit (lodging.advanceDeposit)

• Check-in Date (lodging.checkInDate)

• Check-out Date (lodging.checkOutDate)

• No Show (lodging.noShow)

• Room Number (lodging.roomNumber)

• Room Rate (lodging.roomRate)

• Folio Number (customer.orderNumber)

Send Lodging Parameters

With the Nexio Iframe

1. Prepare the Iframe

   Follow steps 1-2 of the Create a Checkout Page with the Nexio Iframe tutorial.

2. Request a One-time-use Token

   Request an e-commerce one-time-use token. Include the lodging object and the folio number in the body of your request.

   Note: Folio number must be sent in the customer object, labeled orderNumber.

Example Request

curl -X POST https://api.nexiopaysandbox.com/pay/v3/token \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic <Your Basic Auth>'
  -d '{
  "data": {
    "amount": 29.99,
    "currency": "USD",
    "lodging": {
      "advanceDeposit": true,
      "checkInDate": "2018-12-31",
      "checkOutDate": "2019-01-05",
      "roomNumber": 14,
      "roomRate": 143.99
    },
    "customer": {
      "orderNumber": 4566
    }
  }
}'

3. Load the Iframe

   Follow steps 4-6 of the Create a Checkout Page with the Nexio Iframe tutorial.

With Your Own Form

1. Prepare the Iframe

   Follow steps 1-5 of the Create a Checkout Page With Your Own Form tutorial.

2. Post Card Information to Nexio

   Follow step 5 of the Create a Checkout Page With Your Own Form tutorial. Include the lodging object and the folio number in the body of your request.

   Note: Folio number must be sent in the customer object, labeled orderNumber.

Example Request

curl -X POST https://api.nexiopaysandbox.com/pay/v3/process \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic <Your Basic Auth>'
  -d '{
  "data": {
    "lodging": {
      "advanceDeposit": true,
      "checkInDate": "2018-12-31",
      "checkOutDate": "2019-01-05",
      "roomNumber": 14,
      "roomRate": 143.99
    },
    "customer": {
      "orderNumber": 4566
    }
  },
  "tokenex": {
    "token": "6ee140a0-05d1-4958-8325-b38a690dbb9d"
  }
}'

3. Create a Receipt for the Customer

   Follow step 6 of the Create a Checkout Page With Your Own Form tutorial.

With the API

1. Post Card Information to Nexio

   Send a POST request to the Run Card Transaction endpoint. Include the lodging object and the folio number in the body of your request.

   Note: Folio number must be sent in the customer object, labeled orderNumber.

Example Request

curl -X POST https://api.nexiopaysandbox.com/pay/v3/process \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic <Your Basic Auth>'
  -d '{
  "data": {
    "lodging": {
      "advanceDeposit": true,
      "checkInDate": "2018-12-31",
      "checkOutDate": "2019-01-05",
      "roomNumber": 14,
      "roomRate": 143.99
    },
    "customer": {
      "orderNumber": 4566
    }
  },
  "tokenex": {
    "token": "6ee140a0-05d1-4958-8325-b38a690dbb9d"
  }
}'