NAV Navigation
Logo

Quick Start

Introduction

Nexio documentation is getting an Extreme Makeover!

Want a sneak peak? Join our beta program and get early access.
Plus, you can have an influence on content and decisions.

To join, send an email to docs@nexiopay.com and we'll get you started.

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.

Run in Postman

Getting Started

Requirements

To get started using the Nexio API you will need:

Ready to get started?

Create Sandbox Test Account →

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:

Contact Us

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

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
  1. Create the Authorization Header

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

Example
Authorization: Basic bXluYW1lQG5leGlvaHViLmNvbTpteXBhc3N3b3Jk
  1. 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

E-commerce Flows & Operations

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:

You will have hands-on control to:

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

Create a Checkout Page

With the Nexio Iframe

  1. Create an Iframe on Your Web Page
Example
<html>
    <iframe id="myIframe">
    </iframe>
</html>
  1. 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)
    }
});
  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"
}
  1. 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
  2. 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;
  1. 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>
  1. 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.

  2. Send Payment Information to Your Server

  3. 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"
  }
}'

  1. 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)
    }
});
  1. 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"
}
  1. 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
  2. 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;
  1. 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>
  1. 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.

  2. Load the Form

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

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

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

  1. Send Card Information to Your Server

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

  2. 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"
}'

  1. 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:

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>
  1. 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)
    }
});
  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"
}
  1. 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
  2. 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;
  1. 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>
  1. 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.

  2. Send Payment Information to Your Server

  3. 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"
  }
}'

  1. 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)
    }
});
  1. 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"
}
  1. 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
  2. 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;
  1. 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>
  1. 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.

  2. Load the Form

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

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

  1. Send Bank Information to Your Server

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

  2. 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"
}'

  1. 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:

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"
}
  1. 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"
}
  1. 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"
  }
}'

Retail Flows & Operations

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:

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"
}
  1. 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} }
  1. Enter the Card Information
  2. 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/
  1. 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.

  2. Enter or Confirm the Amount

  3. Key in Card Information

  4. Click ‘Pay $X.XX’

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

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.

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

  2. 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
  1. 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

Features

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"
}
  1. 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'

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

  2. 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
}'

  1. 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
}'

  1. 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
}'

  1. 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 '{}'

  1. 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
}'

  1. 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 '{}'

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

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

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

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

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

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

  3. 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:

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

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.

Payment Flow plus PayPal

Google Pay

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


Klarna

This section provides the following topics:

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:


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:

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:


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:

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.

    Express APM

  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.

    Klarna Button

  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

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:


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:

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:

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:

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

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"
    }
  ]
}
  1. 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.

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

  2. 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:

  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.

  1. 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).

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

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

  2. 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": [...]
}
  1. 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.

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

  3. 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"
  }
}
  1. 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

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.

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

  1. 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.)

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

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"
}
  1. 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"
}
  1. 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:

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

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

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

  1. 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>'
  1. 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
}

Fraud Tools

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

  1. 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
  }
}'

  1. Post Card Information to Nexio

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

  2. 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
  }
}'

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

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

  2. Send Card Data To Your Server

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

  3. 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"
}'

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

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

  3. 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"
  }
}'
  1. 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"
  }
}'
  1. 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
  }
}'

  1. 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 '{}'

  1. 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
  }
}'

  1. 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
  }
}'

  1. 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 '{}'

  1. 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
  }
}'

  1. 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
  }
}'

  1. 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
  }
}'
  1. 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
  }
}'

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

Iframe Customization

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:

Out of the Box Translations

Nexio currently provides out of the box localization files for the following languages/regional dialects:

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"
}
  1. 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:

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.": ""
}
  1. 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.

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

  3. 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"
}
  1. 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:

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"
}
  1. Load the Iframe

    You may wish to customize a:

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

  1. 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"
  }
}'

  1. 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"
  }
}'

Payment Routing (BETA)

Nexio allows you to customize the payment flow for consumer purchases. Previously, you could customize the payment flow only through assigning different currencies to each merchant account (MID), running transactions through different API users, using a specific MID, or specifying a specific tag for payment options on each MID.

You can now route transactions based on items in the transaction, monthly gross of authorized transactions (also known as transaction volume), or with an advanced payment routing flow.

This section details how to customize the payment routing based on what you want to accomplish:

  1. I want to keep 'relationshipA' active at nn% - 'relationshipA' refers to the relationship you have with a merchant account provider, a processor, or an acquirer (bank). The 'nn%'' is a specific percentage of transaction volume
  2. I want all orders with xxx to go to 'relationshipB' - 'relationshipB' refers to the relationship you have with a merchant account provider, a processor, or an acquirer (bank). The 'xxx' represents an item that is part of a transaction
  3. I want to do something more complicated

How do I keep a relationship active at a specific transaction percentage?

There may be cases where you want to keep a relationship (with a merchant account provider, a processor, or an acquirer/bank) active or to keep to a contractual monthly gross of authorized transactions (also known as transaction volume).

You do this by setting up target allocations at the level of the Nexio merchant account (MID) for MIDs that support the transaction currency.

Before you begin setting up target allocations, Nexio recommends that you understand the following notes.

Important:

  • If you want routing to be equal for all the API user's MIDs that support the transaction currency, you do not need to create a target allocation rule because that is the default behavior
  • For target allocation, your Nexio account must be configured with a single API user account for all the transactions
  • The transaction volume only includes card and e-check transactions. Transactions using alternative payment methods (APMs) are not included in this volume amount
  • The transaction volume does not get modified for transactions that were successful but then later voided or refunded
  • The transaction volume amount includes the amount for an auth only transaction at the time of the transaction (rather than when the transaction is actually captured)
  • If you change the target allocations, the change is effective from that change date. Thereafter, the system attempts to send transactions based on the new target allocation percentages and based on where the current monthly transaction amount is for each MID. If the change in allocation percentages is large, or if the change happens late in the month, then one MID will get 100% of the transactions for a time during the remainder of the month. Therefore, use caution when making changes in the middle of the month
  • In general, the Nexio system does what it can to allow payments to succeed

Setting up payment routing by target allocation

After you understand the complexities of target allocation (see How do I keep a relationship active at a specific transaction percentage?), you are ready to set it up.

To set up payment routing by target allocation

  1. Work with integration support to set up your Nexio account and merchant accounts so that they are optimized for payment routing by target allocation.

    In general, this means having a single API user with two or more MIDs that support the same transaction currency.

  2. Open the Nexio Dashboard and log in.

    For the sandbox: https://dashboard.nexiopaysandbox.com
    For production: https://dashboard.nexiopay.com

  3. Navigate to Settings > Payment Routing (Beta).

    The tab shows user accounts and the types of rules.

  4. Locate the user account that you want to add to or modify payment routing rules for. Click that row in the table.

    The Payment Routing Rules page displays.

  5. Click Add New Rule.

    The Add Routing Rule dialog displays.

  6. Select the currency you want to add this rule to and then select Target Allocation as the rule type.

    For example, select the USD currency.

  7. Provide values for the Target Allocation fields to match your desired percentages.

    For example, assuming you have two MIDs for your user account and the first one needs to remain at 10% allocation every month, type 10 in the Target Allocation field for MID #1 and type 90 in the Target Allocation field for MID #2.

  8. When you are done creating the rule, click Save.

  9. For the transaction request, configure the API as follows.

    Each payment request must include the following parameters:

    • data.amount
    • data.currency

What happens after you set up target allocation?

The allocation happens over a calendar month and is based on the current monthly volume of authorized transactions for each target and the monetary amount of the transactions. Allocation is not a back and forth ordering, but instead favors the MID that is currently farthest from the target allocation percentage at the time of the transaction. Therefore, if MID #1 is set for 75% and MID #2 is 25%, the system does not necessarily send four transactions to MID #1 and then one transaction to MID #2. The monetary amount of a transaction (and the amount of previous transactions that month) impact which MID the payment is routed to. It is important to note that there is no current way to split a single transaction across two or more MIDs.

Note: A potential unexpected consequence of this method for allocation may happen if there are multiple small transaction amounts throughout the month and then a single large transaction amount that occurs at the end of the month, resulting in the system using the MID with the lower allocation percentage for that transaction and thus putting that MID well above the expected allocation percentage.

After you configure payment routing by target allocation, the following process happens for each transaction for the transaction currency:

  1. A consumer submits payment for a transaction using the target allocation currency.

    For example, the USD currency.

  2. The Nexio system determines the MID with the lowest monthly gross of authorized transactions (also known as transaction volume).

    For example, suppose MID #1, MID #2, and MID #3 can support the currency and MID #4 does not. Only the first 3 are considered.

    Then, if MID #1 has a current volume of $4,500, MID #2 is $10,300, and MID #3 is $8,000, the system prioritizes them as follows:

    • MID #1
    • MID #3
    • MID #2

    In this case, MID #1 has the lowest transaction volume.

  3. The system checks to see if there are target allocation rules that match for this transaction.

    If there are not any target allocation rules, the system skips to step 5 in this sequence.

  4. The system takes the target allocations and re-sorts the list so that the MID that is farthest away from its target allocation is at the top.

    For the following examples, the target allocation is 10% for MID #1, 90% for MID #2, and 0% for MID #3.

    Example 1: Current total transaction volume of $5,600.

MID #1 has a current volume of $300 and 10% allocation, so it is at 5.4% and thus 4.6% away from the target for the month.

MID #2 has a current volume of $4,800 and 90% allocation, so it is at 85.7% and thus 4.3% away from the target for the month.

MID #3 has a current volume of $500 but 0% target allocation, so it is at 8.9%. However, the target is 0%, so no transactions will go to this MID.

