NAV Navigation
Logo

Quick Start

Introduction

Welcome to the new Nexio Hub API Reference!

The Nexio API provides several services to help you manage your payments. With these services, you can:

  • Obtain iframes for tokenizing and saving payment methods
  • Obtain iframes for processing payments
  • Process payments directly via the API
  • Manage transactions
  • Manage chargebacks
  • Get reports

This reference contains information on the Nexio API endpoints, including:

  • Available Parameters
  • Required Parameters
  • Example Requests
  • Example Responses
  • Authentication information
  • Code Samples

For additional code samples (including PHP, Node, C# and plugin examples for WooCommerce and Magento), see our Code Examples on GitHub.

Download and explore our Postman collection here:

Run in Postman

Getting Started

Base URLs and Environments

All endpoints are RESTful with the following base URLs:

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

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

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

Once you have successfully integrated using the sandbox environment you are ready to integrate to the production environment with minimal changes (you will need to update authentication information, encryption keys, etc.)

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 Token

E-commerce One-time-use Token

To obtain an e-commerce one-time-use token, send a request to the One-time-use Token (E-commerce) endpoint.

You will be required to authentication via 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 Method (APM) One-time-use Token

To obtain an alternative payment method one-time-use token, send a request to the One-time-use Token (APM) endpoint.

You will be required to authentication via 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 '{}'

 Example 200 Response 
{
  "expiration": "2018-09-18T15:43:05.664Z",
  "token": "830d36f6-a5e3-4455-9600-3a55b63e2fc2",
  "fraudUrl": "https://api.nexiopaysandbox.com/pay/v3/fingerprint?token=01080f80-76b8-4363-845d-67e8623bf170"
}
  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 the 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",
  "token": "830d36f6-a5e3-4455-9600-3a55b63e2fc2",
  "fraudUrl": "https://api.nexiopaysandbox.com/pay/v3/fingerprint?token=01080f80-76b8-4363-845d-67e8623bf170"
}
  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 the 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 to 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 '{
  "token": "eb50a022-d6de-4244-a1e6-dcb8522b2d19",
  "card": {
    "encryptedNumber": "cu3yRktaYFK2LUC6DpNK289tYDsGRCi7cO+GeG0hkeYFvT7Y8/oY5r53obMz6Q/BZ38gk2u2Ufwy8ojBcX2sfNjG5jplGTXA4NNlSIUjMFfiHe1sff1JFpThoiW/IIlifGlbWu+S1/9pqWPTzJ2+DcjwohbHzsDahhYewFhXgC8qsK0ypi/Shlp+CwRITyIvbVXESD0xz3YOTRHeZLlChvVqN8z4ZzN8nm0MXkmT1wcpYI73bH4KdnPwNU3s7XxvP/ernQP73SHHAOKSLlz4F6AEHFjJiCoXzeLF7LwEjRdxDJ0sKVXbRk3i9BGh+8Nle2VYgjpUWtk2763QkvZiQQ==",
    "expirationMonth": "12",
    "expirationYear": "20",
    "cardHolderName": "John H Doe"
  }
}'

  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

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

 Example 200 Response 
{
  "expiration": "2018-09-18T15:43:05.664Z",
  "token": "830d36f6-a5e3-4455-9600-3a55b63e2fc2",
  "fraudUrl": "https://api.nexiopaysandbox.com/pay/v3/fingerprint?token=01080f80-76b8-4363-845d-67e8623bf170"
}
  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 the 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 '{
  "bank": {
    "accountHolderName": "John Doe",
    "routingNumber": "231375151",
    "encryptedBankAccountNumber": "cu3yRktaYFK2LUC6DpNK289tYDsGRCi7cO+GeG0hkeYFvT7Y8/oY5r53obMz6Q/BZ38gk2u2Ufwy8ojBcX2sfNjG5jplGTXA4NNlSIUjMFfiHe1sff1JFpThoiW/IIlifGlbWu+S1/9pqWPTzJ2+DcjwohbHzsDahhYewFhXgC8qsK0ypi/Shlp+CwRITyIvbVXESD0xz3YOTRHeZLlChvVqN8z4ZzN8nm0MXkmT1wcpYI73bH4KdnPwNU3s7XxvP/ernQP73SHHAOKSLlz4F6AEHFjJiCoXzeLF7LwEjRdxDJ0sKVXbRk3i9BGh+8Nle2VYgjpUWtk2763QkvZiQQ=="
  },
  "data": {}
}'

  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",
  "token": "830d36f6-a5e3-4455-9600-3a55b63e2fc2",
  "fraudUrl": "https://api.nexiopaysandbox.com/pay/v3/fingerprint?token=01080f80-76b8-4363-845d-67e8623bf170"
}
  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 the 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 '{
  "token": "830d36f6-a5e3-4455-9600-3a55b63e2fc2",
  "bank": {
    "accountHolderName": "John Doe",
    "routingNumber": "231375151",
    "encryptedBankAccountNumber": "cu3yRktaYFK2LUC6DpNK289tYDsGRCi7cO+GeG0hkeYFvT7Y8/oY5r53obMz6Q/BZ38gk2u2Ufwy8ojBcX2sfNjG5jplGTXA4NNlSIUjMFfiHe1sff1JFpThoiW/IIlifGlbWu+S1/9pqWPTzJ2+DcjwohbHzsDahhYewFhXgC8qsK0ypi/Shlp+CwRITyIvbVXESD0xz3YOTRHeZLlChvVqN8z4ZzN8nm0MXkmT1wcpYI73bH4KdnPwNU3s7XxvP/ernQP73SHHAOKSLlz4F6AEHFjJiCoXzeLF7LwEjRdxDJ0sKVXbRk3i9BGh+8Nle2VYgjpUWtk2763QkvZiQQ=="
  }
}'

  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",
  "token": "830d36f6-a5e3-4455-9600-3a55b63e2fc2",
  "fraudUrl": "https://api.nexiopaysandbox.com/pay/v3/fingerprint?token=01080f80-76b8-4363-845d-67e8623bf170"
}
  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 '{
  "token": "eb50a022-d6de-4244-a1e6-dcb8522b2d19",
  "card": {
    "encryptedNumber": "cu3yRktaYFK2LUC6DpNK289tYDsGRCi7cO+GeG0hkeYFvT7Y8/oY5r53obMz6Q/BZ38gk2u2Ufwy8ojBcX2sfNjG5jplGTXA4NNlSIUjMFfiHe1sff1JFpThoiW/IIlifGlbWu+S1/9pqWPTzJ2+DcjwohbHzsDahhYewFhXgC8qsK0ypi/Shlp+CwRITyIvbVXESD0xz3YOTRHeZLlChvVqN8z4ZzN8nm0MXkmT1wcpYI73bH4KdnPwNU3s7XxvP/ernQP73SHHAOKSLlz4F6AEHFjJiCoXzeLF7LwEjRdxDJ0sKVXbRk3i9BGh+8Nle2VYgjpUWtk2763QkvZiQQ==",
    "expirationMonth": "12",
    "expirationYear": "20",
    "cardHolderName": "John H Doe"
  }
}'



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",
  "token": "830d36f6-a5e3-4455-9600-3a55b63e2fc2",
  "fraudUrl": "https://api.nexiopaysandbox.com/pay/v3/fingerprint?token=01080f80-76b8-4363-845d-67e8623bf170"
}
  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 '{
  "token": "830d36f6-a5e3-4455-9600-3a55b63e2fc2",
  "bank": {
    "accountHolderName": "John Doe",
    "routingNumber": "231375151",
    "encryptedBankAccountNumber": "cu3yRktaYFK2LUC6DpNK289tYDsGRCi7cO+GeG0hkeYFvT7Y8/oY5r53obMz6Q/BZ38gk2u2Ufwy8ojBcX2sfNjG5jplGTXA4NNlSIUjMFfiHe1sff1JFpThoiW/IIlifGlbWu+S1/9pqWPTzJ2+DcjwohbHzsDahhYewFhXgC8qsK0ypi/Shlp+CwRITyIvbVXESD0xz3YOTRHeZLlChvVqN8z4ZzN8nm0MXkmT1wcpYI73bH4KdnPwNU3s7XxvP/ernQP73SHHAOKSLlz4F6AEHFjJiCoXzeLF7LwEjRdxDJ0sKVXbRk3i9BGh+8Nle2VYgjpUWtk2763QkvZiQQ=="
  }
}'



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 '{
  "bank": {
    "accountHolderName": "John Doe",
    "routingNumber": "231375151",
    "encryptedBankAccountNumber": "cu3yRktaYFK2LUC6DpNK289tYDsGRCi7cO+GeG0hkeYFvT7Y8/oY5r53obMz6Q/BZ38gk2u2Ufwy8ojBcX2sfNjG5jplGTXA4NNlSIUjMFfiHe1sff1JFpThoiW/IIlifGlbWu+S1/9pqWPTzJ2+DcjwohbHzsDahhYewFhXgC8qsK0ypi/Shlp+CwRITyIvbVXESD0xz3YOTRHeZLlChvVqN8z4ZzN8nm0MXkmT1wcpYI73bH4KdnPwNU3s7XxvP/ernQP73SHHAOKSLlz4F6AEHFjJiCoXzeLF7LwEjRdxDJ0sKVXbRk3i9BGh+8Nle2VYgjpUWtk2763QkvZiQQ=="
  },
  "data": {}
}'

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 
{
  "username": "youremail@cmsonline.com",
  "key": "4f211fde-d135-4c91-afbc-bcdb73c0c504",
  "jwt": "t3jraWQiOiI3V2JrOFdSVVliMVljR2p3Mlhwd2swR3lIRWt6THcwVDRqckVhNVVVTjBnPSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiI4YWYzZTQwZC02Y2I0LTQ0ZWQtOWRlZS0yN2Y3NmNmNDc0YmMiLCJlbWFpbF92ZXJpZmllZCI6dHJ1ZSwiaXNzIjoiaHR0cHM6XC9cL2NvZ25pdG8taWRwLnVzLWVhc3QtMS5hbWF6b25hd3MuY29tXC91cy1lYXN0LTFfVlVEN21MeWNqIiwiY3VzdG9tOmFjY291bnRJZCI6ImVjN2NiOWJhLWQwMmQtNDhkYS1hY2I3LWI2ZWQ3YmJiZWQwMiIsImNvZ25pdG86dXNlcm5hbWUiOiJscm9ibGVkb0BjbXNvbmxpbmUuY29tIiwiYXVkIjoiNDBtZWQ2YnNybDZ1aWpnMmpmZzQwcmJzOGkiLCJldmVudF9pZCI6IjE0YmU5MWFjLTM0NjctMTFlOS9iNDZjLWMxMjdjYTkzZjA3NCIsInRva2VuX3VzZSI6ImlkIiwiYXV0aF90aW1lIjoxNTUwNTk1Mjk0LCJleHAiOjE1NTA1OTg4OTRsImN1c3RvbTphY2Nlc3NSaWdodHMiOiJ7XCJtZXJjaGFudElkc1wiOntcIjEwMDAzOVwiOlwiQVwiLFwiMTAwMDQxXCI6XCJBXCIsXCI1MTU3OTQwMDAwMTM1MDRcIjpcIkFcIixcIjkyMzYwMDAwMTEyNDUwM1wiOlwiQVwiLFwiOTIzNTAwMDAxNDMyNzQyXCI6XCJBXCIsXCI1MTM0ODUwMDAwMDAwMThcIjpcIkFcIixcIjkyMzYwMDAwODEyNjYxMFwiOlwiQVwiLFwiOTIzNjAwMDAzMTYzODEwXCI6XCJBXCJ9LFwicm9sZVwiOlwiQVwifSIsImlhdCI6MTU1MDU5NTI5NCwiZW1haWwiOiJscm9ibGVkb0BjbXNvbmxpbmUuY29tIn0.OEEZarSzbSLpxUM55UKmycYtAAWEtm__XUJdqBJ9QPSF_8sdLIL9EXBF8cLarhv3DoLqeWKUpieNgfcME2IsIc8amDXitvJtJe3STQtI_zaJwAibBxJhFKQRLRCrIe3kpslVJPuw3OeST54QcseifLlA64bxNaveXygja7aejwINueE4_Nj0NEzcFGZoYHgNB6br6Ksbjgx-z_SiFIZ1XHS-eOMnBoCIVWjFr3FY9IbfnQf4v0c0AFWKt9mOpjYracSqOHHmSER7GuaMBNrHxfbe0kHVh6hvnrzh10SEnTsF573qbP1R_aZA_Uh80MOLB0UvPWWFzzyP4GniNc3zLw",
  "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",
  "exp": 1550600014
}
  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.