The MIDs would be prioritized as follows:
	- MID #1
	- MID #2
	- (MID #3)

Example 2: Current total transaction volume of $22,800

MID #1 has a current volume of $4,500 and 10% allocation, so it is at 19.7% currently and thus 9.7% over the target for the month.

MID #2 has a current volume of $10,300 and 90% allocation, so it is at 45.2% and thus 44.8% away from the target for the month.

MID #3 has a current volume of $8,000 but 0% target allocation, so it is at 35.1%. However, the target is 0%, so no transactions will go to this MID.

The MIDs would be prioritized as follows:
	- MID #2
	- MID #1
	- (MID #3)
  1. The system routes the payment to the MID at the top of the list.

The following image shows a high-level view of the payment flow from above when you are using target allocation with multiple MIDs.

Target Allocation Routing

How do I route all transactions with a specific item to a relationship?

For cases where a transaction contains a certain item that you want to route to a specific relationship (with a merchant account provider, a processor, or an acquirer/bank), use Nexio's item routing feature.

You do this by setting up item routing at the level of the Nexio merchant account (MID) for an item based on the attributes of item, description, or type from the data.cart.items object.

Before you begin setting up item-based payment routing, Nexio recommends that you understand the following notes.

Important:

  • For routing by item, your Nexio account must be configured with a single API user account for all the transactions
  • If you add, change, or delete an item routing rule, the change becomes effective for transactions after that change date
  • In general, the Nexio system does what it can to allow payments to succeed

Setting up payment routing by item

After you understand the complexities of payment routing by item (see How do I route all transactions with a specific item to a relationship?), you are ready to set it up.

To set up payment routing by item

  1. Work with integration support to set up your Nexio account and merchant accounts (MIDs) so that they are optimized for payment routing by item.

    In general, this means having a single API user with a MID that contains the specific relationship (merchant account provider, processor, or acquirer/bank) that applies for the item routing as well as one or more additional relationships for cases where that item is not in the request.

  2. Open the Nexio Dashboard and log in.

    For the sandbox: https://dashboard.nexiopaysandbox.com
    For production: https://dashboard.nexiopay.com

  3. Navigate to Settings > Payment Routing (Beta).

    The tab shows user accounts and the types of rules.

  4. Locate the user account that you want to add to or modify item routing rules for. Click that row in the table.

    The Payment Routing Rules page displays.

  5. Click Add New Rule.

    The Add Routing Rule dialog displays.

  6. Select Item Routing as the rule type and then select the MID you want to add this rule to.

    For example, select MID #1.

  7. Specify one or more attributes for the item routing rule.

    For example, if you have a CBD item in your catalog (where data.cart.items[n].item contains the text 'CBD') and want to route any transactions with that item to a specific gateway that is associated with MID #1, do the following:

    Example Rule 1a:

If 
  `Item`
  `Contains`
  `CBD`

You may also want to add a second rule in case the text is lowercase:

Example Rule 1b:

If 
  `Item` 
  `Contains` 
  `cbd`

Alternately, you can create only one rule if you use a regular expression that matches on the letters "cbd" in the item, regardless of the case of any of the letters, such as the following:

Example Rule 2:

If 
  `Item` 
  `RegEx(ECMAScript)` 
  `[c|C][b|B][d|D]`
  1. You can then add more attributes if you want. For a rule with multiple attributes, the system only matches when ALL the specified attributes match.

  2. When you are done creating the rule, click Save.

  3. For the transaction request, configure the API as follows.

    Each payment request must include the following parameters for item routing:

    • data.amount
    • data.currency
    • data.cart.items[n]

What happens after you set up item routing?

After you configure payment routing by item, the following process happens for each transaction (using CBD as the example):

  1. A consumer adds an item to the shopping cart where the type is 'CBD' and submits payment.

    For example, data.cart.items[1].type equals 'CBD' and the transaction currency is 'USD'.

  2. The Nexio system determines the merchant account (MID) with the lowest monthly gross of authorized transactions (also known as transaction volume).

    For example, suppose MID #1, MID #2, and MID #3 can support the currency and MID #4 does not. Only the first 3 are considered.

    Then, if MID #1 has a current volume of $4,500, MID #2 is $10,300, and MID #3 is $8,000, the system prioritizes them as follows:

    • MID #1
    • MID #3
    • MID #2

    In this case, MID #1 has the lowest transaction volume.

  3. The system checks whether there are any item routing rules with any of the applicable MIDs.

    For example, MID #1 has a rule about the type being 'CBD', MID #2 has a rule about the description containing 'CBD', and MID #3 has a rule about the type and item containing 'CBD'.

    If there are not any item routing rules, the system skips to step 5 in this sequence.

  4. Based on the items in the cart and the item routing rules, the system identifies which of the MIDs can process the transaction.

    For the following examples, MID #1 has a rule about the type being 'CBD', MID #2 has a rule about the description containing 'CBD', and MID #3 has a rule about the type and item containing 'CBD'.

Example 1:

Filtering when only type is 'CBD'

The MIDs would be prioritized as follows:
- MID #1

Example 2:

Filtering when both type and item are 'CBD'
	
The MIDs would be prioritized as follows:
- MID #1
- MID #3

Example 3:

Filtering when type is 'CBD' and description and item both contain 'CBD'
	
The MIDs would be prioritized as follows:
- MID #1
- MID #3
- MID #2

Example 4:

If applying the item routing rules results in no possible MIDs to process the transaction, the system ignores the rules.

Filtering when description is exactly 'CBD'
	
The list is empty, therefore the system removes the rule filtering, resulting in the following priorities for the MIDs:
- MID #1
- MID #3
- MID #2

  1. The system routes the payment to the MID at the top of the list.

The following image shows a high-level view of the payment flow from above when you are using item routing with multiple MIDs.

Item Payment Routing

How do I set up a more complex payment routing flow?

More complex payment routing flows are also possible with Nexio.

This section provides information about the following complex options:

  1. I want to use both item routing and target allocation together
  2. I want to use a paymentOptionTag with payment routing (with or without target allocation and/or item routing)
  3. I want to send the transaction to a specific payment option for a specific MID
  4. I want to send a transaction to a specific MID

How do I use both item routing and target allocation together?

You can set up rules for both item routing and target allocation to create a complex payment routing flow when you have more than one merchant account (MID).

Before setting up rules, see the Important Notes in the following topics:

To set up payment routing by item and target allocation

  1. Complete steps 1-9 in Setting up payment routing by target allocation

  2. Complete steps 5-10 in Setting up payment routing by item

What happens after you set up both target allocation and item routing?

After you complete the steps for creating rules for both target allocation and item routing, the following process happens for each transaction (using 'CBD' as the item for routing):

  1. A consumer adds an item to the shopping cart where the type is 'CBD' and submits payment.

    For example, data.cart.items[1].type equals 'CBD' and the transaction currency is 'USD'.

  2. The Nexio system determines the merchant account (MID) with the lowest monthly gross of authorized transactions (also known as transaction volume).

    For example, suppose MID #1, MID #2, and MID #3 can support the currency and MID #4 does not. Only the first 3 are considered.

    Then, if MID #1 has a current volume of $4,500, MID #2 is $10,300, and MID #3 is $8,000, the system prioritizes them as follows:

    • MID #1
    • MID #3
    • MID #2

    In this case, MID #1 has the lowest transaction volume.

  3. The system checks whether there are any item routing rules with any of the applicable MIDs.

    For example, MID #1 has a rule about the type being 'CBD', MID #2 has a rule about the description containing 'CBD', and MID #3 has a rule about the type and item containing 'CBD'.

    If there are not any item routing rules, the system skips to step 5 in this sequence.

  4. Based on the items in the cart and the item routing rules, the system identifies which of the MIDs can process the transaction.

    For the following examples, MID #1 has a rule about the type being 'CBD', MID #2 has a rule about the description containing 'CBD', and MID #3 has a rule about the type and item containing 'CBD'.

Example 1:

Filtering when only type is 'CBD'

The MIDs would be prioritized as follows:
- MID #1

Example 2:

Filtering when both type and item are 'CBD'
	
The MIDs would be prioritized as follows:
- MID #1
- MID #3

Example 3:

Filtering when type is 'CBD' and description and item both contain 'CBD'
	
The MIDs would be prioritized as follows:
- MID #1
- MID #3
- MID #2

Example 4:

If applying the item routing rules results in no possible MIDs to process the transaction, the system ignores the rules.

Filtering when description is exactly 'CBD'
	
The list is empty, therefore the system removes the rule filtering, resulting in the following priorities for the MIDs:
- MID #1
- MID #3
- MID #2

  1. The system checks to see if there are target allocation rules that match for this transaction.

    If there are not any target allocation rules, the system skips to step 7 in this sequence.

  2. The system takes the target allocations and re-sorts the list so that the MID that is farthest away from its target allocation is at the top.

    For the following examples, the target allocation is 10% for MID #1, 90% for MID #2, and 0% for MID #3.

    Example 1: Current total transaction volume of $5,600.

MID #1 has a current volume of $300 and 10% allocation, so it is at 5.4% and thus 4.6% away from the target for the month.

MID #2 has a current volume of $4,800 and 90% allocation, so it is at 85.7% and thus 4.3% away from the target for the month.

MID #3 has a current volume of $500 but 0% target allocation, so it is at 8.9%. However, the target is 0%, so no transactions will go to this MID.

The MIDs would be prioritized as follows:
	- MID #1
	- MID #2
	- (MID #3)

Example 2: Current total transaction volume of $22,800

MID #1 has a current volume of $4,500 and 10% allocation, so it is at 19.7% currently and thus 9.7% over the target for the month.

MID #2 has a current volume of $10,300 and 90% allocation, so it is at 45.2% and thus 44.8% away from the target for the month.

MID #3 has a current volume of $8,000 but 0% target allocation, so it is at 35.1%. However, the target is 0%, so no transactions will go to this MID.

The MIDs would be prioritized as follows:
	- MID #2
	- MID #1
	- (MID #3)
  1. The system routes the payment to the MID at the top of the list.

The following image shows a high-level view of the payment flow from above for when you are using both target allocation and item routing with multiple MIDs.

Target and Item Routing

What effect does the use of a paymentOptionTag have on payment routing?

You can limit the routing by specifying processingOptions.paymentOptionTag in the transaction request (such as in POST /pay/v3/process).

The paymentOptionTag parameter is a custom value used to route transactions to a specific gateway or merchant account. In order to use the paymentOptionTag for routing, contact integration support to designate one or more tags for your merchant account.

Before you begin setting up a paymentOptionTag, Nexio recommends that you understand the following notes.

Important:

  • If the value provided for paymentOptionTag in the transaction request is invalid for the account, Nexio sends an error rather than attempt the transaction
  • If the transaction would be disqualified because of the specified parameter, Nexio responds with an error message and does not attempt to process the transaction further
  • If you specify a value for the paymentOptionTag in the request and that tag has been assigned to multiple merchant IDs (MIDs) for your API user account, Nexio checks for target allocation or item routing rules as well. If there are not any rules, the system uses the MID with the current lowest monthly gross of authorized transactions (also known as transaction volume)
  • In addition, if you want to use target allocation or routing based on item with the paymentOptionTag, see the Important Notes in the appropriate topics:

Along with the paymentOptionTag, you can also make the payment routing flow more complex with either or both target allocation and item routing.

To set up paymentOptionTags

  1. Contact integration support to designate one or more tags for your merchant account (MID).

    Example 1: paymentOptionTags for USD as official currency in different countries

     MID #1
     - USD currency for United States: usa
     - USD currency for Puerto Rico: pri
     - USD currency for Ecuador: ecu
    

    Example 2: paymentOptionTags for CBD

     MID #1
     - Gateway that allows transactions with CBD: CBD
     - Gateway to use for all other transactions: NoCBD 
    
  2. Make note of the tags that are created for your MIDs. These are not visible in the Dashboard.

    Note: If you later need to find out what paymentOptionTags have been enabled, contact integration support.

  3. If necessary, complete the steps in Setting up payment routing by target allocation

  4. If necessary, complete the steps in Setting up payment routing by item

  5. For the transaction request, configure the API as follows:

    Each payment request must include the following parameters for payment routing with the paymentOptionTag:

    • data.amount
    • data.currency
    • processingOptions.paymentOptionTag

    To customize payment routing with the paymentOptionTag and item routing, also include the following parameter:

    • data.cart.items[n]

What happens after you set up paymentOptionTags?

After you complete the steps for setting up one or more paymentOptionTags (and potentially also either or both target allocation and item routing), the following process happens for each transaction:

  1. A consumer adds an item to the shopping cart and submits payment with a specific transaction currency.

    For example, The consumer adds a CBD item and uses a card to pay in USD.

    The data.cart.items[1].type parameter is set to 'CBD' and the transaction currency is 'USD'.

    Also, the processingOptions.paymentOptionTag parameter is set to 'CBD'.

    If the consumer instead had a cart of one or more items and none are CBD, then the paymentOptionTag would be 'NoCBD'.

  2. The Nexio system determines the merchant account (MID) with the lowest monthly gross of authorized transactions (also known as transaction volume).

    Example 1: Suppose MID #1, MID #2, and MID #3 can support the currency and paymentOptionTag of CBD and NoCBD and MID #4 does not have any paymentOptionTags. Only the first 3 MIDs are considered.

     Then, if MID #1 has a current volume of $4,500, MID #2 is $10,300, and MID #3 is $8,000, the system prioritizes them as follows:
     - MID #1
     - MID #3
     - MID #2
    
     In this case, MID #1 has the lowest transaction volume.
    

    Example 2: Suppose only MID #1 and MID #3 can support the currency and paymentOptionTag and MID #2 only supports the currency and MID #4 does not have any paymentOptionTags. Only MIDs #1 and #3 are considered.

     Then, if MID #1 has a current volume of $10,300, and MID #3 is $8,000, the system prioritizes them as follows:
     - MID #3
     - MID #1
    
     In this case, MID #3 has the lowest transaction volume.
    
  3. The system checks to see if any routing rules have been configured and that apply.

    For example, all three MIDs have item routing and target allocation rules.

  4. The system checks whether there are any item routing rules with any of the applicable MIDs.

    For example, MID #1 has a rule about the type being 'CBD', MID #2 has a rule about the description containing 'CBD', and MID #3 has a rule about the type and item containing 'CBD'.

    If there are not any item routing rules, the system skips to step 6 in this sequence.

  5. Based on the items in the cart and the item routing rules, the system identifies which of the MIDs can process the transaction.

    For the following examples, MID #1 has a rule about the type being 'CBD', MID #2 has a rule about the description containing 'CBD', and MID #3 has a rule about the type and item containing 'CBD'.

    Example 1:

     Filtering when only type is 'CBD'
    
     The MIDs would be prioritized as follows:
     - MID #1
    

    Example 2:

     Filtering when both type and item are 'CBD'
    
     The MIDs would be prioritized as follows:
     - MID #1
     - MID #3
    

    Example 3:

     Filtering when type is 'CBD' and description and item both contain 'CBD'
    
     The MIDs would be prioritized as follows:
     - MID #1
     - MID #3
     - MID #2
    

    Example 4:

     If applying the item routing rules results in no possible MIDs to process the transaction, the system ignores the rules.{.indent}
    
     	Filtering when description is exactly 'CBD'
    
     	The list is empty, therefore the system removes the rule filtering, resulting in the following priorities for the MIDs:
     	- MID #1
     	- MID #3
     	- MID #2
    
  6. The system checks to see if there are target allocation rules that match for this transaction.

    If there are not any target allocation rules, the system skips to step 8 in this sequence.

  7. The system takes the target allocations and re-sorts the list so that the MID that is farthest away from its target allocation is at the top.

    For the following examples, the target allocation is 10% for MID #1, 90% for MID #2, and 0% for MID #3.

    Example 1: Current total transaction volume of $5,600.

     MID #1 has a current volume of $300 and 10% allocation, so it is at 5.4% and thus 4.6% away from the target for the month.
    
     MID #2 has a current volume of $4,800 and 90% allocation, so it is at 85.7% and thus 4.3% away from the target for the month.
    
     MID #3 has a current volume of $500 but 0% target allocation, so it is at 8.9%. However, the target is 0%, so no transactions will go to this MID.
    
     The MIDs would be prioritized as follows:
     - MID #1
     - MID #2
     - (MID #3)
    

Example 2: Current total transaction volume of $22,800

	MID #1 has a current volume of $4,500 and 10% allocation, so it is at 19.7% currently and thus 9.7% over the target for the month.

	MID #2 has a current volume of $10,300 and 90% allocation, so it is at 45.2% and thus 44.8% away from the target for the month.

	MID #3 has a current volume of $8,000 but 0% target allocation, so it is at 35.1%. However, the target is 0%, so no transactions will go to this MID.

	The MIDs would be prioritized as follows:
	- MID #2
	- MID #1
	- (MID #3)
  1. The system routes the payment to the MID at the top of the list.

The following image shows a high-level view of the payment flow from the above process when you are using paymentOptionTags along with the potential for target allocation and item routing with multiple MIDs.

Payment Option Tags

How do I send a transaction to a specific MID and paymentOptionTag based on transaction currency?

There may be cases where you don't want to use Nexio's smart routing feature and you want to send all transactions for a specific transaction currency to one specific merchant account (MID) and payment option for that MID.

You can limit the routing by specifying both a processingOptions.merchantId and processingOptions.paymentOptionTag in the transaction request (such as in POST /pay/v3/process).

The merchantId parameter is a unique code that Nexio assigns to each MID on your account.

The paymentOptionTag parameter is a custom value used to route transactions to a specific gateway or merchant account. In order to use the paymentOptionTag for routing, contact integration support to designate one or more tags for your merchant account.

Before you begin setting up a paymentOptionTag and using merchantId, Nexio recommends that you understand the following notes.

Important:

  • When you specify a value for both of these parameters (processingOptions.merchantId and processingOptions.paymentOptionTag), Nexio uses only this information to process the transaction. The system will not attempt to use any other possible merchant IDs (MIDs) or payment option tags

    Therefore, using a specific value for both of these parameters means that Nexio does not attempt any other routing, even if other routing rules have been specified in the account

  • If the value provided for either merchantId or paymentOptionTag in the transaction request is invalid for the account, Nexio sends an error rather than attempt the transaction

  • If the transaction would be disqualified because of the specified parameter, Nexio responds with an error message and does not attempt to process the transaction further

To set up paymentOptionTag and merchantId

  1. Contact integration support to learn the merchantId for each MID on your account and to designate one or more paymentOptionTags for your merchant account.

    Example 1: paymentOptionTags for USD as official currency in different countries

     MID #1
     - merchantId is 100000000039
     - USD currency for United States: usa
     - USD currency for Puerto Rico: pri
     - USD currency for Ecuador: ecu
    
     MID #2
     - merchantId is 100000000041
     - USD currency for Ecuador: ecu
    
  2. Make note of the tags that are created for your MIDs. These are not visible in the Dashboard.

    You can see the merchantId for each of your MIDs by going to the Dashboard, then Settings > Merchant Management.

    Note: To get a list of all paymentOptionTags for which a currency is enabled for a given merchant ID, contact integration support.

  3. For the transaction request, configure the API as follows:

Each payment request must include the following parameters for payment routing with the paymentOptionTag and merchantId:
- `data.amount`
- `data.currency`
- `processingOptions.paymentOptionTag`
- `processingOptions.merchantId`

What happens when a transaction request includes a paymentOptionTag and merchantId?

After you complete the steps for setting up one or more paymentOptionTags and know the merchantId you want to use, the following process happens for each transaction:

  1. A consumer adds an item to the shopping cart and submits payment with a specific transaction currency.

    For example, The consumer with an address in Ecuador uses a card to pay in USD.

    Also, the processingOptions.paymentOptionTag parameter is set to 'ecu' and the processingOptions.merchantId parameter is set to '100000000041'.

  2. The Nexio system checks for the specific MID and if it has support for the transaction currency and the paymentOptionTag.

    Example 1:

     For address in Ecuador and MID of 100000000041
    
     MID #2 is the only option because it has the correct merchantId and paymentOptionTag.
    

    Example 2:

     For address in Puerto Rico and MID of 100000000041
    
     Nexio returns an error message because that MID does not include that paymentOptionTag.
    
  3. The system routes the payment to the MID or responds with an error message.

How do I send a transaction to a specific MID based on transaction currency?

There may be cases where you don't want to use Nexio's smart routing feature and you want to send all transactions for a specific transaction currency to one specific merchant account (MID).

You can limit the routing by specifying the processingOptions.merchantId in the transaction request (such as in POST /pay/v3/process).

The merchantId parameter is a unique code that Nexio assigns to each MID on your account.

Before you begin using merchantId, Nexio recommends that you understand the following notes.

Important:

  • When you specify a value for processingOptions.merchantId, Nexio uses only this information to process the transaction. The system will not attempt to use any other possible merchant IDs (MIDs)

    Therefore, using a specific value for this parameter means that Nexio does not attempt any other routing, even if other routing rules or paymentOptionTags have been specified in the account

  • If the value provided for merchantId in the transaction request is invalid for the account, Nexio sends an error rather than attempt the transaction

  • If the transaction would be disqualified because of the specified parameter, Nexio responds with an error message and does not attempt to process the transaction further

To set up merchantId

  1. Contact integration support to learn the merchantId for each MID on your Nexio account.

    Example 1:

     paymentOptionTags for USD as official currency in different countries
    
     MID #1
     - merchantId is 100000000039
     - USD currency for United States: usa
     - USD currency for Puerto Rico: pri
     - USD currency for Ecuador: ecu
    
     MID #2
     - merchantId is 100000000041
     - USD currency for Ecuador: ecu
    
  2. Open the Nexio Dashboard and log in.

    For the sandbox: https://dashboard.nexiopaysandbox.com
    For production: https://dashboard.nexiopay.com

  3. Go to Settings > Merchant Management.

    A list displays of all merchant accounts for your account, including the merchant ID value.

    Make note of the merchant ID value that you want to use.

  4. For the transaction request, configure the API as follows:

    Each payment request must include the following parameters for payment routing with the merchantId:

    • data.amount
    • data.currency
    • processingOptions.merchantId

What happens when a transaction request includes a merchantId?

After you know and assign the merchantId you want to use to transaction rerquests, the following process happens for each transaction:

  1. A consumer adds an item to the shopping cart and submits payment with a specific transaction currency.

    For example, The consumer with an address in Ecuador uses a card to pay in USD.

    Also, the processingOptions.merchantId parameter is set to '100000000041'.

  2. The Nexio system checks that the MID has support for the transaction currency.

    Example 1:

     For address in Ecuador and MID of 100000000041
    
     MID #2 is valid because it has support for the currency.
    

    Example 2:

     For address in Puerto Rico and MID of 100000000041
    
     Nexio returns an error message because that MID does not support that currency for that country.
    
  3. The system routes the payment to the MID or responds with an error message.


Nexio Dashboard

The Nexio Dashboard provides access to transactions, reports, account information, and settings.

You can perform the following tasks in the Dashboard for Payment Routing:

The following section has information about fields on Payment Routing pages in the Dashboard:

Payment Routing by Item

Nexio allows you to specify payment routing rules for an item at the level of the Nexio merchant account (MID) for an item based on the attributes of item, description, or type from the data.cart.items object.

After you understand the complexities of payment routing by item (see How do I route all transactions with a specific item to a relationship?), you are ready to set it up. For information about how the routing rules are prioritized and for a tutorial based on your desired outcome, see the Payment Routing (Beta) section.

Note: If you add, change, or delete an item routing rule, the change becomes effective for transactions after that change date.

To set up payment routing by item

  1. Open the Nexio Dashboard.

    For the sandbox: https://dashboard.nexiopaysandbox.com
    For production: https://dashboard.nexiopay.com

  2. Navigate to Settings > Payment Routing (Beta).

    The tab shows user accounts and the types of rules. For information about this tab, see Fields: Payment Routing (Beta).

  3. Locate the user account that you want to add to or modify payment routing rules for. Click that row in the table.

    The Payment Routing Rules page displays. For information about this page, see Fields: Payment Routing Rules.

  4. Add or modify rules for one or more MIDs:

    • To add a rule, click Add New Rule. The Add New Rule dialog displays
    • To edit an existing rule, locate and select the rule in the table. The Edit New Rule dialog displays
    • To delete an existing rule, open the rule, click Delete and then confirm that deletion
  5. For a new rule, select Item Routing as the rule type and then select the MID you want to add this rule to.

    For example, select MID #1.

  6. Specify one or more attributes for the item routing rule.

    For more information about the options in this dialog, see the item routing information in Fields: Add/Edit Routing Rule.

  7. You can then add more attributes if you want. For a rule with multiple attributes, the system only matches when ALL the specified attributes match.

  8. When you are done creating the rule, click Save.

Payment Routing by Target Allocation

When you have multiple merchant IDs (MIDs) for an account and want to have Nexio route payments based on the total amount processed for each MID for a currency, you can set up routing by target allocation percentage.

After you understand the complexities of target allocation (see How do I keep a relationship active at a specific transaction percentage?), you are ready to set it up. For information about how the routing rules are prioritized and for a tutorial based on your desired outcome, see the Payment Routing (Beta) section.

Note: If you change the target allocations, the change is effective from that change date. Thereafter, the system attempts to send transactions based on the new target allocation percentages and based on where the current monthly transaction amount is for each MID. If the change in allocation percentages is large, or if the change happens late in the month, then one MID will get 100% of the transactions for a time during the remainder of the month. Therefore, use caution when making changes in the middle of the month

To set up payment routing by allocation

  1. Open the Nexio Dashboard.

    For the sandbox: https://dashboard.nexiopaysandbox.com
    For production: https://dashboard.nexiopay.com

  2. Navigate to Settings > Payment Routing (Beta).

    The tab shows user accounts and the types of rules. For information about this tab, see Fields: Payment Routing (Beta).

  3. Locate the user account that you want to add to or modify payment routing rules for. Click that row in the table.

    The Payment Routing Rules page displays. For information about this page, see Fields: Payment Routing Rules.

  4. Add or modify rules for one or more MIDs:

    • To add a rule, click Add New Rule. The Add Routing Rule dialog displays
    • To edit an existing rule, locate and select the rule in the table. The Edit Routing Rule dialog displays
    • To delete an existing rule, open the rule, click Delete and then confirm that deletion
  5. For a new rule, select the currency you want to add this rule to and then select Target Allocation as the rule type.

    For more information about the options in this dialog, see the target allocation information in Fields: Add/Edit Routing Rule.

  6. When you are done creating the rule, click Save.




Dashboard Fields

This section provides information about the fields on the following pages:

Fields: Payment Routing (Beta)

PATH: Settings > Payment Routing (Beta) tab

The Payment Routing tab shows all user accounts for your login, the Merchant IDs (MIDs) associated with each one, and the types of rules associated with each user account.

Refresh (icon)

Lets you refresh the table display.

User and Routing List

Displays a list of the user accounts and what kinds of routing rules (if any) are associated with that account.

Click anywhere in a row to go to the Payment Routing Rules page.

The list displays the following information:

Option Description
User E-mail Displays the email address associated with the user account. Start typing an email address or any part thereof to dynamically filter the list.

Click the heading to sort the account list in alphabetical order. Click the heading again to sort the account list in reverse-alphabetical order.
Merchants Displays the merchant ID (MID) or merchant IDs that are associated with the user account.
Routing Rule Type Displays the type of routing rule associated with the user account. Options are "None" "Item Rule", and "Target Allocation".

**+ (plus sign)** (icon)

Lets you select which columns display in the table.

List Navigation

Lets you move to specific locations in the list of user accounts.

The navigation has the following controls:

  • < First - Go to the first page of accounts
  • Previous - Go to the previous page of accounts
  • x-y of z - Displays the current location in the list of accounts
  • Next - Go to the next page of accounts
  • Last > - Go to the last page of accounts

Fields: Payment Routing Rules

PATH: Settings > Payment Routing (Beta) tab > [user account]

The Payment Routing Rules page lets you create and modify existing routing rules for a selected user account.

User email

Displays the email address of the currently selected user account.

Add New Rule

Lets you add a payment routing rule for the user account. Clicking the button opens the Add New Rule dialog.

Refresh (icon)

Lets you refresh the table display.

Routing Rules List

Displays a list of the merchant accounts for the user and routing rules (if any) associated with each merchant account.

Click anywhere in a row to go to the Edit Routing Rule dialog.

The list displays the following information:

Option Description
Merchant Displays the name of the merchant account. Or, for Target Allocation routing rules, displays "Multiple". Start typing a merchant name or any part thereof to dynamically filter the list.

Click the heading to sort the list in alphabetical order by merchant name. Click the heading again to sort the list in reverse-alphabetical order.
Merchant ID Displays the merchant ID (MID) associated with the merchant account. Or, for Target Allocation routing rules, displays "Multiple".
Currency Displays the three-character code for the currency associated with a Target Allocation routing rule.
Routing Rule Type Displays the type of routing rule associated with the user account. Options are "Item Rule" or "Target Allocation".

**+ (plus sign)** (icon)

Lets you select which columns display in the table.

Fields: Add/Edit Routing Rule

PATH: Settings > Payment Routing (Beta) tab > [user account] > Add New Rule
PATH: Settings > Payment Routing (Beta) tab > [user account] > [rule name]

Lets you create or edit the routing rule.

For the steps on how to set up a rule, see Payment Routing (BETA).

Rule Type

For a new rule, lets you select the type of routing rule to create, either Item Routing or Target Allocation. Target Allocation is the default selection.

For editing an existing rule, displays the type of routing rule.

Rule Info

For Item Routing, the following fields display:

Option Description
Merchant Lets you select the merchant account for the item routing rule. You must select the MID for the remaining fields to display.
Attributes The attributes section lets you configure the settings of the item routing rule. Each attribute rule starts with an "If" statement. The fields are the following:
- Attribute - Specifies the attribute of an item to use for the rule. The values come from the parameters of the items[] object. Options are "Item", "Description", or "Type".
- Type - Specifies the type of search or filter to use with the selected attribute. Options are "RegEx (ECMAScript)", "Contains", "Does Not Contain", "Matches Exactly", or "Does Not Match Exactly".
- Enter text - Specifies the text to use for the search or filter of this rule. This value is case sensitive.
Add Another Attribute Lets you add one or more additional attributes as part of this item routing rule. When you have more than two attributes, they are joined by the Boolean AND, so that all attributes must apply for the rule to be used for item routing.

For Target Allocation, the following fields display:

Option Description
Currency Lets you select the currency to set up a target allocation for with the user account. You must select the currency for the remaining fields to display.
Merchant list The merchant list shows the possible merchant accounts that can be allocated for the specified currency. The list displays the merchant account name and merchant ID (MID) as well as the current Target Allocation (if any).

Specify the allocation percentage that you want to assign to each MID in the Target Allocations fields. You can specify a 0 for one or more MIDs or 100 for only one MID, however the total must add up to 100% for the allocation across all MIDs before you can save the rule.

**Delete**

Lets you completely remove an existing routing rule from this merchant account.

Save

Click this button to save the routing rule.

Payouts

Payouts Overview

A common recipient payout experience is logging into a payout provider portal and claiming funds.

Nexio has integrated several payout providers while continuing to provide the same portal experience to recipients, including email notifications and a reporting interface.

What is a recipient?

A recipient is the individual or business receiving payments. Before paying out to a recipient, a recipient profile must first be created either as a separate step or simultaneously with the payout request.

What is a payout?

A payout is the request from the payer (merchant or business, for example) to fund a recipient’s balance, wallet, or account.

What is the recipient's experience?

Depending on the chosen payout provider, the payout experience for recipients does not have to change at all.

What is the payer's experience?

The payer (merchant or business, for example) can keep the exact same experience with the payout provider portal, including manual uploads to the provider's portal.

Nexio adds the option for payers to send payouts to recipients through an integration, and gives them a centralized location to track payouts and access reports in the Nexio Dashboard.

What is the integration experience?

An integrator can leverage Nexio's API to do the following:

  • Create a recipient profile to which payments will be sent
  • Retrieve information for one or multiple recipient profiles
  • Create a request to process one or more payout transactions
  • Retrieve details for one or more payout transactions

The overall payout experience is as follows:

  1. Your application creates a recipient profile (before or during a payout request).

    For details about using the API to create a profile, see the Create a Recipient, Submit Payouts, or Submit Payouts using Batch File endpoint.

  2. Your application submits a payout request.

    For details about using the API to submit a payout request, see the Submit Payouts or Submit Payouts using Batch File endpoint.

  3. The recipient receives an email notification from the payout provider prompting them to log in and accept the payment.

  4. The recipient activates their payout account and selects their preferred transfer method.

  5. The recipient’s transfer method is funded.

  6. The payer (merchant or business, for example) views payout information in the Nexio Dashboard (or using the payout provider portal).

    For details about using the API to retrieve information for one or more recipient profiles, see the View a Recipient or View Recipients endpoint.

    For details about using the API to retrieve information for one or more payouts, see the View a Payout or View Payouts endpoint.

    For details about configuring and using webhooks to retrieve payout event information, see Webhooks.

Subscriptions

Nexio's subscription service allows you to run recurring transactions. These can be in the form of basic subscriptions or pay plans.

Subscriptions

Subscriptions set transactions to run for a specified amount on a predefined schedule. When you create a subscription you will set the following parameters:

  • Amount: (payment.data.amount) The amount that will be charged during each transaction

  • Interval: (schedule.interval) The schedule's time period. May be days, weeks, months or years

  • Interval count: (schedule.intervalCount) The number of intervals that will pass between transactions. See the table below for examples of how the interval and interval count create the subscription schedule

  • Initial billing period (optional): If desired, you may set an initial billing period during which the transactions will be run for an amount different than the subscription amount. (For example, during a discounted trial period.) To set an initial billing period, include the following parameters:

    • Initial Billing Period End Date: (schedule.dateInitialBillingEnd) The date at which the initial billing period will end. Transactions prior to this date will be run for the initial billing amount. Transactions after this date will be run for the subscription amount.
    • Initial billing Amount: (schedule.initialBillingAmount) The transaction amount during the initial billing period

Subscription Schedule Examples

Interval Count Interval Explanation
30 Day Transactions will run every 30 days
4 Week Transactions will run every 4 weeks
2 Month Transactions will run every other month

Create a Subscription

  1. Determine your Settings

    Determine whether to include an initial billing period and the proper subscription settings. (These will generally be pre-determined by the shopper's selections on your checkout page.)

  2. Send a Request to Nexio

    Send a POST request to the Create Subscription endpoint. Include the billing amounts and subscription settings as determined in step 1.

The example below will create a recurring subscription that will run a transaction for 19.99 USD every other week.

Basic Subscription
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"
    }
  },
  "schedule": {
    "interval": "week",
    "intervalCount": 2
  }
}'

The example below will create a recurring subscription that will run a transaction once a month. The transaction amount will be 15 USD until October 5, 2021. After that the transaction amount will be 25 USD.

Subscription with Initial Billing Period
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": 25,
      "currency": "USD",
      "customer": {
        "customerRef": "RP006"
      }
    },
    "tokenex": {
      "token": "6ee140a0-05d1-4958-8325-b38a690dbb9d"
    }
  },
  "schedule": {
    "interval": "month",
    "intervalCount": 1,
    "dateInitialBillingEnd": "2021-10-05",
    "initialBillingAmount": 15
  }
}'

Note: If the initial transaction is declined, the subscription will not be created. It must be re-created with a new card token.

  1. Configure Webhooks (Optional)

    If desired, you may configure webhooks to be sent every time a transaction is run through the subscription service. See the Webhooks tutorial for step-by-step instructions on how to configure and receive webhooks.

    Note: You will continue to receive webhooks for any previously configured transaction events.

Example Request
curl -X POST https://api.nexiopaysandbox.com/webhook/v3/config \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic <Your Basic Auth>'
  -d '{
  "merchantId": "100039",
  "webhooks": {
    "SUBSCRIPTION_DETAILS": {
      "url": "https://your-company-webhook-url-here.com"
    }
  }
}'

Pay Plans

Pay plans set recurring transactions to run until the pre-specified balance is paid in full. To create a pay plan, create a subscription and include the following parameters in your request:

  • Balance: (schedule.balance) The total amount to be charged over the course of the pay plan
  • Interval: (schedule.interval) The pay plans's time period. May be days, weeks, months or years
  • Interval count: (schedule.intervalCount) The number of intervals that will pass between transactions. See the table below for examples of how the interval and interval count create the subscription schedule
  • Amount (optional): (payment.data.amount) The amount to be charged during each transaction
  • Duration (optional): (schedule.duration) The duration of the subscription. This is the number of transactions that will run before the pay plan terminates. If amount is not provided the duration will also be used to calculate the amount to be charged during each transaction

Note: You must provide either an amount or a duration. If you provide both, amount will be used, duration will be ignored.

Create a Pay Plan

  1. Determine your Settings

    Determine the pay plan balance and schedule. Also determine whether you would like to provide an amount or a duration (not both). These may be pre-determined by the shopper's selections on your checkout page.

  2. Send a Request to Nexio

    Send a POST request to the Create Subscription endpoint. Include the balance, schedule and amount/duration as determined in step 1.

The example below will create a pay plan with a balance of 100 USD. It will run a transaction once a month for 10 USD. After the 10th transaction, the balance will be paid in full and the pay plan with terminate.

Pay Plan with Transaction Amount
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": 10,
      "currency": "USD",
      "customer": {
        "customerRef": "RP006"
      }
    },
    "tokenex": {
      "token": "6ee140a0-05d1-4958-8325-b38a690dbb9d"
    }
  },
  "schedule": {
    "balance": 100,
    "interval": "month",
    "intervalCount": 1
  }
}'

The example below will create a pay plan with a balance of 100 USD that will run every month for 5 months. In order for the balance to be paid in full, each transaction will automatically be run for 20 USD.

PAY PLAN WITH DURATION
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": {
      "currency": "USD",
      "customer": {
        "customerRef": "RP006"
      }
    },
    "tokenex": {
      "token": "6ee140a0-05d1-4958-8325-b38a690dbb9d"
    }
  },
  "schedule": {
    "balance": 100,
    "duration": 5,
    "interval": "month",
    "intervalCount": 1
  }
}'
  1. Configure Webhooks (Optional)

    If desired, you may configure webhooks to be sent every time a transaction is run through the subscription service. See the Webhooks tutorial for step-by-step instructions on how to configure and receive webhooks.

    Note: You will continue to receive webhooks for any previously configured transaction events.

Example Request
curl -X POST https://api.nexiopaysandbox.com/webhook/v3/config \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic <Your Basic Auth>'
  -d '{
  "merchantId": "100039",
  "webhooks": {
    "SUBSCRIPTION_DETAILS": {
      "url": "https://your-company-webhook-url-here.com"
    }
  }
}'

Dev Tools

Handling Errors and Declines

For most situations you will encounter a handful of HTTP response status codes for error and success -- including 200, 401, 404, 400, and 500.

The most common responses will be:

  • 200: Operation was successful

  • 4xx: Operation failed (In the case of payments, a 4xx status code means the payment was not processed)

Note: Due to PCI regulations error messages may often be intentionally ambiguous. Please contact us if you wish to discuss your error messages, or see our list of common errors.

Errors in the payment forms can be handled by adding an event listener to the window.

Example
window.addEventListener('message', function messageListener(event) {
    if (event.origin === iframeDomain) {
        if (event.data.event === 'error' || event.data.event === 'success' || event.data.event === 'processed') {
        // handle success or error messages
        }
        if (event.data.event === 'loaded') {
        //handle form loaded state
        }
        if (event.data.event === 'cardSaved') {
        //handle cardSaved
        }
        console.log(event.data.event);
    }
});

Common Errors