Run a Terminal Transaction

Nexio's API allows you to process card present (EMV) transactions using a terminal. To do so, follow the steps below:

  1. Request a Terminal List

    Send a GET request to the Get Terminal List endpoint. A successful request will return 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 
[
  {
    "merchantId": "103002",
    "merchantName": "Test Merchant",
    "gatewayName": "yourGateway",
    "gatewayType": 110,
    "gatewayLabel": "...2e21,...5ee7",
    "terminalName": "Terminal 1",
    "terminalSerialNumber": "84937213",
    "terminalId": "eyJtZXJjaGFudElkIjoiMTAxMDM5IiwiZ2F0ZXdheUxhYmVsIjoiLi4uMmUyMSwuLi41ZWU3IiwidGVybWluYWwiOnsiaWQiOiIxMWU5MDIxMGNmZTdmNmFlOWVkNWUwYTgiLCJsb2NhdGlvbklkIjoiMTFlOGNkNmE4YjQ0YzUzZWFkNmFkY2UxIn19"
  }
]
  1. Copy the Terminal ID

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

  2. POST Transaction Details

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

    A successful response will return 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 
{
  "terminalRequestStatus": "initialized",
  "terminalRequestId": "64ea267f-2766-49b8-9e0e-aeb91b2fe722"
}
  1. 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 
{
  "terminalRequestStatus": "initialized",
  "terminalRequestId": "64ea267f-2766-49b8-9e0e-aeb91b2fe722",
  "gatewayResponse": {
    "gatewayName": "yourGateway"
  }
}

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

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

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 
{
  "key": "aafb1033-599a-4392-859e-f98033fc37f5.5292712865664733",
  "merchantId": "100100",
  "data": {...},
  "tokenex": {...},
  "dateCreated": "2019-07-31T17:02:39.035Z",
  "dateLastModified": "2019-07-31T18:33:30.660Z",
  "card": {...},
  "originalCard": {...},
  "tokenHistory": {...},
  "accountUpdaterStatus": "isExcluded",
  "shouldUpdateCard": true
}

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 
{
  "key": "aafb1033-599a-4392-859e-f98033fc37f5.5292712865664733",
  "merchantId": "100100",
  "data": {...},
  "tokenex": {...},
  "dateCreated": "2019-07-31T17:02:39.035Z",
  "dateLastModified": "2019-07-31T18:33:30.660Z",
  "card": {...},
  "originalCard": {...},
  "tokenHistory": {...},
  "accountUpdaterStatus": "isExcluded",
  "shouldUpdateCard": true
}

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": 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 
{
  "key": "aafb1033-599a-4392-859e-f98033fc37f5.5292712865664733",
  "merchantId": "100100",
  "data": {...},
  "tokenex": {...},
  "dateCreated": "2019-07-31T17:02:39.035Z",
  "dateLastModified": "2019-07-31T18:33:30.660Z",
  "card": {...},
  "originalCard": {...},
  "tokenHistory": {...},
  "accountUpdaterStatus": "isExcluded",
  "shouldUpdateCard": true
}

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 '{
  "token": "eb50a022-d6de-4244-a1e6-dcb8522b2d19",
  "card": {
    "encryptedNumber": "cu3yRktaYFK2LUC6DpNK289tYDsGRCi7cO+GeG0hkeYFvT7Y8/oY5r53obMz6Q/BZ38gk2u2Ufwy8ojBcX2sfNjG5jplGTXA4NNlSIUjMFfiHe1sff1JFpThoiW/IIlifGlbWu+S1/9pqWPTzJ2+DcjwohbHzsDahhYewFhXgC8qsK0ypi/Shlp+CwRITyIvbVXESD0xz3YOTRHeZLlChvVqN8z4ZzN8nm0MXkmT1wcpYI73bH4KdnPwNU3s7XxvP/ernQP73SHHAOKSLlz4F6AEHFjJiCoXzeLF7LwEjRdxDJ0sKVXbRk3i9BGh+8Nle2VYgjpUWtk2763QkvZiQQ==",
    "expirationMonth": "12",
    "expirationYear": "20",
    "cardHolderName": "John H Doe"
  },
  "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 '{
  "token": "eb50a022-d6de-4244-a1e6-dcb8522b2d19",
  "card": {
    "encryptedNumber": "cu3yRktaYFK2LUC6DpNK289tYDsGRCi7cO+GeG0hkeYFvT7Y8/oY5r53obMz6Q/BZ38gk2u2Ufwy8ojBcX2sfNjG5jplGTXA4NNlSIUjMFfiHe1sff1JFpThoiW/IIlifGlbWu+S1/9pqWPTzJ2+DcjwohbHzsDahhYewFhXgC8qsK0ypi/Shlp+CwRITyIvbVXESD0xz3YOTRHeZLlChvVqN8z4ZzN8nm0MXkmT1wcpYI73bH4KdnPwNU3s7XxvP/ernQP73SHHAOKSLlz4F6AEHFjJiCoXzeLF7LwEjRdxDJ0sKVXbRk3i9BGh+8Nle2VYgjpUWtk2763QkvZiQQ==",
    "expirationMonth": "12",
    "expirationYear": "20",
    "cardHolderName": "John H Doe"
  },
  "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 value.)
toDelete Indicates that Nexio must first de-register the card before deleting the token.
pendingDeletion Card is in the process of being de-registered after which the token will be deleted (usually takes three to four business days).

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 or send shoppers directly to a single APM of your choice.

The Express APM iframe allows shoppers to choose their preferred APM from a list of available options. Nexio will then redirect the shopper to their selected APM where they will complete the payment. Payment response information will be sent to the parent document as a message event. To integrate with Express APM, see the Express APM tutorial.

If you prefer, you may send shoppers directly to a single APM. With this option, you redirect shoppers to the APM URL provided by Nexio. After shoppers complete the payment, they will be sent to the customer redirect URL, if provided. Payment response information will be appended to the customer redirect URL as query parameters. To integrate with a single APM, follow the instructions in the Single APM Integration tutorial.

Supported APMs

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

APM Supported Transaction Types
Alipay Sale, Refund
Paynet Sale
SPEI Sale
PayPal Sale, Auth only, Capture, Void, Refund
UnionPay Sale, Refund
WeChat Pay Sale, Refund

Run a Transaction

Express APM

Nexio's Express APM service allows shoppers to run transactions through any 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.

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

    You may choose to have Nexio provide an in-frame submit button or your own external button by adjusting 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
  }
}'

A successful response will include the expressIFrameUrl. Copy or store this 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"
    }
  ]
}
  1. Redirect the Shopper to the Select APM Page

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

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', 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 checkout page.
  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 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 Sale Response
{
  "id": "eyJuYW1lIjoidXNhZXBheSIsInJlZk51bWJlciI6IjMxMDA5MDc4MTkiLCJtZXJjaGFudElkIjoiMTAwMDM5IiwicmFuZG9tIjoiMzEwMDkwNzgxOSIsImN1cnJlbmN5IjoiVVNEIn0=",
  "isAuthOnly": true,
  "merchantId": "100039",
  "transactionDate": "2019-01-15T13:19:39.329Z",
  "authCode": "035410",
  "transactionStatus": "pending",
  "amount": 34.25,
  "transactionType": "sale",
  "currency": "USD",
  "gatewayResponse": {...},
  "data": {...},
  "card": {...},
  "kountResponse": {...}
}

Single APM Integration

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

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

  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

    Note: If you do not include a customerRedirectUrl, the popup window will immediately be closed and you will not be able to access the payment response information.

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": "www.your-ecommcerce-website.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"
      }
  ]
}
  1. Redirect the Shopper to the APM

    Copy the url of your chosen APM and redirect the user to that page.

  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.
Example Sale Response
{
  "id": "eyJuYW1lIjoidXNhZXBheSIsInJlZk51bWJlciI6IjMxMDA5MDc4MTkiLCJtZXJjaGFudElkIjoiMTAwMDM5IiwicmFuZG9tIjoiMzEwMDkwNzgxOSIsImN1cnJlbmN5IjoiVVNEIn0=",
  "isAuthOnly": true,
  "merchantId": "100039",
  "transactionDate": "2019-01-15T13:19:39.329Z",
  "authCode": "035410",
  "transactionStatus": "pending",
  "amount": 34.25,
  "transactionType": "sale",
  "currency": "USD",
  "gatewayResponse": {...},
  "data": {...},
  "card": {...},
  "kountResponse": {...}
}
  1. 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 and payment ID as query parameters. If the payment failed, the redirect URL will include the status and an error message as query parameters.