Nexio Error Code Description HTTP Status Code
404 The requested item is not found 404
404 Merchant not found or invalid merchant configuration 404
408 Payment gateway timeout 400
409 No merchants enabled for processing on this account for selected currency 409
418 Unsupported action or browser, or device does not support Apple Pay 400
431 Kount has identified a possible risk with the transaction 400
432 Invalid currency 400
433 Invalid gateway 400
434 Invalid TokenEx configuration 400
435 Unable to process with gateway 400
436 Unable to capture void or refund 400
436 Missing required fields 400
437 Failed CVC check 400
438 Invalid request 400
439 Unable to load TokenEx 500
440 Insufficient access 401
441 Amount needs to be a number 400
443 Verify AVS Failed 400
5xx Generic server error 500

Gateway Declines

If a card transaction is declined by the gateway, Nexio will return an HTTP status code and a Nexio error code. The payment will not be processed.

The response will be shaped as shown in the example below.

Example Gateway Decline
{
  "error": 435,
  "message": "Declined for CVV failure",
  "gatewayResponse": {
    "gatewayName": "yourGateway",
    "refNum": "3113320943",
    "status": "pending"
  },
  "merchantId": "100100"
}

Common Gateway Declines

See the table below for a list of the most common gateway declines.

Nexio Error Code Message HTTP Status Code
435 Declined 400
435 Pickup Card 400
435 Do not Honor 400
435 Invalid Transaction 400
435 Invalid Issuer 400
435 Unable to locate Record 400
435 Insufficient funds 400
435 Invalid Pin 400
435 Transaction Not Permitted 400
435 Restricted Card 400
435 Excess withdrawal count 400
435 Allowable number of pin tries exceeded 400
435 No checking account 400
435 Declined for CVV failure 400

CVC Verification Failures

There are two main reasons that a verifyCvc check while saving a card token can fail.

  • Incorrect card security code or similar problem
  • Error with some part of the CVC process outside of Nexio

Incorrect Card Security Code or Card Problem

If you submit a save card transaction where you have verifyCvc enabled and the specified card security code is not correct, then the matchCvv response returns as false and the cvvresponse returns as N. Although the verifyCvc check completed successfully, because the card security code was invalid, the system returns an HTTP status code of 400 and a Nexio error code of 437. In addition, the card token is not saved.

Other card problems from submitting this transaction also return the matchCvv as false and the card token does not get saved. The cvvresponse in the gateway message is also N for these cases. The message from the gateway provides additional detail about the specific problem, such as expired card or insufficient funds.

The response will be shaped as shown in the example below.

Example CVC Verification Failure
{
  "error": 437,
  "message": "Verify CVC Failed",
  "cvcResults": {
    "matchCvv": false,
    "error": false,
    "gatewayMessage": {
      "cvvresponse": "N",
      "message": "CVV2/CVC2 no match"
    }
  },
  "merchantId": "100100"
}

Error with a Verification Provider During the Check

In addition to the card security code being incorrect, there may be a problem with doing the verification process. The error parameter will be set to true.

After getting any of these errors, you may want to delete the card token.

The following table lists of the most common card CVC verification errors.

CVV Response Code Message Description
P Not processed This error indicates a general error that caused the verification check to not run at all. The card token is still saved.
S Merchant has indicated that CVV2/CVC2 is not present on card This error indicates that the merchant had a problem when doing the verification check, such as when a card security code is given but no code is associated with that card. The card token is still saved.
U Issuer is not certified and/or has not provided Visa encryption keys This error indicates that the bank had a problem when doing the verification check. The card token is still saved.
X unknown This error indicates that no CVC data was available.

The response will be shaped as shown in the example below for the S cvvresponse.

Example Provider Verification Error
{
  "token": {...},
  "data": {...},
  "card": {...},
  "merchantId": "100100",
  "shouldUpdateCard": true,
  "kountResponse": {...},
  "cvcResults": {
    "error": true,
    "gatewayMessage": {
      "cvvresponse": "S",
      "message": "Merchant has indicated that CVV2/CVC2 is not present on card"
    }
  },
  "cardType": "visa"
}

Frequently Asked Questions

Error Codes

Q: I keep receiving the error: '442 Invalid one time use token'. Why is my token not working?

Once a one-time-use token has been used to submit an iframe it cannot be used to load another. You must request a new one-time-use token prior to submitting each iframe.

Q: Why am I getting a 403 error when I send a request for a one-time-use token? I know my credentials are correct.

To request a one-time-use token you must send a POST request. Sending a GET request will result in a 403 Forbidden error.

Q: I'm getting a 440 error when I try to specify which merchant to process with.

To troubleshoot this issue, follow the steps below:

  1. Make sure there are no typos when you enter the merchant ID.
  2. Check that you have access to this merchant. You can do this by logging into the Nexio Dashboard. If you do not see your desired merchant in the merchant selector dropdown, contact CMS Customer Service
  3. Make sure you are sending the variable merchantId as a string and not as an integer.

Q: Why do I keep receiving a 431 'Error from Kount' error while testing?

Please note that Kount verification will be performed by default when saving a card token or running a card transaction. To solve for unexpected 431 errors while testing your integration, try either of the following solutions:

  • Make sure your tests do not include any of the values shown here
  • Disable Kount verification by including the parameter"processingOptions": { "checkFraud": false } in the body of your request. (See the Enable Kount Verification tutorial for reference.)

Q: Why am I getting an error saying Authorization header requires 'Credential' parameter?

The following is a common AWS error: { "message": "Authorization header requires 'Credential' parameter. Authorization header requires 'Signature' parameter. Authorization header requires 'SignedHeaders' parameter. Authorization header requires existence of either a 'X-Amz-Date' or a 'Date' header. Authorization=Basic Og==" }

To debug it, please try the following:

  • Check that your HTTP method is correct. (For example, if the HTTP method is set to PUT when it should be POST you may receive this error)
  • Check that your request includes all required path and query parameters
  • Check your request for typos in the URL

If you still cannot resolve the error, please contact integration support.

Testing

Q: Can I test the iframes before integrating?

Yes! Once you have a Nexio account, you can use our Sandbox Tester.

Q: Are there any cards I can test with?

Yes. Test cards vary by implementation. Contact integration support for test cards specific to your needs.

Note: If you are testing with the Processing Option verifyCvc: true you must set the CVC equal to 111, otherwise you will receive a 437 Invalid CVC error.

Other

Q: All payments are coming back as pending, are these actually successful? Can I mark the order as paid and ship product?

The status of pending means the transaction is approved but the batch has not yet settled.

Settled transactions will show a status of authorized.

You can be assured that any pending/authorized transactions will settle without any issue.

Note: Batch close time is typically at 11pm PDT.

See the Transaction Status table for more information.

Q: Is there a joint auth & capture method?

Yes! The endpoint is called Run Card Transaction. When you send a request to this endpoint, by default the transaction will be authorized and captured.

If you wish to run an auth only transaction, send isAuthOnly: true in the body of your request.

Q: I see two custom field entries, what are those for?

The two custom fields provided are optional for partners to use for reconciliation and/or reporting purposes.

Q: Is it possible to run an auth only using the iframe and then capture through the API?

Yes, you can use the Nexio iframe in AuthOnly mode then capture the sale later if that is best for your workflow.

To run an auth only in the iframe, include isAuthOnly: true the body of your request when you retrieve a one-time-use token.

You can then capture using the Capture Transaction endpoint of the API or through Nexio dashboard.

Q: Can I host my localization/translation JSON file as a GitHub gist?

Yes, you can host your sandbox localization/translation file anywhere you choose.

To use a GitHub gist to host your translation file, follow the steps below:

  1. Create a GitHub gist containing your translation JSON file

    • Note: The gist must be public in order for Nexio to access it
  2. Copy the gist's URL. It will look like this:

    https://gist.github.com/your-github-username/8bdeaf3e8bc8c473d06b82ad56dd1c7d

  3. Append /raw to end of the URL from step 2:

    https://gist.github.com/your-github-username/8bdeaf3e8bc8c473d06b82ad56dd1c7d/raw

    • This allows Nexio to access the raw JSON file hosted in your gist repository
  4. Proceed to step 4 of the Iframe Label Translation tutorial

Note: These steps do not apply to the production environment. Production translation/localization files must be hosted by Nexio. See step 3 of the Iframe Label Translation tutorial for more information.

Glossary

Authorize

A card transaction is authorized when the issuing bank approves the transaction. Funds are not moved during authorization. A transaction may be run as an auth only and captured at a later time or authorized and captured simultaneously.

Auth Only

An auth only transaction is a transaction that is only authorized. It must be captured in order for funds to be moved.

Authorize and Capture

A transaction is processed once it has been authorized and captured. By default, all card transactions run through Nexio are authorized and captured simultaneously.

Capture

A transaction is captured when the funds are moved.

Card Transaction

A card transaction refers to either a credit or debit card transaction.

Merchant ID

Each merchant account will be assigned a merchant ID upon signing a contract with Nexio. (Also called MID.)

Processed

See Authorize and capture.

Reference Tables

Iframe Events

The following events may be emitted by various Nexio iframes.

For an example of how to create an event listener for one or more of these, see Event Listener Example below.

The 'Iframe' column lists the iframe(s) that may emit that event. If 'All' is listed that event applies to all of the following iframes:

Event Iframe Description Example Event Response
cardSaved Save Card, Retail Save Card The card token has successfully been saved
eCheckProcessed Run E-check Transaction The e-check has successfully been processed
eCheckSaved Save E-check The e-check token has successfully been saved
error All An error has occurred eventName: error
{
  "error": 481,
  "message": "User canceled 3DS"
}
fingerprintPosted All Device fingerprinting information eventName: fingerprintPosted
{
  "data": {
    "key": "31b0441b-6b5d-43c6-9d03-33b7b2ea1203",
    "kount": "31b0441b6b5d43c69d0333b7b2ea1203"
  }
}
formValidations All Indicates form validation success or error per form field and for the form overall.

You can check for true for one or more individual form fields or check for true for only isFormValid to know that all fields have been validated
eventName:formValidations
{
  billToAddressOneValid: true
  billToAddressTwoValid: true
  billToCityValid: true
  billToCountryValid: true
  billToPostalValid: true
  billToStateValid: true
  cardExpirationValid: true
  cardHolderNameValid: true
  cardNumberValid: false
  cardSecurityCodeValid: false
  cardTypeValid: false
  isFormValid: false
}
loaded All The iframe has finished loading eventName: loaded
{}
initiate APMs The user clicks 'confirm' to be redirected to the APM eventName: initiate
{
  message: ‘user initiated 3ds’
}
processed Run Card Transaction The credit card transaction has been processed
submit All The form has been submitted eventName: submit
{
  "cardHolderName": "Default Test",
  "customer": {
    "billToCity": "Testerville",
    "billToState": "UT",
    "billToCountry": "US",
    "billToAddressTwo": "Suite 123",
    "billToAddressOne": "123 Test St",
    "billToPostal": "12345"
  }
}
success Retail Run Card Transaction The credit card transaction has been processed

Event Listener Example

The following is an example of how to create an event listener.

This listener is checking that the iframe has finished loading and that the entire form has been validated. You could use something like this to make your submit button inactive so that users cannot click on it until the form errors are corrected.

window.addEventListener('message', function messageListener(event) {
  if (event.origin === iframeUrl) {
    const eventData = event.data?.data;
	const eventType = event.data?.event;

	if (eventType === ‘loaded’) {
	  // iframe successfully loaded.
	}

	if (eventType === ‘formValidations’) {
	  const jsonData = JSON.parse(eventData);
	  if (jsonData.isFormValid) {
	    // form is ready to submit.
			}
      }
	  // switch on event.data properties
      // (e.g. loaded, formValidations, error)
    }
});

Constant Values

When querying transaction data, the following numerical values are returned which represent the corresponding constant value.

Transaction Status (transactionStatus)

The tables below describe the transaction statuses for card and e-check transactions.

Please note that:

Card Transaction Status

Status Description Nexio Dashboard Status Transaction Service transactionStatus Payment Service transactionStatus
Auth Only Pending The payment is asynchronous and may receive a webhook notice with a status of authOnly in the future AUTHONLYPENDING 3 authOnlyPending
Authorized Pending The payment is asynchronous. The payment is pending and may receive a webhook notice with status of settled in the future AUTHORIZEDPENDING 9 authorizedPending
Authorized The transaction has been successfully authorized and is pending settlement AUTHORIZED 10 pending
Auth Only The payment is Auth Only and capturing is required to receive the funds. The transaction can also be voided AUTHONLY 11 authOnly
Declined The transaction was declined DECLINED 30 declined
Fraud Reject The transaction was declined by Kount prior to being submitted to the gateway FRAUDREJECT 32 fraudReject
Settled The transaction is settled. It can be refunded but not voided SETTLED 20 settled
Void Pending The payment is asynchronous and may receive a webhook notice with a status of voided in the future VOIDPENDING 39 voidPending
Voided The payment has been voided VOIDED 40 voided
Error An error has occurred ERROR 50 error

E-check Transaction Status

Status Description Nexio Dashboard Status Transaction Service transactionStatus Payment Service transactionStatus
Pending The transaction is pending PENDING 12 pending
Settled The transaction is settled SETTLED 20 settled
Submitted The payment was submitted to the bank for authorization SUBMITTED 13 submitted
Rejected The transaction was rejected REJECTED 33 rejected

Transaction Type (transactionType)

Name Value
Sale 10
Refund 20

Card Type (cardType)

Name Value
Visa 10
MasterCard 20
Discover 30
American Express 40
Unknown null

Process Method (processMethod)

Name Value
Card 10
Card Present 11
Card Not Present 12
APM (Alternative Payment Method) 20
E-check 40
Credit 50
Cash 60

Currency (currency)

Name Value
Australian Dollar 036
Canadian Dollar 124
Yuan 156
Yen 392
Won 410
Mexican Peso 484
Pound Sterling 826
US Dollar 840
Euro 978

ACH

For e-check transactions, the following values are used.

Standard Entry Class code (secCode)

The Standard Entry Class (SEC) code (secCode) is for e-check transactions. These values can be sent in the following requests as the data.secCode parameter:

The following table displays the commonly used codes. Contact your e-check processor for the codes that you can use for your account.

secCode Description
ARC Accounts Receivable Entry
BOC Back Office Conversion
CCD Corporate Credit or Debit
CIE Customer-Initiated Entry
CTX Corporate Trade Exchange
IAT International ACH Transaction
POP Point-of-Purchase Entry
POS Point-of-Sale
PPD Prearranged Payment and Deposit
RCK Re-presented Check Entry
TEL Telephone-Initiated Entry
WEB Internet-Initiated/Mobile Entry
XCK Destroyed Check Entry

Payouts

When querying payouts data, the following numerical values are returned which represent the corresponding constant value.

Payout Status (payoutStatus)

The following table displays the commonly used codes for the payout status.

payoutStatus Status Name Description
10 pendingProviderAction The payout request is being processed by the provider. No further action is required at this time.
11 pendingMerchantAction The payout request is pending until the merchant takes action.
12 pendingRecipientAction The payout request is pending until the recipient takes action.
20 completed The payout request has been completed. Funds are available for the recipient. No further action is required.
30 expired The payout request has expired. The payout is no longer available for the recipient.
40 canceled The payout request has been canceled. The payout is no longer available for the recipient.
50 returned The payout request has failed, most commonly due to rejection by the recipient’s bank. The payout is no longer available for the recipient.
90 failed The payout request has failed. For more details about what failed, see the providerResponse parameter in the API response.

Transfer Status (transferStatus)

The following table displays the commonly used codes for the transfer status.

transferStatus Status Name Description
10 available Payout money has been transferred. No further action is required at this time.
20 completed The recipient has claimed available funds. Note: This status is not available for all payout providers.
90 failed An error occurred during the transfer.

Test Cards

Test transactions can be submitted using the following card numbers:

Issuer Number
Visa 4111111111111111
Mastercard 5431111111111111
Discover 6011601160116611
American Express 341111111111111

Release Notes

2020

June 9, 2020

  • Update to the token object in the response of the Save Card Token API endpoint. The token object will always include the following keys. (Previously, some keys were not included in the response unless provided in the request):
    • firstSix
    • lastFour
    • token
    • success
    • sesssionId
    • customerReferenceNumber

April 22, 2020

  • New Processing Option available: shouldUseFingerprint (default: true). Allows you to enable or disable the use of the saved fingerprint while processing a transaction. Check out the processingOptions object in the Parameters table of the Run Card Transaction API reference section for a full description.

March 25, 2020

March 24, 2020

hidePhone Example
uiOptions: {
  hideBilling: {
    hidePhone: true
  }
}

See the Parameters table in the One-time-use Token endpoint reference for more information.

January 22, 2020

  • New webhook event types available:
    • ACCOUNT_UPDATER_CONTACT_CARDHOLDER
    • ACCOUNT_UPDATER_ACCOUNT_CLOSED

2019

November 27, 2019

September 11, 2019

  • All transaction endpoints now accepting billToPhone and shipToPhone parameters. This information is especially helpful for Kount verification.

  • All e-check transactions now accepting secCode.

  • New transaction status: fraudReject.

September 7, 2019

  • 3D Secure now available for switch transactions run through the API.

July 10, 2019

  • Now accepting PayPal as an [alternative payment method](#alternative-payment-methods.

May 29, 2019

  • Updated webhook request body message when a TRANSACTION_CAPTURED event type has resulted in an error or decline.
    • data.gatewayProcessingError is now data.error

May 23, 2019

  • New options have been added to allow greater control over the hideBilling UI Option for iframes.
HideBilling Object
{
    "hidePostal": true,
    "hideCountry": true,
    "hideAddressOne": true,
    "hideAddressTwo": true,
    "hideCity": true,
    "hideState": true
}
  • Note: hideBilling will continue to accept true and false if you wish to hide all billing fields. (Default continues to be false)"

May 22, 2019

  • Webhook events TRANSACTION_AUTHORIZED and TRANSACTION_CAPTURED are now fired when a card transaction is processed.
  • The retail iframe can now be configured for webhooks.
  • When card information is manually provided to run a transaction for a card that has already been saved:
    • If the saved expiration date is better than the provided expiration date:
      • The saved card will be used and the provided card information date will be disregarded.
    • If the new expiration date is better than the saved expiration date:
      • The provided card information will be used.
      • A new card token will be created and returned in the response.
      • If applicable, webhooks will be fired.
      • The old card token will still be valid.

May 9, 2019

  • You may now choose to prevent a card token from being saved when a transaction is run using the Run Card Transaction iframe.
    • To do so, set processingOptions.saveCardToken to false in your request for a One-time-use Token.
    • (Note: If you do not provide this option a card token will be saved by default.)
  • Option to return an HTML response when an iframe returns an error. (By default error response content-type will be application/json.)
    • To use this option, send shouldReturnHtml=true as a query parameter to your GET request.

May 8, 2019

  • Recently added features:
    • Ability to configure Webhooks in order to retrieve real-time data regarding events that occur in your Payment Service iframes.
    • Retail iframe added.
    • New Simple Login endpoint: allowing trusted users to proceed directly to the retail/MOTO Iframe without the necessity of entering a Nexio username and password.
    • Option to include Lodging data when making a payment.

January 28, 2019

  • The following deprecated response objects have now been removed from the Run Credit Card Payment endpoint:
    • foreignProcessingCurrency
    • cardDetails
    • customFields
    • customerInfo
    • cart
  • The following deprecated response object has now been removed from the Save Card and Run Credit Card Payment endpoints:
    • kountResponse.kountData

2018

December 12, 2018

  • Additional fields being passed along to Nexio's fraud tools:
    • Customer created at date (data.customer.createdAtDate)
    • Shipping Address (data.customer.shipTo)
    • This information is useful for customizing your fraud rules

November 7, 2018

  • New processing option allows users to choose which merchant to use to process a transaction.

October 10, 2018

  • AVS results (avsResults) returned in response object.
  • EnsureBill account updater now available.
  • Nexio Dashboard:
    • Merchant ID selector filtering: you may now filter merchants by name, merchant ID, and currency code.

October 3, 2018

  • Address Verification Service (AVS) now enabled.
  • Nexio Dashboard:
    • Chargeback widget added.
    • Currency selector changes all charts and widgets.
    • Column filtering on tables can now search for partial amounts.
    • Merchant ID selector widens to fit merchant name.
    • Now importing Customer ID from Gateway responses.
    • Chargeback page now shows Cardholder Name when linked to a transaction.

September 26, 2018

  • Additional Authorize.Net features now available in Nexio Dashboard: ability to void transactions, approve or decline auth only transactions, and refund settled transactions.
  • Processor Management: Clients with multiple merchants can now choose which merchants to process with, or to balance their processing equally across all merchants. This feature works by checking each merchant's processing volume at the time of the transaction and then running the transaction against whichever merchant has less volume.
  • Nexio Dashboard:
    • Merchant ID selector now accommodates long merchant names.
    • Merchant ID selector now lists merchant names alphabetically.
    • New widgets: Transactions, Salesf, Approvals & Declines.

September 12, 2018

  • Gateway Failover: Merchants set up with more than one gateway are now able to choose a backup gateway in case of primary gateway failure
  • Option to limit country list in the Make Payment and Save Card iframes
  • Option to choose default country in the Make Payment and Save Card iframes
  • Nexio Dashboard:
    • New Reserve Tab for merchants with a reserve account

September 5, 2018

  • Integration with Authorize.Net
  • Refund disabled on transactions with pending chargeback

August 22, 2018

  • Added Order ID to Refunds in the Transactions Tab of Nexio
  • Added the ability to delete tokens in the API

July 16, 2018

  • Fixed bug where View Only users were able to run transactions. This functionality is now limited to Admin and Standard users

Supported Browsers

In order to provide the best user experience, we test our payment iframes on the following browsers:

  • Chrome
  • Edge
  • Firefox
  • Safari 12
  • Internet Explorer 11

If you are having a browser-related issue, please contact integration support.

Filtering Results and Including Additional Parameters for an API Request

Some Nexio API endpoints allow the use of query parameters as a way to filter (or limit) the results returned from the request. You can also use query parameters to request that those specific parameters be included in the response.

The following APIs allow filtering and additional parameters with certain endpoints:

Using Query Parameters

When searching for report data or payouts data, you may request additional parameters to be returned. This is useful for parameters that are not returned by default. You can also filter the response to only include records that match a specific value for one or more parameters.

You may request additional parameters or filter the results for any of the following API endpoints:

Request Additional Parameters

The response for the reporting APIs (for transactions, chargebacks, and statements and adjustments) and payouts APIs (for view recipients and view payouts) returns a default set of parameters. For example, transactionDate and cardType in the reporting API or recipientIdNumbers in the payouts API. For a full list of parameters, see the specific endpoint in the Reporting API Reference or Payouts API Reference.

You can also specify in the request that the system returns one or more additional parameters in the response. To do this, you only need to include, in the GET request, the name of the query parameter followed by a dot. When you use a parameter from one of these as a filter, the entire object automatically gets included in the response. Combine multiple additional parameters by including an ampersand (&) between each one.

For example, the following Reporting request returns only the default parameters for up to 20 transactions:

Transaction List with Filter
curl -X GET https://api.nexiopaysandbox.com/transaction/v3?limit=20 \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic <Your Basic Auth>'

To request an additional parameter, include an empty query parameter in your GET request followed by a dot.

For example, the following returns a standard list of up to 20 transactions along with the customer object for each one:

Transaction List with Filter and Customer Object
curl -X GET https://api.nexiopaysandbox.com/transaction/v3?limit=20&customer. \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic <Your Basic Auth>'

Now, the same request for the same 20 transactions with the default parameters, but also requesting that the response include additional information about Kount, our payment plugins, customer, processor, and gateway:

Transaction List with Filter and Additional Parameters
curl -X GET https://api.nexiopaysandbox.com/transaction/v3?limit=20&kount.&plugin.&customer.&processor.&gateway. \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic <Your Basic Auth>'

For the list of additional parameters, see the Transactions Filtering and Additional Parameters and Payouts Filtering and Additional Parameters tables.

Filter Using Query Parameters

Path parameters that you include in a regular endpoint request already act like a filter for the response. But, for the Reporting endpoints of Transactions, Chargebacks, and Statements and Adjustments and the Payouts endpoints of View Recipients and View Payouts, there is an additional method for creating a filter, using query parameters.

For these endpoints in the Reporting or Payouts API, you can also filter query parameters by specifying the desired parameter to filter on, an equals ( = ) sign, and the value to use for the filter. For parameters in an object, use the object name, a dot, and the parameter name before the equals. You can combine multiple filters by including an ampersand (&) between each one.

Use this feature, along with requesting additional parameters, to limit the scope of the response and to get back the specific parameters that you want.

For example, the following request returns all transactions (made in the Nexio Payment API) for the specified zip code where the gateway status is 'Approved' and where the response includes all the default parameters plus the content for the customer and gateway objects.

Transaction List with Additional Filters
curl -X GET https://api.nexiopaysandbox.com/transaction/v3?customer.postalCode=12345&gateway.message=Approved \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic <Your Basic Auth>'

As another example, the following searches for a transaction made in the Nexio Payment API with the to-be-specified payment ID, and also includes its Kount information in the results.

Transaction List with Additional Filters
curl -X GET https://api.nexiopaysandbox.com/transaction/v3?kount.&plugin.originalId={payment_ID} \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic <Your Basic Auth>'

Reference Tables

The following tables show all the fields that you can use for filtering with the additional query parameters. (The default fields can also be used for filtering. See the API reference documentation for each endpoint for details).

Transactions Filtering and Additional Parameters

For information about each field, see the specific endpoint in the Reporting API Reference.

Name Additional Parameter Filtering Field
Customer customer. id
firstName
lastName
postalCode
phone
email
company
customerRef
transactionId
Kount kount. id
status
rules
refNumber
merc
score
ruleCount
warningCount
counterCount
wasDeviceFingerprinted
mode
velo
vmax
transactionId
Bank Transfer bankTransfer. id
account
routing
checkNumber
transactionId
Plugin plugin. id
originalId
invoice
orderNumber
description
userId
pluginType
paymentOptionTag
transactionId
Foreign Processing Currency foreignProcessingCurrency. id
amount
currencyId
transactionId
Gateway gateway. id
merchantId
batchRef
refNumber
additionalRefNumber
trackingCode
gatewayType
message
transactionId
Processor processor. id
transactionRef
batchRef
originalId
processorType
transactionId
Customer Addresses customerAddresses. id
billingAddressOne
billingAddressTwo
billingCity
billingState
billingPostalCode
billingCountry
billingPhone
shippingAddressOne
shippingAddressTwo
shippingCity
shippingState
shippingPostalCode
shippingCountry
shippingPhone
transactionId
Transaction Details transactionDetails. id
description
clientIp
userName
shoppingCart
customFields
retryCount
paymentType
paymentToken
transactionId
Subscription subscription. id
remainingBalance
initialBalance
interval
intervalCount
subscriptionRef
accountId
scheduleType
transactionId

Payouts Filtering and Additional Parameters

For information about each field, see the specific endpoint in the Payouts API Reference.

Name Additional Parameter Filtering Field
Recipient ID Numbers recipientIdNumbers. governmentId
passportId
driversLicenseId
employerIId

Find a Transaction

To query for a transaction created through the Nexio Payment iframe or API, follow the steps below:

  1. Run a payment using the Run Card Transaction iframe or the Nexio Payment API.
 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"
}
  1. Save the id from the response. This is the Payment ID.

  2. Use the Payment ID to query the transaction service.

Example Request
curl -X GET https://api.nexiopaysandbox.com/transaction/v3?plugin.originalId=eyJuYW1lIjoidXNhZXBheSIsInJlZk51bWJlciI6IjMxMDA5MDc4MTkiLCJtZXJjaGFudElkIjoiMTAwMDM5IiwicmFuZG9tIjoiMzEwMDkwNzgxOSIsImN1cnJlbmN5IjoiVVNEIn0 \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic <Your Basic Auth>'

You may also request to have additional query parameters returned or filter the request based on fields of the query parameters.

Note: Transactions from the Payment Service are added to the Transaction Service every minute and not in real time. Attempting to query the Transaction Service sooner than one minute after running a transaction may return no results.

Webhooks

Configure webhooks to retrieve real-time information about payment events. When webhooks are set up, Nexio will send a POST request with event information to the specified endpoint. You may also choose to receive a signature header—allowing you to verify the webhook's authenticity.

Configure Webhooks

To configure webhooks for a merchant, follow the steps below:

  1. Check Your Merchant's Role (Optional)

    In order to configure webhooks for a merchant you must have administrator access to that merchant account. If you know that your user has sufficient rights, skip to step 2.

    To check your account's access rights, send a request to the Who Am I endpoint in the User Management Service. In the example below, the user has authorization to configure webhooks for merchant ID 100039 only.

Example Access Rights
{
    "accessRights": {
        "merchantIds": {
            "100039": "A", // Admin access
            "100040": "W", // Write access
            "100068": "R" // Read-only access
        },
        "role": "A"
    }
}
  1. Determine the Event Types

    See our Event Types table below and note the event types you would like to trigger a webhook.

  2. Post Configuration Information to Nexio

    Send a POST request to the Configure Merchant endpoint. Include the merchant ID, the event type(s) you selected in step 2, and the endpoint to which the data will be sent.

    The example below will configure a webhook to be sent to https://your-company-webhook-url-here.com when a transaction is authorized or refunded for merchant ID 100039.

Example Request
curl -X POST https://api.nexiopaysandbox.com/webhook/v3/config \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic <Your Basic Auth>'
  -d '{
  "merchantId": "100039",
  "webhooks": {
    "TRANSACTION_AUTHORIZED": {
      "url": "https://your-company-webhook-url-here.com"
    },
    "TRANSACTION_REFUNDED": {
      "url": "https://your-company-webhook-url-here.com"
    }
  }
}'

  1. Check the Webhook's Configuration (Optional)

    To check the webhook configuration you completed in step 4, send a GET request to the Merchant Configuration endpoint.

Example Request
curl -X GET https://api.nexiopaysandbox.com/webhook/v3/config/100039 \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic <Your Basic Auth>'

 Example 200 Response 
{
  "dateCreated": "2019-03-22T16:58:51.957Z",
  "webhooks": {
    "TRANSACTION_AUTHORIZED": {
      "url": "https://your-company-webhook-url-here.com"
    },
    "TRANSACTION_CAPTURED": {
      "url": "https://your-company-webhook-url-here.com"
    }
  },
  "merchantName": "My Company",
  "dateLastModified": "2019-04-04T18:54:58.011Z",
  "merchantId": "100039"
}
  1. Configure the Merchant Secret (Optional)

    For additional security you may set up a merchant secret. When configured, you will be provided with a merchant secret and each webhook will include a header containing a signature. These can be used to verify that all data received is authentic.

    To configure the merchant secret, send a POST request to the Create Merchant Secret endpoint. Include the merchant ID to be configured in the body of your request.

Example Request
curl -X POST https://api.nexiopaysandbox.com/webhook/v3/secret \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic <Your Basic Auth>'
  -d '{
  "merchantId": "100039"
}'

A successful request will return a response object containing the merchant secret. Store the secret in a secure location. You will use it later for signature verification.

Example Merchant Secret
{
  "secret": "446946d5-bdd9-48c7-9504-0459d19c08e5"
}

Once you have configured the merchant secret, each webhook will include a signature header.

Event Types

Below are the possible values for webhook event types.

Event Type Description Example Webhook Body
ACCOUNT_UPDATER_ACCOUNT_CLOSED Webhook will be sent when the account associated with the card has been closed Account Closed Example
ACCOUNT_UPDATER_CONTACT_CARDHOLDER Webhook will be sent when the card brand advises you to contact the cardholder Contact Cardholder Example
CARD_DATA_UPDATED Webhook will be sent when card data has been updated Card Updated Example
CARD_SAVED Webhook will be sent when card data has been saved Card Saved Example
ECHECK_SAVED Webhook will be sent when e-check data has been saved E-check Saved Example
PAYOUT Webhook will be sent when a recipient has accepted a payout through the Interchecks payout provider. For information about payout events with other payout providers, contact Integrations Support. Payout Event Example
SUBSCRIPTION_DETAILS Webhook will be sent when a subscription has been processed Subscription Example
TRANSACTION_AUTHORIZED Webhook will be sent when a transaction is authorized Transaction Event Example
TRANSACTION_CAPTURED Webhook will be sent when a transaction is captured Transaction Event Example
TRANSACTION_PENDING Webhook will be sent when a transaction is marked as pending Transaction Event Example
TRANSACTION_REFUNDED Webhook will be sent when a transaction is refunded Transaction Event Example
TRANSACTION_SETTLED Webhook will be sent when a transaction is settled Transaction Event Example
TRANSACTION_VOIDED Webhook will be sent when a transaction is voided Transaction Event Example

Receive Webhooks

Once you have configured webhooks, listen for Nexio's POST requests on the URL you provided in step 3 of the Configure Webhooks tutorial. The body of the request will include the eventType and a data object, with information about the event. See the webhook body examples for more information.