Successful Payment Redirect
https://www.your-ecommcerce-website.com?status=pending&paymentId=eyJuYW1lIjoidXNhZXBheSIsInJlZk51bWJlciI6IjMxMDA5MDc4MTkiLCJtZXJjaGFudElkIjoiMTAwMDM5IiwicmFuZG9tIjoiMzEwMDkwNzgxOSIsImN1cnJlbmN5IjoiVVNEIn0
Failed Payment Redirect
https://www.your-ecommcerce-website.com?status=pending&error=error_message

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

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

  1. Prepare You Checkout Page

    Follow steps 1-2 of the Single APM Integration tutorial.

  2. Request the APM Redirect URL

    Follow step 3 of the Single APM 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": "www.your-ecommcerce-website.com"
}'

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

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 Single APM Integration tutorial. A successful auth only transaction will return a status of 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
Paynet TRANSACTION_SETTLED, TRANSACTION_PENDING
SPEI TRANSACTION_SETTLED, TRANSACTION_PENDING
PayPal TRANSACTION_AUTHORIZED, TRANSACTION_CAPTURED, TRANSACTION_REFUNDED, TRANSACTION_SETTLED, TRANSACTION_VOIDED
UnionPay TRANSACTION_SETTLED, TRANSACTION_REFUNDED
WeChat Pay TRANSACTION_SETTLED, TRANSACTION_REFUNDED

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 with the Nexio iframe with your own form, or through the API.

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",
  "token": "830d36f6-a5e3-4455-9600-3a55b63e2fc2",
  "fraudUrl": "https://api.nexiopaysandbox.com/pay/v3/fingerprint?token=01080f80-76b8-4363-845d-67e8623bf170"
}
  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",
  "token": "830d36f6-a5e3-4455-9600-3a55b63e2fc2",
  "fraudUrl": "https://api.nexiopaysandbox.com/pay/v3/fingerprint?token=01080f80-76b8-4363-845d-67e8623bf170"
}

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 the next step.

  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

    Copy or store the value of fingerprintPosted. You will use it in step 4.

  2. Send Card Data and Fingerprint To Your Server

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

    In addition to the card information, send the fingerprintPosted to your server.

  3. Post Card Information to Nexio

    POST the token from step 1, the fingerprintPosted, 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 '{
  "token": "eb50a022-d6de-4244-a1e6-dcb8522b2d19",
  "card": {
    "encryptedNumber": "cu3yRktaYFK2LUC6DpNK289tYDsGRCi7cO+GeG0hkeYFvT7Y8/oY5r53obMz6Q/BZ38gk2u2Ufwy8ojBcX2sfNjG5jplGTXA4NNlSIUjMFfiHe1sff1JFpThoiW/IIlifGlbWu+S1/9pqWPTzJ2+DcjwohbHzsDahhYewFhXgC8qsK0ypi/Shlp+CwRITyIvbVXESD0xz3YOTRHeZLlChvVqN8z4ZzN8nm0MXkmT1wcpYI73bH4KdnPwNU3s7XxvP/ernQP73SHHAOKSLlz4F6AEHFjJiCoXzeLF7LwEjRdxDJ0sKVXbRk3i9BGh+8Nle2VYgjpUWtk2763QkvZiQQ==",
    "expirationMonth": "12",
    "expirationYear": "20",
    "cardHolderName": "John H Doe"
  },
  "fingerprint": "asdfklajsdfl;kj"
}'

  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",
  "token": "830d36f6-a5e3-4455-9600-3a55b63e2fc2",
  "fraudUrl": "https://api.nexiopaysandbox.com/pay/v3/fingerprint?token=01080f80-76b8-4363-845d-67e8623bf170"
}

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

    Copy or store the value of fingerprintPosted for use in step 4.

  2. Send Payment Data and Fingerprint To Your Server

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

    Send the transaction information and the value of fingerprintPosted to your server.

  3. Post Payment Information to Nexio POST the transaction information and the value of fingerprintPosted 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": {},
  "tokenex": {
    "token": "6ee140a0-05d1-4958-8325-b38a690dbb9d"
  },
  "fingerprintPosted": "asdfklajsdfl;kj"
}'

  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": {},
  "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 '{
  "token": "eb50a022-d6de-4244-a1e6-dcb8522b2d19",
  "card": {
    "encryptedNumber": "cu3yRktaYFK2LUC6DpNK289tYDsGRCi7cO+GeG0hkeYFvT7Y8/oY5r53obMz6Q/BZ38gk2u2Ufwy8ojBcX2sfNjG5jplGTXA4NNlSIUjMFfiHe1sff1JFpThoiW/IIlifGlbWu+S1/9pqWPTzJ2+DcjwohbHzsDahhYewFhXgC8qsK0ypi/Shlp+CwRITyIvbVXESD0xz3YOTRHeZLlChvVqN8z4ZzN8nm0MXkmT1wcpYI73bH4KdnPwNU3s7XxvP/ernQP73SHHAOKSLlz4F6AEHFjJiCoXzeLF7LwEjRdxDJ0sKVXbRk3i9BGh+8Nle2VYgjpUWtk2763QkvZiQQ==",
    "expirationMonth": "12",
    "expirationYear": "20",
    "cardHolderName": "John H Doe"
  },
  "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": {...}
  },
  "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.

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

  1. Post Card Information to Nexio

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

    Include the object "processingOptions": { "verifyCvc": true } in the body of your request. Be sure to also include the CVC 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": {
    "encryptedNumber": "cu3yRktaYFK2LUC6DpNK289tYDsGRCi7cO+GeG0hkeYFvT7Y8/oY5r53obMz6Q/BZ38gk2u2Ufwy8ojBcX2sfNjG5jplGTXA4NNlSIUjMFfiHe1sff1JFpThoiW/IIlifGlbWu+S1/9pqWPTzJ2+DcjwohbHzsDahhYewFhXgC8qsK0ypi/Shlp+CwRITyIvbVXESD0xz3YOTRHeZLlChvVqN8z4ZzN8nm0MXkmT1wcpYI73bH4KdnPwNU3s7XxvP/ernQP73SHHAOKSLlz4F6AEHFjJiCoXzeLF7LwEjRdxDJ0sKVXbRk3i9BGh+8Nle2VYgjpUWtk2763QkvZiQQ==",
    "expirationMonth": "12",
    "expirationYear": "20",
    "cardHolderName": "John H Doe"
  },
  "processingOptions": {
    "verifyCvc": true
  },
  "data": {
    "card": {
      "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.

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 1, the card information and the object "processingOptions": { "verifyCvc": 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": {
    "verifyCvc": true
  }
}'

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 CVC Response 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. 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",
  "token": "830d36f6-a5e3-4455-9600-3a55b63e2fc2",
  "fraudUrl": "https://api.nexiopaysandbox.com/pay/v3/fingerprint?token=01080f80-76b8-4363-845d-67e8623bf170"
}
  1. Use the token from the response in step 1 to send a GET request for the desired iframe. You may wish to customize a:

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 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. Replace any values you would like to customize.

    Note: If any value is an empty string, or the property is left out, the default value will be used.

  2. 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: Send the file to integrations@nexiopay.com for approval. Once approved, we will host it on our secure servers and provide you with the URL to use in step 4
  3. 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 '{
  "uiOptions": {
    "customTextUrl": "https://your-webpage.com/custom-labels.json"
  }
}'

 Example 200 Response 
{
  "expiration": "2018-09-18T15:43:05.664Z",
  "token": "830d36f6-a5e3-4455-9600-3a55b63e2fc2",
  "fraudUrl": "https://api.nexiopaysandbox.com/pay/v3/fingerprint?token=01080f80-76b8-4363-845d-67e8623bf170"
}
  1. Use the token from the response in step 4 to send a GET request for the desired iframe. You may wish to customize a:
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",
  "token": "830d36f6-a5e3-4455-9600-3a55b63e2fc2",
  "fraudUrl": "https://api.nexiopaysandbox.com/pay/v3/fingerprint?token=01080f80-76b8-4363-845d-67e8623bf170"
}
  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 that help qualify lodging transactions. While the entire lodging object is optional, the following are the minimum required parameters to qualify lodging transactions:

  • Check-in Date (lodging.checkInDate)
  • Check-out Date (lodging.checkOutDate)
  • Room Rate (lodging.roomNumber)
  • Either of the following flags:
    • Advanced Despoit (lodging.advanceDeposit)
    • No Show (lodging.noShow)
  • Folio Number (customer.orderNumber)

Note: Passing these data points does not guarantee lodging transaction rates.

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": {
    "lodging": {
      "advanceDeposit": true,
      "checkInDate": "2018-12-31",
      "checkOutDate": "2019-01-05"
    },
    "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"
    },
    "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"
    },
    "customer": {
      "orderNumber": 4566
    }
  },
  "tokenex": {
    "token": "6ee140a0-05d1-4958-8325-b38a690dbb9d"
  }
}'

Dev Tools

Error Handling

For most situations you will encounter a handful of error and success codes including 200, 401, 404, 400 and 500. The most common responses will be:

  • 200: Payment was successful

  • 4xx: Payment was not processed, due to gateway decline or another reason

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') {
        // 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);
    }
});

Frequently Asked Questions

Common Errors

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

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, see below for test card references:

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.

Reference Tables

Iframe Events

The following events may be emitted by various Nexio iframes.

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 Description Iframe
cardSaved The card token has successfully been saved Save Card, Retail Save Card
eCheckProcessed The e-check has successfully been processed Run E-check Transaction
eCheckSaved The e-check token has successfully been saved Save E-check
error An error has occurred All
formValidations There are form validation errors All
loaded The iframe has finished loading All
initiate The user clicks 'confirm' to be redirected to the APM APMs
processed The credit card transaction has been processed Run Card Transaction
submit The form has been submitted All
success The credit card transaction has been processed Retail Run Card Transaction

Common Errors

Error Description Status Code
404 The requested item is not found 404
404 Merchant not found or invalid merchant configuration 404
409 No merchants enabled for processing on this account for selected currency 409
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 Invalid CVC 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

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
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. It can be refunded but not voided 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
AliPay 20
CUP 30
E-check 40
PayPal 50
Cash 60
ACH 70

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

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

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 30, 2019

  • New UI option: useLegacyIframe
    • Default: true
    • Set to false to use Nexio's iframe without TokenEx.

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.

Webhooks

Nexio's Webhook service allows you to 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 additionally 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

    To check your account's access rights, send a request to the Who Am I endpoint in the User Management Service.

  2. Determine the Event Types

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

  3. 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 \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic <Your Basic Auth>'
Example Response
{
  "dateCreated": "2019-03-29T02:59:45.689Z",
  "webhooks": {
    "TRANSACTION_AUTHORIZED": {
      "url": "https://your-company-webhook-url-here.com"
    },
    "TRANSACTION_REFUNDED": {
      "url": "https://your-company-webhook-url-here.com"
    }
  }
  "dateLastModified": "2019-12-30T20:14:59.451Z",
  "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
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",
    "updateType": 30,
    "usageType": 10,
    "tokenex": {
      "token": "05bf4598-eac3-4493-aea3-546b84afa135",
      "firstSix": "411111",
      "lastFour": "1111"
    },
    "key": "1feec6e7-95b0-43ed-a7c5-9e0fe66c9299.5292712865664733",
    "merchantId": "100039",
    "reportDate": "2020-01-18T16:07:32Z",
    "cardKey": "60b4ce1b-c907-40da-a8f1-0c743a42049d.5292712865664733",
    "cardNumber": "510510******5100",
    "originalCardNumber": "******"
  }
}
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.

Card Saved Example Body
{
  "eventType": "CARD_DATA_UPDATED",
  "data": {
    "data": {
      "key": "60b4ce1b-c907-40da-a8f1-0c743a42049d.5292712865664733",
      "merchantId": "100039",
      "data": {
        "customer": {...}
      },
      "tokenex": {...},
      "dateCreated": "2019-12-23T20:55:02.667Z",
      "dateLastModified": "2019-12-30T18:06:44.384Z",
      "card": {
        "expirationYear": "24",
        "expirationMonth": "10",
        "cardHolderName": "Jane Doe"
      },
      "originalCard": {
        "expirationYear": "18",
        "cardHolderName": "Jane Doe",
        "expirationMonth": "10"
      },
      "tokenHistory": [],
      "accountUpdaterStatus": "isExcluded",
      "shouldUpdateCard": true
    }
  }
}
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": {
    "key": "f104db8b-aad2-4c13-8e20-e0ecf3260ae6.5292712865664733",
    "merchantId": "100039",
    "data": {
      "customer": {...}
    },
    "tokenex": {...},
    "dateCreated": "2019-12-23T21:41:15.504Z",
    "dateLastModified": "2019-12-23T21:41:15.504Z",
    "card": {...},
    "originalCard": {},
    "tokenHistory": [],
    "accountUpdaterStatus": "isExcluded",
    "shouldUpdateCard": true,
    "kountResponse": {...},
    "clientIp": null
  }
}
Contact Cardholder
Contact Cardholder Example Body
{
  "eventType": "ACCOUNT_UPDATER_CONTACT_CARDHOLDER",
  "data": {
    "updateCode": "204",
    "updateType": 40,
    "usageType": 10,
    "tokenex": {
      "token": "05bf4598-eac3-4493-aea3-546b84afa135",
      "firstSix": "411111",
      "lastFour": "1111"
    },
    "key": "60b4ce1b-c907-40da-a8f1-0c743a42049d.5292712865664733Z",
    "merchantId": "100039",
    "reportDate": "2020-01-18T16:07:32Z",
    "cardKey": "05bf4598-eac3-4493-aea3-546b84afa135.5292712865664733",
    "cardNumber": "411111******1111",
    "originalCardNumber": "******"
  }
}

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

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": {
    "expirationMonth": "12",
    "expirationYear": "20",
    "cardHolderName": "John H Doe",
    "classification": "business",
    "password": "12",
    "businessNumber": "1234567890"
  },
  "shouldUpdateCard": true,
  "processingOptions": {
    "checkFraud": false,
    "verboseResponse": true,
    "verifyAvs": 2,
    "verifyCvc": false,
    "webhookUrl": "",
    "webhookFailUrl": "The URL provided in <code>webhookUrl</code>"
  },
  "uiOptions": {
    "customTextUrl": "",
    "displaySubmitButton": true,
    "hideBilling": {
      "hideCountry": false,
      "hideAddressOne": false,
      "hideAddressTwo": false,
      "hideCity": false,
      "hideState": false,
      "hidePostal": false,
      "hidePhone": false
    },
    "css": "https://tester.nexiopaysandbox.com/example1.css",
    "limitCountriesTo": [
      "US"
    ]
  }
}'

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 the 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
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
processingOptions object Processing Options
uiOptions object Used to customize the iframe's user interface

Example responses

200 Response

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

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.
token string Your one-time-use token
fraudUrl string The URL to be used for device fingerprinting

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 '{
  "token": "eb50a022-d6de-4244-a1e6-dcb8522b2d19",
  "card": {
    "encryptedNumber": "cu3yRktaYFK2LUC6DpNK289tYDsGRCi7cO+GeG0hkeYFvT7Y8/oY5r53obMz6Q/BZ38gk2u2Ufwy8ojBcX2sfNjG5jplGTXA4NNlSIUjMFfiHe1sff1JFpThoiW/IIlifGlbWu+S1/9pqWPTzJ2+DcjwohbHzsDahhYewFhXgC8qsK0ypi/Shlp+CwRITyIvbVXESD0xz3YOTRHeZLlChvVqN8z4ZzN8nm0MXkmT1wcpYI73bH4KdnPwNU3s7XxvP/ernQP73SHHAOKSLlz4F6AEHFjJiCoXzeLF7LwEjRdxDJ0sKVXbRk3i9BGh+8Nle2VYgjpUWtk2763QkvZiQQ==",
    "expirationMonth": "12",
    "expirationYear": "20",
    "cardType": "visa",
    "cardHolderName": "John H Doe",
    "securityCode": 927
  },
  "tokenex": {
    "token": "6ee140a0-05d1-4958-8325-b38a690dbb9d",
    "firstSix": "479300",
    "lastFour": "3313"
  },
  "processingOptions": {
    "checkFraud": false,
    "verboseResponse": true,
    "verifyAvs": 2,
    "verifyCvc": false,
    "webhookUrl": "",
    "webhookFailUrl": "The URL provided in <code>webhookUrl</code>"
  },
  "shouldUpdateCard": true
}'

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.

Parameters

Name Type Description
token
Required
string A one-time-use token.
card
Required
object Credit card information
tokenex object A previously saved card token. Required if the card object is not included
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

Example responses

200 Response

{
  "token": {
    "token": "6ee140a0-05d1-4958-8325-b38a690dbb9d",
    "firstSix": "479300",
    "lastFour": "3313"
  },
  "data": {
    "amount": 29.99,
    "currency": "USD",
    "settlementCurrency": "CAD",
    "customer": {
      "firstName": "John",
      "lastName": "Doe",
      "invoice": "IN0001",
      "orderNumber": "210058A",
      "birthDate": "1990-12-05",
      "customerRef": "RP006",
      "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",
      "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",
      "roomNumber": 14,
      "roomRate": 143.99,
      "noShow": false
    },
    "customFields": {
      "exampleKey": "Example string"
    },
    "description": "test purchase",
    "descriptor": "",
    "secCode": "ICL"
  },
  "card": {
    "expirationMonth": "12",
    "expirationYear": "20",
    "cardHolderName": "John H Doe",
    "cardType": "visa",
    "securityCode": 927,
    "classification": "business",
    "password": "12",
    "businessNumber": "1234567890"
  },
  "merchantId": "100100",
  "key": "3ef55100-3bde-45c3-96b1-5643a0854544.5292712865664733",
  "kountResponse": {
    "status": "success",
    "kountRules": "{\"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}"
  },
  "avsResults": {
    "matchAddress": true,
    "matchPostal": true,
    "gatewayResponse": {}
  }
}

Responses

Status Meaning Description
200 OK Success

Response Schema

Status Code 200

Name Type Description
token object Card token information
data object Transaction data
card object Credit card information. Required if tokenex.token if not included
merchantId string The merchant ID (MID)
key string none
kountResponse object Fraud data and rules
avsResults object The results of the AVS check. See the AVS Response section for more information

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

Responses

Status Meaning Description
200 OK Success

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 '{
  "isAuthOnly": false,
  "data": {
    "amount": 29.99,
    "currency": "USD",
    "customer": {
      "firstName": "John",
      "lastName": "Doe",
      "invoice": "IN0001",
      "orderNumber": "210058A",
      "birthDate": "1990-12-05",
      "customerRef": "RP006",
      "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",
      "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",
      "roomNumber": 14,
      "roomRate": 143.99,
      "noShow": false
    },
    "customFields": {
      "exampleKey": "Example string"
    },
    "description": "test purchase",
    "descriptor": ""
  },
  "tokenex": {
    "token": "6ee140a0-05d1-4958-8325-b38a690dbb9d",
    "firstSix": "479300",
    "lastFour": "3313"
  },
  "card": {
    "expirationMonth": "12",
    "expirationYear": "20",
    "cardHolderName": "John H Doe",
    "cardType": "visa",
    "securityCode": 927,
    "classification": "business",
    "password": "12",
    "businessNumber": "1234567890"
  },
  "installment": {
    "period": 10
  },
  "processingOptions": {
    "checkFraud": false,
    "check3ds": true,
    "merchantId": "string",
    "paymentOptionTag": "switch",
    "saveCardToken": true,
    "shouldUseFingerprint": true,
    "verboseResponse": true,
    "webhookUrl": "",
    "webhookFailUrl": "The URL provided in <code>webhookUrl</code>"
  }
}'

POST /pay/v3/process

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

Parameters

Name Type Description
isAuthOnly boolean Set to true to run an auth only transaction
Default: false
data
Required
object Transaction data
tokenex
Required
object A previously saved card token. Required if the card object is not included
card object Credit card information. Required if tokenex.token if not included
installment object none
processingOptions object Processing Options

Example responses

200 Response

{
  "id": "eyJuYW1lIjoidXNhZXBheSIsInJlZk51bWJlciI6IjMxMDA5MDc4MTkiLCJtZXJjaGFudElkIjoiMTAwMDM5IiwicmFuZG9tIjoiMzEwMDkwNzgxOSIsImN1cnJlbmN5IjoiVVNEIn0=",
  "isAuthOnly": true,
  "merchantId": "100039",
  "transactionDate": "2019-01-15T13:19:39.329Z",
  "authCode": "035410",
  "transactionStatus": "pending",
  "amount": 34.25,
  "transactionType": "sale",
  "currency": "USD",
  "gatewayResponse": {
    "result": "Approved",
    "batchRef": "2226631049",
    "refNumber": "3107885809",
    "additionalRefNumber": "299471011",
    "trackingCode": "string",
    "gatewayName": "nmi",
    "message": "Success",
    "installment": "string"
  },
  "data": {
    "amount": 29.99,
    "currency": "USD",
    "settlementCurrency": "CAD",
    "customer": {
      "firstName": "John",
      "lastName": "Doe",
      "invoice": "IN0001",
      "orderNumber": "210058A",
      "birthDate": "1990-12-05",
      "customerRef": "RP006",
      "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",
      "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",
      "roomNumber": 14,
      "roomRate": 143.99,
      "noShow": false
    },
    "customFields": {
      "exampleKey": "Example string"
    }
  },
  "card": {
    "expirationMonth": "12",
    "expirationYear": "20",
    "cardType": "visa",
    "cardHolder": "John H Doe"
  },
  "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}"
  }
}

Responses

Status Meaning Description
200 OK Success

Response Schema

Status Code 200

Name Type Description
id string Nexio Payment ID
isAuthOnly boolean Will be true if the transaction was only authorized. Will be false if the transaction was authorized and captured
merchantId string The merchant ID through which the transaction was processed
transactionDate string The transaction date
authCode string The authorization code
transactionStatus string The transaction status
amount number The transaction amount
transactionType string The transaction type
currency string The three-character currency code
gatewayResponse object Gateway specific information. Included keys may vary by gateway
data object Transaction data
card object Credit card information
kountResponse object Fraud data and rules

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

Example responses

200 Response

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

Responses

Status Meaning Description
200 OK Success

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 '{
  "token": "830d36f6-a5e3-4455-9600-3a55b63e2fc2",
  "bank": {
    "accountHolderName": "John Doe",
    "routingNumber": "231375151",
    "encryptedBankAccountNumber": "cu3yRktaYFK2LUC6DpNK289tYDsGRCi7cO+GeG0hkeYFvT7Y8/oY5r53obMz6Q/BZ38gk2u2Ufwy8ojBcX2sfNjG5jplGTXA4NNlSIUjMFfiHe1sff1JFpThoiW/IIlifGlbWu+S1/9pqWPTzJ2+DcjwohbHzsDahhYewFhXgC8qsK0ypi/Shlp+CwRITyIvbVXESD0xz3YOTRHeZLlChvVqN8z4ZzN8nm0MXkmT1wcpYI73bH4KdnPwNU3s7XxvP/ernQP73SHHAOKSLlz4F6AEHFjJiCoXzeLF7LwEjRdxDJ0sKVXbRk3i9BGh+8Nle2VYgjpUWtk2763QkvZiQQ=="
  },
  "tokenex": {
    "lastFour": "1111",
    "success": true,
    "customerRefNumber": "74771a19-3c28-4c27-83c6-9",
    "cardType": "visa",
    "sesssionID": "115a44ea7f804229acd7c88d5e15b988",
    "error": true,
    "token": "aafb1033-599a-4392-859e-f98033fc37f5"
  },
  "processingOptions": {
    "verboseResponse": true,
    "webhookUrl": "",
    "webhookFailUrl": "The URL provided in <code>webhookUrl</code>"
  }
}'

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.