If you configured the merchant secret (step 5 of the Configure Webhooks tutorial), the request will include a header, which you will use to to verify the merchant signature.

See the tutorial below for instructions.

Verify the Signature

  1. Listen for Nexio's POST Request

  2. Extract the Signature and Timestamp from the Header

Example Signature Header
Nexio-signature: t=1554146049,v1=f66f6c47e7288e4922629ffe87819678b793944c60668d8695804e4a2b9f90d1

a. Split the header string at the , character

b. Split each of the two strings at the = characters

c. Save the data following the t= as a variable

Example
var timestamp = 1554146049;

d. Save the data following the s= as a variable

Example
var signature = 'f66f6c47e7288e4922629ffe87819678b793944c60668d8695804e4a2b9f90d1';
  1. Save the Request Body

    Save the JSON request body as a string.

Example
var body = '
{
    "eventType": "TRANSACTION_AUTHORIZED",
    "data": {
        "id": "2eruYW1lIjoidXNhZXBheSIZYXABCiOiIxMDAwMzkiLCJyZWZOdW1iZXIiOiZYXABCcmFuZG9tIjowLCJjdXJyZW5jeSI6InVzZCJ9",
        "shouldUpdateCard": true,
        "merchantId": "100039",
        "transactionDate": "2019-12-23T20:50:23.060Z",
        "authCode": "458399",
        "transactionStatus": "pending",
        "amount": 1.15,
        "transactionType": "sale",
        "currency": "USD",
        "gatewayResponse": {...},
        "data": {
            "amount": 1.15,
            "currency": "USD",
            "settlementCurrency": "USD",
            "customFields": {...},
            "customer": {...},
            "cart": {...},
            "lodging": {...}
        },
        "card": {...},
        "kountResponse": {...},
        "token": {...}
    }
}';
  1. Create the Payload

    Concatenate timestamp and body with a . character in between and save it as a variable.

Example
var payload = ${timestamp}.${body};
  1. Re-create the Expected Signature

    Create an HMAC using the SHA256 hash function. Use the merchant secret as the key and the payload as the message. This is the expected signature.

    Note: If you did not save the secret when you configured the webhook (step 5), you can retrieve it again by sending a GET request to Nexio's merchant secret endpoint.

  2. Compare the Signatures

    Compare the expected signature from step 4 with the signature you received from Nexio. (The signature from step 1d.)

Steps 1-5 Node.js Example
import crypto from 'crypto';

function verifyHMACSignature(payload, signature, sharedSecret) {
    //Create an HMAC using the SHA256 hash function
    const hmac = crypto.createHmac('sha256', sharedSecret);
    hmac.update(payload);

    const mySig = hmac.digest().toString('hex');

    //Compare the expected signature with the signature you received
    return mySig.length === signature.length
        && crypto.timingSafeEqual(Buffer.from(mySig, 'hex'), Buffer.from(signature, 'hex'));
}

function verifyNexioSignature(body, signatureHeader, sharedSecret) {
    //Split the Nexio-Signature on the comma to get the timestamp field and the signature field
    const [timeStampField, signatureField] = signatureHeader.split(',');

    //Split each of the two strings on the equals signs and save them as variables
    const timestamp = timeStampField.split('=')[1];
    const signature = signatureField.split('=')[1];

    //Recreate the payload that was signed by Nexio
    const payload = `${timestamp}.${body}`;

    return verifyHMACSignature(payload, signature, sharedSecret);
}

Body Examples

Every webhook will include a body with the following keys:

  • eventType: (string) The event that triggered the webhook. See the Event Type Table for a full list of possible values
  • data: (object) Information about the event

Transaction Events

The data object will be shaped the same for any transaction event. To see full examples of the values contained in the data object, see the example 200 response in the Run Card Transaction reference section.

Transaction Event Example Body
{
    "eventType": "TRANSACTION_CAPTURED",
    "data": {
        "id": "2eruYW1lIjoidXNhZXBheSIZYXABCiOiIxMDAwMzkiLCJyZWZOdW1iZXIiOiZYXABCcmFuZG9tIjowLCJjdXJyZW5jeSI6InVzZCJ9",
        "shouldUpdateCard": true,
        "merchantId": "100039",
        "transactionDate": "2019-12-23T20:50:23.060Z",
        "authCode": "458399",
        "transactionStatus": "pending",
        "amount": 1.15,
        "transactionType": "sale",
        "currency": "USD",
        "gatewayResponse": {...},
        "data": {
            "amount": 1.15,
            "currency": "USD",
            "settlementCurrency": "USD",
            "customFields": {...},
            "customer": {...},
            "cart": {...},
            "lodging": {...}
        },
        "card": {...},
        "kountResponse": {...},
        "token": {...}
    }
}

Card Events

Account Closed
Account Closed Example Body
{
  "eventType": "ACCOUNT_UPDATER_ACCOUNT_CLOSED",
  "data": {
    "updateCode": "203",
    "reportDate": "2021-09-09T16:44:41.000Z",
    "merchantId": "101039",
    "originalCard": {
      "lastFour": "2223",
      "firstSix": "400060"
    },
    "tokenex": {
      "lastFour": "2223",
      "token": "192b8c0f-ef3a-4e13-8465-2b41971db046",
      "firstSix": "400060"
    },
    "card": {
      "expirationYear": "02",
      "expirationMonth": "02"
    },
    "cardNumber": "400060******2223",
    "updateType": 30
  }
}
Card Updated

To see full examples of the values contained in the data object, see the example 200 response in the Save Card Token reference section.

The following example shows that the expiration date has been updated.

Card Saved Example 1 Body
{
  "eventType": "CARD_DATA_UPDATED",
  "data": {
    "updateCode": "201",
    "reportDate": "2021-09-09T16:12:32.000Z",
    "merchantId": "101039",
    "originalCard": {
      "lastFour": "2222",
      "firstSix": "400020"
    },
    "tokenex": {
      "lastFour": "2222",
      "token": "ac719225-cb55-4605-a673-8f0ccb822c4c",
      "firstSix": "400020"
    },
    "card": {
      "expirationYear": "2033",
      "expirationMonth": "02"
    },
    "cardNumber": "400020******2222",
    "updateType": 20
    }
}

The following example shows that both the expiration date and the card number have been updated.

Card Saved Example 2 Body
{
  "eventType": "CARD_DATA_UPDATED",
  "data": {
    "updateCode": "202",
    "reportDate": "2021-09-09T16:44:41.000Z",
    "merchantId": "101039",
    "originalCard": {
      "lastFour": "2224",
      "firstSix": "400010"
    },
    "tokenex": {
      "lastFour": "2229",
      "token": "7f657119-a7e6-47cb-a0b5-153db253512a",
      "firstSix": "400010"
    },
    "card": {
      "expirationYear": "2033",
      "expirationMonth": "02"
    },
    "cardNumber": "400010******2229",
    "updateType": 10
  }
}
Card Saved

To see full examples of the values contained in the data object, see the example 200 response in the Save Card Token reference section.

Card Saved Example Body
{
  "eventType": "CARD_SAVED",
  "data": {
    "data": {
      "customer": {...}
    },
    "merchantId": "101040",
    "shouldUpdateCard": true,
    "cardType": "masterCard",
    "kountResponse": {...},
    "card": {
      "expirationYear": "2021",
      "cardType": "masterCard",
      "expirationMonth": "10",
      "cardHolderName": "Jane Doe"
    },
    "token": {
      "lastFour": "5100",
      "cardType": "masterCard",
      "firstSix": "510510",
      "token": "b01bfaee-31b2-4222-8d89-24d1a42fd50e"
    }
  }
}
Contact Cardholder
Contact Cardholder Example Body
{
  "eventType": "ACCOUNT_UPDATER_CONTACT_CARDHOLDER",
  "data": {
    "updateCode": "204",
    "reportDate": "2021-09-09T16:46:41.000Z",
    "merchantId": "101039",
    "originalCard": {
      "lastFour": "2221",
      "firstSix": "400070"
    },
    "tokenex": {
      "lastFour": "2221",
      "token": "269c3057-4f7d-47a2-80cd-3196f803631e",
      "firstSix": "400070"
    },
    "card": {
      "expirationYear": "02",
      "expirationMonth": "02"
    },
    "cardNumber": "400070******2221",
    "updateType": 40
  }
}

E-check Events

E-check Saved

To see full examples of the values contained in the data object, see the example 200 response in the Save E-check Token reference section.

E-check Saved Example Body
{
  "eventType": "ECHECK_SAVED",
  "data": {
    "data": {
      "key": "871446789.5292712865664733",
      "merchantId": "100039",
      "data": {
        "customer": {...},
        "customFields": {...}
      },
      "tokenex": {
        "success": true,
        "error": null,
        "token": "871446789",
        "sesssionID": "fca21ef9067d4f009e58e302dbc115a4",
        "customerRefNumber": "b210bad6-a013-4e91-b5bf-0",
        "characterCount": 9,
        "lastFour": "6789"
      },
      "dateCreated": "2019-12-30T18:06:15.188Z",
      "dateLastModified": "2019-12-30T18:06:15.193Z",
      "bank": {
        "accountHolderName": "Todd Smitherton",
        "routingNumber": "123456789"
      }
    }
  }
}

Payout Event

After configuring webhooks for payouts, a webhook will be sent every time a recipient accepts your payout to them through the Interchecks payout provider. For information about payout events with other payout providers, contact Integrations Support.

After the recipient accepts the payout, the data.transferStatus changes to 20.

For more information about the parameters returned in the data object, see the specific Response parameters in the View a payout or View payouts endpoint.

Note: For payouts, the body of the webhook contains only a small subset of the possible parameters for a payout. To view the values for all the available parameters, use the View a payout or View payouts endpoint.

Payout Example Body
{
    "eventType": "PAYOUT",
    "data": {
        "payoutStatus": 20,
        "eventType": "PAYOUT",
        "transferStatus": 20,
        "payoutId": 2437652
    }
}

Subscription Event

Once configured, webhooks will be sent every time a recurring payment is run through the subscription service. You will also receive webhooks for all transaction events that have previously been configured.

To see full examples of the values contained in the data.paymentResult object, see the example 200 response in the Run Card Transaction or Run E-check Transaction reference section.

The payment object will contain the values provided when the subscription was created.

Subscription Example Body
{
  "eventType": "SUBSCRIPTION_DETAILS",
  "data": {
    "dateCreated": "2020-09-21T17:27:46.836Z",
    "accountId": "6862a4dc-490e-4eec-9a23-a3fec25979b6",
    "customerRef": "metest2",
    "paymentResult": {
      "id": "eyJuYW1lIjoidXNhZXBheSIsIm1lcmNoYW50SWQiOiIxMDEwMzkiLCJyZWZOdW1iZXIiOiIzMTEzMjc5MDI0IiwicmFuZG9tIjowLCJjdXJyZW5jeSI6InVzZCJ9",
      "merchantId": "101039",
      "transactionDate": "2020-09-21T17:31:49.680Z",
      "authCode": "026252",
      "transactionStatus": "pending",
      "amount": 10,
      "transactionType": "sale",
      "currency": "USD",
      "gatewayResponse": {...},
      "data": {
        "amount": 10,
        "currency": "USD",
        "settlementCurrency": "USD",
        "customer": {...},
        "cart": {...}
      },
      "card": {...},
      "kountResponse": {...},
      "token": {...}
    },
    "dateLastModified": "2020-09-21T17:32:11.016Z",
    "userName": "kkacprzynski@cmsonline.com",
    "dateNextRun": "2020-10-21",
    "active": true,
    "schedule": {
      "duration": 5,
      "dateInitialBillingEnd": "2020-09-21",
      "initialBillingAmount": null,
      "balance": 30,
      "scheduleType": 20,
      "intervalCount": 1,
      "initialBalance": 50,
      "interval": "month"
    },
    "lastPaymentStatus": "success",
    "dateLastRun": "2020-09-21T17:31:28.699Z",
    "payment": {
      "data": {
        "amount": 10,
        "currency": "USD",
        "cart": {...},
        "customer": {...}
      },
      "tokenex": {...},
      "isProcessedFromServer": true,
      "clientIp": "10.0.0.1"
    },
    "id": "cdd9d4b2-bf86-445b-8b54-59861a9ad3ae",
    "accessRights": {
      "merchantIds": {
        "101039": "A"
      }
    }
  }
}

Full API Reference