Parameters

Name Type Description
token
Required
string Your one-time-use token
bank
Required
object Bank account information. Required if tokenex.token is not included
tokenex object A previously saved e-check token. Required if the bank object is not included
processingOptions object Processing Options

Example responses

200 Response

{
  "token": {
    "lastFour": "1111",
    "success": true,
    "customerRefNumber": "74771a19-3c28-4c27-83c6-9",
    "cardType": "visa",
    "sesssionID": "115a44ea7f804229acd7c88d5e15b988",
    "error": true,
    "token": "aafb1033-599a-4392-859e-f98033fc37f5"
  },
  "data": {
    "amount": 29.99,
    "currency": "USD",
    "customer": {
      "firstName": "John",
      "lastName": "Doe",
      "invoice": "IN0001",
      "orderNumber": "210058A",
      "birthDate": "1990-12-05",
      "customerRef": "RP006",
      "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",
      "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",
      "roomNumber": 14,
      "roomRate": 143.99,
      "noShow": false
    },
    "customFields": {
      "exampleKey": "Example string"
    },
    "description": "test purchase",
    "descriptor": "",
    "secCode": "ICL"
  },
  "bank": {
    "accountHolderName": "John Doe",
    "routingNumber": "231375151",
    "encryptedBankAccountNumber": "cu3yRktaYFK2LUC6DpNK289tYDsGRCi7cO+GeG0hkeYFvT7Y8/oY5r53obMz6Q/BZ38gk2u2Ufwy8ojBcX2sfNjG5jplGTXA4NNlSIUjMFfiHe1sff1JFpThoiW/IIlifGlbWu+S1/9pqWPTzJ2+DcjwohbHzsDahhYewFhXgC8qsK0ypi/Shlp+CwRITyIvbVXESD0xz3YOTRHeZLlChvVqN8z4ZzN8nm0MXkmT1wcpYI73bH4KdnPwNU3s7XxvP/ernQP73SHHAOKSLlz4F6AEHFjJiCoXzeLF7LwEjRdxDJ0sKVXbRk3i9BGh+8Nle2VYgjpUWtk2763QkvZiQQ=="
  },
  "merchantId": "100100",
  "key": "3ef55100-3bde-45c3-96b1-5643a0854544.5292712865664733"
}

Responses

Status Meaning Description
200 OK Success

Response Schema

Status Code 200

Name Type Description
token object E-check token information
data object Transaction data
bank object Bank account information. Required if tokenex.token is not included
merchantId string The merchant ID (MID)
key string none

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

Example responses

200 Response

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

Responses

Status Meaning Description
200 OK Success

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 '{
  "bank": {
    "accountHolderName": "John Doe",
    "routingNumber": "231375151",
    "encryptedBankAccountNumber": "cu3yRktaYFK2LUC6DpNK289tYDsGRCi7cO+GeG0hkeYFvT7Y8/oY5r53obMz6Q/BZ38gk2u2Ufwy8ojBcX2sfNjG5jplGTXA4NNlSIUjMFfiHe1sff1JFpThoiW/IIlifGlbWu+S1/9pqWPTzJ2+DcjwohbHzsDahhYewFhXgC8qsK0ypi/Shlp+CwRITyIvbVXESD0xz3YOTRHeZLlChvVqN8z4ZzN8nm0MXkmT1wcpYI73bH4KdnPwNU3s7XxvP/ernQP73SHHAOKSLlz4F6AEHFjJiCoXzeLF7LwEjRdxDJ0sKVXbRk3i9BGh+8Nle2VYgjpUWtk2763QkvZiQQ=="
  },
  "data": {
    "amount": 29.99,
    "currency": "USD",
    "settlementCurrency": "CAD",
    "customer": {
      "firstName": "John",
      "lastName": "Doe",
      "invoice": "IN0001",
      "orderNumber": "210058A",
      "birthDate": "1990-12-05",
      "customerRef": "RP006",
      "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",
      "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",
      "roomNumber": 14,
      "roomRate": 143.99,
      "noShow": false
    },
    "customFields": {
      "exampleKey": "Example string"
    }
  },
  "tokenex": {
    "lastFour": "1111",
    "success": true,
    "customerRefNumber": "74771a19-3c28-4c27-83c6-9",
    "cardType": "visa",
    "sesssionID": "115a44ea7f804229acd7c88d5e15b988",
    "error": true,
    "token": "aafb1033-599a-4392-859e-f98033fc37f5"
  },
  "processingOptions": {
    "merchantId": "string",
    "verboseResponse": true,
    "webhookUrl": "",
    "webhookFailUrl": "The URL provided in <code>webhookUrl</code>"
  }
}'

POST /pay/v3/processECheck

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

Parameters

Name Type Description
bank
Required
object Bank account information. Required if tokenex.token is not included
data
Required
object Transaction data
tokenex object A previously saved e-check token. Required if the bank object is not included
processingOptions object Processing Options

Example responses

200 Response

{
  "id": "eyJuYW1lIjoidXNhZXBheSIsInJlZk51bWJlciI6IjMxMDA5MDc4MTkiLCJtZXJjaGFudElkIjoiMTAwMDM5IiwicmFuZG9tIjoiMzEwMDkwNzgxOSIsImN1cnJlbmN5IjoiVVNEIn0=",
  "isAuthOnly": true,
  "merchantId": "100039",
  "transactionDate": "2019-01-15T13:19:39.329Z",
  "authCode": "035410",
  "transactionStatus": "pending",
  "amount": 34.25,
  "transactionType": "sale",
  "currency": "USD",
  "gatewayResponse": {
    "result": "Approved",
    "batchRef": "2226631049",
    "refNumber": "3107885809",
    "additionalRefNumber": "299471011",
    "trackingCode": "string",
    "gatewayName": "nmi",
    "message": "Success",
    "installment": "string"
  },
  "data": {
    "amount": 29.99,
    "currency": "USD",
    "settlementCurrency": "CAD",
    "customer": {
      "firstName": "John",
      "lastName": "Doe",
      "invoice": "IN0001",
      "orderNumber": "210058A",
      "birthDate": "1990-12-05",
      "customerRef": "RP006",
      "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",
      "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",
      "roomNumber": 14,
      "roomRate": 143.99,
      "noShow": false
    },
    "customFields": {
      "exampleKey": "Example string"
    }
  },
  "card": {
    "expirationMonth": "12",
    "expirationYear": "20",
    "cardType": "visa",
    "cardHolder": "John H Doe"
  },
  "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}"
  }
}

Responses

Status Meaning Description
200 OK success

Response Schema

Status Code 200

Name Type Description
id string Nexio Payment ID
isAuthOnly boolean Will be true if the transaction was only authorized. Will be false if the transaction was authorized and captured
merchantId string The merchant ID through which the transaction was processed
transactionDate string The transaction date
authCode string The authorization code
transactionStatus string The transaction status
amount number The transaction amount
transactionType string The transaction type
currency string The three-character currency code
gatewayResponse object Gateway specific information. Included keys may vary by gateway
data object Transaction data
card object Credit card information
kountResponse object Fraud data and rules

Run E-check Transaction Iframe

Example request

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

GET /pay/v3/processECheck

Returns an iframe that can be used to securely process an e-check transaction

Parameters

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

Example responses

200 Response

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

Responses

Status Meaning Description
200 OK Success

Void Transaction

Example request

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

POST /pay/v3/void

Allows you to void a credit card transaction using the Nexio Payment ID. To do so:

  1. Run a transaction using the Run Card Transaction endpoint.
  2. Retrieve the id from the response. This is the Nexio Payment ID.
  3. Include the id in the body of your request to this endpoint.

Parameters

Name Type Description
id
Required
string The Nexio Payment ID. (To void a transaction through this endpoint it must have been captured through the Nexio Payment API)

Example responses

200 Response

{
  "id": "eyJuYW1lIjoidXNhZXBheSIsInJlZk51bWJlciI6IjMxMDA5MDc4MTkiLCJtZXJjaGFudElkIjoiMTAwMDM5IiwicmFuZG9tIjoiMzEwMDkwNzgxOSIsImN1cnJlbmN5IjoiVVNEIn0=",
  "merchantId": "100100",
  "transactionDate": "2019-01-15T13:19:39.329Z",
  "authCode": "035410",
  "transactionStatus": "pending",
  "amount": 15.25,
  "transactionType": "sale",
  "currency": "USD",
  "gatewayResponse": {
    "result": "Approved",
    "batchRef": "2226631049",
    "refNumber": "3107885809",
    "additionalRefNumber": "299471011",
    "trackingCode": "string",
    "gatewayName": "nmi",
    "message": "Success",
    "installment": "string"
  },
  "data": {
    "amount": 29.99,
    "currency": "USD",
    "settlementCurrency": "CAD"
  },
  "message": "success"
}

Responses

Status Meaning Description
200 OK Success
400 Bad Request Bad Request

Response Schema

Status Code 200

Name Type Description
id string Nexio Payment ID
merchantId string The merchant ID through which the transaction was originally run
transactionDate string The transaction date
authCode string The authorization code
transactionStatus string The transaction status
amount number The amount to be voided
transactionType string The transaction type
currency string The three-character ISO currency code for the transaction
gatewayResponse object Gateway specific information. Included keys may vary by gateway
data object Transaction data
message string none

Capture Transaction

Example request

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

POST /pay/v3/capture

Allows you to capture an auth only transaction. To do so:

  1. Run an auth only transaction using the Run Card Transaction endpoint.
  2. Retrieve the id from the response. This is the Nexio Payment ID.
  3. Include the id in the body of your request to this endpoint.

Parameters

Name Type Description
id
Required
string The Nexio Payment ID
data
Required
object Transaction data

Example responses

200 Response

{
  "id": "eyJuYW1lIjoidXNhZXBheSIsInJlZk51bWJlciI6IjMxMDA5MDc4MTkiLCJtZXJjaGFudElkIjoiMTAwMDM5IiwicmFuZG9tIjoiMzEwMDkwNzgxOSIsImN1cnJlbmN5IjoiVVNEIn0=",
  "merchantId": "100100",
  "transactionDate": "2019-01-15T13:19:39.329Z",
  "authCode": "035410",
  "transactionStatus": "pending",
  "amount": 15.25,
  "transactionType": "sale",
  "currency": "USD",
  "gatewayResponse": {
    "result": "Approved",
    "batchRef": "2226631049",
    "refNumber": "3107885809",
    "additionalRefNumber": "299471011",
    "trackingCode": "string",
    "gatewayName": "nmi",
    "message": "Success",
    "installment": "string"
  },
  "data": {
    "amount": 29.99,
    "currency": "USD",
    "settlementCurrency": "CAD"
  },
  "message": "success"
}

Responses

Status Meaning Description
200 OK Success

Response Schema

Status Code 200

Name Type Description
id string Nexio Payment ID
merchantId string The merchant ID through which the transaction was originally run
transactionDate string The transaction date
authCode string The authorization code
transactionStatus string The transaction status
amount number The amount to be captured
transactionType string The transaction type
currency string The three-character ISO currency code for the transaction
gatewayResponse object Gateway specific information. Included keys may vary by gateway
data object Transaction data
message string none

Refund Transaction

Example request

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

POST /pay/v3/refund

Allows you to refund a credit card transaction using the Nexio Payment ID. To do so:

  1. Run a transaction using the Run Credit Card Transaction endpoint.
  2. Retrieve the id from the response. This is the Nexio Payment ID.
  3. Include the id in the body of your request to this endpoint.

Parameters

Name Type Description
id
Required
string The Nexio Payment ID. (To void a transaction through this endpoint it must have been captured through the Nexio Payment API)
data
Required
object none

Example responses

200 Response

{
  "id": "eyJuYW1lIjoidXNhZXBheSIsInJlZk51bWJlciI6IjMxMDA5MDc4MTkiLCJtZXJjaGFudElkIjoiMTAwMDM5IiwicmFuZG9tIjoiMzEwMDkwNzgxOSIsImN1cnJlbmN5IjoiVVNEIn0=",
  "merchantId": "100100",
  "transactionDate": "2019-01-15T13:19:39.329Z",
  "authCode": "035410",
  "transactionStatus": "pending",
  "amount": 15.25,
  "transactionType": "sale",
  "currency": "USD",
  "gatewayResponse": {
    "result": "Approved",
    "batchRef": "2226631049",
    "refNumber": "3107885809",
    "additionalRefNumber": "299471011",
    "trackingCode": "string",
    "gatewayName": "nmi",
    "message": "Success",
    "installment": "string"
  },
  "data": {
    "amount": 29.99,
    "currency": "USD",
    "settlementCurrency": "CAD"
  },
  "message": "success"
}

Responses

Status Meaning Description
200 OK Success

Response Schema

Status Code 200

Name Type Description
id string Nexio Payment ID
merchantId string The merchant ID through which the transaction was originally run
transactionDate string The transaction date
authCode string The authorization code
transactionStatus string The transaction status
amount number The amount to be refunded
transactionType string The transaction type
currency string The three-character ISO currency code for the transaction
gatewayResponse object Gateway specific information. Included keys may vary by gateway
data object Transaction data
message string none

View Card Token

Example request

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

GET /pay/v3/vault/card/{cardToken}

Allows you to view details of a specific card token.

Parameters

Name Type Description
cardToken
Required
string The card token you wish to view

Example responses

200 Response

{
  "key": "aafb1033-599a-4392-859e-f98033fc37f5.5292712865664733",
  "merchantId": "100100",
  "data": {
    "lodging": {
      "advanceDeposit": true,
      "checkInDate": "2018-12-31",
      "checkOutDate": "2019-01-05",
      "roomNumber": 14,
      "roomRate": 143.99,
      "noShow": false
    },
    "allowedCardTypes": [
      "discover"
    ],
    "customFields": {
      "exampleKey": "Example string"
    },
    "paymentMethod": "creditCard",
    "description": "string",
    "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": {
      "firstName": "John",
      "lastName": "Doe",
      "invoice": "IN0001",
      "orderNumber": "210058A",
      "birthDate": "1990-12-05",
      "customerRef": "RP006",
      "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",
      "shipToAddressOne": "1725 Slough Avenue",
      "shipToAddressTwo": "Suite 200",
      "shipToCity": "Scranton",
      "shipToState": "PA",
      "shipToPostal": "18505",
      "shipToCountry": "US",
      "shipToPhone": "1555555555"
    }
  },
  "tokenex": {
    "lastFour": "1111",
    "success": true,
    "customerRefNumber": "74771a19-3c28-4c27-83c6-9",
    "cardType": "visa",
    "sesssionID": "115a44ea7f804229acd7c88d5e15b988",
    "error": true,
    "token": "aafb1033-599a-4392-859e-f98033fc37f5"
  },
  "dateCreated": "2019-07-31T17:02:39.035Z",
  "dateLastModified": "2019-07-31T18:33:30.660Z",
  "card": {
    "expirationMonth": "07",
    "expirationYear": "2022",
    "cardHolderName": "Jane Doe"
  },
  "originalCard": {
    "expirationMonth": "07",
    "expirationYear": "2019",
    "cardHolderName": "Jane Doe"
  },
  "tokenHistory": [
    {
      "token": "blf38djf-599a-4392-859e-f293jf837f5",
      "lastFour": "1111",
      "firstSix": "123456",
      "createdAt": "string"
    }
  ],
  "accountUpdaterStatus": "isExcluded",
  "shouldUpdateCard": true
}

Responses

Status Meaning Description
200 OK Success

Response Schema

Status Code 200

Name Type Description
key string The primary key used to identify the token in Nexio's database
merchantId string The merchant account under which the card token is saved
data object Additional data attached to the card token
tokenex object E-check token information
dateCreated string The date and time at which the card was created
dateLastModified string The date and time at which the card was last modified
card object Card information
originalCard object Original card details
tokenHistory array An array of card objects
accountUpdaterStatus string The card's account updater status. See this table for a list of possible values and their meanings
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

Edit Card Token

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 '{
  "card": {
    "expirationMonth": "12",
    "expirationYear": "22",
    "cardHolderName": "Jane Doe"
  },
  "data": {
    "customer": {
      "firstName": "John",
      "lastName": "Doe",
      "invoice": "IN0001",
      "orderNumber": "210058A",
      "birthDate": "1990-12-05",
      "customerRef": "RP006",
      "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",
      "shipToAddressOne": "1725 Slough Avenue",
      "shipToAddressTwo": "Suite 200",
      "shipToCity": "Scranton",
      "shipToState": "PA",
      "shipToPostal": "18505",
      "shipToCountry": "US",
      "shipToPhone": "1555555555"
    }
  },
  "shouldUpdateCard": true
}'

PUT /pay/v3/vault/card/{cardToken}

Allows you to edit expiration date, account updater status, and customer information for an existing token.
Use this endpoint to register/deregister card tokens with the account updater service.
Note: Cards registered with the account updater service may take up to 72 hours to be deregistered.

Parameters

Name Type Description
cardToken
Required
string The card token you wish to edit. (Sent as a path parameter)
card object Card information you wish to edit. Only provided fields will be edited
data object Optional data you wish to edit. Only provided fields will be edited
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

Example responses

200 Response

{
  "card": {
    "expirationMonth": "07",
    "expirationYear": "2019",
    "cardHolderName": "Jane Doe"
  },
  "data": {
    "customer": {
      "firstName": "John",
      "lastName": "Doe",
      "invoice": "IN0001",
      "orderNumber": "210058A",
      "birthDate": "1990-12-05",
      "customerRef": "RP006",
      "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",
      "shipToAddressOne": "1725 Slough Avenue",
      "shipToAddressTwo": "Suite 200",
      "shipToCity": "Scranton",
      "shipToState": "PA",
      "shipToPostal": "18505",
      "shipToCountry": "US",
      "shipToPhone": "1555555555"
    }
  },
  "shouldUpdateCard": true,
  "accountUpdaterStatus": "isExcluded"
}

Responses

Status Meaning Description
200 OK Success

Response Schema

Status Code 200

Name Type Description
card object Card information
data object none
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
accountUpdaterStatus string The card's account updater status. See this table for a list of possible values and their meanings

Delete Card Tokens

Example request

curl -X POST https://api.nexiopaysandbox.com/pay/v3/deleteToken \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic <Your Basic Auth>'
  -d '{
  "tokens": [
    "p6711abg-41fd-m56a-81a1-t0k3n287799b"
  ]
}'

POST /pay/v3/deleteToken

Allows you to delete card tokens from the card vault.
Note: Cards registered with the account updater service may take up to 72 hours to be removed.

Parameters

Name Type Description
tokens
Required
array An array of card tokens

Example responses

200 Response

[
  {
    "key": "p6711abg-41fd-m56a-81a1-t0k3n287799b",
    "message": "Successfully removed from vault",
    "error": "",
    "status": "success"
  }
]

Responses

Status Meaning Description
200 OK Success

Response Schema

Status Code 200

Name Type Description
key string none
message string none
error string none
status string none

Retail

Simple Login

Example request

curl -X POST https://api.nexiopaysandbox.com/auth/v3/createSimpleLogin \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic <Your Basic Auth>'

POST /auth/v3/createSimpleLogin

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

Example responses

200 Response

{
  "username": "youremail@cmsonline.com",
  "key": "4f211fde-d135-4c91-afbc-bcdb73c0c504",
  "jwt": "t3jraWQiOiI3V2JrOFdSVVliMVljR2p3Mlhwd2swR3lIRWt6THcwVDRqckVhNVVVTjBnPSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiI4YWYzZTQwZC02Y2I0LTQ0ZWQtOWRlZS0yN2Y3NmNmNDc0YmMiLCJlbWFpbF92ZXJpZmllZCI6dHJ1ZSwiaXNzIjoiaHR0cHM6XC9cL2NvZ25pdG8taWRwLnVzLWVhc3QtMS5hbWF6b25hd3MuY29tXC91cy1lYXN0LTFfVlVEN21MeWNqIiwiY3VzdG9tOmFjY291bnRJZCI6ImVjN2NiOWJhLWQwMmQtNDhkYS1hY2I3LWI2ZWQ3YmJiZWQwMiIsImNvZ25pdG86dXNlcm5hbWUiOiJscm9ibGVkb0BjbXNvbmxpbmUuY29tIiwiYXVkIjoiNDBtZWQ2YnNybDZ1aWpnMmpmZzQwcmJzOGkiLCJldmVudF9pZCI6IjE0YmU5MWFjLTM0NjctMTFlOS9iNDZjLWMxMjdjYTkzZjA3NCIsInRva2VuX3VzZSI6ImlkIiwiYXV0aF90aW1lIjoxNTUwNTk1Mjk0LCJleHAiOjE1NTA1OTg4OTRsImN1c3RvbTphY2Nlc3NSaWdodHMiOiJ7XCJtZXJjaGFudElkc1wiOntcIjEwMDAzOVwiOlwiQVwiLFwiMTAwMDQxXCI6XCJBXCIsXCI1MTU3OTQwMDAwMTM1MDRcIjpcIkFcIixcIjkyMzYwMDAwMTEyNDUwM1wiOlwiQVwiLFwiOTIzNTAwMDAxNDMyNzQyXCI6XCJBXCIsXCI1MTM0ODUwMDAwMDAwMThcIjpcIkFcIixcIjkyMzYwMDAwODEyNjYxMFwiOlwiQVwiLFwiOTIzNjAwMDAzMTYzODEwXCI6XCJBXCJ9LFwicm9sZVwiOlwiQVwifSIsImlhdCI6MTU1MDU5NTI5NCwiZW1haWwiOiJscm9ibGVkb0BjbXNvbmxpbmUuY29tIn0.OEEZarSzbSLpxUM55UKmycYtAAWEtm__XUJdqBJ9QPSF_8sdLIL9EXBF8cLarhv3DoLqeWKUpieNgfcME2IsIc8amDXitvJtJe3STQtI_zaJwAibBxJhFKQRLRCrIe3kpslVJPuw3OeST54QcseifLlA64bxNaveXygja7aejwINueE4_Nj0NEzcFGZoYHgNB6br6Ksbjgx-z_SiFIZ1XHS-eOMnBoCIVWjFr3FY9IbfnQf4v0c0AFWKt9mOpjYracSqOHHmSER7GuaMBNrHxfbe0kHVh6hvnrzh10SEnTsF573qbP1R_aZA_Uh80MOLB0UvPWWFzzyP4GniNc3zLw",
  "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",
  "exp": 1550600014
}