Payments API Reference

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 '{
  "card": {
    "businessNumber": "1234567890",
    "cardHolderName": "John H Doe",
    "classification": "business",
    "expirationMonth": "12",
    "expirationYear": "20",
    "password": "12"
  },
  "data": {
    "allowedCardTypes": [
      "visa"
    ],
    "currency": "USD",
    "customer": {
      "billToAddressOne": "2147 West Silverlake Drive",
      "billToAddressTwo": "Apt 42",
      "billToCity": "Scranton",
      "billToCountry": "US",
      "billToPhone": "1555555555",
      "billToPostal": "18503",
      "billToState": "PA",
      "birthDate": "1990-12-05",
      "createdAtDate": "2005-03-01",
      "customerRef": "RP006",
      "email": "jdoe@yourwebsite.com",
      "firstName": "John",
      "invoice": "IN0001",
      "lastName": "Doe",
      "orderDate": "2021-08-26",
      "orderNumber": "210058A",
      "phone": "1555555555",
      "shipToAddressOne": "1725 Slough Avenue",
      "shipToAddressTwo": "Suite 200",
      "shipToCity": "Scranton",
      "shipToCountry": "US",
      "shipToPhone": "1555555555",
      "shipToPostal": "18505",
      "shipToState": "PA"
    },
    "customFields": {
      "exampleKey": "Example string"
    }
  },
  "processingOptions": {
    "checkFraud": false,
    "verboseResponse": true,
    "verifyAvs": 2,
    "verifyCvc": false,
    "webhookFailUrl": "https://your-company-webhook-fail-url-here.com",
    "webhookUrl": "https://your-company-webhook-url-here.com"
  },
  "shouldUpdateCard": true,
  "uiOptions": {
    "css": "https://tester.nexiopaysandbox.com/example1.css",
    "customTextUrl": "",
    "displaySubmitButton": true,
    "hideBilling": {
      "hideAddressOne": false,
      "hideAddressTwo": false,
      "hideCity": false,
      "hideCountry": false,
      "hidePostal": false,
      "hidePhone": false,
      "hideState": false
    },
    "hideCvc": true,
    "limitCountriesTo": [
      "US"
    ],
    "requireCvc": false
  }
}'

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 '{
  "bank": {
    "accountHolderName": "John Doe",
    "routingNumber": "231375151"
  },
  "data": {
    "customer": {
      "billToAddressOne": "2147 West Silverlake Drive",
      "billToAddressTwo": "Apt 42",
      "billToCity": "Scranton",
      "billToCountry": "US",
      "billToPhone": "1555555555",
      "billToPostal": "18503",
      "billToState": "PA",
      "birthDate": "1990-12-05",
      "createdAtDate": "2005-03-01",
      "customerRef": "RP006",
      "email": "jdoe@yourwebsite.com",
      "firstName": "John",
      "invoice": "IN0001",
      "lastName": "Doe",
      "orderDate": "2021-08-26",
      "orderNumber": "210058A",
      "phone": "1555555555",
      "shipToAddressOne": "1725 Slough Avenue",
      "shipToAddressTwo": "Suite 200",
      "shipToCity": "Scranton",
      "shipToCountry": "US",
      "shipToPhone": "1555555555",
      "shipToPostal": "18505",
      "shipToState": "PA"
    },
    "customFields": {
      "exampleKey": "Example string"
    }
  },
  "processingOptions": {
    "verboseResponse": true,
    "webhookFailUrl": "https://your-company-webhook-fail-url-here.com",
    "webhookUrl": "https://your-company-webhook-url-here.com"
  },
  "uiOptions": {
    "css": "https://tester.nexiopaysandbox.com/example1.css",
    "customTextUrl": "",
    "displaySubmitButton": true,
    "hideBilling": {
      "hideAddressOne": false,
      "hideAddressTwo": false,
      "hideCity": false,
      "hideCountry": false,
      "hidePostal": false,
      "hidePhone": false,
      "hideState": false
    },
    "hideCvc": true,
    "limitCountriesTo": [
      "US"
    ],
    "requireCvc": false
  }
}'

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",
    "allowedCardTypes": [
      "visa"
    ],
    "cart": {
      "items": [
        {
          "item": "913261",
          "description": "Hammermill Premium 8.5 x 11 Color Copy Paper, 28 lbs. 500/Ream",
          "quantity": 8,
          "price": 16.49,
          "type": "sale"
        }
      ]
    },
    "customer": {
      "billToAddressOne": "2147 West Silverlake Drive",
      "billToAddressTwo": "Apt 42",
      "billToCity": "Scranton",
      "billToCountry": "US",
      "billToPhone": "1555555555",
      "billToPostal": "18503",
      "billToState": "PA",
      "birthDate": "1990-12-05",
      "createdAtDate": "2005-03-01",
      "customerRef": "RP006",
      "email": "jdoe@yourwebsite.com",
      "firstName": "John",
      "invoice": "IN0001",
      "lastName": "Doe",
      "orderDate": "2021-08-26",
      "orderNumber": "210058A",
      "phone": "1555555555",
      "shipToAddressOne": "1725 Slough Avenue",
      "shipToAddressTwo": "Suite 200",
      "shipToCity": "Scranton",
      "shipToCountry": "US",
      "shipToPhone": "1555555555",
      "shipToPostal": "18505",
      "shipToState": "PA"
    },
    "customFields": {
      "exampleKey": "Example string"
    },
    "description": "test purchase",
    "descriptor": "",
    "lodging": {
      "advanceDeposit": true,
      "checkInDate": "2018-12-31",
      "checkOutDate": "2019-01-05",
      "noShow": false,
      "roomNumber": 14,
      "roomRate": 143.99
    }
  },
  "card": {
    "businessNumber": "1234567890",
    "cardHolderName": "John H Doe",
    "classification": "business",
    "expirationMonth": "12",
    "expirationYear": "20",
    "password": "12"
  },
  "installment": {
    "period": 10
  },
  "isAuthOnly": false,
  "processingOptions": {
    "checkFraud": false,
    "customerRedirectUrl": "https://your-ecommerce-website.example.com",
    "merchantId": "100039",
    "paymentOptionTag": "switch",
    "saveCardToken": true,
    "shouldUseFingerprint": true,
    "verboseResponse": true,
    "webhookFailUrl": "https://your-company-webhook-fail-url-here.com",
    "webhookUrl": "https://your-company-webhook-url-here.com"
  },
  "uiOptions": {
    "css": "https://tester.nexiopaysandbox.com/example1.css",
    "customTextUrl": "",
    "displaySubmitButton": true,
    "hideBilling": {
      "hideAddressOne": false,
      "hideAddressTwo": false,
      "hideCity": false,
      "hideCountry": false,
      "hidePostal": false,
      "hidePhone": false,
      "hideState": false
    },
    "hideCvc": true,
    "limitCountriesTo": [
      "US"
    ],
    "requireCvc": false
  }
}'

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",
    "cart": {
      "items": [
        {
          "item": "913261",
          "description": "Hammermill Premium 8.5 x 11 Color Copy Paper, 28 lbs. 500/Ream",
          "quantity": 8,
          "price": 16.49,
          "type": "sale"
        }
      ]
    },
    "customer": {
      "billToAddressOne": "2147 West Silverlake Drive",
      "billToAddressTwo": "Apt 42",
      "billToCity": "Scranton",
      "billToCountry": "US",
      "billToPhone": "1555555555",
      "billToPostal": "18503",
      "billToState": "PA",
      "birthDate": "1990-12-05",
      "createdAtDate": "2005-03-01",
      "customerRef": "RP006",
      "email": "jdoe@yourwebsite.com",
      "firstName": "John",
      "invoice": "IN0001",
      "lastName": "Doe",
      "orderDate": "2021-08-26",
      "orderNumber": "210058A",
      "phone": "1555555555",
      "shipToAddressOne": "1725 Slough Avenue",
      "shipToAddressTwo": "Suite 200",
      "shipToCity": "Scranton",
      "shipToCountry": "US",
      "shipToPhone": "1555555555",
      "shipToPostal": "18505",
      "shipToState": "PA"
    },
    "customFields": {
      "exampleKey": "Example string"
    },
    "description": "test purchase",
    "descriptor": "",
    "secCode": "IAT"
  },
  "bank": {
    "accountHolderName": "John Doe",
    "routingNumber": "231375151"
  },
  "processingOptions": {
    "merchantId": "100039",
    "verboseResponse": true,
    "webhookFailUrl": "https://your-company-webhook-fail-url-here.com",
    "webhookUrl": "https://your-company-webhook-url-here.com"
  },
  "uiOptions": {
    "css": "https://tester.nexiopaysandbox.com/example1.css",
    "customTextUrl": "",
    "displaySubmitButton": true,
    "hideBilling": {
      "hideAddressOne": false,
      "hideAddressTwo": false,
      "hideCity": false,
      "hideCountry": false,
      "hidePostal": false,
      "hidePhone": false,
      "hideState": false
    },
    "hideCvc": true,
    "limitCountriesTo": [
      "US"
    ],
    "requireCvc": false
  }
}'

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": {
    "currency": "USD"
  },
  "processingOptions": {
    "checkFraud": false,
    "verboseResponse": true,
    "verifyAvs": 2,
    "verifyCvc": false,
    "webhookFailUrl": "https://your-company-webhook-fail-url-here.com",
    "webhookUrl": "https://your-company-webhook-url-here.com"
  }
}'

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": {
    "verboseResponse": true,
    "webhookFailUrl": "https://your-company-webhook-fail-url-here.com",
    "webhookUrl": "https://your-company-webhook-url-here.com"
  }
}'

POST /pay/v3/token

A token from this endpoint is necessary prior to loading any e-commerce iframe. The available and required parameters differ based on the iframe to be loaded. See the dropdown below to see which parameters are available and required for each iframe. All processing options and UI options for your iframes must be sent in the body of this request. Any data (ex. card or customer information) you wish to be pre-filled in your iframe forms must also be sent in this request. Any parameter included here will be overwritten if the same parameter is included in the iframe’s event body.

Note: Once a token has been used to submit an iframe it cannot be used to load another. You must request a new one-time-use token prior to submitting each iframe.

Parameters

Name Type Description
card object Credit card information
data object Additional optional data
processingOptions object Processing Options
shouldUpdateCard boolean The card's account updater enrollment tag
When true, the card or e-check token is tagged for registration with account updater
Note: The card or e-check will not be registered until the merchant account is enrolled. See this table for more information
Default: true
uiOptions object Used to customize the iframe's user interface

Example responses

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

401 Response

{
  "message": "Unauthorized"
}

Responses

Status Meaning Description
200 OK Success
401 Unauthorized Unauthorized

Response Schema


Status Code 200

Name Type Description
expiration string The date and time at which the one-time-use token will expire, in ISO 8601 format.
fraudUrl string The URL to be used for device fingerprinting
token string Your one-time-use token

Status Code 401

Name Type Description
message string A message from Nexio about the state of the request

Save Card Token

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",
    "cardType": "visa",
    "securityCode": 927,
    "firstSix": "479300",
    "lastFour": "3313"
  },
  "token": "eb50a022-d6de-4244-a1e6-dcb8522b2d19",
  "data": {
    "currency": "USD",
    "customer": {
      "billToAddressOne": "2147 West Silverlake Drive",
      "billToAddressTwo": "Apt 42",
      "billToCity": "Scranton",
      "billToCountry": "US",
      "billToPhone": "1555555555",
      "billToPostal": "18503",
      "billToState": "PA",
      "birthDate": "1990-12-05",
      "createdAtDate": "2005-03-01",
      "customerRef": "RP006",
      "email": "jdoe@yourwebsite.com",
      "firstName": "John",
      "invoice": "IN0001",
      "lastName": "Doe",
      "orderNumber": "210058A",
      "phone": "1555555555",
      "shipToAddressOne": "1725 Slough Avenue",
      "shipToAddressTwo": "Suite 200",
      "shipToCity": "Scranton",
      "shipToCountry": "US",
      "shipToPhone": "1555555555",
      "shipToPostal": "18505",
      "shipToState": "PA"
    },
    "customFields": {
      "exampleKey": "Example string"
    }
  },
  "shouldUpdateCard": true,
  "tokenex": {
    "token": "6ee140a0-05d1-4958-8325-b38a690dbb9d",
    "firstSix": "479300",
    "lastFour": "3313"
  },
  "merchantId": "100039"
}'

POST /pay/v3/saveCard

Allows you to securely save a card token without a browser or using your own form. You may save a new card by including the card object or add existing TokenEx card token for use in Nexio by including the token object.

Note: Processing options must be sent in the request for a one-time-use token.

Parameters

Name Type Description
card
Required
object Credit card information
token
Required
string A one-time-use token.
data object Additional optional data
shouldUpdateCard boolean The card's account updater enrollment tag
When true, the card or e-check token is tagged for registration with account updater
Note: The card or e-check will not be registered until the merchant account is enrolled. See this table for more information
Default: true
tokenex object A previously saved TokenEx card token. (Use this option if you have pre-existing TokenEx tokens you would like to start using through Nexio.) Conditionally Required if the card.encryptedNumber is not included
merchantId string The merchant ID (MID).

Example responses

200 Response

{
  "card": {
    "expirationMonth": "12",
    "expirationYear": "20",
    "cardHolderName": "John H Doe",
    "cardType": "visa"
  },
  "data": {
    "customer": {
      "billToAddressOne": "2147 West Silverlake Drive",
      "billToAddressTwo": "Apt 42",
      "billToCity": "Scranton",
      "billToCountry": "US",
      "billToPhone": "1555555555",
      "billToPostal": "18503",
      "billToState": "PA",
      "birthDate": "1990-12-05",
      "createdAtDate": "2005-03-01",
      "customerRef": "RP006",
      "email": "jdoe@yourwebsite.com",
      "firstName": "John",
      "invoice": "IN0001",
      "lastName": "Doe",
      "orderNumber": "210058A",
      "phone": "1555555555",
      "shipToAddressOne": "1725 Slough Avenue",
      "shipToAddressTwo": "Suite 200",
      "shipToCity": "Scranton",
      "shipToCountry": "US",
      "shipToPhone": "1555555555",
      "shipToPostal": "18505",
      "shipToState": "PA"
    }
  },
  "kountResponse": {
    "status": "success",
    "rules": "{\"VERS\":\"0630\",\"MODE\":\"Q\",\"TRAN\":\"7V7D0V1BMKPX\",\"MERC\":\"717000\",\"SESS\":\"3bbb89edcd5742f18e2502ebb2bbb18b\",\"ORDR\":\"14233\",\"AUTO\":\"A\",\"SCOR\":\"29\",\"GEOX\":\"US\",\"BRND\":\"VISA\",\"REGN\":null,\"NETW\":\"N\",\"KAPT\":\"N\",\"CARDS\":\"1\",\"DEVICES\":\"1\",\"EMAILS\":\"1\",\"VELO\":\"0\",\"VMAX\":\"0\",\"SITE\":\"DEFAULT\",\"DEVICE_LAYERS\":\"....\",\"FINGERPRINT\":null,\"TIMEZONE\":null,\"LOCALTIME\":\" \",\"REGION\":null,\"COUNTRY\":null,\"PROXY\":null,\"JAVASCRIPT\":null,\"FLASH\":null,\"COOKIES\":null,\"HTTP_COUNTRY\":null,\"LANGUAGE\":null,\"MOBILE_DEVICE\":null,\"MOBILE_TYPE\":null,\"MOBILE_FORWARDER\":null,\"VOICE_DEVICE\":null,\"PC_REMOTE\":null,\"RULES_TRIGGERED\":0,\"COUNTERS_TRIGGERED\":0,\"REASON_CODE\":null,\"MASTERCARD\":\"\",\"DDFS\":null,\"DSR\":null,\"UAS\":null,\"BROWSER\":null,\"OS\":null,\"PIP_IPAD\":null,\"PIP_LAT\":null,\"PIP_LON\":null,\"PIP_COUNTRY\":null,\"PIP_REGION\":null,\"PIP_CITY\":null,\"PIP_ORG\":null,\"IP_IPAD\":null,\"IP_LAT\":null,\"IP_LON\":null,\"IP_COUNTRY\":null,\"IP_REGION\":null,\"IP_CITY\":null,\"IP_ORG\":null,\"WARNING_COUNT\":0}"
  },
  "merchantId": "100100",
  "shouldUpdateCard": true,
  "token": {
    "firstSix": "479300",
    "lastFour": "3313",
    "token": "6ee140a0-05d1-4958-8325-b38a690dbb9d",
    "cardType": "visa"
  },
  "cvcResults": {
    "matchCvv": true,
    "error": true,
    "gatewayMessage": {
      "cvvresponse": "S",
      "message": "Merchant has indicated that CVV2/CVC2 is not present on card"
    }
  },
  "cardType": "visa"
}

400 Response

{
  "error": 0,
  "message": "string",
  "cvcResults": {...},
  "merchantId": "100039"
}

401 Response

{
  "message": "Unauthorized"
}

Responses

Status Meaning Description
200 OK Success
400 Bad Request Bad Request
401 Unauthorized Unauthorized

Response Schema


Status Code 200

Name Type Description
card object Card information
data object Additional data, if provided in the request
kountResponse object Fraud data and rules
merchantId string The merchant ID (MID)
shouldUpdateCard boolean The card's account updater enrollment tag
When true, the card or e-check token is tagged for registration with account updater
Note: The card or e-check will not be registered until the merchant account is enrolled. See this table for more information
token object Card token information
cvcResults object If `verifyCvc` was specified in the request for a one-time use token, then the Save Card Token endpoint includes this object in the response.
cardType string The card type. May be any of the following:
- visa
- mastercard
- discover
- amex

Status Code 400

Name Type Description
error number The Nexio error code. For an HTTP status code of 400, this value is 437.
message string The message associated with the error. For an HTTP status code of 400, this message will be "CVV2/CVC2 no match".
cvcResults object The results of the verification of the card security code.
merchantId string The merchant ID (MID).

Status Code 401

Name Type Description
message string A message from Nexio about the state of the request

Save Card Token Iframe

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'

GET /pay/v3/saveCard

Returns an iframe that can be used to securely save a credit card token.

Parameters

Name Type Description
token
Required
string Your one-time-use token

Example responses

200 Response

"<html>A save card form</html>"

401 Response

{
  "message": "Unauthorized"
}

Responses

Status Meaning Description
200 OK Success
401 Unauthorized Unauthorized

Response Schema


Status Code 401

Name Type Description
message string A message from Nexio about the state of the request

Run Card 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": {
    "amount": 29.99,
    "currency": "USD",
    "cart": {
      "items": [
        {
          "item": "913261",
          "description": "Hammermill Premium 8.5 x 11 Color Copy Paper, 28 lbs. 500/Ream",
          "quantity": 8,
          "price": 16.49,
          "type": "sale"
        }
      ]
    },
    "customer": {
      "billToAddressOne": "2147 West Silverlake Drive",
      "billToAddressTwo": "Apt 42",
      "billToCity": "Scranton",
      "billToCountry": "US",
      "billToPhone": "1555555555",
      "billToPostal": "18503",
      "billToState": "PA",
      "birthDate": "1990-12-05",
      "createdAtDate": "2005-03-01",
      "customerRef": "RP006",
      "email": "jdoe@yourwebsite.com",
      "firstName": "John",
      "invoice": "IN0001",
      "lastName": "Doe",
      "orderDate": "2021-08-26",
      "orderNumber": "210058A",
      "phone": "1555555555",
      "shipToAddressOne": "1725 Slough Avenue",
      "shipToAddressTwo": "Suite 200",
      "shipToCity": "Scranton",
      "shipToCountry": "US",
      "shipToPhone": "1555555555",
      "shipToPostal": "18505",
      "shipToState": "PA"
    },
    "customFields": {
      "exampleKey": "Example string"
    },
    "description": "test purchase",
    "descriptor": "",
    "lodging": {
      "advanceDeposit": true,
      "checkInDate": "2018-12-31",
      "checkOutDate": "2019-01-05",
      "noShow": false,
      "roomNumber": 14,
      "roomRate": 143.99
    }
  },
  "tokenex": {
    "token": "6ee140a0-05d1-4958-8325-b38a690dbb9d",
    "firstSix": "479300",
    "lastFour": "3313"
  },
  "card": {
    "businessNumber": "1234567890",
    "cardHolderName": "John H Doe",
    "cardType": "visa",
    "classification": "business",
    "expirationMonth": "12",
    "expirationYear": "20",
    "password": "12",
    "securityCode": 927
  },
  "installment": {
    "period": 10
  },
  "isAuthOnly": false,
  "processingOptions": {
    "checkFraud": false,
    "customerRedirectUrl": "https://your-ecommerce-website.example.com",
    "merchantId": "100039",
    "paymentOptionTag": "switch",
    "saveCardToken": true,
    "shouldUseFingerprint": true,
    "verboseResponse": true,
    "webhookFailUrl": "https://your-company-webhook-fail-url-here.com",
    "webhookUrl": "https://your-company-webhook-url-here.com"
  }
}'