Responses

Status Meaning Description
200 OK Success

Response Schema

Status Code 200

Name Type Description
username string The simple login username
key string The simple login key
jwt string The JWT
refreshToken string The refresh token
exp integer The expiration time of the Simple Login

Get Terminal List

Example request

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

GET /pay/v3/getTerminalList

Retrieves a list of available terminals.
Note: Before terminals are made available for processing, they are first configured in the gateway account directly by Nexio integration support. If you do not see a terminal in the list retrieved here, contact Integration Support for assistance.

Example responses

200 Response

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

Responses

Status Meaning Description
200 OK Success

Response Schema

Status Code 200

Name Type Description

Process from Terminal

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

POST /pay/v3/processFromTerminal

Initiates a terminal transaction. See these steps for more information on how to process through EMV.

Parameters

Name Type Description
data
Required
object Transaction data
terminalId string An ID used to identify a specific terminal. For a list of terminal IDs see the Get Terminal List endpoint.

Example responses

200 Response

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

Responses

Status Meaning Description
200 OK Success

Response Schema

Status Code 200

Name Type Description
terminalRequestStatus string The status of the transaction initiated using a terminal
terminalRequestId string An ID used to identify a transaction initiated using a terminal

Terminal Transaction Status

Example request

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

GET /pay/v3/processFromTerminal/{terminalRequestId}

Checks the status of a transaction run through the terminal.

Parameters

Name Type Description
terminalRequestId
Required
string The terminal request ID. Found in the response of Process from Terminal endpoint

Example responses

200 Response

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

Responses

Status Meaning Description
200 OK Success
490 Unknown Error

Response Schema

Status Code 200

Name Type Description
terminalRequestStatus string The status of the transaction initiated using a terminal
terminalRequestId string An ID used to identify a transaction initiated using a terminal
gatewayResponse object Gateway specific information. Included keys may vary by gateway

Status Code 490

Name Type Description
message string The response message
error integer The error code, if applicable
gatewayResponse object Gateway specific information. Included keys may vary by gateway

Subscriptions

Create Subscription

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": 29.99,
      "currency": "USD",
      "customer": {
        "firstName": "John",
        "lastName": "Doe",
        "invoice": "IN0001",
        "orderNumber": "210058A",
        "birthDate": "1990-12-05",
        "customerRef": "RP006",
        "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",
        "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",
        "roomNumber": 14,
        "roomRate": 143.99,
        "noShow": false
      },
      "customFields": {
        "exampleKey": "Example string"
      },
      "description": "test purchase",
      "descriptor": ""
    },
    "tokenex": {
      "token": "6ee140a0-05d1-4958-8325-b38a690dbb9d",
      "firstSix": "479300",
      "lastFour": "3313"
    },
    "isAuthOnly": false,
    "processingOptions": {
      "checkFraud": false,
      "check3ds": true,
      "merchantId": "string",
      "paymentOptionTag": "switch",
      "shouldUseFingerprint": true,
      "verboseResponse": true,
      "webhookUrl": "",
      "webhookFailUrl": "The URL provided in <code>webhookUrl</code>"
    }
  },
  "schedule": {
    "interval": "month",
    "intervalCount": 0
  }
}'

POST /subscription/v3

Creates a recurring payment. A successful request to this endpoint will:

  1. Process a payment with the values provided in the payment object
  2. Schedule recurring payments with the values provided in the schedule object

Note: This service is in beta. Contact integration support if you would like to use this feature.

Parameters

Name Type Description
payment
Required
object Payment information for initial and future payments
schedule object The schedule for future payments

Example responses

200 Response

{
  "customerRef": "RP006",
  "accountId": "27592004",
  "id": "e80d63dd-a77b-407a-9124-42acf00740dd",
  "payment": {
    "isAuthOnly": true,
    "data": {
      "amount": 29.99,
      "currency": "USD",
      "customer": {
        "firstName": "John",
        "lastName": "Doe",
        "invoice": "IN0001",
        "orderNumber": "210058A",
        "birthDate": "1990-12-05",
        "customerRef": "RP006",
        "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",
        "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",
        "roomNumber": 14,
        "roomRate": 143.99,
        "noShow": false
      },
      "customFields": {
        "exampleKey": "Example string"
      },
      "description": "test purchase",
      "descriptor": ""
    },
    "tokenex": {
      "token": "6ee140a0-05d1-4958-8325-b38a690dbb9d",
      "firstSix": "479300",
      "lastFour": "3313"
    },
    "processingOptions": {
      "checkFraud": false,
      "check3ds": true,
      "merchantId": "string",
      "paymentOptionTag": "switch",
      "shouldUseFingerprint": true,
      "verboseResponse": true,
      "webhookUrl": "",
      "webhookFailUrl": "The URL provided in <code>webhookUrl</code>"
    }
  },
  "schedule": {
    "interval": "month",
    "intervalCount": 0
  },
  "paymentResponse": {
    "id": "eyJuYW1lIjoidXNhZXBheSIsInJlZk51bWJlciI6IjMxMDA5MDc4MTkiLCJtZXJjaGFudElkIjoiMTAwMDM5IiwicmFuZG9tIjoiMzEwMDkwNzgxOSIsImN1cnJlbmN5IjoiVVNEIn0=",
    "isAuthOnly": true,
    "merchantId": "100039",
    "transactionDate": "2019-01-15T13:19:39.329Z",
    "authCode": "035410",
    "transactionStatus": "pending",
    "amount": 34.25,
    "transactionType": "sale",
    "currency": "USD",
    "gatewayResponse": {
      "result": "Approved",
      "batchRef": "2226631049",
      "refNumber": "3107885809",
      "additionalRefNumber": "299471011",
      "trackingCode": "string",
      "gatewayName": "nmi",
      "message": "Success",
      "installment": "string"
    },
    "data": {
      "amount": 29.99,
      "currency": "USD",
      "settlementCurrency": "CAD",
      "customer": {
        "firstName": "John",
        "lastName": "Doe",
        "invoice": "IN0001",
        "orderNumber": "210058A",
        "birthDate": "1990-12-05",
        "customerRef": "RP006",
        "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",
        "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",
        "roomNumber": 14,
        "roomRate": 143.99,
        "noShow": false
      },
      "customFields": {
        "exampleKey": "Example string"
      }
    },
    "card": {
      "expirationMonth": "12",
      "expirationYear": "20",
      "cardType": "visa",
      "cardHolder": "John H Doe"
    },
    "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}"
    }
  },
  "userName": "jdoe@yourwebsite.com",
  "dateCreated": "2020-04-28T19:19:33.183Z",
  "dateLastModified": "2020-04-28T19:19:33.185Z",
  "dateLastRun": "2020-04-28T18:50:04.866Z",
  "dateNextRun": "2020-07-28"
}

Responses

Status Meaning Description
200 OK Success

Response Schema

Status Code 200

Name Type Description
customerRef string Customer identifier. You can use this field to pass a customer ID to the gateway or APM or to manage user subscriptions
accountId string Your Nexio account number
id string The subscription ID
payment object Payment information for future payments
schedule object The schedule for future payments
paymentResponse object The response from a successful payment. (In the case of a subscription, this is the response of the initial payment)
userName string The username of the account through which the subscription was created
dateCreated string The date and time the subscription was created
dateLastModified string The date and time the subscription was last modified
dateLastRun string The date and time a payment in this subscription was last run
dateNextRun string The date a payment in this subscription is next scheduled to run

Update Subscription

Example request

curl -X PUT https://api.nexiopaysandbox.com/subscription/v3 \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic <Your Basic Auth>'
  -d '{
  "payment": {
    "isAuthOnly": true,
    "data": {
      "customer": {
        "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",
        "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",
        "roomNumber": 14,
        "roomRate": 143.99,
        "noShow": false
      },
      "customFields": {
        "exampleKey": "Example string"
      },
      "description": "test purchase",
      "descriptor": ""
    },
    "processingOptions": {
      "checkFraud": false,
      "merchantId": "string",
      "paymentOptionTag": "switch",
      "shouldUseFingerprint": true,
      "verboseResponse": true,
      "webhookUrl": "",
      "webhookFailUrl": "The URL provided in <code>webhookUrl</code>"
    }
  },
  "schedule": {
    "interval": "month",
    "intervalCount": 0
  }
}'

PUT /subscription/v3

Updates an existing payment subscription. Card token, currency, amount, and customer reference cannot be updated. If you need to change any of these values, delete the existing subscription and create a new one. The only user with rights to edit the subscription is the original creator.

Note: This service is in beta. Contact integration support if you would like to use this feature.

Parameters

Name Type Description
payment object Payment information for future payments
schedule object The schedule for future payments

Example responses

200 Response

{
  "customerRef": "RP006",
  "accountId": "27592004",
  "id": "e80d63dd-a77b-407a-9124-42acf00740dd",
  "payment": {
    "isAuthOnly": true,
    "data": {
      "amount": 29.99,
      "currency": "USD",
      "settlementCurrency": "CAD",
      "customer": {
        "firstName": "John",
        "lastName": "Doe",
        "invoice": "IN0001",
        "orderNumber": "210058A",
        "birthDate": "1990-12-05",
        "customerRef": "RP006",
        "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",
        "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",
        "roomNumber": 14,
        "roomRate": 143.99,
        "noShow": false
      },
      "customFields": {
        "exampleKey": "Example string"
      },
      "description": "test purchase",
      "descriptor": "",
      "secCode": "ICL"
    },
    "tokenex": {
      "token": "6ee140a0-05d1-4958-8325-b38a690dbb9d",
      "firstSix": "479300",
      "lastFour": "3313"
    },
    "processingOptions": {
      "checkFraud": false,
      "check3ds": true,
      "merchantId": "string",
      "paymentOptionTag": "switch",
      "shouldUseFingerprint": true,
      "verboseResponse": true,
      "webhookUrl": "",
      "webhookFailUrl": "The URL provided in <code>webhookUrl</code>"
    }
  },
  "schedule": {
    "interval": "month",
    "intervalCount": 0
  },
  "userName": "jdoe@yourwebsite.com",
  "dateCreated": "2020-04-28T19:19:33.183Z",
  "dateLastModified": "2020-04-28T19:19:33.185Z",
  "dateLastRun": "2020-04-28T18:50:04.866Z",
  "dateNextRun": "2020-07-28"
}

Responses

Status Meaning Description
200 OK Success

Response Schema

Status Code 200

Name Type Description
customerRef string Customer identifier. You can use this field to pass a customer ID to the gateway or APM or to manage user subscriptions
accountId string Your Nexio account number
id string The subscription ID
payment object Payment information for future payments
schedule object The schedule for future payments
userName string The username of the account through which the subscription was created
dateCreated string The date and time the subscription was created
dateLastModified string The date and time the subscription was last modified
dateLastRun string The date and time a payment in this subscription was last run
dateNextRun string The date a payment in this subscription is next scheduled to run