POST /pay/v3/process

Allows you to securely process a card transaction without a browser.

Parameters

Name Type Description
data
Required
object Transaction data
tokenex
Required
object A previously saved card token.
card object Credit card information
installment object Creates an installment associated with the transaction. For a list of supported gateways, contact integration support.
isAuthOnly boolean Set to true to run an auth only transaction
Default: false
processingOptions object Processing Options

Example responses

200 Response

{
  "amount": 34.25,
  "authCode": "035410",
  "card": {
    "expirationMonth": "12",
    "expirationYear": "20",
    "cardType": "visa",
    "cardHolder": "John H Doe"
  },
  "currency": "USD",
  "data": {
    "amount": 29.99,
    "currency": "USD",
    "settlementCurrency": "CAD",
    "customer": {
      "customerRef": "RP006",
      "firstName": "John",
      "lastName": "Doe",
      "invoice": "IN0001",
      "orderNumber": "210058A",
      "birthDate": "1990-12-05",
      "createdAtDate": "2005-03-01",
      "email": "jdoe@yourwebsite.com",
      "phone": "1555555555",
      "billToAddressOne": "2147 West Silverlake Drive",
      "billToAddressTwo": "Apt 42",
      "billToCity": "Scranton",
      "billToState": "PA",
      "billToPostal": "18503",
      "billToCountry": "US",
      "billToPhone": "1555555555",
      "orderDate": "2021-08-26",
      "shipToAddressOne": "1725 Slough Avenue",
      "shipToAddressTwo": "Suite 200",
      "shipToCity": "Scranton",
      "shipToState": "PA",
      "shipToPostal": "18505",
      "shipToCountry": "US",
      "shipToPhone": "1555555555"
    },
    "cart": {
      "items": [
        {
          "item": "913261",
          "description": "Hammermill Premium 8.5 x 11 Color Copy Paper, 28 lbs. 500/Ream",
          "quantity": 8,
          "price": 16.49,
          "type": "sale"
        }
      ]
    },
    "lodging": {
      "advanceDeposit": true,
      "checkInDate": "2018-12-31",
      "checkOutDate": "2019-01-05",
      "noShow": false,
      "roomNumber": 14,
      "roomRate": 143.99
    },
    "customFields": {
      "exampleKey": "Example string"
    }
  },
  "gatewayResponse": {
    "gatewayName": "nmi",
    "refNumber": "3107885809"
  },
  "id": "eyJuYW1lIjoidXNhZXBheSIsInJlZk51bWJlciI6IjMxMDA5MDc4MTkiLCJtZXJjaGFudElkIjoiMTAwMDM5IiwicmFuZG9tIjoiMzEwMDkwNzgxOSIsImN1cnJlbmN5IjoiVVNEIn0=",
  "kountResponse": {
    "status": "success",
    "rules": "{\"VERS\":\"0630\",\"MODE\":\"Q\",\"TRAN\":\"7V7D0V1BMKPX\",\"MERC\":\"717000\",\"SESS\":\"3bbb89edcd5742f18e2502ebb2bbb18b\",\"ORDR\":\"14233\",\"AUTO\":\"A\",\"SCOR\":\"29\",\"GEOX\":\"US\",\"BRND\":\"VISA\",\"REGN\":null,\"NETW\":\"N\",\"KAPT\":\"N\",\"CARDS\":\"1\",\"DEVICES\":\"1\",\"EMAILS\":\"1\",\"VELO\":\"0\",\"VMAX\":\"0\",\"SITE\":\"DEFAULT\",\"DEVICE_LAYERS\":\"....\",\"FINGERPRINT\":null,\"TIMEZONE\":null,\"LOCALTIME\":\" \",\"REGION\":null,\"COUNTRY\":null,\"PROXY\":null,\"JAVASCRIPT\":null,\"FLASH\":null,\"COOKIES\":null,\"HTTP_COUNTRY\":null,\"LANGUAGE\":null,\"MOBILE_DEVICE\":null,\"MOBILE_TYPE\":null,\"MOBILE_FORWARDER\":null,\"VOICE_DEVICE\":null,\"PC_REMOTE\":null,\"RULES_TRIGGERED\":0,\"COUNTERS_TRIGGERED\":0,\"REASON_CODE\":null,\"MASTERCARD\":\"\",\"DDFS\":null,\"DSR\":null,\"UAS\":null,\"BROWSER\":null,\"OS\":null,\"PIP_IPAD\":null,\"PIP_LAT\":null,\"PIP_LON\":null,\"PIP_COUNTRY\":null,\"PIP_REGION\":null,\"PIP_CITY\":null,\"PIP_ORG\":null,\"IP_IPAD\":null,\"IP_LAT\":null,\"IP_LON\":null,\"IP_COUNTRY\":null,\"IP_REGION\":null,\"IP_CITY\":null,\"IP_ORG\":null,\"WARNING_COUNT\":0}"
  },
  "merchantId": "100039",
  "token": {
    "firstSix": "479300",
    "lastFour": "3313",
    "token": "6ee140a0-05d1-4958-8325-b38a690dbb9d"
  },
  "transactionDate": "2019-01-15T13:19:39.329Z",
  "transactionStatus": "pending",
  "transactionType": "sale"
}

400 Response

{
  "error": 435,
  "message": "Declined for CVV failure",
  "gatewayResponse": {...},
  "merchantId": "100100"
}

401 Response

{
  "message": "Unauthorized"
}

Responses

Status Meaning Description
200 OK Success
400 Bad Request Bad Request
401 Unauthorized Unauthorized

Response Schema


Status Code 200

Name Type Description
amount number The transaction amount
authCode string The authorization code
card object Credit card information
currency string The three-character ISO currency code for the transaction.
data object Transaction data
gatewayResponse object Gateway-specific information. Details will vary by gateway. Do NOT code to any information included in this object
id string Nexio Payment ID
kountResponse object Fraud data and rules
merchantId string The merchant ID through which the transaction was processed
token object The card token used to process the transaction
transactionDate string The transaction date and time
transactionStatus string The transaction status
transactionType string The transaction type

Status Code 400

Name Type Description
error integer Nexio's error code
message string The reason for the failure to authenticate
gatewayResponse object The failure response from the gateway. Details will vary by gateway
merchantId string The merchant ID

Status Code 401

Name Type Description
message string A message from Nexio about the state of the request

Run Card Transaction Iframe

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'

GET /pay/v3

Returns an iframe that can be used to securely run a credit or debit card transaction.

Parameters

Name Type Description
token
Required
string Your one-time-use token. This is a query parameter.

Example responses

200 Response

"<html>A run transaction form</html>"

401 Response

{
  "message": "Unauthorized"
}

Responses

Status Meaning Description
200 OK Success
401 Unauthorized Unauthorized

Response Schema


Status Code 401

Name Type Description
message string A message from Nexio about the state of the request

Save E-check Token

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",
    "encryptedBankAccountNumber": "cu3yRktaYFK2LUC6DpNK289tYDsGRCi7cO+GeG0hkeYFvT7Y8/oY5r53obMz6Q/BZ38gk2u2Ufwy8ojBcX2sfNjG5jplGTXA4NNlSIUjMFfiHe1sff1JFpThoiW/IIlifGlbWu+S1/9pqWPTzJ2+DcjwohbHzsDahhYewFhXgC8qsK0ypi/Shlp+CwRITyIvbVXESD0xz3YOTRHeZLlChvVqN8z4ZzN8nm0MXkmT1wcpYI73bH4KdnPwNU3s7XxvP/ernQP73SHHAOKSLlz4F6AEHFjJiCoXzeLF7LwEjRdxDJ0sKVXbRk3i9BGh+8Nle2VYgjpUWtk2763QkvZiQQ=="
  },
  "token": "830d36f6-a5e3-4455-9600-3a55b63e2fc2",
  "data": {
    "customer": {
      "billToAddressOne": "2147 West Silverlake Drive",
      "billToAddressTwo": "Apt 42",
      "billToCity": "Scranton",
      "billToState": "PA",
      "billToPostal": "18503",
      "billToCountry": "US",
      "billToPhone": "1555555555",
      "companyName": "Green Thumb Lawn Care",
      "createdAtDate": "2005-03-01",
      "customerRef": "RP006",
      "email": "jdoe@yourwebsite.com",
      "firstName": "John",
      "invoice": "IN0001",
      "lastName": "Doe",
      "orderNumber": "210058A",
      "phone": "1555555555",
      "shipToAddressOne": "1725 Slough Avenue",
      "shipToAddressTwo": "Suite 200",
      "shipToCity": "Scranton",
      "shipToState": "PA",
      "shipToPostal": "18505",
      "shipToCountry": "US",
      "shipToPhone": "1555555555"
    },
    "customFields": {
      "exampleKey": "Example string"
    }
  },
  "tokenex": {
    "token": "585436789",
    "customerRefNumber": "74771a19-3c28-4c27-83c6-9",
    "lastFour": "1111"
  }
}'

POST /pay/v3/saveECheck

Allows you to securely save bank account information without a browser or using your own form. You may save a new e-check by including the card object or add existing TokenEx e-check token for use in Nexio by including the token object.

Note: Processing options must be sent in the request for a one-time-use token.

Parameters

Name Type Description
bank
Required
object Bank account information
token
Required
string Your one-time-use token
data object Additional optional data
tokenex object The TokenEx e-check token. (Use this option if you have pre-existing TokenEx tokens you would like to start using through Nexio). Conditionally Required if the bank.encryptedBankAccountNumber is not included.

Example responses

200 Response

{
  "token": {
    "lastFour": "1111",
    "token": "aafb1033-599a-4392-859e-f98033fc37f5"
  },
  "data": {
    "customer": {
      "billToAddressOne": "2147 West Silverlake Drive",
      "billToAddressTwo": "Apt 42",
      "billToCity": "Scranton",
      "billToCountry": "US",
      "billToPhone": "1555555555",
      "billToPostal": "18503",
      "billToState": "PA",
      "companyName": "Green Thumb Lawn Care",
      "createdAtDate": "2005-03-01",
      "customerRef": "RP006",
      "email": "jdoe@yourwebsite.com",
      "firstName": "John",
      "invoice": "IN0001",
      "lastName": "Doe",
      "orderNumber": "210058A",
      "phone": "1555555555",
      "shipToAddressOne": "1725 Slough Avenue",
      "shipToAddressTwo": "Suite 200",
      "shipToCity": "Scranton",
      "shipToCountry": "US",
      "shipToPhone": "1555555555",
      "shipToPostal": "18505",
      "shipToState": "PA"
    }
  },
  "bank": {
    "accountHolderName": "John Doe",
    "routingNumber": "231375151"
  },
  "merchantId": "100100"
}

401 Response

{
  "message": "Unauthorized"
}

Responses

Status Meaning Description
200 OK Success
401 Unauthorized Unauthorized

Response Schema


Status Code 200

Name Type Description
token object E-check token information
data object Additional data, if provided in the request
bank object Bank information
merchantId string The merchant ID (MID)

Status Code 401

Name Type Description
message string A message from Nexio about the state of the request

Save E-check Token Iframe

Example request

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

GET /pay/v3/saveECheck

Returns an iframe that can be used to securely save a bank account information.

Parameters

Name Type Description
token
Required
string Your one-time-use token. This is a query parameter.

Example responses

200 Response

"<html>A save e-check form</html>"

401 Response

{
  "message": "Unauthorized"
}

Responses

Status Meaning Description
200 OK Success
401 Unauthorized Unauthorized

Response Schema


Status Code 401

Name Type Description
message string A message from Nexio about the state of the request

Run E-check Transaction

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",
    "cart": {
      "items": [
        {
          "item": "913261",
          "description": "Hammermill Premium 8.5 x 11 Color Copy Paper, 28 lbs. 500/Ream",
          "quantity": 8,
          "price": 16.49,
          "type": "sale"
        }
      ]
    },
    "customer": {
      "billToAddressOne": "2147 West Silverlake Drive",
      "billToAddressTwo": "Apt 42",
      "billToCity": "Scranton",
      "billToState": "PA",
      "billToPostal": "18503",
      "billToCountry": "US",
      "billToPhone": "1555555555",
      "companyName": "Green Thumb Lawn Care",
      "createdAtDate": "2005-03-01",
      "customerRef": "RP006",
      "email": "jdoe@yourwebsite.com",
      "firstName": "John",
      "invoice": "IN0001",
      "lastName": "Doe",
      "orderNumber": "210058A",
      "phone": "1555555555",
      "shipToAddressOne": "1725 Slough Avenue",
      "shipToAddressTwo": "Suite 200",
      "shipToCity": "Scranton",
      "shipToState": "PA",
      "shipToPostal": "18505",
      "shipToCountry": "US",
      "shipToPhone": "1555555555"
    },
    "customFields": {
      "exampleKey": "Example string"
    },
    "secCode": "IAT",
    "settlementCurrency": "CAD"
  },
  "tokenex": {
    "token": "aafb1033-599a-4392-859e-f98033fc37f5",
    "customerRefNumber": "74771a19-3c28-4c27-83c6-9",
    "lastFour": "1111"
  },
  "bank": {
    "accountHolderName": "John Doe",
    "routingNumber": "231375151"
  },
  "processingOptions": {
    "merchantId": "100039",
    "verboseResponse": true,
    "webhookFailUrl": "https://your-company-webhook-fail-url-here.com",
    "webhookUrl": "https://your-company-webhook-url-here.com"
  }
}'

POST /pay/v3/processECheck

Allows you to securely process an e-check transaction without a browser.

Parameters

Name Type Description
data
Required
object Transaction data
tokenex
Required
object The e-check token.
bank object Bank account information
processingOptions object Processing Options

Example responses

200 Response

{
  "amount": 34.25,
  "authCode": "035410",
  "bank": {
    "accountHolderName": "John Doe",
    "routingNumber": "******6789",
    "accountNumber": "***********6789"
  },
  "currency": "USD",
  "data": {
    "amount": 29.99,
    "cart": {
      "items": [
        {
          "item": "913261",
          "description": "Hammermill Premium 8.5 x 11 Color Copy Paper, 28 lbs. 500/Ream",
          "quantity": 8,
          "price": 16.49,
          "type": "sale"
        }
      ]
    },
    "currency": "USD",
    "customFields": {
      "exampleKey": "Example string"
    },
    "customer": {
      "billToAddressOne": "2147 West Silverlake Drive",
      "billToAddressTwo": "Apt 42",
      "billToCity": "Scranton",
      "billToCountry": "US",
      "billToPhone": "1555555555",
      "billToPostal": "18503",
      "billToState": "PA",
      "companyName": "Green Thumb Lawn Care",
      "createdAtDate": "2005-03-01",
      "customerRef": "RP006",
      "email": "jdoe@yourwebsite.com",
      "firstName": "John",
      "invoice": "IN0001",
      "lastName": "Doe",
      "orderNumber": "210058A",
      "phone": "1555555555",
      "shipToAddressOne": "1725 Slough Avenue",
      "shipToAddressTwo": "Suite 200",
      "shipToCity": "Scranton",
      "shipToCountry": "US",
      "shipToPhone": "1555555555",
      "shipToPostal": "18505",
      "shipToState": "PA"
    },
    "lodging": {
      "advanceDeposit": true,
      "checkInDate": "2018-12-31",
      "checkOutDate": "2019-01-05",
      "noShow": false,
      "roomNumber": 14,
      "roomRate": 143.99
    },
    "settlementCurrency": "CAD"
  },
  "gatewayResponse": {
    "gatewayName": "nmi",
    "refNumber": "3107885809"
  },
  "id": "eyJuYW1lIjoidXNhZXBheSIsInJlZk51bWJlciI6IjMxMDA5MDc4MTkiLCJtZXJjaGFudElkIjoiMTAwMDM5IiwicmFuZG9tIjoiMzEwMDkwNzgxOSIsImN1cnJlbmN5IjoiVVNEIn0=",
  "merchantId": "100039",
  "transactionDate": "2019-01-15T13:19:39.329Z",
  "transactionStatus": "pending",
  "transactionType": "sale"
}

401 Response

{
  "message": "Unauthorized"
}

Responses

Status Meaning Description
200 OK success
401 Unauthorized Unauthorized

Response Schema


Status Code 200

Name Type Description
amount number The transaction amount
authCode string The authorization code
bank object Bank account information
currency string The three-character ISO currency code for the transaction.
data object Transaction data