Get Subscription

Example request

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

GET /subscription/v3/{id}

Returns the payment information and schedule for an existing subscription.

Note: This service is in beta. Contact integration support if you would like to use this feature.

Parameters

Name Type Description
id
Required
string The subscription ID

Example responses

200 Response

{
  "customerRef": "RP006",
  "accountId": "27592004",
  "id": "e80d63dd-a77b-407a-9124-42acf00740dd",
  "payment": {
    "isAuthOnly": true,
    "data": {
      "amount": 29.99,
      "currency": "USD",
      "settlementCurrency": "CAD",
      "customer": {
        "firstName": "John",
        "lastName": "Doe",
        "invoice": "IN0001",
        "orderNumber": "210058A",
        "birthDate": "1990-12-05",
        "customerRef": "RP006",
        "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",
        "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",
        "roomNumber": 14,
        "roomRate": 143.99,
        "noShow": false
      },
      "customFields": {
        "exampleKey": "Example string"
      },
      "description": "test purchase",
      "descriptor": "",
      "secCode": "ICL"
    },
    "tokenex": {
      "token": "6ee140a0-05d1-4958-8325-b38a690dbb9d",
      "firstSix": "479300",
      "lastFour": "3313"
    },
    "processingOptions": {
      "checkFraud": false,
      "check3ds": true,
      "merchantId": "string",
      "paymentOptionTag": "switch",
      "shouldUseFingerprint": true,
      "verboseResponse": true,
      "webhookUrl": "",
      "webhookFailUrl": "The URL provided in <code>webhookUrl</code>"
    }
  },
  "schedule": {
    "interval": "month",
    "intervalCount": 0
  },
  "userName": "jdoe@yourwebsite.com",
  "dateCreated": "2020-04-28T19:19:33.183Z",
  "dateLastModified": "2020-04-28T19:19:33.185Z",
  "dateLastRun": "2020-04-28T18:50:04.866Z",
  "dateNextRun": "2020-07-28"
}

Responses

Status Meaning Description
200 OK Success

Response Schema

Status Code 200

Name Type Description
customerRef string Customer identifier. You can use this field to pass a customer ID to the gateway or APM or to manage user subscriptions
accountId string Your Nexio account number
id string The subscription ID
payment object Payment information for future payments
schedule object The schedule for future payments
userName string The username of the account through which the subscription was created
dateCreated string The date and time the subscription was created
dateLastModified string The date and time the subscription was last modified
dateLastRun string The date and time a payment in this subscription was last run
dateNextRun string The date a payment in this subscription is next scheduled to run

Delete Subscription

Example request

curl -X DELETE https://api.nexiopaysandbox.com/subscription/v3/{id} \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic <Your Basic Auth>'

DELETE /subscription/v3/{id}

Deletes an existing payment subscription.

Note: This service is in beta. Contact integration support if you would like to use this feature.

Parameters

Name Type Description
id
Required
string The subscription ID

Example responses

200 Response

{
  "customerRef": "RP006",
  "accountId": "27592004",
  "id": "e80d63dd-a77b-407a-9124-42acf00740dd",
  "payment": {
    "isAuthOnly": true,
    "data": {
      "amount": 29.99,
      "currency": "USD",
      "settlementCurrency": "CAD",
      "customer": {
        "firstName": "John",
        "lastName": "Doe",
        "invoice": "IN0001",
        "orderNumber": "210058A",
        "birthDate": "1990-12-05",
        "customerRef": "RP006",
        "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",
        "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",
        "roomNumber": 14,
        "roomRate": 143.99,
        "noShow": false
      },
      "customFields": {
        "exampleKey": "Example string"
      },
      "description": "test purchase",
      "descriptor": "",
      "secCode": "ICL"
    },
    "tokenex": {
      "token": "6ee140a0-05d1-4958-8325-b38a690dbb9d",
      "firstSix": "479300",
      "lastFour": "3313"
    },
    "processingOptions": {
      "checkFraud": false,
      "check3ds": true,
      "merchantId": "string",
      "paymentOptionTag": "switch",
      "shouldUseFingerprint": true,
      "verboseResponse": true,
      "webhookUrl": "",
      "webhookFailUrl": "The URL provided in <code>webhookUrl</code>"
    }
  },
  "schedule": {
    "interval": "month",
    "intervalCount": 0
  },
  "userName": "jdoe@yourwebsite.com",
  "dateCreated": "2020-04-28T19:19:33.183Z",
  "dateLastModified": "2020-04-28T19:19:33.185Z",
  "dateLastRun": "2020-04-28T18:50:04.866Z",
  "dateNextRun": "2020-07-28"
}

Responses

Status Meaning Description
200 OK Success

Response Schema

Status Code 200

Name Type Description
customerRef string Customer identifier. You can use this field to pass a customer ID to the gateway or APM or to manage user subscriptions
accountId string Your Nexio account number
id string The subscription ID
payment object Payment information for future payments
schedule object The schedule for future payments
userName string The username of the account through which the subscription was created
dateCreated string The date and time the subscription was created
dateLastModified string The date and time the subscription was last modified
dateLastRun string The date and time a payment in this subscription was last run
dateNextRun string The date a payment in this subscription is next scheduled to run

Get Customer Subscriptions

Example request

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

GET /subscription/v3/customerRef/{customerRef}

Returns a list of subscriptions for a given customer reference.

Parameters

Name Type Description
customerRef
Required
string The customer reference

Example responses

200 Response

[
  {
    "customerRef": "RP006",
    "accountId": "27592004",
    "id": "e80d63dd-a77b-407a-9124-42acf00740dd",
    "payment": {
      "isAuthOnly": true,
      "data": {
        "amount": 29.99,
        "currency": "USD",
        "settlementCurrency": "CAD",
        "customer": {
          "firstName": "John",
          "lastName": "Doe",
          "invoice": "IN0001",
          "orderNumber": "210058A",
          "birthDate": "1990-12-05",
          "customerRef": "RP006",
          "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",
          "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",
          "roomNumber": 14,
          "roomRate": 143.99,
          "noShow": false
        },
        "customFields": {
          "exampleKey": "Example string"
        },
        "description": "test purchase",
        "descriptor": "",
        "secCode": "ICL"
      },
      "tokenex": {
        "token": "6ee140a0-05d1-4958-8325-b38a690dbb9d",
        "firstSix": "479300",
        "lastFour": "3313"
      },
      "processingOptions": {
        "checkFraud": false,
        "check3ds": true,
        "merchantId": "string",
        "paymentOptionTag": "switch",
        "shouldUseFingerprint": true,
        "verboseResponse": true,
        "webhookUrl": "",
        "webhookFailUrl": "The URL provided in <code>webhookUrl</code>"
      }
    },
    "schedule": {
      "interval": "month",
      "intervalCount": 0
    },
    "userName": "jdoe@yourwebsite.com",
    "dateCreated": "2020-04-28T19:19:33.183Z",
    "dateLastModified": "2020-04-28T19:19:33.185Z",
    "dateLastRun": "2020-04-28T18:50:04.866Z",
    "dateNextRun": "2020-07-28"
  }
]

Responses

Status Meaning Description
200 OK Success

Response Schema

Status Code 200

Name Type Description
customerRef string Customer identifier. You can use this field to pass a customer ID to the gateway or APM or to manage user subscriptions
accountId string Your Nexio account number
id string The subscription ID
payment object Payment information for future payments
schedule object The schedule for future payments
userName string The username of the account through which the subscription was created
dateCreated string The date and time the subscription was created
dateLastModified string The date and time the subscription was last modified
dateLastRun string The date and time a payment in this subscription was last run
dateNextRun string The date a payment in this subscription is next scheduled to run

Alternative Payment Methods

APM One-time-use Token

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": false,
  "data": {
    "amount": 29.99,
    "currency": "USD",
    "dueDate": "2020-01-01 23:59",
    "paymentMethod": "payPal",
    "description": "test purchase",
    "customer": {
      "firstName": "Maria",
      "lastName": "Velasquez",
      "email": "mvelaquez@fake.email",
      "orderNumber": "210058A",
      "invoice": "IN0001",
      "billToAddressOne": "2147 West Silverlake Drive",
      "billToAddressTwo": "Apt 42",
      "billToCity": "San Francisco",
      "billToState": "PA",
      "billToPostal": "94115",
      "billToCountry": "US",
      "billToPhone": "1555555555",
      "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",
      "roomNumber": 14,
      "roomRate": 143.99,
      "noShow": false
    },
    "customFields": {
      "exampleKey": "Example string"
    },
    "secCode": "ICL"
  },
  "customerRedirectUrl": "www.your-ecommcerce-website.com",
  "processingOptions": {
    "merchantId": "string",
    "webhookUrl": "",
    "webhookFailUrl": "The URL provided in <code>webhookUrl</code>"
  },
  "uiOptions": {
    "displaySubmitButton": true,
    "css": "https://tester.nexiopaysandbox.com/example1.css"
  }
}'

POST /apm/v3/token

A token from this endpoint is necessary prior to loading any of the Alternative Payment Method iframes.

Any data (amount, currency, etc.) that you wish to be sent to the alternate payment method must be included in the body of this request.

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
isAuthOnly boolean Set to true to run an auth only transaction
Default: false
data
Required
object Transaction data
customerRedirectUrl string The URL to which the customer will be redirected after completing their payment. The customer will be sent here upon successful or failed payment
processingOptions object Processing Options
uiOptions object Used to customize the iframe's user interface

Detailed descriptions

isAuthOnly: Set to true to run an auth only transaction

Note: Auth only transactions are currently only supported through PayPal

Example responses

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

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.
token string Your one-time-use token
expressIFrameUrl string The Express APM redirect URL. Will allow the user to choose from a list of available APMs before redirecting for payment. See the [Express APM](#express-apm) tutorial for more information
redirectUrls array A collection of redirect URLs. Used to send a customer directly to a single APM. See the [Integrate with a Single APM](#single-apm) tutorial for more information

APM Iframe

Example request

curl -X GET https://api.nexiopaysandbox.com/apm/v3?token=477d626c-9d29-46cf-8a41-abab04874eac \
  -H 'One-time-use Token: API_KEY'

GET /apm/v3

Returns an iframe that will allow a user to redirect to the chosen alternative payment method's web page in a new window.

The alternative payment method must be chosen upon retrieval of a One-time-use token.

Note: This iframe will emit events, alerting you when the transaction has been submitted, processed, etc.

Parameters

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

Responses

Status Meaning Description
200 OK Success
401 Unauthorized Unauthorized

Capture APM Transaction

Example request

curl -X POST https://api.nexiopaysandbox.com/apm/v3/capture \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic <Your Basic Auth>'
  -d '{
  "id": "eyJuYW1lIjoidXNhZXBheSIsInJlZk51bWJlciI6IjMxMDA5MDc4MTkiLCJtZXJjaGFudElkIjoiMTAwMDM5IiwicmFuZG9tIjoiMzEwMDkwNzgxOSIsImN1cnJlbm