Quick Start
Introduction
The new developer portal is at https://docs.nexiopay.com
This is the old version of the documentation. It has not been updated since March 2022.
This old version of the site will only be available until September 30, 2022.
If you have any questions about the new documentation, please contact us.
Welcome to Nexio’s API documentation. From start-ups to enterprise businesses, Nexio will help you manage your customer’s experience from start to finish. The Nexio Hub manages the payment process for credit cards, alternative payment methods, international currencies, fraud mitigation, and more.
In this documentation you will find tutorials and our complete API Reference. To see what's new, check out our release notes. For more code samples (including PHP, Node, C# and plugin examples for WooCommerce and Magento), see our code examples on GitHub. To start sending test requests without writing any code, download and explore our Postman collection using the button below.
Getting Started
Requirements
To get started using the Nexio API you will need:
- Nexio credentials: To request credentials, send us a message at sandbox@nexiopay.com
- An HTTP client: Our API reference includes cURL examples. You can also download our Postman Collection or use your preferred HTTP client
Ready to get started?
Create Sandbox Test Account →
Base URLs and Environments
All endpoints are RESTful with the following base URLs:
-
Sandbox:
https://api.nexiopaysandbox.com
-
Production:
https://api.nexiopay.com
The sandbox environment allows you to run test transactions without affecting live data.
Once you have integrated with the sandbox environment you are ready to integrate to production with minimal changes. (Required updates include authentication information and encryption keys.)
Your First Request
A good place to start getting familiar with our API is by sending a request to the Who Am I endpoint.
A successful request to this endpoint will return information about the user whose credentials have been used to authenticate the request, including:
- First Name
- Last Name
- Username
- A list of merchants to which the user has access rights
To send a request, follow the steps below:
-
Authenticate via basic authentication.
-
Send a
GET
request to the Who Am I endpoint.
Example Request
curl -X GET https://api.nexiopaysandbox.com/user/v3/account/whoAmI \
-H 'Accept: application/json' \
-H 'Authorization: Basic <Your Basic Auth>'
Example 200 Response
{
"cognitoSub": "g52679a2-tan5-4a56-b6gc-2592aedd373e",
"firstName": "John",
"lastName": "Doe",
"userName": "jdoe@yourwebsite.com",
"accessRights": {
"merchantIds": {
"100039": "A"
},
"role": "A"
},
"dateLastModified": "2019-03-08T00:58:27.893Z",
"dateCreated": "2018-09-27T14:27:39.626Z",
"enabled": true,
"phone": "15555555555",
"notifications": false
}
Next steps
Once you have successfully made your first request, you are ready to move on. Depending on your workflow, you may wish to:
- Load a retail iframe
- Load an e-commerce iframe
- Use an alternative payment method
- Configure webhooks to notify you when transaction events take place
- Retrieve a list of transactions
- Dispute a chargeback
Contact Us
If you have additional questions, our integrations team is happy to help:
- Message us on Slack
- Email us at: integrations@nexiopay.com
If you would like to provide feedback on any part of this documentation, please email us at: docs@nexiopay.com
Authentication
Basic Authentication
To authenticate with basic authentication you will need a Nexio username and password. Please contact integration support to create a Nexio account.
-
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
-
Create the Authorization Header
Prefix the value from step 1 with the string "Basic ".
Example
Authorization: Basic bXluYW1lQG5leGlvaHViLmNvbTpteXBhc3N3b3Jk
-
Send a Request
Include the string from step 2 in authorization header of your API request.
Example
curl -X get https://api.nexiopaysandbox.com/user/v3/account/whoAmI \
-H 'Accept: application/json' \
-H 'Authorization: Basic bXluYW1lQG5leGlvaHViLmNvbTpteXBhc3N3b3Jk'
One-time-use Tokens
E-commerce
You will need a one-time-use token to load any e-commerce iframes or to save a card token via the API.
To get a one-time-use token, send a request to the E-Commerce One-time-use Token endpoint. Authenticate using basic authentication. Include any information you wish to pass along to the applicable iframe or popup in the body of your request. See the E-commerce One-time-use Token API Reference for a complete list of parameters.
Alternative Payment Methods
You will need a one-time-use token to load an Alternative Payment Method (APM) Iframe. To obtain an alternative payment method one-time-use token, send a request to the One-time-use Token (APM) endpoint. Authentication using basic authentication. Include any information you wish to pass along to the iframe in the body of your request. See the retail UI options section for a complete list.
Notes
- CORS requires that every request for a one-time-use token must be sent from a server. If you attempt to send a request a frontend you will receive an error
- One-time-use tokens for e-commerce iframes and alternative payment methods are not interchangeable
- Not all body parameters that may be included in the body of a request for a one-time-use token apply to every iframe or popup
- Each one-time-use token can only be used to submit a single form
- Each one-time-use token expires after one hour
E-commerce Flows & Operations
Overview
Getting Started
To get started with our e-commerce API, you will need a Nexio username and password. Contact integrations support to request credentials.
Prior to accessing any endpoint, you will be required to authenticate. Please see our API Reference for more information on the required authentication for each endpoint. The form of authentication required for each endpoint is listed in a yellow box at the top of each section.
Nexio's e-commerce API enables you to:
- Create a checkout page for your e-commerce website
- Create a save card page for your e-commerce website
- Authorize, Capture, Void and Refund card or e-check transactions
- Initiate a transaction using an alternative payment method
- Capture, Void and Refund alternative payment method transactions
- View transaction and chargeback reports, and deposit summaries,
- Dispute Chargebacks
- And more!
You will have hands-on control to:
- Translate iframe labels for localization
- Enable webhook notifications
- Customize the iframe's CSS to match your site's style
- Choose which fields to display or require
You can also choose to enable built-in fraud protection services, including:
Was this section helpful?
Create a Checkout Page
With the Nexio Iframe
- Create an Iframe on Your Web Page
Example
<html>
<iframe id="myIframe">
</iframe>
</html>
-
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)
}
});
-
Request a One-time-use Token
Send a
POST
request to the E-commerce One-time-use Token endpoint.
Example Request
curl -X POST https://api.nexiopaysandbox.com/pay/v3/token \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Basic <Your Basic Auth>'
-d '{
"data": {
"amount": 29.99,
"currency": "USD"
}
}'
Example 200 Response
{
"expiration": "2018-09-18T15:43:05.664Z",
"fraudUrl": "https://api.nexiopaysandbox.com/pay/v3/fingerprint?token=01080f80-76b8-4363-845d-67e8623bf170",
"token": "830d36f6-a5e3-4455-9600-3a55b63e2fc2"
}
-
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
orprocessingOptions
must be included in this step
-
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;
-
Create an Event Listener
Add an event listener to your form's submit button that will trigger a
POST
request inside the iframe. Now when a user clicks submit on your outer form, the iframe will submit itself. Because of the event listener you created in step 2, your code is aware of iframe responses and errors.
Example
myForm.addEventListener('submit', function processPayment(event) {
event.preventDefault();
const url = 'https://api.nexiopaysandbox.com';
myIframe.contentWindow.postMessage('posted', url);
return false; // keeps the form from auto submitting
});
With Your Own Form
-
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.
-
Create a Form on Your Web Page
Example
<html>
<form id="myForm">
</form>
</html>
-
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.
- Amount (
-
Send Payment Information to Your Server
-
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"
}
}'
-
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.
Was this section helpful?
Create a Save Card Page
With the Nexio Iframe
-
Create an Iframe on your Web Page
-
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)
}
});
-
Request a One-time-use Token
Send a
POST
request to the One-time-use Token (E-commerce) endpoint.
Example Request
curl -X POST https://api.nexiopaysandbox.com/pay/v3/token \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Basic <Your Basic Auth>'
-d '{}'
Example 200 Response
{
"expiration": "2018-09-18T15:43:05.664Z",
"fraudUrl": "https://api.nexiopaysandbox.com/pay/v3/fingerprint?token=01080f80-76b8-4363-845d-67e8623bf170",
"token": "830d36f6-a5e3-4455-9600-3a55b63e2fc2"
}
-
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
orprocessingOptions
must be included in this step
-
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;
-
Create an event listener
Add an event listener to your form's submit button that will trigger a
POST
request inside the iframe. Now when a user clicks submit on your outer form, the iframe will submit itself. Because of the event listener you created in step 2, your code is aware of iframe responses and errors.
Example
myForm.addEventListener('submit', function processPayment(event) {
event.preventDefault();
const url = 'https://api.nexiopaysandbox.com';
myIframe.contentWindow.postMessage('posted', url);
return false; // keeps the form from auto submitting
});
With Your Own Form
Please note that although card data never touches your servers, using your own form changes your PCI liability from SAQ A to SAQ A-EP.
- Create a Form on Your Web Page
Example
<html>
<form id="myForm">
</form>
</html>
-
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.
- Cardholder name (
-
Load the Form
Load the form on your page and allow the user to enter their information.
-
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.
-
Encrypt the Card Number
Prior to sending the card information to Nexio, you must encrypt it using browser-based encryption. To do so, follow the steps below.
a. Contact us to obtain the public key. While testing in the sandbox environment, you may use the sandbox public key, shown below.
Sandbox Public Key
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAvWpIQFjQQCPpaIlJKpeg
irp5kLkzLB1AxHmnLk73D3TJbAGqr1QmlsWDBtMPMRpdzzUM7ZwX3kzhIuATV4Pe
7RKp3nZlVmcrT0YCQXBrTwqZNh775z58GP2kZs+gVfNqBampJPzSB/hB62KkByhE
Cn6grrRjiAVwJyZVEvs/2vrxaEpO+aE16emtX12RgI5JdzdOiNyZEQteU6zRBRJE
ocPWVxExaOpVVVJ5+UnW0LcalzA+lRGRTrQJ5JguAPiAOzRPTK/lYFFpCAl/F8wt
oAVG1c8zO2NcQ0Pko+fmeidRFxJ/did2btV+9Mkze3mBphwFmvnxa35LF+Cs/XJHDwIDAQAB
b. Encrypt the card number using the public key and standard RSA encryption. See this JSFiddle for an example of how to encrypt data to be tokenized.
Note: If you want to store the token in your own database you must either use a callback or use the token returned in the event info.
If you do not perform browser-based encryption in the card holder's browser, you have full PCI liability.
-
Send Card Information to Your Server
Send the encrypted card number and other card information to your server.
-
Post Card Information to Nexio
a. Request a one-time-use token
b. Send a
POST
request from your server to Nexio's Save Card Token API endpoint with the one-time-use token and the card information.
Example Request
curl -X POST https://api.nexiopaysandbox.com/pay/v3/saveCard \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Basic <Your Basic Auth>'
-d '{
"card": {
"cardHolderName": "John H Doe",
"encryptedNumber": "cu3yRktaYFK2LUC6DpNK289tYDsGRCi7cO+GeG0hkeYFvT7Y8/oY5r53obMz6Q/BZ38gk2u2Ufwy8ojBcX2sfNjG5jplGTXA4NNlSIUjMFfiHe1sff1JFpThoiW/IIlifGlbWu+S1/9pqWPTzJ2+DcjwohbHzsDahhYewFhXgC8qsK0ypi/Shlp+CwRITyIvbVXESD0xz3YOTRHeZLlChvVqN8z4ZzN8nm0MXkmT1wcpYI73bH4KdnPwNU3s7XxvP/ernQP73SHHAOKSLlz4F6AEHFjJiCoXzeLF7LwEjRdxDJ0sKVXbRk3i9BGh+8Nle2VYgjpUWtk2763QkvZiQQ==",
"expirationMonth": "12",
"expirationYear": "20"
},
"token": "eb50a022-d6de-4244-a1e6-dcb8522b2d19"
}'
-
Listen for Nexio's Response
If Nexio returns a 200 status:
- Display a success page to the customer
- Save the card token (
tokenex.token
). You will need this token to run a transaction as well as to view, edit or delete the card token
If Nexio returns a non-200 status:
- Display a failure page to the customer
- Handle the error. See our list of common errors for more information
- Contact integration support if you need additional help
Was this section helpful?
Create an E-check Checkout Page
Create a checkout page for e-check (ACH) transactions, either by using the Nexio Iframe or with your own form.
Please note that e-check transactions cannot be voided or refunded.
With the Nexio Iframe
- Create an Iframe on Your Web Page
Example
<html>
<iframe id="myIframe">
</iframe>
</html>
-
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)
}
});
-
Request a One-time-use Token
Send a
POST
request to the E-commerce One-time-use Token endpoint.
Example Request
curl -X POST https://api.nexiopaysandbox.com/pay/v3/token \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Basic <Your Basic Auth>'
-d '{
"data": {
"amount": 29.99,
"currency": "USD"
}
}'
Example 200 Response
{
"expiration": "2018-09-18T15:43:05.664Z",
"fraudUrl": "https://api.nexiopaysandbox.com/pay/v3/fingerprint?token=01080f80-76b8-4363-845d-67e8623bf170",
"token": "830d36f6-a5e3-4455-9600-3a55b63e2fc2"
}
-
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
orprocessingOptions
must be included in this step
-
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;
-
Create an Event Listener
Add an event listener to your form's submit button that will trigger a
POST
request inside the iframe. Now when a user clicks submit on your outer form, the iframe will submit itself. Because of the event listener you created in step 2, your code is aware of iframe responses and errors.
Example
myForm.addEventListener('submit', function processPayment(event) {
event.preventDefault();
const url = 'https://api.nexiopaysandbox.com';
myIframe.contentWindow.postMessage('posted', url);
return false; // keeps the form from auto submitting
});
With Your Own Form
-
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.
-
Create a Form on Your Web Page
Example
<html>
<form id="myForm">
</form>
</html>
-
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
)
- Account holder name (
See the Run E-check Transaction endpoint reference for a complete list of possible parameters.
- Amount (
-
Send Payment Information to Your Server
-
Post Payment Information to Nexio
Send a
POST
request from your server to Nexio's Run E-check Transaction API endpoint with the payment information.Note: You will be required to authenticate via basic authentication.
Example Request
curl -X POST https://api.nexiopaysandbox.com/pay/v3/processECheck \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Basic <Your Basic Auth>'
-d '{
"data": {
"amount": 29.99,
"currency": "USD"
},
"tokenex": {
"token": "aafb1033-599a-4392-859e-f98033fc37f5"
}
}'
-
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.
Was this section helpful?
Create a Save E-check Page
With the Nexio Iframe
-
Create an Iframe on your Web Page
-
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)
}
});
-
Request a One-time-use Token
Send a
POST
request to the One-time-use Token (E-commerce) endpoint.
Example Request
curl -X POST https://api.nexiopaysandbox.com/pay/v3/token \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Basic <Your Basic Auth>'
-d '{}'
Example 200 Response
{
"expiration": "2018-09-18T15:43:05.664Z",
"fraudUrl": "https://api.nexiopaysandbox.com/pay/v3/fingerprint?token=01080f80-76b8-4363-845d-67e8623bf170",
"token": "830d36f6-a5e3-4455-9600-3a55b63e2fc2"
}
-
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
orprocessingOptions
must be included in this step
-
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;
-
Create an event listener
Add an event listener to your form's submit button that will trigger a
POST
request inside the iframe. Now when a user clicks submit on your outer form, the iframe will submit itself. Because of the event listener you created in step 2, your code is aware of iframe responses and errors.
Example
myForm.addEventListener('submit', function processPayment(event) {
event.preventDefault();
const url = 'https://api.nexiopaysandbox.com';
myIframe.contentWindow.postMessage('posted', url);
return false; // keeps the form from auto submitting
});
With Your Own Form
Please note that although bank data never touches your servers, using your own form changes your PCI liability from SAQ A to SAQ A-EP.
- Create a Form on Your Web Page
Example
<html>
<form id="myForm">
</form>
</html>
-
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.
- Account holder name (
-
Load the Form
Load the form on your page and allow the user to enter their information.
-
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.
-
Send Bank Information to Your Server
Send the encrypted bank account number and other bank information to your server.
-
Post Bank Information to Nexio
a. Request a one-time-use token
b. Send a
POST
request from your server to Nexio's Save E-check Token API endpoint with the one-time-use token and the bank information.
Example Request
curl -X POST https://api.nexiopaysandbox.com/pay/v3/saveECheck \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Basic <Your Basic Auth>'
-d '{
"bank": {
"accountHolderName": "John Doe",
"routingNumber": "231375151"
},
"token": "830d36f6-a5e3-4455-9600-3a55b63e2fc2"
}'
-
Listen for Nexio's Response
If Nexio returns a 200 status:
- Display a success page to the customer
- Save the e-check token (
tokenex.token
). You will need this token to run a transaction as well as to view, edit or delete the card token
If Nexio returns a non-200 status:
- Display a failure page to the customer
- Handle the error. See our list of common errors for more information
- Contact integration support if you need additional help
Was this section helpful?
More
Save a Card Token With the Nexio API
-
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.)
-
Request a One-time-use Token
Send a
POST
request to the One-time-use Token endpoint. (Do not include any card information or other body parameters—you will do that in step 3.)Copy or store the
token
from Nexio's response. It will be used in the next step.
Example Request
curl -X POST https://api.nexiopaysandbox.com/pay/v3/token \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Basic <Your Basic Auth>'
-d '{}'
Example 200 Response
{
"expiration": "2018-09-18T15:43:05.664Z",
"fraudUrl": "https://api.nexiopaysandbox.com/pay/v3/fingerprint?token=01080f80-76b8-4363-845d-67e8623bf170",
"token": "830d36f6-a5e3-4455-9600-3a55b63e2fc2"
}
-
Post Card Information to Nexio
Send a
POST
request to the Save Card Token endpoint. Include thetoken
from step 2 and the card information in the body of your request.
Example Request
curl -X POST https://api.nexiopaysandbox.com/pay/v3/saveCard \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Basic <Your Basic Auth>'
-d '{
"card": {
"cardHolderName": "John H Doe",
"encryptedNumber": "cu3yRktaYFK2LUC6DpNK289tYDsGRCi7cO+GeG0hkeYFvT7Y8/oY5r53obMz6Q/BZ38gk2u2Ufwy8ojBcX2sfNjG5jplGTXA4NNlSIUjMFfiHe1sff1JFpThoiW/IIlifGlbWu+S1/9pqWPTzJ2+DcjwohbHzsDahhYewFhXgC8qsK0ypi/Shlp+CwRITyIvbVXESD0xz3YOTRHeZLlChvVqN8z4ZzN8nm0MXkmT1wcpYI73bH4KdnPwNU3s7XxvP/ernQP73SHHAOKSLlz4F6AEHFjJiCoXzeLF7LwEjRdxDJ0sKVXbRk3i9BGh+8Nle2VYgjpUWtk2763QkvZiQQ==",
"expirationMonth": "12",
"expirationYear": "20"
},
"token": "eb50a022-d6de-4244-a1e6-dcb8522b2d19"
}'
Run a Transaction With the Nexio API
Authorize and Capture
To authorize and capture a transaction using the API, follow the steps below:
-
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.)
-
Save a Card Token
This may be done directly through the API, through your own form, or using the Nexio Save Card iframe.
-
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:
-
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.)
-
Save a Card Token
This may be done directly through the API, through your own form, or using the Nexio Save Card iframe.
-
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
-
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.)
-
Request a One-time-use Token
Send a
POST
request to the One-time-use Token endpoint. (Do not include any bank information or other body parameters—you will do that in step 3.)Copy or store the
token
from Nexio's response. It will be used in the next step.
Example Request
curl -X POST https://api.nexiopaysandbox.com/pay/v3/token \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Basic <Your Basic Auth>'
-d '{}'
Example 200 Response
{
"expiration": "2018-09-18T15:43:05.664Z",
"fraudUrl": "https://api.nexiopaysandbox.com/pay/v3/fingerprint?token=01080f80-76b8-4363-845d-67e8623bf170",
"token": "830d36f6-a5e3-4455-9600-3a55b63e2fc2"
}
-
Post Bank Information to Nexio
Send a
POST
request to the Save E-check Token endpoint. Include thetoken
from step 2 and the card information in the body of your request.
Example Request
curl -X POST https://api.nexiopaysandbox.com/pay/v3/saveECheck \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Basic <Your Basic Auth>'
-d '{
"bank": {
"accountHolderName": "John Doe",
"routingNumber": "231375151"
},
"token": "830d36f6-a5e3-4455-9600-3a55b63e2fc2"
}'
Run an E-check Transaction With the Nexio API
-
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.)
-
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.
-
Post Payment Information to Nexio
Post payment details along with the card token to the Run E-check Transaction endpoint.
Example Request
curl -X POST https://api.nexiopaysandbox.com/pay/v3/processECheck \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Basic <Your Basic Auth>'
-d '{
"data": {
"amount": 29.99,
"currency": "USD"
},
"tokenex": {
"token": "aafb1033-599a-4392-859e-f98033fc37f5"
}
}'
Was this section helpful?
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:
-
Request a Simple Login Key
Send a request to the Simple Login endpoint. A successful request will return a response with the following shape:
Example 200 Response
{
"exp": 1550600014,
"jwt": "t3jraWQiOiI3V2JrOFdSVVliMVljR2p3Mlhwd2swR3lIRWt6THcwVDRqckVhNVVVTjBnPSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiI4YWYzZTQwZC02Y2I0LTQ0ZWQtOWRlZS0yN2Y3NmNmNDc0YmMiLCJlbWFpbF92ZXJpZmllZCI6dHJ1ZSwiaXNzIjoiaHR0cHM6XC9cL2NvZ25pdG8taWRwLnVzLWVhc3QtMS5hbWF6b25hd3MuY29tXC91cy1lYXN0LTFfVlVEN21MeWNqIiwiY3VzdG9tOmFjY291bnRJZCI6ImVjN2NiOWJhLWQwMmQtNDhkYS1hY2I3LWI2ZWQ3YmJiZWQwMiIsImNvZ25pdG86dXNlcm5hbWUiOiJscm9ibGVkb0BjbXNvbmxpbmUuY29tIiwiYXVkIjoiNDBtZWQ2YnNybDZ1aWpnMmpmZzQwcmJzOGkiLCJldmVudF9pZCI6IjE0YmU5MWFjLTM0NjctMTFlOS9iNDZjLWMxMjdjYTkzZjA3NCIsInRva2VuX3VzZSI6ImlkIiwiYXV0aF90aW1lIjoxNTUwNTk1Mjk0LCJleHAiOjE1NTA1OTg4OTRsImN1c3RvbTphY2Nlc3NSaWdodHMiOiJ7XCJtZXJjaGFudElkc1wiOntcIjEwMDAzOVwiOlwiQVwiLFwiMTAwMDQxXCI6XCJBXCIsXCI1MTU3OTQwMDAwMTM1MDRcIjpcIkFcIixcIjkyMzYwMDAwMTEyNDUwM1wiOlwiQVwiLFwiOTIzNTAwMDAxNDMyNzQyXCI6XCJBXCIsXCI1MTM0ODUwMDAwMDAwMThcIjpcIkFcIixcIjkyMzYwMDAwODEyNjYxMFwiOlwiQVwiLFwiOTIzNjAwMDAzMTYzODEwXCI6XCJBXCJ9LFwicm9sZVwiOlwiQVwifSIsImlhdCI6MTU1MDU5NTI5NCwiZW1haWwiOiJscm9ibGVkb0BjbXNvbmxpbmUuY29tIn0.OEEZarSzbSLpxUM55UKmycYtAAWEtm__XUJdqBJ9QPSF_8sdLIL9EXBF8cLarhv3DoLqeWKUpieNgfcME2IsIc8amDXitvJtJe3STQtI_zaJwAibBxJhFKQRLRCrIe3kpslVJPuw3OeST54QcseifLlA64bxNaveXygja7aejwINueE4_Nj0NEzcFGZoYHgNB6br6Ksbjgx-z_SiFIZ1XHS-eOMnBoCIVWjFr3FY9IbfnQf4v0c0AFWKt9mOpjYracSqOHHmSER7GuaMBNrHxfbe0kHVh6hvnrzh10SEnTsF573qbP1R_aZA_Uh80MOLB0UvPWWFzzyP4GniNc3zLw",
"key": "4f211fde-d135-4c91-afbc-bcdb73c0c504",
"refreshToken": "t3jjdHkiOiJKV1QiLCJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiUlNBLU9BRVAifQ.CejuLZHvZcrISuiwE7N4xg7EYq6ArivbyNwDVE2X7eTdr7CTO4l5udgc9ZUV1byTe1r3eLN_szbte1nlaimbQj5ZcJpim1zmW5pkk7aFVF-WcnLjIBVPilp6bLW8gsZaB04WErDjwzt4r7Bxnz6YnmLM7e3V15ZVkY6GLFqgrUF9Tb9UOFbCDD_H8qe1AdFktVeeVgefekJew3RuZ8p2BnKWejt1BcyMUnYY-QgaLm3TzUpd14PRbdvOfBG3D9KmJCnZ_6H9sQ5FUirqsF_U6eXNppE1QXZdjhFg4oic791Kq5rXU2xbMI9ggeFoGIjLLP0Keb0iT66NwXpf50-h4w.eUOjohgz3zXTJWHH.IBQMMiNKtbAZ02r0QGXJXw_zM2c3epH5LGtdZxIVUReMRr5CLm-ptE7zaFTK0D1tpUHcVonqiDuXyc09IN0IO4jL32QqQjgeG-V9LBYgpr1xV3qyc5TR-L2VNHjJt3A3SbJsIzxHDqKLucJw2N0WaiOgLb577q8B8lu0pLCpOV_POlUiT4BLAvycMCKkgUCDrejyjzR39ofCUqtZKuMglXanUfVE3hC0OaNOMpl65N_utjuf9vzklyZZRQMTgokQ7V0yp0VSpCC6D_zNBvwTPUKHVFyMrzEC4wJZ9uOtIS9h9rv_HywpwrPqHYajsGYNrv7QvHE1Kg80I73CbL0owW-J5bKEbgImqkahNVhBoFJejnvN3PEr9zthNey15Q_utOUFUkR0Po9GH6fnXFXxQnIC7c2hQ4lgjV2wR3WGzEiE5L0aNLF1Cnjyn-t1VZxQHG2uiyiT1aIUFBPbItTkVPjKhkFKf7AfXqOTAl52VFdBPpFdbG5Ecwfm_4ZGgO_4KJnLcb7qMQuEI6G20xelkPD2NHIpdS9gHx7XIlyfiBPkvq3YEKMtOQQbRAQ_Hcy7leeZnSyPgq65Bnsn22xZ4NG5bSshSEEMlq5lbOV4-dzBGV8SA6dOeNHR7GeQvSr1XQ89sBloJlMKJLe9WL0fYhkY6u-MbmecvMoU1OrC4mvIv-0l53TIeeGDMtn8UkcaSxQG7HBEqcQlvaFAxGaol7kiDPlAMxdp11lnk0ix3G0M74xHRFpZalIFtUAPm2xEVFJLWlwLqalRgJpO70asiw9QJ_pi0HERT5N_wCXraxeQyNrknNmi157ih5yP7SGm7MXrSVUOHu6GIBZktAfP8IURhJNQZfSk3Do_up1vUBPN7yLNumqPq2PWH3CgFXle3nDaQYCVsVkGU-FZTy7KLIbKc2EStkOFOCPiYYSoD8h1-C8kclCeIKFLDFQIo7weJyIGjQqV_pY9HEPQivgXw6X1ti711x0YZ2bhl9tPuUEtXeja7hGAxLnrU4QqHr2iS58J9F5NMVc6LlK_NcExLzrlnQBJws7urmDkV_yoOtCRadxVuAxVCYqfAh8X4gzQ7LQMT27pFeV98iCvAmkhWx4RpAmFYHmacUJIXUVXKe6eTlN27gsYir1H9SrkbFgjOjvoUBj5p-mn-mMathsdAbRtlryJEjfCzAfBWis-7d4GsxCZGQnCJ0NezIP50_2dCPyzpgYcUwt4E4kHIA5-SBOLWneULDPz7VpRJxKv8BaYxOZuotnV2zz2nwB3vlDWK1h6cgRfMT8o8iphcUMxdZdjd-FElzNCdQ.SDQXbyIYZu6_jdCeAzTzoA",
"username": "youremail@cmsonline.com"
}
-
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
-
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
-
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} }
- Enter the Card Information
- Click 'Save Card'
Run a Keyed Transaction
-
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
-
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/
-
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.
-
Enter or Confirm the Amount
-
Key in Card Information
-
Click ‘Pay $X.XX’
-
Create a Receipt
The iframe will display a simple success page—it does not generate a default receipt. Use our response to create a success/confirmation page and your own receipt.
Process a Transaction with a Terminal
Nexio's API allows you to process card present (EMV) transactions using a terminal.
Follow the steps below, depending on your gateway.
USAePay
In order to process a card present transaction with a terminal through USAePay, you need to set up your terminal and then pair it and process the transaction either via iframe or via API.
Setup Terminal for Pairing
Set up your terminal for pairing.
Note: After you have completed these steps once, you do not need to complete them again unless you want to change the terminal mode or reconfigure the internet connection.
-
Power on the terminal.
- If the terminal is not connected to the internet and is not paired, the main menu displays
- If the terminal is connected to the internet and is not paired, the pairing screen displays.
Exit the pairing screen by pressing the red button until the main menu displays
-
From the main menu, press the correct buttons to go to Settings and then Mode Select. A menu with options for Production and SANDBOX displays.
-
Select the mode.
- If you are processing test transactions, select SANDBOX. An icon of a flask displays in the upper-left corner of the main menu screen
- If you are processing live transactions, select Production
After you select the mode, the system returns you to the Settings menu.
-
From the Settings menu, select Connection Type. A menu with options for WiFi and Ethernet displays.
-
Select WiFi or Ethernet.
- If you select WiFi, return to the Settings menu by pressing the red button and select Rescan WiFi. When the terminal finds your desired network, select it and type the password. After you have connected to the WiFi, if the terminal is rebooted, it connects to the chosen network automatically
- If you select Ethernet and the cable is plugged in, the terminal is ready for pairing. Press the red button to get to the main screen
- From the main screen, press the red button to get to the pairing screen.
You have successfully set up your terminal. Now that your terminal is connected to the internet, you can pair it and process a transaction via iframe or via API.
Pair terminal via iframe
In order to pair your terminal using Nexio's retail iframe, you must have completed setup.
Note: After pairing completes, the connection is permanent until the device is unpaired or the pairing is removed in the USAePay portal.
-
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
-
Load the retail iframe.
- The retail iframe loads by default
- You may also select additional UI options as shown in the UI options table
-
From the Payment Method menu of the iframe, select Card (terminal).
-
Click Add Terminal at the bottom of the iframe to open the Add Terminal dialog.
-
Type the terminal name you want to use. If the name is longer than 12 characters, the terminal only displays 12 characters after the name is saved.
-
Click Submit to save the name and close the dialog.
-
Type the pairing code that appears in the iframe into your terminal.
-
Wait until the iframe displays "Pairing Complete".
Now that you have paired your terminal via iframe, you can process a transaction by following the process below.
Process transaction via iframe
In order to process a transaction via iframe, you must have completed setup and paired your terminal via iframe.
- 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
- Load the retail iframe.
- The retail iframe loads by default
- You may also select additional UI options as shown in the UI options table
- From the Processing Account menu of the iframe, select the correct processing account.
- From the Payment Method menu, select Card (terminal).
- Select the correct value from the Currency menu.
- Type the correct value in the Amount field.
- From the Terminal menu, select the paired terminal you want to use. If the terminal you want to use does not appear in the Terminal menu, it may not be paired.
- Click Submit to send the payment to the terminal.
- Complete the transaction at the terminal. The response posts to the iframe.
Pair terminal via API
In order to pair your terminal using Nexio's retail iframe, you must have completed setup.
Note: After pairing completes, the connection is permanent until the device is unpaired or the pairing is removed in the USAePay portal.
-
Send a
POST
request to the Pair terminal endpoint. A successful request returns a response including apairingCode
.Example Request
curl -X POST https://api.nexiopaysandbox.com/pay/v3/processFromTerminal \ -H 'Content-Type: application/json' \ -H 'Accept: application/json' \ -H 'Authorization: Basic <Your Basic Auth>' -d '{ "data": { "merchantId": "100111", "terminalName": "FrontDesk1" }'
Example 200 Response
[ { "terminalName": "FrontDesk1", "pairingCode": 712677, "expirationDate": "2022-01-31T10:09:33.000Z", "key": "sa_a04ZF6U2J99wwvAOzHtMOVzOm9WSb", "random-4611765": "6fec4a03-3a9f-40de-90bc-23a513ac904c" } ]
-
Type the
pairingCode
from the response into the pairing screen of the terminal. If successful, the terminal displays the WELCOME screen and up to 12 characters of theterminalName
. -
Send a
GET
request to the View terminal list endpoint. A successful request returns an array of terminal objects. These are the terminals currently enabled on your merchant ID. -
Confirm that the newly paired terminal is in the response.
Example Request
curl -X GET https://api.nexiopaysandbox.com/pay/v3/getTerminalList \ -H 'Accept: application/json' \ -H 'Authorization: Basic <Your Basic Auth>'
Example 200 Response
[ { "merchantId": "100111", "merchantName": "Merchant Name", "gatewayName": "usaepay", "gatewayType": 10, "gatewayLabel": "...5tjb", "terminalName": "FrontDesk1", "terminalSerialNumber":"000118205206486", "terminalKey": "sa_a04ZF6U2J99wwvAOzHtMOVzOm9WSb", "terminalStatus": "connected", "terminalId": "eyJtZXJjaGFudElkIjoiMTAwODg4IiwiZ2F0ZXdheUxhYmVsIjoiLi4uNXRqYiIsInRlcm1pbmFsIjp7ImlkIjoic2FfYTA0WkY2VTJKOTl3d3ZBT3pIdE1PVnpPbTlXU2IiLCJsb2NhdGlvbklkIjoiZm40eHJ2YmRyZzNqN3QzMjgifX0=" } ]
Process transaction via API
In order to process a transaction via API, you must have completed setup and paired your terminal via API.
-
Send a
POST
request with the transactiondata
andterminalId
to the Process transaction from terminal endpoint. A successful request returns aterminalRequestStatus
ofinitialized
.Example Request
curl -X POST https://api.nexiopaysandbox.com/pay/v3/processFromTerminal \ -H 'Content-Type: application/json' \ -H 'Accept: application/json' \ -H 'Authorization: Basic <Your Basic Auth>' -d '{ "data": { "amount": "13.45" }, "terminalId": "eyJtZXJjaGFudElkIjoiMTAxMDM5IiwiZ2F0ZXdheUxhYmVsIjoiLi4uMmUyMSwuLi41ZWU3IiwidGVybWluYWwiOnsiaWQiOiIxMWU5MDIxMGNmZTdmNmFlOWVkNWUwYTgiLCJsb2NhdGlvbklkIjoiMTFlOGNkNmE4YjQ0YzUzZWFkNmFkY2UxIn19" }'
Example 200 Response
{ "terminalRequestId": "8524beee-70f1-4890-9382-3d5bb8871a4c", "terminalRequestStatus": "initialized", }
-
After submitting the request to process from terminal, the terminal displays the
amount
that was in the request and an image indicating that it is ready for you to present the card. -
Complete the transaction at the terminal.
-
Send a request to the View terminal transaction status endpoint as frequently as once per second until the
terminalRequestStatus
returns assuccess
. You may see apending
status before thesuccess
status. This means that it was submitted but the transaction with the gateway is not complete.
Unpair the terminal
- From the WELCOME screen, navigate to the main menu.
- For the Vega3000 model, press and hold the 9 button for three seconds
- For the MP200 model, press and hold the down arrow button for three seconds
- Go to Settings.
- Select Unpair Device.
- Press the green button to confirm.
Zeamster
-
Request a Terminal List
Send a
GET
request to the Get Terminal List endpoint. A successful request returns an array of terminal objects. These are the terminals currently enabled on your merchant ID.Example Request
curl -X GET https://api.nexiopaysandbox.com/pay/v3/getTerminalList \ -H 'Accept: application/json' \ -H 'Authorization: Basic <Your Basic Auth>'
Example 200 Response
[ { "gatewayLabel": "...2e21,...5ee7", "gatewayName": "yourGateway", "gatewayType": 110, "merchantId": "103002", "merchantName": "Test Merchant", "terminalId": "eyJtZXJjaGFudElkIjoiMTAxMDM5IiwiZ2F0ZXdheUxhYmVsIjoiLi4uMmUyMSwuLi41ZWU3IiwidGVybWluYWwiOnsiaWQiOiIxMWU5MDIxMGNmZTdmNmFlOWVkNWUwYTgiLCJsb2NhdGlvbklkIjoiMTFlOGNkNmE4YjQ0YzUzZWFkNmFkY2UxIn19", "terminalName": "Terminal 1", "terminalSerialNumber": "84937213" } ]
-
Copy the Terminal ID
Copy the
terminalId
from the response above. You will use it in step 3. -
Post Transaction Details
Send a
POST
request with the transaction details andterminalId
to the Process From Terminal endpoint.A successful response returns a
terminalRequestId
. You can use theterminalRequestId
to check the status of the transaction.Example Request
curl -X POST https://api.nexiopaysandbox.com/pay/v3/processFromTerminal \ -H 'Content-Type: application/json' \ -H 'Accept: application/json' \ -H 'Authorization: Basic <Your Basic Auth>' -d '{ "data": { "amount": "13.45" }, "terminalId": "eyJtZXJjaGFudElkIjoiMTAxMDM5IiwiZ2F0ZXdheUxhYmVsIjoiLi4uMmUyMSwuLi41ZWU3IiwidGVybWluYWwiOnsiaWQiOiIxMWU5MDIxMGNmZTdmNmFlOWVkNWUwYTgiLCJsb2NhdGlvbklkIjoiMTFlOGNkNmE4YjQ0YzUzZWFkNmFkY2UxIn19" }'
Example 200 Response
{ "terminalRequestId": "64ea267f-2766-49b8-9e0e-aeb91b2fe722", "terminalRequestStatus": "initialized" }
-
Check the Transaction Status (Optional)
Send a
GET
request with theterminalRequestId
to the Terminal Transaction Status endpoint.Example Request
curl -X GET https://api.nexiopaysandbox.com/pay/v3/processFromTerminal/{terminalRequestId} \ -H 'Accept: application/json' \ -H 'Authorization: Basic <Your Basic Auth>'
Example 200 Response
{ "gatewayResponse": { "gatewayName": "yourGateway" }, "terminalRequestId": "64ea267f-2766-49b8-9e0e-aeb91b2fe722", "terminalRequestStatus": "initialized" }
More
Customize the Iframe
To customize the retail/MOTO iframe, include a settings
object as a query parameter in your request to https://retail.nexiopaysandbox.com.
You can include settings with or without a Simple Login key.
See the examples below:
Save Card Iframe without Simple Login
https://retail.nexiopaysandbox.com/?settings={%22uiOptions%22:{%22saveCard%22:true} }
Run Transaction Iframe with Simple Login and a Default Amount of $20
https://retail.nexiopaysandbox.com/?simpleLogin={key}&settings={%22processingOptions%22:{%22amountDefault%22:"20"} }
UI Options
Name | Description |
---|---|
amountSet |
Prepopulates the amount field. User will not be able to change it |
amountDefault |
Prepopulates the amount field. User will be able to change it |
amountMax |
The maximum amount the user may enter into the amount field |
hideAuthOnly |
Hides or display the Auth Only Checkbox (default: true ) |
hideBilling |
Hides or displays all billing fields (default: false ) |
limitCountriesTo |
If this array is nonempty, the Country Dropdown field will be limited to the countries on the list. Note: These must be the two-character (Alpha-2) ISO country codes |
merchantIdDefault |
Prepopulates the merchant dropdown. User will be able to change it |
merchantIdSet |
Prepopulates the merchant dropdown. User will not be able to change it |
Features
3D Secure
3DS, or three-domain secure, helps prevent fraud by requiring cardholders to authenticate with their issuing bank when making online purchases. To comply with the PSD2’s Strong Customer Authentication (SCA) requirements, especially in regions where mandated, merchants should ensure transactions are properly authenticated prior to being processed with 3DS helping to fulfill those requirements.
Nexio uses 3DS 2.0 protocol whenever possible with 3DS 1.0 fallback enabled for cases where issuers do not yet support 2.0. When a transaction is attempted, card issuers use the transactional data provided to determine whether a challenge is required. If a challenge is issued, additional information from the cardholder will be needed, such as a password or one-time code received via a mobile device.
3DS through Nexio
The 3DS authentication workflow happens through a redirect provided by the cardholder’s issuing bank.
Nexio’s secure e-commerce iframe will prompt shoppers to confirm they are being redirected to their bank's page for authentication. Upon confirmation the iframe will open a new tab in which authentication will be completed.
Merchants using only the Nexio API to process transactions will need to handle the redirect separately. After the shopper completes the authentication, the transaction will be processed.
Use 3D Secure
You can enable 3DS using Nexio's e-commerce iframe or directly through the API.
Use 3D Secure with Nexio's E-commerce Iframe
-
Request a One-time-use Token
Send a
POST
request to the E-commerce One-time-use Token endpoint.
Example Request
curl -X POST https://api.nexiopaysandbox.com/pay/v3/token \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Basic <Your Basic Auth>'
-d '{
"data": {
"amount": 29.99,
"currency": "USD"
}
}'
Example 200 Response
{
"expiration": "2018-09-18T15:43:05.664Z",
"fraudUrl": "https://api.nexiopaysandbox.com/pay/v3/fingerprint?token=01080f80-76b8-4363-845d-67e8623bf170",
"token": "830d36f6-a5e3-4455-9600-3a55b63e2fc2"
}
-
Load the Iframe
Use the
token
from the response above to send a request to theGET
Run Card Transaction Iframe endpoint:
Example Request
curl -X GET https://api.nexiopaysandbox.com/pay/v3?token=830d36f6-a5e3-4455-9600-3a55b63e2fc2 \
-H 'Accept: application/json' \
-H 'One-time-use Token: API_KEY'
-
Redirect and Complete the Transaction
If the transaction requires 3DS authentication Nexio’s iframe will prompt shoppers to confirm they are being redirected for authentication. Upon confirmation the iframe will open a new tab in which authentication will be completed.
Once users have successfully authenticated, the transaction will be attempted. Upon completion, the response will be returned as a message to the browser.
Example 200 Response
{
"amount": 34.25,
"authCode": "035410",
"card": {...},
"currency": "USD",
"data": {...},
"gatewayResponse": {...},
"id": "eyJuYW1lIjoidXNhZXBheSIsInJlZk51bWJlciI6IjMxMDA5MDc4MTkiLCJtZXJjaGFudElkIjoiMTAwMDM5IiwicmFuZG9tIjoiMzEwMDkwNzgxOSIsImN1cnJlbmN5IjoiVVNEIn0=",
"kountResponse": {...},
"merchantId": "100039",
"token": {...},
"transactionDate": "2019-01-15T13:19:39.329Z",
"transactionStatus": "pending",
"transactionType": "sale"
}
Notes:
- The response schema will be the same as that of a standard
POST
request to the Run Card Transaction endpoint - The page does not generate a default confirmation page. We recommend using our response to create your own confirmation page
Use 3D Secure with Nexio's API
-
Post Transaction Information
Send a
POST
request to the Run Card Transaction endpoint. Include the parameterprocessingOptions.customerRedirectUrl
in the body of your request. This is the URL to which the shopper will be redirected after completing the 3DS authentication.
Example Request
curl -X POST https://api.nexiopaysandbox.com/pay/v3/process \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Basic <Your Basic Auth>'
-d '{
"data": {},
"tokenex": {
"token": "6ee140a0-05d1-4958-8325-b38a690dbb9d"
},
"processingOptions": {
"customerRedirectUrl": "https://your-ecommerce-website.example.com"
}
}'
If the payment requires 3DS authentication,
Nexio's response will include a redirectUrl
.
Example 200 Response
{
"status": "redirect",
"message": "Provide redirect url to shopper to complete 3ds authentication and transaction",
"redirectUrl": "https://api.nexiopaysandbox.com/pay/v3/threeDS/frame?token=4c0e5734-63f6-4ada-9fc5-e632109e2a77"
}
-
Redirect the User
Display the
redirectUrl
from the response above in a browser. Shoppers will be prompted to confirm they are being redirected for authentication. -
User Authenticates
Once users have successfully authenticated, the transaction will be attempted. Upon completion, the user will be redirected to the
customerRedirectUrl
provided in step 1. The transactionid
andstatus
will be returned to the browser.
Example 200 Response
{
"id": "eyJuYW1lIjoidXNhZXBheSIsInJlZk51bWJlciI6IjMxMDA5MDc4MTkiLCJtZXJjaGFudElkIjoiMTAwMDM5IiwicmFuZG9tIjoiMzEwMDkwNzgxOSIsImN1cnJlbmN5IjoiVVNEIn0=",
"status": "pending"
}
Notes:
- The response schema will be the same as that of a standard
POST
request to the Run Card Transaction endpoint - The page does not generate a default confirmation page. We recommend using our response to create your own confirmation page
3DS Requirements
Initial Transactions
Initial or first-time transactions may be subject to cardholder authentication depending on the merchant account and/or region. Nexio will provide transaction information to the gateway and respond to your system with a 3DS redirect URL where required. We recommend, therefore, that your system be equipped to handle any 3DS redirect returned by Nexio.
Nexio’s check3ds
flag allows you to indicate whether your system is equipped to handle a 3DS redirect.
If set to true
,
Nexio will return the redirect URL to you or prompt users to continue with the authentication if using the e-commerce iframe.
If set to false
,
Nexio will attempt to process transactions without 3DS.
If 3DS is required, Nexio will instead return an error so your system does not get hung up with the 3DS workflow.
Recurring transactions
If you intend to process recurring transactions,
you will need to set check3ds: false
for any recurring transactions.
This indicates to Nexio one of the following:
- The transaction is using a payment token that has been previously authenticated or used for processing a transaction
- Your system is not equipped to handle a 3DS redirect workflow
Do not include check3ds: true
in recurring transactions as they are out-of-scope of SCA.
Nexio will determine whether to flag transactions as recurring to the gateway.
This flag will be determined based on the check3ds
value and the token provided at the time of a transaction.
Account Updater
The account updater service allows merchants to automatically update saved cards due to changes in card number or expiration date.
Merchants that process recurring transactions will see fewer declines due to invalid or expired cards by having the most recent card information before the transaction is attempted.
By default, each new card token is tagged for registration with account updater. However, they will not be registered until you have enrolled your merchant account with account updater. We recommend configuring all existing card tokens prior to enrolling your merchant account with account updater.
Contact your Nexio sales agent to enroll your merchant account in account updater.
You may also want to configure webhooks for the various event types that may be returned due to changes or actions from the account updater service. For more information and examples of possible responses, see Event Types in the Webhooks section.
Configure Existing Card Tokens
Prior to enrolling in account updater, we recommend checking the configuration of your existing card tokens. Tag any card you do not wish to be registered with account updater for exclusion. (By default, all cards are tagged for registration.)
If you are already enrolled account updater, you may tag a a card that is currently registered for de-registration or tag a card that is currently not registered for registration.
Check a Card's Enrollment Tag
To check the enrollment tag of an existing card token,
send a GET
request to the View Card Token endpoint.
Replace the {cardToken}
in the example below with the card token you wish to view.
The response will include a boolean value called shouldUpdateCard
.
This is the card's enrollment tag.
It indicates whether a card will be registered or excluded from account updater.
Note: The card will not be registered until the merchant account is enrolled. See the Account Updater Enrollment Tag table below for more information.
Example Request
curl -X GET https://api.nexiopaysandbox.com/pay/v3/vault/card/{cardToken} \
-H 'Accept: application/json' \
-H 'Authorization: Basic <Your Basic Auth>'
Example 200 Response
{
"accountUpdaterStatus": "isExcluded",
"card": {...},
"data": {...},
"dateCreated": "2019-07-31T17:02:39.035Z",
"dateLastModified": "2019-07-31T18:33:30.660Z",
"merchantId": "100100",
"shouldUpdateCard": true,
"tokenex": {...}
}
Tag an Existing Card For Registration
-
Update the Card's Registration Tag
Send a
PUT
request to the Edit Card Token endpoint. Include the parametershouldUpdateCard: 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
}'
-
Check the Card's Status (Optional)
Send a
GET
request to the View Card Token endpoint. The response will include a string value calledaccountUpdaterStatus
. This is the card's enrollment status. See the Account Updater Card Status table for more information.Note: It usually takes three to four business days for a card token to become registered with account updater.
Example Request
curl -X GET https://api.nexiopaysandbox.com/pay/v3/vault/card/{cardToken} \
-H 'Accept: application/json' \
-H 'Authorization: Basic <Your Basic Auth>'
Example 200 Response
{
"accountUpdaterStatus": "isExcluded",
"card": {...},
"data": {...},
"dateCreated": "2019-07-31T17:02:39.035Z",
"dateLastModified": "2019-07-31T18:33:30.660Z",
"merchantId": "100100",
"shouldUpdateCard": true,
"tokenex": {...}
}
Tag an Existing Card For De-registration
-
Update the Card's Registration Tag
Send a
PUT
request to the Edit Card Token endpoint. Include the parametershouldUpdateCard: false
in the body of your request.
Example Request
curl -X PUT https://api.nexiopaysandbox.com/pay/v3/vault/card/{cardToken} \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Basic <Your Basic Auth>'
-d '{
"shouldUpdateCard": false
}'
-
Check the Card's Status (Optional)
Send a
GET
request to the View Card Token endpoint. The response will include a string value calledaccountUpdaterStatus
. This is the card's enrollment status. See the Account Updater Card Status table for more information.Note: It usually takes three to four business days for a card token to become de-registered with account updater.
Example Request
curl -X GET https://api.nexiopaysandbox.com/pay/v3/vault/card/{cardToken} \
-H 'Accept: application/json' \
-H 'Authorization: Basic <Your Basic Auth>'
Example 200 Response
{
"accountUpdaterStatus": "isRegistered",
"card": {...},
"data": {...},
"dateCreated": "2019-07-31T17:02:39.035Z",
"dateLastModified": "2019-07-31T18:33:30.660Z",
"merchantId": "100100",
"shouldUpdateCard": false,
"tokenex": {...}
}
Configure New Card Tokens
Tag a New Card for Enrollment
By default, all cards are tagged for enrollment in account updater upon creation.
Tag a New Card for Exclusion
With the Nexio Iframe
-
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.
-
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
}'
-
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
-
Prepare the Iframe
Follow steps 1-6 of the Create a Save Card Page Using the Iframe tutorial.
-
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 '{}'
-
Post Card Information to Nexio
Follow step 7b of the Create a Save Card Page Using the Iframe tutorial. Include the parameter
shouldUpdateCard: false
in the body of your request.
Example Request
curl -X POST https://api.nexiopaysandbox.com/pay/v3/saveCard \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Basic <Your Basic Auth>'
-d '{
"card": {
"cardHolderName": "John H Doe",
"encryptedNumber": "cu3yRktaYFK2LUC6DpNK289tYDsGRCi7cO+GeG0hkeYFvT7Y8/oY5r53obMz6Q/BZ38gk2u2Ufwy8ojBcX2sfNjG5jplGTXA4NNlSIUjMFfiHe1sff1JFpThoiW/IIlifGlbWu+S1/9pqWPTzJ2+DcjwohbHzsDahhYewFhXgC8qsK0ypi/Shlp+CwRITyIvbVXESD0xz3YOTRHeZLlChvVqN8z4ZzN8nm0MXkmT1wcpYI73bH4KdnPwNU3s7XxvP/ernQP73SHHAOKSLlz4F6AEHFjJiCoXzeLF7LwEjRdxDJ0sKVXbRk3i9BGh+8Nle2VYgjpUWtk2763QkvZiQQ==",
"expirationMonth": "12",
"expirationYear": "20"
},
"token": "eb50a022-d6de-4244-a1e6-dcb8522b2d19",
"shouldUpdateCard": false
}'
-
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
-
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 '{}'
-
Post Card Information to Nexio
Send a
POST
request to the Save Card Token endpoint. Include thetoken
from step 2, the card information and the parametershouldUpdateCard: false
in the body of your request.
Example Request
curl -X POST https://api.nexiopaysandbox.com/pay/v3/saveCard \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Basic <Your Basic Auth>'
-d '{
"card": {
"cardHolderName": "John H Doe",
"encryptedNumber": "cu3yRktaYFK2LUC6DpNK289tYDsGRCi7cO+GeG0hkeYFvT7Y8/oY5r53obMz6Q/BZ38gk2u2Ufwy8ojBcX2sfNjG5jplGTXA4NNlSIUjMFfiHe1sff1JFpThoiW/IIlifGlbWu+S1/9pqWPTzJ2+DcjwohbHzsDahhYewFhXgC8qsK0ypi/Shlp+CwRITyIvbVXESD0xz3YOTRHeZLlChvVqN8z4ZzN8nm0MXkmT1wcpYI73bH4KdnPwNU3s7XxvP/ernQP73SHHAOKSLlz4F6AEHFjJiCoXzeLF7LwEjRdxDJ0sKVXbRk3i9BGh+8Nle2VYgjpUWtk2763QkvZiQQ==",
"expirationMonth": "12",
"expirationYear": "20"
},
"token": "eb50a022-d6de-4244-a1e6-dcb8522b2d19",
"shouldUpdateCard": false
}'
Account Updater Enrollment Tag
Merchant's Enrollment in Account Updater | shouldUpdateCard |
Action |
---|---|---|
Enrolled | true |
The card will be registered with account updater |
Enrolled | false |
The card will be excluded from account updater. If the card was previously registered it will be de-registered |
Not Enrolled | true |
The card is tagged for registration. Upon merchant enrollment the card will be registered with account updater |
Not Enrolled | false |
The card is tagged for exclusion. Upon merchant enrollment the card will be excluded from account updater |
Account Updater Card Status
accountUpdaterStatus |
Description |
---|---|
isRegistered |
Card has been successfully registered. Automatic card updates will occur. |
pendingExclusion |
Card is in the process of being de-registered (usually takes about three to four business days). |
isExcluded |
Card is excluded or has been de-registered from the account updater service. (This is the default status before a card is run through the account updater service.) |
toDelete |
Indicates that Nexio must first de-register the card before deleting the token. |
pendingDeletion |
Card is in the process of being de-registered. The token will be deleted within three to four business days. |
Account Updater Test Cards
Test transactions for Account Updater can be submitted using the following card numbers:
Test Card Number | Response Code | Description |
---|---|---|
4000200011112222 | 201 | Expiration date has been updated (3 years added to the expiration date) |
4000200111112221 | 201 | Expiration date has been updated (3 years added to the expiration date) |
4000100011112224 | 202 | Card number updated to 4000100511112229 |
4000100111112223 | 202 | Card number updated to 4000100611112228 |
4000600011112223 | 203 | Closed account |
4000600111112222 | 203 | Closed account |
4000700011112221 | 204 | Contact cardholder |
4000700111112220 | 204 | Contact cardholder |
Alternative Payment Methods
Nexio's alternative payment method (APM) service allows you to offer shoppers multiple APMs with a single integration. Based on your preferred workflow, you may want to use the Express APM iframe display one or more Nexio-provided APM button iframes or send shoppers directly to your chosen APM using Nexio-provided redirect URLs.
Nexio's Express APM integration allows you to offer shoppers multiple alternative payment methods with a single iframe. Nexio will provide a radio button list of all configured APMs. The shopper will then be redirected to their selected APM where they will complete the payment. Payment response information will be sent to the parent document as a message event. See the Express APM tutorial for integration instructions.
Supported APMs
The table below lists all available APMs and their supported transaction types.
Please note that Braintree PayPal, Apple Pay, and Google Pay are currently only available through Nexio's APM button iframes.
Apple Pay and Google Pay also require additional configuration steps. See the Apple Pay configuration / Google Pay configuration sections for instructions.
APM | Supported Transaction Types | paymentMethod |
---|---|---|
Alipay | Sale, Refund | nihaoPayAliPay |
ApplePay | Sale, Auth only, Capture, Void, Refund | applePayAuthNet applePayCyberSource applePayCheckout |
GooglePay | Sale, Auth only, Capture, Void, Refund | googlePayAuthNet googlePayCyberSource |
Klarna | Sale, Auth only, Capture, Refund | klarna |
Paynet | Sale | paynet |
SPEI | Sale | openpaySpei |
PayPal | Sale, Auth only, Capture, Void, Refund Sale (Button Iframe URLs only), Merchant-initiated, Auth only, Capture, Void, Refund |
payPal braintreePayPal |
SEPA | Sale, Auth only, Capture | adyenSepa |
UnionPay | Sale, Refund | nihaoPayUnionPay |
WeChat Pay | Sale, Refund | nihaoPayWechatPay |
Configuration
The following alternative payment methods (APMs) require additional configuration steps:
Apple Pay
In order to configure your account for use with Apple Pay, you will need the following:
- An Apple computer
- An Apple Developer account
- An Authorize.Net account
Once you have the above, you are ready to follow the configuration steps below:
- Step 1: Create an Apple Pay Merchant ID
- Step 2: Create A Payment Processing Certificate
- Step 3: Create a Merchant Identity Certificate
- Step 4: Verify Your Domain
- Step 5: Provide Your Configuration Settings to Integration Support
Note: When integrating Apple Pay to multiple environments, you will need to complete step 4 for each environment. However, steps 1-3 only need to be completed once.
Step 1: Create an Apple Pay Merchant ID
Follow the steps below to create an Apple Pay Merchant ID.
-
Navigate to the Apple Developer Portal
Go to the Apple Developer Portal
-
Navigate to Identifiers List
a. Click on 'Accounts'
b. Click on 'Certificates, IDs and Profiles'
c. Click on 'Identifiers'
d. Click on the '+' sign
-
Create the Merchant ID
Select the 'Merchant ID' radio button, then click 'Create'. Fill in the required fields. Copy or note the Merchant ID. You will need it when you create the payment processing certificate and the merchant identity certificate.
Step 2: Create A Payment Processing Certificate
Follow the steps below to download a Payment Processing Certificate through Authorize.Net and upload it to Apple Pay.
-
Navigate to Authorize.Net
Go to the Authorize.Net developer portal
-
Click on 'Digital Payment Solutions'
-
Click on 'Apple Pay'
Enter the Merchant ID you created in step 1
-
Download the Certificate
Click the 'Download' button to download the Payment Processing Certificate. You will use this certificate in the next step.
-
Upload the Payment Processing Certificate
a. Navigate to the Apple Developer Portal
b. Click the 'Upload' button and upload the Payment Processing Certificate from the previous step.
Step 3: Create a Merchant Identity Certificate
Follow the steps below to create an Apple Pay Merchant Identity Certificate.
-
Create the Certificate Signing Request
In this step you will create the certificate signing request (CSR) for a Merchant Identity Certificate. (The steps below are adapted from Apple's tutorial on how to create a certificate signing request)
a. Launch Keychain Access located in
/Applications/Utilities
b. Choose Keychain Access > Certificate Assistant > Request a Certificate from a Certificate Authority
c. In the Certificate Assistant dialog, enter an email address in the User Email Address field. (Any email address will work)
d. Enter the Common Name. You may pick a common name of your choice, but for this tutorial we will call it 'Nexio Apple Pay Merchant Cert'
e. Leave the CA Email Address field empty
f. Choose 'Saved to disk', and click Continue
g. The default 'Save As' name will be something like CertificateSigningRequest.certSigningRequest. We will call it
NexioApplePayMerchant.certSigningRequest
Successful completion of the above steps will create the following files:
- CSR (saved to the location you selected with the name you chose in the step g)
- A private key (saved to the KeyChain tool, with the same name as the Common Name you chose in step d)
- A public key (saved to the KeyChain tool, with the same name as Common Name you chose in step d)
-
Upload the CSR to Apple's developer portal
a. Go to the Apple Developer Portal
b. Click to expand App IDs dropdown menu (in the top right)
c. Select merchant IDs
d. Select the desired merchant ID (If you do not see the merchant ID, create it now)
e. Under 'Apple Pay Merchant Identity Certificate' click on 'Create Certificate'
f. Upload the certificate you created in step 1
g. Download the certificate Name it
NexioApplePayMerchant.cer
-
Export the Private Key From Step 1
a. Go back to the KeyChain tool on your MacBook
b. Right click on the private key and select Export
c. Export as NexioApplePayMerchantKey.p12
Note: If p12 is greyed out you choose the wrong key
-
Convert the Format of the Private Key Convert the format of the private key you downloaded in step 3. Convert it first to a PEM certificate, then to a Base64 string.
a. Navigate to the directory where the private key is saved (Documents, by default):
cd Documents
b. Create the privatePem by typing the following in the terminal:
openssl pkcs12 -in NexioApplePayMerchantKey.p12 -out NexioApplePayMerchantKey.pem -nodes -clcerts
c. Convert .pem file to a Base64 string:
base64 NexioApplePayMerchantCRT.pem
-
Convert the Format of the Apple Pay Certificate Convert the format of the certificate you downloaded in step 2. Convert it first to a PEM certificate, then to a Base64 string.
a. Navigate to the directory where the private key is saved (Downloads, by default):
cd Downloads
b. Create the certPem by typing the following in the terminal:
openssl x509 -inform DER -outform PEM -in NexioApplePayMerchant.cer -out NexioApplePayMerchantCRT.pem
c. Convert the files to base64 strings
base64 NexioApplePayMerchantCRT.pem
Step 4: Verify Your Domain
Follow these steps to verify the domain to be used with Apple Pay. If you have multiple domains (for example, for development environments) repeat these steps for each.
-
Navigate to the Apple Developer Portal
Go to the Apple Developer Portal
-
Add the Domain
a. Click on 'Merchant Domains'
b. Click on 'Add Domain'
c. Enter the URL of the domain you plan to use. Click 'Save'.
d. Apple Pay will provide you with a text file to download and a URL. Download the file and copy the URL, you will use both in the next step.
-
Host the Text File at the Proper URL
Host the text file at the exact URL provided by Apple.
Step 5: Provide Your Configuration Settings to Integration Support
Once you have completed **steps 1-4**,
[contact integration support](#contact-us) to provide them with the following:
- Your [Apple Pay Merchant ID](#create-an-apple-pay-merchant-id)
- Your [Payment Processing Certificate](#create-a-payment-processing-certificate)
- Your [Merchant Identity Certificate](#create-a-merchant-identity-certificate)
- Your Authorize.Net Login ID
- Your Authorize.Net Transaction Key
- The [verified domain](#verify-your-domain) for processing
**Note:** The verified domain you provide to integration support will be used by default to process any Apple Pay transactions on your account.
If you have multiple verified domains for testing purposes,
you can dynamically choose the domain by providing `data.applePayDomain` in the payload when you request a [one-time-use token](#apm-one-time-use-token).
(See **step 4** of the [Button Iframes](#button-iframe-urls) tutorial for more information.)
PayPal (with Braintree)
In order to configure your account for use with PayPal (with Braintree), you will need the following:
- A login for the PayPal developer site
- A Braintree account
- PayPal accounts ready for your different markets
After you have the above, and have worked with integration support to get your PayPal ClientID, you are ready to follow the configuration steps.
Link PayPal Account to Braintree Environment
Integration support helps you complete this step for the Sandbox environment. However, you must do the configuration for your production environment.
Follow these steps to link your PayPal account:
-
Navigate to the Braintree Control Panel
Go to the Braintree Control Panel and log in.
-
Get the API keys
Go to Settings > API.
The system displays all the API keys.
-
Locate the Merchant ID
The Merchant ID displays at the bottom of the Keys page.
Make note of this ID because you will use this value in Step 7.
-
Navigate to Processing Options
Go back to the home screen.
Go to Settings > Processing > Processing Options.
-
Configure Options
In the PayPal area, click Options.
You are prompted to log in with your PayPal account credentials.
After successfully logging in, the PayPal Accounts page displays. Braintree retrieves the necessary clientID, PayPal email, and Client Secret.
-
Link One or More PayPal Accounts
Merchant account IDs are created and added to the merchant account by PayPal, after the merchant has signed all the necessary PayPal documentation. Contact PayPal and the merchant to arrange the creation of merchant account IDs. Follow this same process when you need to add new payment methods to the merchant account.
a. Click the +Link New PayPal Account button.
b. Provide PayPal account details and URLs for Privacy Policy and Terms and Conditions.
c. In the new account row (the one that does not show any merchant accounts), click Edit.
d. Start typing the merchant account name so that the selector displays a list of all potential matches.
e. If you want to enable PayPal Disputes for this account, select Manage PayPal Disputes in the Braintree Control Panel.
Note: If you link a merchant account here, any previous links made to that merchant account are removed.
-
Add Merchant Account IDs for Each Currency to Support
To support multiple currencies, you must have a different merchant account ID for each currency. Work with your PayPal account representative to arrange this, using the value you noted in Step 3.
PayPal (with Braintree) Payment Flow
The following show the general flows for a customer accessing a merchant site through payment using PayPal with Braintree, either from the cart or the checkout page.
Customer adds item to shopping cart and clicks PayPal button to pay
-
The customer adds one or more items to a shopping cart.
-
The customer goes to that cart, the order amount displays, along with a Pay with PayPal button.
-
If the customer clicks that button, they are asked to log in to PayPal and to select their payment options and address information.
-
After making those selections, the customer clicks an Agree & Continue button.
-
The customer is redirected to a Confirm/Place Order page. Based on the address selected, they see tax and shipping costs for this order and are asked to confirm payment.
-
The customer is redirected to a Receipt page.
Customer adds item to cart and clicks Checkout button
-
The customer adds one or more items to a shopping cart.
-
The customer goes to that cart, the order amount displays, along with a Pay with PayPal button.
-
Customer instead clicks the Checkout button and is redirected to a Checkout page with all available payment options (potentially including PayPal). Customer address information is collected (or retrieved) and is used to generate tax and shipping costs.
-
If the customer clicks the PayPal button here, they are asked to log in to PayPal and to select their payment options.
If the customer clicks a different APM button, the process for that specific APM continues through to confirming the payment options.
If the customer submits payment for card or ACH, the process continues based on the entered payment options.
-
The customer is redirected to a Receipt page.
Google Pay
In order to configure your account for use with Google Pay, you will need the following:
- A Google Pay Console account
- A Google Pay Console Business Profile
- A Google Pay Console Merchant ID
- An Authorize.Net account
Klarna
This section provides the following topics:
- Overview
- Run a Transaction through Klarna
- Response Handling
- Status Workflows
- Error handling
- Troubleshooting
Overview
Klarna is a payment provider allowing consumers to pay using their payment methods saved to their Klarna account. This section is intended to help you implement Klarna based on your preferred integration workflow.
You can offer Klarna as a payment provider for your consumers in any of the following ways:
- In an iframe that displays all payment methods available to the consumer (based on the consumer’s location and the merchant’s configured payment methods)
- In an individual iframe for Klarna
Solution
Regardless of the implementation workflow you implement, consumers will be redirected to Klarna to complete their transactions.
Nexio supports the following transaction types for Klarna:
Nexio supports the following countries and regions for Klarna:
- United States
- Great Britain
- European Region
- Canada
- Australia
- Sweden
- New Zealand
- Norway
- Denmark
- Switzerland
Nexio currently supports the following processing currencies for Klarna:
- USD
- GDP
- EUR
- CAD
- AUD
- SEK
- NZD
- NOK
- DKK
- CHF
The merchant needs to go through Klarna’s underwriting process and the merchant needs to contract with Klarna directly for them to provision a Production merchant ID (MID) with the payment methods for the region that the merchant wants to process. Only the payment methods approved and contracted with Klarna and the merchant will be the ones available at checkout for the consumer.
Development scope
This guide walks you through the process of getting Klarna set up in the sandbox environment and connecting your website using our API.
Intended audience
This guide is intended for developers looking to allow online consumers to make purchases on a merchant’s website using Klarna.
You should already have experience using the Nexio APIs and understand how to create one-time-use tokens, send and receive requests, and work with the Sale, Auth Only, Capture, and Refund transaction types. If you need more information about these things, see the Getting Started section and work through the concepts and examples in e-Commerce Flows and Operations.
Prerequisites
The following table shows the required and optional fields for Klarna transactions in the APM One-time Use Token request.
Field | Required? | Description |
---|---|---|
data.amount |
Y | The transaction amount. This value must equal data.cart.items[n].quantity times data.cart.items[n].price . |
data.currency |
Y | The three-character ISO currency code for the transaction. Note: See Solution for the list of supported processing currencies with Klarna. |
data.customer.orderNumber |
Y | The order number. |
data.customer.firstName |
Y | The customer's first name, as it appears on the credit card. |
data.customer.lastName |
Y | The customer's last name, as it appears on the credit card. |
data.customer.email |
Y | The customer's email address. |
data.customer.billToCountry |
Y | The two-character (Alpha-2) ISO country code. Note: See Solution for the list of supported countries with Klarna. |
data.cart.items[n].description |
Y | A description of the item. |
data.cart.items[n].price |
Y | The price per item. |
data.cart.items[n].quantity |
Y | The quantity sold. |
data.cart.items[n].item |
Optional | Item number or code. |
data.totalTaxAmount |
Optional | Total tax amount. |
Testing Data
For testing data, see Klarna’s Testing Environment page.
Use 4.00
as the amount in your request to continue the payment in Klarna.
Run a Transaction through Klarna
You can offer Klarna as a payment provider for your consumers in any of the following ways:
- Through Express APM, in an iframe that displays all payment methods available to the consumer, including Klarna
- In an individual iframe for Klarna
Express APM with Klarna
Nexio's Express APM service allows shoppers to run transactions through many of our supported alternative payment methods (APMs) with a single integration, including Klarna. When you integrate with Express APM, shoppers will be shown a list of all available APMs (based on their location and the merchant’s configured payment methods), prompted to select their preference, then be redirected to complete payment.
Notes:
- This service is not compatible with embedded browsers in apps
- For instructions on how to do an auth only transaction with Klarna, see Express APM for Auth Only with Klarna
To integrate with Express APM for Klarna, follow the steps below.
-
Configure Your Account
Contact integration support to enable Klarna on your merchant account.
-
Create a Checkout Page
Create a checkout page with an iframe.
-
Request an Express Iframe URL
Send a
POST
request to the APM One-time-use Token endpoint.Include the following required parameters:
data.amount
(must equal the price times the quantity)data.currency
(see Solution for the list of supported processing currencies with Klarna)data.customer.orderNumber
data.customer.firstName
data.customer.lastName
data.customer.email
data.customer.billToCountry
(see Solution for the list of supported countries with Klarna)data.cart.items[n].description
data.cart.items[n].price
data.cart.items[n].quantity
In addition, you may include the following optional parameters:
data.totalTaxAmount
data.cart.items[n].item
You may choose to have Nexio provide an in-frame submit button or your own external button by setting the
displaySubmitButton
UI Option totrue
for an in-frame submit button orfalse
for an external submit button.Example Request
curl -X POST https://api.nexiopaysandbox.com/apm/v3/token \ -H 'Content-Type: application/json' \ -H 'Accept: application/json' \ -H 'Authorization: Basic <Your Basic Auth>' -d '{ "data": { "amount": 4.00, "currency": "USD", "customer": { "orderNumber": "12345678", "firstName": "John", "lastName": "Doe", "email": "john@doe.com", "billToCountry": "US" }, "totalTaxAmount": 0, "cart": { "items": [ { "item": "E200", "description": "Platinum set", "quantity": 2, "price": 2 } ] } } }'
A successful response will include the
expressIFrameUrl
. Copy or store theexpressIFrameUrl
value for use in step 4.Example 200 Response
{ "expiration": "2021-07-22T20:49:50.000Z", "token": "54a0106y-7750-45b1-961e-29ad95763a23", "expressIFrameUrl": "https://api.nexiopaysandbox.com/apm/v3?token=54a0106y-7750-45b1-961e-29ad95763a23", "redirectUrls": [ { "paymentMethod": "klarnaPayments", "url": "https://api.nexiopaysandbox.com/apm/v3/popup?token=54a0106b-7750-45b1-961e-29ad95763a23&paymentMethod=klarnaPayments" } ], "buttonIFrameUrls": [ { "paymentMethod": "klarnaPayments", "url": "https://api.nexiopaysandbox.com/apm/v3?token=54a0106b-7750-45b1-961e-29ad95763a23&paymentMethod=klarnaPayments" }, { "paymentMethod": "braintreePayPal", "url": "https://api.nexiopaysandbox.com/apm/v3?token=54a0106b-7750-45b1-961e-29ad95763a23&paymentMethod=braintreePayPal" } ], "scriptUrl": "https://api.nexiopaysandbox.com/apm/v3/scripts?token=54a0106y-7750-45b1-961e-29ad95763a23" }
-
Redirect the Shopper to the Selected APM Page
Assign the
expressIframeUrl
from the previous step to your iframe'ssrc
tag.If using your own external button, you can style the button and create custom actions that run when the consumer clicks it (in addition to going to the APM payment page).
Example
var url = "https://www.api.nexiopaysandbox.com/v3?token=54a0106y-7750-45b1-961e-29ad95763a23"; window.document.getElementById('myIframe').src = url;
When your iframe loads, shoppers will be prompted to select from a list of configured APMs, including Klarna. The shopper makes their selection of Klarna, clicks 'Submit' (on your button or the iframe button, depending on your choice), then gets redirected to Klarna to complete payment.
-
Shopper Completes Payment
Users will be prompted to complete the transaction.
Afterward they will be redirected back to the merchant website.
The consumer is redirected to the checkout page. Nexio provides a response as event messages
If your merchant account is configured to receive webhooks, in addition to one of the above, Nexio provides responses as event messages to the webhook URLs that have been registered.
-
Create a Receipt for the Shopper
After the shopper has completed payment (or payment has failed), Nexio's iframe will request to be closed and send a message event with the payment information.
- If the payment was successful, the message will include the status and payment ID. For information about status, see Status Workflows
- If the payment failed, the message will include the status and an error message. For information about handling errors with Klarna, see Error Handling in Klarna
Use the message information to create a success (such as a receipt) or failure page for the shopper. You may also want to send a receipt to the shopper via email.
Example event message response:
Example Sale Response
{ "id": "eyJuYW1lIjoia2xhcm5hIiwibWVyY2hhbnRJZCI6IjEwMDI2MCIsInJlZk51bWJlciI6Ijk1M2VmOTFkLTkzNTYtNGRhYi1hZGQ3LTQyOTI0ZGUyNTk3OSIsInJhbmRvbSI6MCwiY3VycmVuY3kiOiJ1c2QifQ==", "merchantId": "100260", "transactionDate": "2021-07-22T19:54:51.033Z", "transactionStatus": "pending", "amount": 4, "transactionType": "sale", "currency": "USD", "gatewayResponse": { "result": 200, "refNumber": "953ef91d-9356-4dab-add7-42924de25979", "gatewayName": "klarnaPayments", "message": "checkout_complete" }, "data": { "amount": 4, "currency": "USD", "settlementCurrency": "USD", "customer": { "lastName": "Doe", "shipToAddressOne": "123 Ship St", "shipToPhone": "5033335678", "orderNumber": "7beb71d234c441e5a3c6a475835f8590", "shipToCountry": "US", "shipToAddressTwo": "Warehouse 456", "billToState": "AL", "billToCity": "Huntsville", "shipToPostal": "67890", "firstName": "John", "shipToCity": "Shipperville", "billToAddressOne": "107 Shoalford Dr", "billToCountry": "US", "billToPostal": "35806", "billToAddressTwo": "Suite 123", "billToPhone": "8015551234", "email": "nexiotest@example.com", "shipToState": "OR" }, "cart": { "items": [ { "description": "Platinum set", "item": "E200", "quantity": 2, "type": "sale", "price": 2 } ] } } }
Button Iframe URLs with Klarna
To integrate with Button Iframe URLs with Klarna, follow the steps below.
-
Configure Your Account
Contact integration support to enable Klarna on your merchant account.
-
Create a Checkout Page
-
Add Iframes to your checkout page
Add an iframe for Klarna.
Note: The ID for the iframe is optional. You can use it with your own CSS.
Example 1: Klarna only
<iframe id='nexio-klarna-iframe'> <!-- Klarna Iframe Option 1 --> </iframe>
Example 2: Klarna plus others
<iframe id='nexio-klarna-iframe'> <!-- Klarna Iframe with other iframes --> </iframe> <iframe id='<unique-iframe-id>'> <!-- Any other APM iframe. Add more as needed. --> </iframe>
-
Request the APM Button Iframe URLs
Send a
POST
request to the APM One-time-use Token endpoint.Include the following required parameters:
data.amount
(must equal the price times the quantity)data.currency
(see Solution for the list of supported processing currencies with Klarna)data.customer.orderNumber
data.customer.firstName
data.customer.lastName
data.customer.email
data.customer.billToCountry
(see Solution for the list of supported countries with Klarna)data.cart.items[n].description
data.cart.items[n].price
data.cart.items[n].quantity
In addition, you may include the following optional parameters:
data.totalTaxAmount
data.cart.items[n].item
Example Request
curl -X POST https://api.nexiopaysandbox.com/apm/v3/token \ -H 'Content-Type: application/json' \ -H 'Accept: application/json' \ -H 'Authorization: Basic <Your Basic Auth>' -d '{ "data": { "amount": 4.00, "currency": "USD", "customer": { "orderNumber": "12345678", "firstName": "John", "lastName": "Doe", "email": "john@doe.com", "billToCountry": "US" }, "totalTaxAmount": 0, "cart": { "items": [ { "item": "E200", "description": "Platinum set", "quantity": 2, "price": 2 } ] } } }'
A successful request will return an array of
buttonIFrameUrls
. This array is a list of all APMs currently enabled on your merchant account. Copy theurl
of the Klarna APM for use in step 5.Example 200 Response
{ "expiration": "2021-07-22T20:49:50.000Z", "token": "54a0106y-7750-45b1-961e-29ad95763a23", "expressIFrameUrl": "https://api.nexiopaysandbox.com/apm/v3?token=54a0106y-7750-45b1-961e-29ad95763a23", "redirectUrls": [ { "paymentMethod": "klarnaPayments", "url": "https://api.nexiopaysandbox.com/apm/v3/popup?token=54a0106b-7750-45b1-961e-29ad95763a23&paymentMethod=klarnaPayments" } ], "buttonIFrameUrls": [ { "paymentMethod": "klarna", "url": "https://api.nexiopaysandbox.com/apm/v3?token=54a0106b-7750-45b1-961e-29ad95763a23&paymentMethod=klarnaPayments" }, { "paymentMethod": "braintreePayPal", "url": "https://api.nexiopaysandbox.com/apm/v3?token=54a0106b-7750-45b1-961e-29ad95763a23&paymentMethod=braintreePayPal" } ], "scriptUrl": "https://api.nexiopaysandbox.com/apm/v3/scripts?token=54a0106y-7750-45b1-961e-29ad95763a23" }
-
Add the Klarna URL to your Iframe
Add the
url
of the Klarna APM to thesrc
tag of the Klarna iframe you created in step 3.Example
var url = "https://api.nexiopaysandbox.com/apm/v3?token=54a0106b-7750-45b1-961e-29ad95763a23&paymentMethod=klarnaPayments"; window.document.getElementById('nexio-klarna-iframe').src = url;
Now, when the page loads, the shopper will see a button for each APM iframe you added to the page, including Klarna.
-
Shopper Completes Payment
When a consumer clicks the Klarna button, or any other, a popup window opens (or they are redirected to) to the appropriate APM page in which the consumer can complete payment.
Afterward, the popup window will close and they will be redirected back to the merchant website.
The consumer is redirected to the checkout page. Nexio provides a response as event messages.
If your merchant account is configured to receive webhooks, in addition to one of the above, Nexio provides responses as event messages to the webhook URLs that have been registered.
-
Shopper Redirected
Once the shopper has completed payment (or payment has failed) Nexio's iframe will request to be closed and send a message event with the payment information.
If the payment was successful, the message will include the status and payment ID. For information about status, see Status Workflows. If the payment failed, the message will include the status and an error message. For information about handling errors with Klarna, see Error Handling in Klarna.
Use the message information to create a success (such as a receipt) or failure page for the shopper. You may also want to send a receipt to the shopper via email.
Example event message response:
Example Sale Response
{ "token": "86da4b93-9867-4f30-a99b-c69f96eb801a", "id": "eyJuYW1lIjoia2xhcm5hIiwibWVyY2hhbnRJZCI6IjEwMDI2MCIsInJlZk51bWJlciI6Ijk1M2VmOTFkLTkzNTYtNGRhYi1hZGQ3LTQyOTI0ZGUyNTk3OSIsInJhbmRvbSI6MCwiY3VycmVuY3kiOiJ1c2QifQ==", "merchantId": "100260", "transactionDate": "2021-07-22T19:54:51.033Z", "transactionStatus": "pending", "amount": 4, "transactionType": "sale", "currency": "USD", "gatewayResponse": { "result": 200, "refNumber": "953ef91d-9356-4dab-add7-42924de25979", "gatewayName": "klarnaPayments", "message": "checkout_complete" }, "data": { "amount": 4, "currency": "USD", "settlementCurrency": "USD", "customer": { "lastName": "Doe", "shipToAddressOne": "123 Ship St", "shipToPhone": "5033335678", "orderNumber": "7beb71d234c441e5a3c6a475835f8590", "shipToCountry": "US", "shipToAddressTwo": "Warehouse 456", "billToState": "AL", "billToCity": "Huntsville", "shipToPostal": "67890", "firstName": "John", "shipToCity": "Shipperville", "billToAddressOne": "107 Shoalford Dr", "billToCountry": "US", "billToPostal": "35806", "billToAddressTwo": "Suite 123", "billToPhone": "8015551234", "email": "nexiotest@example.com", "shipToState": "OR" }, "cart": { "items": [ { "description": "Platinum set", "item": "E200", "quantity": 2, "type": "sale", "price": 2 } ] } } }
Response Handling
Nexio responds with transaction results in one of three ways, depending on your integration workflow:
- Event messages: This applies to all integrations
- Webhook notification: If your merchant account is configured to receive webhooks, in addition to the above, Nexio provides responses to the webhook URLs that have been registered
For information about how to run each of the integration workflows, see Run a Transaction through Klarna.
Status Workflows
The status of a successful transaction with Klarna varies, depending on the options you choose.
Sale
When isAuthOnly
is false
, successful sale transactions will have the following statuses:
- pending (called "authorized" when querying transactions and in Nexio Dashboard)
- settled
When isAuthOnly
is true
, successful sale transactions will have the following statuses:
- authOnlyPending
- authOnly
Capture
Successful capture transactions will have the following status:
- settled
Refund
Successful refund transactions will have the following status:
- settled
Error handling
For help with errors and declines, see the Handling Errors and Declines topic.
Troubleshooting
If you encounter issues while implementing or testing Klarna, contact integration support.
SEPA
This guide provides the following topics:
- Overview
- Run a Transaction through SEPA
- Run an Auth Only Transaction through SEPA
- Response Handling
- Status Workflows
- Error handling
- Troubleshooting
Overview
The SEPA (Single Euro Payments Area) with Adyen is is a pan-European network that allows consumers to send and receive payments in euros (€) between two cross-border bank accounts in the eurozone. With SEPA, sending money within the eurozone is as easy as making your usual domestic bank transfers.
A SEPA credit transfer is a single transfer of euros from one person or organization to another. For example, this could be to pay the deposit for a holiday rental or to settle an invoice. A SEPA direct debit is a recurring payment. For example, to pay monthly rent or for a service like a mobile phone contract.
This section is intended to help you implement SEPA with Adyen based on your preferred integration workflow.
You can offer SEPA as a payment provider for your consumers only in the following way:
Solution
Regardless of the implementation workflow you implement, consumers will be redirected to Adyen to complete their transactions.
Nexio supports the following transaction types for SEPA with Adyen:
Nexio currently supports the following currency for SEPA with Adyen:
- EUR
Note: SEPA with Adyen does not support chargebacks.
Development scope
This guide walks you through the process of getting SEPA with Adyen set up in the sandbox environment and connecting your website using our API.
Intended audience
This guide is intended for developers looking to allow online consumers to make purchases on a merchant’s website using SEPA.
You should already have experience using the Nexio APIs and understand how to create one-time-use tokens, send and receive requests, and work with the Sale, Auth Only, Capture, and Refund transaction types. If you need more information about these things, see the Getting Started section of the "Developer Documentation" and work through the concepts and examples in e-Commerce Flows and Operations.
Prerequisites
The following table shows the required and optional fields for SEPA with Adyen transactions in the APM One-time Use Token request.
Field | Required? | Description |
---|---|---|
isAuthOnly |
N | Set to true to run an auth only transaction. |
data.amount |
Y | The transaction amount. |
data.currency |
Y | The three-character ISO currency code for the transaction. Note: Nexio only supports EUR with SEPA. |
data.paymentMethod |
Y | The desired alternative payment method. This value must be adyenSepa . |
data.dueDate |
N | The date by which the customer must complete the payment. |
data.description |
N | A description of the transaction. |
data.customer.orderNumber |
Y | The order number. |
data.customer.firstName |
Y | The customer's first name, as it appears on the credit card. |
data.customer.lastName |
Y | The customer's last name, as it appears on the credit card. |
data.customer.email |
Y | The customer's email address. |
data.customer.billToAddressOne |
N | The customer's billing street address. |
data.customer.billToAddressTwo |
N | Additional street address information, if required. |
data.customer.city |
N | The customer's billing city. |
data.customer.billToCountry |
N | The two-character (Alpha-2) ISO country code. |
data.customer.billToPhone |
N | The billing phone number. |
data.customer.billToPostal |
N | The customer's billing postal code. |
data.customer.billToState |
N | The state or province on file with the credit card provider. |
data.customer.customerRef |
N | Customer identifier. You can use this field to pass a customer ID to the gateway or APM or to manage user subscriptions. |
data.customer.shipToAddressOne |
N | The shipping address, if different from the billing address. |
data.customer.shipToAddressTwo |
N | Additional shipping address information, if required. |
data.customer.shipToCity |
N | The shipping city. |
data.customer.shipToCountry |
N | The two-character (Alpha-2) ISO country code. |
data.customer.shipToPhone |
N | The shipping phone number. |
data.customer.shipToPostal |
N | The shipping postal code. |
data.customer.shipToState |
N | The shipping state or province. |
processingOptions.paymentOptionTag |
N | A custom value used to route transactions to a specific gateway or merchant account. |
processingOptions.merchantId |
N | The merchant ID (MID). |
Testing Data
Adyen has an extensive list of test accounts. For more information, see SEPA Direct Debit on Adyen's site.
Run a Transaction through SEPA
You can offer SEPA as a payment provider for your consumers in the following way:
- Through Express APM, in an iframe that displays the SEPA form fields and Pay button to the consumer
Express APM with SEPA
Nexio's Express APM service allows shoppers to run transactions through many of our supported alternative payment methods (APMs) with a single integration, including SEPA. When you integrate with Express APM, shoppers will be shown a list of all available APMs (based on their location and the merchant’s configured payment methods), prompted to select their preference, then be redirected to complete payment.
Notes:
- This service is not compatible with embedded browsers in apps
- For instructions on how to do an auth only transaction with SEPA, see Express APM for Auth Only with SEPA
To integrate with Express APM for SEPA, follow the steps below.
-
Configure Your Account
Contact integration support to enable SEPA with Adyen on your merchant account.
-
Create a Checkout Page
Create a checkout page with an iframe for SEPA.
-
Request an Express Iframe URL
Send a
POST
request to the APM One-time-use Token endpoint.Include the following required parameters:
data.amount
data.currency
(EUR is currently the only supported currency for SEPA with Adyen)data.paymentMethod
- Use the value of adyenSepa for SEPA with Adyendata.customer.orderNumber
data.customer.firstName
data.customer.lastName
data.customer.email
In addition, you may include any of the the optional parameters. For the list of optional paramters, see Prerequisites.
Example Request
curl -X POST https://api.nexiopaysandbox.com/apm/v3/token \ -H 'Content-Type: application/json' \ -H 'Accept: application/json' \ -H 'Authorization: Basic <Your Basic Auth>' -d '{ "data": { "amount": 5.00, "currency": "EUR", "paymentMethod": "adyenSepa", "customer": { "orderNumber": "7beb71d234c441e5a3c6a475835f8590", "firstName": "John", "lastName": "Doe", "email": "john@doe.com" } } }'
A successful response will include the
expressIFrameUrl
. Copy or store theexpressIFrameUrl
value for use in step 4.Example 200 Response
{ "expiration": "2021-07-22T20:49:50.000Z", "token": "cb1f6727-f425-4ac9-b958-2b43c8bf7ae8", "expressIFrameUrl": "https://api.nexiopaysandbox.com/apm/v3?token=cb1f6727-f425-4ac9-b958-2b43c8bf7ae8", "redirectUrls": [ { "paymentMethod": "adyenSepa", "url": "https://api.nexiopaysandbox.com/apm/v3/popup?token=cb1f6727-f425-4ac9-b958-2b43c8bf7ae8&paymentMethod=adyenSepa" } ], "buttonIFrameUrls": [ { "paymentMethod": "adyenSepa", "url": "https://api.nexiopaysandbox.com/apm/v3?token=cb1f6727-f425-4ac9-b958-2b43c8bf7ae8&paymentMethod=adyenSepa" }, { "paymentMethod": "braintreePayPal", "url": "https://api.nexiopaysandbox.com/apm/v3?token=cb1f6727-f425-4ac9-b958-2b43c8bf7ae8&paymentMethod=braintreePayPal" } ], "scriptUrl": "https://api.nexiopaysandbox.com/apm/v3/scripts?token=cb1f6727-f425-4ac9-b958-2b43c8bf7ae8" }
-
Add the URL to the iframe.
Assign the
expressIframeUrl
from the previous step to your iframe'ssrc
tag.Example
var url = "https://www.api.nexiopaysandbox.com/v3?token=54a0106y-7750-45b1-961e-29ad95763a23"; window.document.getElementById('myIframe').src = url;
When your iframe loads, SEPA displays a form with fields for Holder Name and Account Number (IBAN), along with a Pay button.
-
Shopper Completes Payment
Users type appropriate values and click Pay.
Nexio provides a response as event messages.
-
Create a Receipt for the Shopper
After the shopper has completed payment (or payment has failed), Nexio's iframe sends a message event with the payment information.
- If the payment was successful, the message includes the status and payment ID. For information about status, see Status Workflows
- If the payment failed, the message includes the status and an error message. For information about handling errors with SEPA, see Error Handling in SEPA
Use the message information to create a success (such as a receipt) or failure page for the shopper. You may also want to send a receipt to the shopper via email.
Example event message response:
Example Sale Response
{ "id": "eyJuYW1lIjoia2xhcm5hIiwibWVyY2hhbnRJZCI6IjEwMDI2MCIsInJlZk51bWJlciI6Ijk1M2VmOTFkLTkzNTYtNGRhYi1hZGQ3LTQyOTI0ZGUyNTk3OSIsInJhbmRvbSI6MCwiY3VycmVuY3kiOiJ1c2QifQ==", "merchantId": "100260", "transactionDate": "2021-07-22T19:54:51.033Z", "transactionStatus": "pending", "amount": 5, "transactionType": "sale", "currency": "EUR", "gatewayResponse": { "result": "pending", "refNumber": "953ef91d-9356-4dab-add7-42924de25979", "gatewayName": "adyenSepa", "message": "Authorised" }, "data": { "amount": 5, "currency": "EUR", "settlementCurrency": "EUR", "customer": { "firstName": "John", "lastName": "Doe", "orderNumber": "7beb71d234c441e5a3c6a475835f8590", "email": "john@doe.com" } } }
Run an Auth Only Transaction through SEPA
You may wish to authorize a transaction (auth only) and capture it at a later time.
You can run an auth only transaction through SEPA using the following integration method:
Express APM for Auth Only with SEPA
To run an auth only transaction through SEPA using Express APM, follow the steps below.
-
Prepare Your Checkout Page
Follow steps 1-2 of the Express APM with SEPA tutorial.
-
Request an Express Iframe URL
Follow step 3 of the Express APM with SEPA tutorial.
Include
isAuthOnly: true
in the body of your request.Example Request
curl -X POST https://api.nexiopaysandbox.com/apm/v3/token \ -H 'Content-Type: application/json' \ -H 'Accept: application/json' \ -H 'Authorization: Basic <Your Basic Auth>' -d '{ "isAuthOnly": true; "data": { "amount": 5.00, "currency": "EUR", "paymentMethod": "adyenSepa", "customer": { "orderNumber": "7beb71d234c441e5a3c6a475835f8590", "firstName": "John", "lastName": "Doe", "email": "john@doe.com" } } }'
A successful response will include the
expressIFrameUrl
. Copy or store this for use in step 3.Example 200 Response
{ "expiration": "2021-07-22T20:49:50.000Z", "token": "cb1f6727-f425-4ac9-b958-2b43c8bf7ae8", "expressIFrameUrl": "https://api.nexiopaysandbox.com/apm/v3?token=cb1f6727-f425-4ac9-b958-2b43c8bf7ae8", "redirectUrls": [ { "paymentMethod": "adyenSepa", "url": "https://api.nexiopaysandbox.com/apm/v3/popup?token=cb1f6727-f425-4ac9-b958-2b43c8bf7ae8&paymentMethod=adyenSepa" } ], "buttonIFrameUrls": [ { "paymentMethod": "adyenSepa", "url": "https://api.nexiopaysandbox.com/apm/v3?token=cb1f6727-f425-4ac9-b958-2b43c8bf7ae8&paymentMethod=adyenSepa" }, { "paymentMethod": "braintreePayPal", "url": "https://api.nexiopaysandbox.com/apm/v3?token=cb1f6727-f425-4ac9-b958-2b43c8bf7ae8&paymentMethod=braintreePayPal" } ], "scriptUrl": "https://api.nexiopaysandbox.com/apm/v3/scripts?token=cb1f6727-f425-4ac9-b958-2b43c8bf7ae8" }
-
Complete the Payment Process
Follow steps 4-6 of the Express APM with SEPA tutorial.
A successful auth only transaction will return a status of
authOnly
.
Response Handling with SEPA
Nexio responds with transaction results with Event messages.
For information about how to run the integration workflow, see Run a Transaction through SEPA.
Status Workflows with SEPA
The status of a successful transaction with SEPA varies, depending on the options you choose.
Sale
When isAuthOnly
is false
, successful sale transactions will have the following statuses:
- pending (called "authorized" when querying transactions and in Nexio Dashboard)
- settled
When isAuthOnly
is true
, successful sale transactions will have the following status:
- authOnly
Capture
Successful capture transactions will have the following status:
- settled
Error handling with SEPA
For help with errors and declines, see the Handling Errors and Declines topic in "Developer Documentation".
Troubleshooting with SEPA
If you encounter issues while implementing or testing SEPA with Adyen, contact integration support.
Run a Transaction
Express APM
Nexio's Express APM service allows shoppers to run transactions through many of our supported alternative payment methods (APMs) with a single integration. When you integrate with Express APM, shoppers will be shown a list of all available APMs, prompted to select their preference, then be redirected to complete payment.
Notes:
- This service is not compatible with embedded browsers in apps
- Apple Pay, Google Pay, and PayPal (with Braintree) are not currently supported through Express APM
- For the Klarna APM, see Express APM with Klarna for specific instructions on running transactions using Express APM
- For the SEPA APM, see Express APM with SEPA for specific instructions on running transactions using Express APM
To integrate with Express APM, follow the steps below.
-
Configure Your Account
Contact integration support to enable any desired APMs on your merchant account.
-
Create a Checkout Page
Create a checkout page with an iframe.
-
Request an Express Iframe URL
Send a
POST
request to the APM One-time-use Token endpoint. Include the following required parameters:data.amount
data.currency
data.customer.firstName
data.customer.lastName
data.customer.email
data.customer.orderNumber
customerRedirectUrl
(only required if you intend to use your own external submit button)
You may choose to have Nexio provide an in-frame submit button or your own external button by using the
displaySubmitButton
UI Option.
Example Request
curl -X POST https://api.nexiopaysandbox.com/apm/v3/token \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Basic <Your Basic Auth>'
-d '{
"data": {
"amount": 29.99,
"currency": "USD",
"customer": {
"firstName": "Maria",
"lastName": "Velasquez",
"email": "mvelaquez@fake.email",
"orderNumber": "210058A"
}
},
"uiOptions": {
"displaySubmitButton": true
},
"customerRedirectUrl": "https://your-ecommerce-website.example.com"
}'
A successful response will include the expressIFrameUrl
.
Copy or store the expressIFrameUrl
value for use in step 4.
Example 200 Response
{
"expiration": "2018-09-18T15:43:05.664Z",
"token": "830d36f6-a5e3-4455-9600-3a55b63e2fc2",
"expressIFrameUrl": "https://www.api.nexiopaysandbox.com/v3?token=79001ef6-fb40-4917-b8ae-2294fdfe1cf2",
"redirectUrls": [
{
"paymentMethod": "payPal",
"url": "https://www.api.nexiopaysandbox.com/v3/popup?token=79001ef6-fb40-4917-b8ae-2294fdfe1cf2&paymentMethod=payPal"
}
],
"buttonIFrameUrls": [
{
"paymentMethod": "applePayAuthNet",
"url": "https://api.nexiopaysandbox.com/apm/v3?token=b61ca2a9-b804-4a28-a00e-b794c8975dee&paymentMethod=applePay"
}
]
}
-
Redirect the Shopper to the Select APM Page
Assign the
expressIframeUrl
from the previous step to your iframe'ssrc
tag.If using your own external button, you can style the button and create custom actions that run when the consumer clicks it (in addition to going to the APM payment page).
Example
var url = "https://www.api.nexiopaysandbox.com/v3?token=79001ef6-fb40-4917-b8ae-2294fdfe1cf2";
window.document.getElementById('myIframe').src = url;
When your iframe loads, shoppers will be prompted to select from a list of configured APMs. The shopper will make their selection, click 'Submit' (on your own external button or the iframe button, depending on your choice), then be redirected to their chosen APM to complete payment.
-
Shopper Completes Payment
This step varies slightly depending on the APM.
- Voucher payments (Paynet and SPEI): Users will be prompted to print or close the voucher page
- All other APMs: Users will be prompted to complete the transaction
Afterward they will be redirected back to the merchant site.
- If you did not send the
customerRedirectUrl
in the request from step 3, the consumer is redirected to the checkout page. Nexio provides a response as event messages - If you did send the
customerRedirectUrl
in the request from step 3, the customer is redirected to that URL. Nexio provides a response via query string parameters in the URL
If your merchant account is configured to receive webhooks, in addition to one of the above, Nexio provides responses as event messages to the webhook URLs that have been registered.
-
Create a Receipt for the Shopper
Once the shopper has completed payment (or payment has failed) Nexio's iframe will request to be closed and send a message event or redirect URL with the payment information. If the payment was successful, the message will include the status and payment ID. If the payment failed, the message will include the status and an error message.
Use the message information to create a success (such as a receipt) or failure page for the shopper. You may also wish to send a receipt to the shopper via email.
Example event message response (for request without customerRedirectUrl or for webhook):
Example Sale Response
{
"id": "eyJuYW1lIjoicGF5UGFsIiwibWVyY2hhbnRJZCI6IjEwMDAzOSIsInJlZk51bWJlciI6IjlLQTI2NzUwSEs5NzM2OTNBIiwicmFuZG9tIjowLCJjdXJyZW5jeSI6InVzZCJ9",
"merchantId": "100039",
"transactionDate": "2020-06-29T18:54:01.087Z",
"transactionStatus": "settled",
"amount": 1.15,
"transactionType": "sale",
"currency": "USD",
"gatewayResponse": {
"result": 201,
"refNumber": "9KA26750HK973693A",
"gatewayName": "payPal",
"message": 201
},
"data": {
"amount": 1.15,
"currency": "USD",
"settlementCurrency": "USD",
"customer": {
"lastName": "Test",
"shipToAddressOne": "123 Ship St",
"shipToPhone": "5033335678",
"orderNumber": "054204daf0f7456bac59a014e952fb33",
"shipToCountry": "US",
"shipToAddressTwo": "Warehouse 456",
"billToState": "UT",
"billToCity": "Testerville",
"shipToPostal": "67890",
"firstName": "Nexio",
"shipToCity": "Shipperville",
"billToAddressOne": "123 Test St",
"billToCountry": "US",
"billToPostal": "12345",
"billToAddressTwo": "Suite 123",
"billToPhone": "8015551234",
"email": "nexiotest@example.com",
"shipToState": "OR"
}
}
}
Example URL query string parameters response (for customerRedirectUrl):
Successful Payment Redirect
https://www.yourwebsite.com?id=eyJuYW1lIjoicGF5UGFsIiwibWVyY2hhbnRJZCI6IjEwMDAzOSIsInJlZk51bWJlciI6IjlLQTI2NzUwSEs5NzM2OTNBIiwicmFuZG9tIjowLCJjdXJyZW5jeSI6InVzZCJ9&status=success&orderNumber=054204daf0f7456bac59a014e952fb33
Button Iframe URLs
Notes:
- For the Klarna APM, see Button Iframe URLs with Klarna for specific instructions on running transactions using a button iframe URL
-
Configure Your Account
Contact integration support to enable the desired APM on your merchant account. Note: Apple Pay and Google Pay require additional configuration steps, please see the Apple Pay configuration /Google Pay configuration sections for additional information.
-
Create Necessary Payment Flow Pages
Generally, a merchant site has the following pages:
- Shopping Cart
- Confirm/Place Order
- Checkout
- Receipt
-
Configure the Shopping Cart Page
This page displays all items in the cart and has a button for going to the Checkout page.
You can also offer alternative payment options (APMs), such as PayPal, as buttons on the page. The purpose of having these buttons at the Shopping Cart level is to have greater conversion before the customer goes to the checkout page.
a. Add an iframe for each APM you plan to offer to your shoppers. The ID for the iframe is optional (except for Apple Pay). Use it with your own CSS.
Apple Pay only: Assign the iframe that will be used for Apple Pay an ID of
nexioApplePayApmIframe
(other, less common options, arenexio-apm-iframe
ornexio-applePayAuthNet-apm-iframe
).
Example 1: Apple Pay
<iframe id='nexioApplePayApmIframe'> <!-- Apple Pay Iframe Option 1 -->
</iframe>
<iframe> <!- Any other APM iframe->
</iframe>
Example 2: Other APMs
<iframe id='nexio-paypal-iframe'> <!-- PayPal Iframe. ID only needed for your CSS. -->
</iframe>
<iframe id='<unique-iframe-id>'> <!-- Any other APM iframe. ID only needed for your CSS. -->
</iframe>
<!- Add more as needed. ->
b. To generate these buttons, send a POST
request to the APM One-time-use Token endpoint.
Include the following required parameters:
data.amount
data.currency
data.customer.firstName
data.customer.lastName
data.customer.email
data.customer.orderNumber
customerRedirectUrl
(only required if you intend to use your own external submit buttons)
Apple Pay only: If you wish to run the transaction through a domain other than the one you configured in step 1, include the parameter data.applePayDomain
in the body of your request.
Braintree PayPal only: If you want to save a recurring token for a future merchant-initiated transaction, include the parameter processingOptions.saveRecurringToken
in the body of your one-time-use token request and set it equal to true
. In addition, if the amount to process on the Confirm/Place Order page will be more than the current amount, you must include this parameter so that you can send the payment request (for example, if adding tax and shipping costs to the amount).
Example Request
curl -X POST https://api.nexiopaysandbox.com/apm/v3/token \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Basic <Your Basic Auth>'
-d '{
"data": {
"amount": 29.99,
"currency": "USD",
"customer": {
"firstName": "Maria",
"lastName": "Velasquez",
"email": "mvelaquez@fake.email",
"orderNumber": "210058A"
}
},
"customerRedirectUrl": "https://your-ecommerce-website.example.com"
}'
A successful request returns an array of buttonIFrameUrls
.
This array is a list of all APMs currently enabled on your merchant account.
Copy the url
of the desired APM from the buttonIFrameUrls
array for use in step 5.
Apple Pay only: Copy the scriptUrl
value as well for use in step 5.
Example 200 Response
{
"expiration": "2018-09-18T15:43:05.664Z",
"token": "830d36f6-a5e3-4455-9600-3a55b63e2fc2",
"scriptUrl": "https://api.nexiopaysandbox.com/apm/v3/script?token=b61ca2a9-b804-4a28-a00e-b794c8975dee",
"expressIFrameUrl": "https://www.api.nexiopaysandbox.com/v3?token=79001ef6-fb40-4917-b8ae-2294fdfe1cf2",
"redirectUrls": [...],
"buttonIFrameUrls": [
{
"paymentMethod": "nihaoPayAliPay",
"url": "https://api.nexiopaysandbox.com/apm/v3?token=b61ca2a9-b804-4a28-a00e-b794c8975dee&paymentMethod=nihaoPayAliPay"
},
{
"paymentMethod": "nihaoPayWechatPay",
"url": "https://api.nexiopaysandbox.com/apm/v3?token=b61ca2a9-b804-4a28-a00e-b794c8975dee&paymentMethod=nihaoPayWechatPay"
},
{
"paymentMethod": "payPal",
"url": "https://api.nexiopaysandbox.com/apm/v3?token=b61ca2a9-b804-4a28-a00e-b794c8975dee&paymentMethod=payPal"
},
{
"paymentMethod": "braintreePayPal",
"url": "https://api.nexiopaysandbox.com/apm/v3?token=b61ca2a9-b804-4a28-a00e-b794c8975dee&paymentMethod=braintreePayPal"
},
{
"paymentMethod": "nihaoPayUnionPay",
"url": "https://api.nexiopaysandbox.com/apm/v3?token=b61ca2a9-b804-4a28-a00e-b794c8975dee&paymentMethod=nihaoPayUnionPay"
},
{
"paymentMethod": "applePayAuthNet",
"url": "https://api.nexiopaysandbox.com/apm/v3?token=b61ca2a9-b804-4a28-a00e-b794c8975dee&paymentMethod=applePayAuthNet"
},
{
"paymentMethod": "googlePayAuthNet",
"url": "https://api.nexiopaysandbox.com/apm/v3?token=b61ca2a9-b804-4a28-a00e-b794c8975dee&paymentMethod=googlePayAuthNet"
}
]
}
c. Add each url
to the src tag of each iframe you created in step 3a, if applicable.
Apple Pay only: Copy the scriptUrl
to the src
of a script tag in the body tag of your checkout page. (If you add the script to the wrong tag on the page, the page will load but the script will not work.)
Now, when the page loads, the customer sees a button for each APM iframe you added to the page.
When they click a button (on your own external button or the iframe button, depending on the page configuration) they are sent to the appropriate APM page to complete payment (either redirected to the page or a popup window opened).
Apple Pay or Google Pay: The customer is not redirected. Rather, a popup window opens in which the shopper can complete payment.
PayPal with Braintree only: A popup window opens for the customer to log in. After setting an address (can be passed in the one-time-use token request and displayed to the customer as a default option) and payment method, the customer clicks Agree and Continue. The customer is redirected to the Confirm/Place Order page.
-
Configure the Confirm/Place Order Page
The Confirm/Place Order page is used to calculate taxes and shipping cost after gathering address information from the customer.
This page is important for PayPal. The customer gets redirected here after clicking the PayPal button on the Shopping Cart page, going through the PayPal login, and selecting their payment options.
a. In the response from PayPal (with Braintree), you get the address information and a token for completing the payment in the full amount (with shipping and tax included).
b. Based on the address returned, calculate the taxes and shipping cost as you normally would and display that on the page.
c. Use the token returned from step 3b with the Pay button to send the full payment amount to PayPal.
d. After the customer clicks the button, they are redirected to the page you specified in your PayPal configuration (such as a Receipt page).
-
Configure the Checkout Page
The Checkout page gives the customer the opportunity to provide address and payment information, and for the page to calculate and display tax and shipping cost.
In addition to a Pay button, you can also offer alternative payment options (APMs), such as PayPal, as buttons on the page so consumers have more options for payment.
a. Add an iframe for each APM you plan to offer to your shoppers. The ID for the iframe is optional (except for Apple Pay). Use it with your own CSS.
Apple Pay only: Assign the iframe that will be used for Apple Pay an ID of
nexioApplePayApmIframe
(other, less common options, arenexio-apm-iframe
ornexio-applePayAuthNet-apm-iframe
).
Example 1: Apple Pay
<iframe id='nexioApplePayApmIframe'> <!-- Apple Pay Iframe Option 1 -->
</iframe>
<iframe> <!- Any other APM iframe->
</iframe>
Example 2: Other APMs
<iframe id='nexio-paypal-iframe'> <!-- PayPal Iframe. ID only needed for your CSS. -->
</iframe>
<iframe id='<unique-iframe-id>'> <!-- Any other APM iframe. ID only needed for your CSS. -->
</iframe>
<!- Add more as needed. ->
b. To generate these buttons, send a POST
request to the APM One-time-use Token endpoint.
Include the following required parameters:
data.amount
data.currency
data.customer.firstName
data.customer.lastName
data.customer.email
data.customer.orderNumber
customerRedirectUrl
(only required if you intend to use your own external submit buttons)
Apple Pay only: If you wish to run the transaction through a domain other than the one you configured in step 1, include the parameter data.applePayDomain
in the body of your request.
Braintree PayPal only: If you want to save a recurring token for a future merchant-initiated transaction, include the parameter processingOptions.saveRecurringToken
in the body of your one-time-use token request and set it equal to true
.
Example Request
curl -X POST https://api.nexiopaysandbox.com/apm/v3/token \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Basic <Your Basic Auth>'
-d '{
"data": {
"amount": 29.99,
"currency": "USD",
"customer": {
"firstName": "Maria",
"lastName": "Velasquez",
"email": "mvelaquez@fake.email",
"orderNumber": "210058A"
}
},
"customerRedirectUrl": "https://your-ecommerce-website.example.com"
}'
A successful request returns an array of buttonIFrameUrls
.
This array is a list of all APMs currently enabled on your merchant account.
Copy the url
of the desired APM from the buttonIFrameUrls
array for use in step 5.
Apple Pay only: Copy the scriptUrl
value as well for use in step 5.
Example 200 Response
{
"expiration": "2018-09-18T15:43:05.664Z",
"token": "830d36f6-a5e3-4455-9600-3a55b63e2fc2",
"scriptUrl": "https://api.nexiopaysandbox.com/apm/v3/script?token=b61ca2a9-b804-4a28-a00e-b794c8975dee",
"expressIFrameUrl": "https://www.api.nexiopaysandbox.com/v3?token=79001ef6-fb40-4917-b8ae-2294fdfe1cf2",
"redirectUrls": [...],
"buttonIFrameUrls": [
{
"paymentMethod": "nihaoPayAliPay",
"url": "https://api.nexiopaysandbox.com/apm/v3?token=b61ca2a9-b804-4a28-a00e-b794c8975dee&paymentMethod=nihaoPayAliPay"
},
{
"paymentMethod": "nihaoPayWechatPay",
"url": "https://api.nexiopaysandbox.com/apm/v3?token=b61ca2a9-b804-4a28-a00e-b794c8975dee&paymentMethod=nihaoPayWechatPay"
},
{
"paymentMethod": "payPal",
"url": "https://api.nexiopaysandbox.com/apm/v3?token=b61ca2a9-b804-4a28-a00e-b794c8975dee&paymentMethod=payPal"
},
{
"paymentMethod": "braintreePayPal",
"url": "https://api.nexiopaysandbox.com/apm/v3?token=b61ca2a9-b804-4a28-a00e-b794c8975dee&paymentMethod=braintreePayPal"
},
{
"paymentMethod": "nihaoPayUnionPay",
"url": "https://api.nexiopaysandbox.com/apm/v3?token=b61ca2a9-b804-4a28-a00e-b794c8975dee&paymentMethod=nihaoPayUnionPay"
},
{
"paymentMethod": "applePayAuthNet",
"url": "https://api.nexiopaysandbox.com/apm/v3?token=b61ca2a9-b804-4a28-a00e-b794c8975dee&paymentMethod=applePayAuthNet"
},
{
"paymentMethod": "googlePayAuthNet",
"url": "https://api.nexiopaysandbox.com/apm/v3?token=b61ca2a9-b804-4a28-a00e-b794c8975dee&paymentMethod=googlePayAuthNet"
}
]
}
c. Add each url
to the src tag of each iframe you created in step 3a, if applicable.
Apple Pay only: Copy the scriptUrl
to the src
of a script tag in the body tag of your checkout page. (If you add the script to the wrong tag on the page, the page will load but the script will not work.)
Now, when the page loads, the customer sees a button for each APM iframe you added to the page.
When they click a button (on your own external button or the iframe button, depending on the page configuration) they are sent to the appropriate APM page to complete payment (either redirected to the page or a popup window opened).
Apple Pay or Google Pay: The customer is not be redirected. Rather, a popup window opens in which the shopper can complete payment.
PayPal with Braintree only: A popup window opens for the customer to log in. After setting an address (can be passed in the one-time-use token request and displayed to the customer as a default option) and payment method, the customer clicks Agree and Continue. The customer gets redirected to the Confirm/Place Order page.
-
Shopper Completes Payment
This step varies slightly depending on the APM.
- Voucher payments (Paynet and SPEI): Users will be prompted to print or close the voucher page
- Braintree PayPal only: If the customer checked out using Braintree PayPal and
saveRecurringToken
was set totrue
in the one-time-use token request, then the response includes anapm.token
parameter. For example:
{ "apm": { "token": "apm:f58kq4b5-h408-3a29-s07b-c384j3958fkw" } }
- All other APMs: Users will be prompted to complete the transaction
After the consumer completes payment, the popup window closes and they are redirected back to the merchant website.
- If you did not send the
customerRedirectUrl
in the request from step 3, the consumer is redirected to the checkout page. Nexio provides a response as event messages - If you did send the
customerRedirectUrl
in the request from step 3, the customer is redirected to that URL. Nexio provides a response via query string parameters in the URL
If your merchant account is configured to receive webhooks, in addition to one of the above, Nexio provides responses as event messages to the webhook URLs that have been registered.
-
Shopper Redirected
Once the shopper has completed payment (or payment has failed) Nexio's iframe will request to be closed and send a message event or redirect URL with the payment information. If the payment was successful, the message will include the status and payment ID. If the payment failed, the message will include the status and an error message.
Use the message information to create a success (such as a receipt) or failure page for the shopper. You may also wish to send a receipt to the shopper via email.
Example URL query string parameters response (for customerRedirectUrl):
Successful Payment Redirect
https://www.your-ecommerce-website.com?status=pending&paymentId=eyJuYW1lIjoidXNhZXBheSIsInJlZk51bWJlciI6IjMxMDA5MDc4MTkiLCJtZXJjaGFudElkIjoiMTAwMDM5IiwicmFuZG9tIjoiMzEwMDkwNzgxOSIsImN1cnJlbmN5IjoiVVNEIn0&orderNumber=228c3778fe
Example URL query string parameters response (for customerRedirectUrl) for a failed payment:
Failed Payment Redirect
https://your-ecommerce-website.example.com?status=pending&error=error_message
Example event message response (for request without customerRedirectUrl or for webhook):
Example Sale Response
{
"id": "eyJuYW1lIjoicGF5UGFsIiwibWVyY2hhbnRJZCI6IjEwMDAzOSIsInJlZk51bWJlciI6IjlLQTI2NzUwSEs5NzM2OTNBIiwicmFuZG9tIjowLCJjdXJyZW5jeSI6InVzZCJ9",
"merchantId": "100039",
"transactionDate": "2020-06-29T18:54:01.087Z",
"transactionStatus": "settled",
"amount": 1.15,
"transactionType": "sale",
"currency": "USD",
"gatewayResponse": {
"result": 201,
"refNumber": "9KA26750HK973693A",
"gatewayName": "payPal",
"message": 201
},
"data": {
"amount": 1.15,
"currency": "USD",
"settlementCurrency": "USD",
"customer": {
"lastName": "Test",
"shipToAddressOne": "123 Ship St",
"shipToPhone": "5033335678",
"orderNumber": "054204daf0f7456bac59a014e952fb33",
"shipToCountry": "US",
"shipToAddressTwo": "Warehouse 456",
"billToState": "UT",
"billToCity": "Testerville",
"shipToPostal": "67890",
"firstName": "Nexio",
"shipToCity": "Shipperville",
"billToAddressOne": "123 Test St",
"billToCountry": "US",
"billToPostal": "12345",
"billToAddressTwo": "Suite 123",
"billToPhone": "8015551234",
"email": "nexiotest@example.com",
"shipToState": "OR"
}
}
}
Redirect URLs
The single APM integration option allows you to send shoppers directly to a single APM to complete payment. Upon completion (payment success or failure) shoppers will be redirected to the customer redirect URL provided in step 3 of the tutorial below.
Notes:
- PayPal (with Braintree) is not currently supported through Redirect URLs
- Klarna is not currently supported through Redirect URLs
To integrate with a single APM, follow the steps below.
-
Configure Your Account
Contact integration support to enable the desired APM on your merchant account.
-
Create a Checkout Page
On the page, for each APM you want, include a button, image, link, or similar element that the consumer can click.
-
Request an APM Redirect URL
Send a
POST
request to the APM One-time-use Token endpoint. Include the following required parameters:data.amount
data.currency
data.customer.firstName
data.customer.lastName
data.customer.email
data.customer.orderNumber
customerRedirectUrl
Example Request
curl -X POST https://api.nexiopaysandbox.com/apm/v3/token \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Basic <Your Basic Auth>'
-d '{
"data": {
"amount": 29.99,
"currency": "USD",
"customer": {
"firstName": "Maria",
"lastName": "Velasquez",
"email": "mvelaquez@fake.email",
"orderNumber": "210058A"
}
},
"customerRedirectUrl": "https://your-ecommerce-website.example.com"
}'
A successful request will return an array of redirectUrls
.
This array is a list of all APMs currently enabled on your merchant account.
Copy the url
of the desired APM for use in step 4.
Example 200 Response
{
"expiration": "2018-09-18T15:43:05.664Z",
"token": "830d36f6-a5e3-4455-9600-3a55b63e2fc2",
"expressIFrameUrl": "https://www.api.nexiopaysandbox.com/v3?token=79001ef6-fb40-4917-b8ae-2294fdfe1cf2",
"redirectUrls": [
{
"paymentMethod": "nihaoPayAliPay",
"url": "https://www.api.nexiopaysandbox.com/v3/popup?token=79001ef6-fb40-4917-b8ae-2294fdfe1cf2&paymentMethod=nihaoPayAliPay"
},
{
"paymentMethod": "payPal",
"url": "https://www.api.nexiopaysandbox.com/v3/popup?token=79001ef6-fb40-4917-b8ae-2294fdfe1cf2&paymentMethod=payPal"
},
{
"paymentMethod": "paynet",
"url": "https://www.api.nexiopaysandbox.com/v3/popup?token=79001ef6-fb40-4917-b8ae-2294fdfe1cf2&paymentMethod=paynet"
},
{
"paymentMethod": "openpaySpei",
"url": "https://www.api.nexiopaysandbox.com/v3/popup?token=79001ef6-fb40-4917-b8ae-2294fdfe1cf2&paymentMethod=openpaySpei"
},
{
"paymentMethod": "nihaoPayUnionPay",
"url": "https://www.api.nexiopaysandbox.com/v3/popup?token=79001ef6-fb40-4917-b8ae-2294fdfe1cf2&paymentMethod=nihaoPayUnionPay"
},
{
"paymentMethod": "nihaoPayWechatPay",
"url": "https://www.api.nexiopaysandbox.com/v3/popup?token=79001ef6-fb40-4917-b8ae-2294fdfe1cf2&paymentMethod=nihaoPayWechatPay"
}
],
"buttonIFrameUrls": [...]
}
-
Redirect the Shopper to the APM
For each APM, add the
url
copied from step 3 to the appropriate form action, onClick location.url event, link src, and so forth for the element you added in step 2.Now, when the page loads, the shopper will see a button, image, and so forth for the APM (or APMs). The shopper clicks the element and then gets redirected (or a popup window opens) to the APM to complete payment.
-
Shopper Completes Payment
This step varies slightly depending on the APM.
- Voucher payments (Paynet and SPEI): Users will be prompted to print or close the voucher page
- All other APMs: Users will be prompted to complete the transaction
Afterward, the popup window will close and they will be redirected back to the merchant website specified in the
customerRedirectUrl
from Step 3. Nexio provides a response via query string parameters in the URL.If your merchant account is configured to receive webhooks, in addition to the above, Nexio provides responses to the webhook URLs that have been registered.
-
Shopper Redirected
Once the shopper has completed payment (or payment has failed) they will be redirected to the
customerRedirectUrl
you provided in step 3. If the payment was successful, the redirect URL will include the status, payment ID and order number as query parameters. If the payment failed, the redirect URL will include the status and an error message as query parameters.If your merchant account is configured to receive webhooks, in addition to the above, Nexio provides responses as event messages to the webhook URLs that have been registered.
Successful Payment Redirect
https://www.your-ecommerce-website.com?status=pending&paymentId=eyJuYW1lIjoidXNhZXBheSIsInJlZk51bWJlciI6IjMxMDA5MDc4MTkiLCJtZXJjaGFudElkIjoiMTAwMDM5IiwicmFuZG9tIjoiMzEwMDkwNzgxOSIsImN1cnJlbmN5IjoiVVNEIn0&orderNumber=228c3778fe
Failed Payment Redirect
https://your-ecommerce-website.example.com?status=pending&error=error_message
Example response for a webhook:
Example Sale Response
{
"id": "eyJuYW1lIjoicGF5UGFsIiwibWVyY2hhbnRJZCI6IjEwMDAzOSIsInJlZk51bWJlciI6IjlLQTI2NzUwSEs5NzM2OTNBIiwicmFuZG9tIjowLCJjdXJyZW5jeSI6InVzZCJ9",
"merchantId": "100039",
"transactionDate": "2020-06-29T18:54:01.087Z",
"transactionStatus": "settled",
"amount": 1.15,
"transactionType": "sale",
"currency": "USD",
"gatewayResponse": {
"result": 201,
"refNumber": "9KA26750HK973693A",
"gatewayName": "payPal",
"message": 201
},
"data": {
"amount": 1.15,
"currency": "USD",
"settlementCurrency": "USD",
"customer": {
"lastName": "Test",
"shipToAddressOne": "123 Ship St",
"shipToPhone": "5033335678",
"orderNumber": "054204daf0f7456bac59a014e952fb33",
"shipToCountry": "US",
"shipToAddressTwo": "Warehouse 456",
"billToState": "UT",
"billToCity": "Testerville",
"shipToPostal": "67890",
"firstName": "Nexio",
"shipToCity": "Shipperville",
"billToAddressOne": "123 Test St",
"billToCountry": "US",
"billToPostal": "12345",
"billToAddressTwo": "Suite 123",
"billToPhone": "8015551234",
"email": "nexiotest@example.com",
"shipToState": "OR"
}
}
}
Merchant-Initiated Transactions
You may want to support merchant-initiated transactions through PayPal (with Braintree) for your customers, such as for recurring transactions.
To allow for merchant-initiated transactions, follow the steps below.
-
Configure Your Account
Configure your Nexio account to use Braintree PayPal. If you need to have this done, contact integration support.
-
Create Necessary Payment Flow Pages
Complete step 2 in Button Iframe URLs to create any needed pages.
-
Configure Pages
Complete step 3 in Button Iframe URLs to create a Shopping Cart page. Include the URL from the "braintreePayPal"
paymentMethod
to add that payment option to the checkout page. IMPORTANT: Make sure to include theprocessingOptions.saveRecurringToken
parameter in the body of your one-time-use token request and set it equal totrue
.Complete step 4 in Button Iframe URLs to create a Confirm/Place Order page.
Complete step 5 in Button Iframe URLs to create a Checkout page. Include the URL from the "braintreePayPal"
paymentMethod
to add that payment option to the checkout page. IMPORTANT: Make sure to include theprocessingOptions.saveRecurringToken
parameter in the body of your one-time-use token request and set it equal totrue
. -
Shopper Completes Payment and You Save APM Token
If the customer clicks the PayPal (through Braintree) button as the payment method (steps 6-7 in Button Iframe URLs), then, in the event posted to your window, the response includes an
apm.token
parameter.Save the
apm.token
value somewhere in order to use it again (probably similar to how you save TokenEx tokens already).WARNING: This
apm.token
value cannot be retrieved through the API at any other time.By way of example, a response may look like the following. Notice the
apm
object and itstoken
:
Example Braintree PayPal Sale Response
{
"id": "eyJuYW1lIjoiYnJhaW50cmVlUGF5UGFsIiwibWVyY2hhbnRJZCI6IjEwMTAzOSIsInJlZk51bWJlciI6InA0NXljeWQ5IiwicmFuZG9tIjowLCJjdXJyZW5jeSI6InVzZCJ9",
"merchantId": "101039",
"transactionDate": "2021-07-13T22:12:56.780Z",
"transactionStatus": "settled",
"amount": 4,
"transactionType": "sale",
"currency": "USD",
"gatewayResponse": {
"result": "settling",
"refNumber": "p45ycyd9",
"gatewayName": "braintreePayPal",
"message": "settling"
},
"data": {
"amount": 4,
"currency": "USD",
"settlementCurrency": "USD",
"customer": {
"lastName": "Test",
"shipToAddressOne": "123 Ship St",
"shipToPhone": "5033335678",
"orderNumber": "1151057c04214a688c382ee1f666e76e",
"shipToCountry": "US",
"shipToAddressTwo": "Warehouse 456",
"billToState": "UT",
"billToCity": "Testerville",
"shipToPostal": "67890",
"firstName": "Nexio",
"shipToCity": "Shipperville",
"billToAddressOne": "123 Test St",
"billToCountry": "US",
"billToPostal": "12345",
"billToAddressTwo": "Suite 123",
"billToPhone": "8015551234",
"email": "nexiotest@example.com",
"shipToState": "OR"
}
},
"apm": {
"token": "apm:66b742ee-7abc-4e36-81ea-0a26d23d2822"
}
}
-
Run Merchant-Initiated Payment
Later, when you are ready to initiate another transaction for the customer without their input, use that stored
apm.token
value from step 4 above to run a payment.Send a
POST
request to the APM Run Transaction endpoint, as in the following example. Notice the inclusion of theapm
object with itstoken
in the body of the request:
Example Merchant-Initiated Request
curl -X POST https://api.nexiopaysandbox.com/apm/v3/process \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Basic <Your Basic Auth>'
-d '{
"isAuthOnly": false,
"apm": {
"token": "apm:66b742ee-7abc-4e36-81ea-0a26d23d2822"
},
"data": {
"currency":"USD",
"amount": 9.95,
"description": "test purchase",
"customer": {
"orderNumber": "sdgsrgrsb",
"firstName":"Joe",
"lastName":"Brown",
"billToAddressOne": "123 Street",
"billToAddressTwo": "Box 232",
"billToCity": "Narnia",
"billToState": "TX",
"billToPostal": "46632",
"billToCountry": "USA"
}
}
}'
You will then get a response, which will be similar to other payment responses that you normally get. On success, the response looks similar to the following:
Example 200 Response
{
"id": "eyJuYW1lIjoiYnJhaW50cmVlUGF5UGFsIiwibWVyY2hhbnRJZCI6IjEwMTAzOSIsInJlZk51bWJlciI6Ims3ZDN6cDJlIiwicmFuZG9tIjowLCJjdXJyZW5jeSI6InVzZCJ9",
"merchantId": "101039",
"transactionDate": "2021-07-13T22:14:03.514Z",
"transactionStatus": "settled",
"amount": 9.95,
"transactionType": "sale",
"currency": "USD",
"gatewayResponse": {
"result": "settling",
"refNumber": "k7d3zp2e",
"gatewayName": "braintreePayPal",
"message": "settling"
},
"data": {
"amount": 88,
"currency": "USD",
"settlementCurrency": "USD",
"customer": {
"orderNumber": "sdgsrgrsb",
"firstName": "Joe",
"lastName": "Brown",
"billToAddressOne": "123 Street",
"billToAddressTwo": "Box 232",
"billToCity": "Narnia",
"billToState": "TX",
"billToPostal": "46632",
"billToCountry": "USA"
}
}
}
Run an Auth Only Transaction
You may wish to authorize a transaction (auth only) and capture it at a later time. Please note that auth only transaction(s) are currently only available through the following alternative payment methods:
PayPal
To run an auth only transaction through PayPal, follow the steps below.
-
Prepare Your Checkout Page
Follow steps 1-2 of the Redirect URLs Integration tutorial.
-
Request the APM Redirect URL
Follow step 3 of the Redirect URLs Integration tutorial. Include
isAuthOnly: true
in the body of your request.
Example Request
curl -X POST https://api.nexiopaysandbox.com/apm/v3/token \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Basic <Your Basic Auth>'
-d '{
"data": {
"amount": 29.99,
"currency": "USD",
"customer": {
"firstName": "Maria",
"lastName": "Velasquez",
"email": "mvelaquez@fake.email",
"orderNumber": "210058A"
}
},
"isAuthOnly": true,
"customerRedirectUrl": "https://your-ecommerce-website.example.com"
}'
Example 200 Response
{
"expiration": "2018-09-18T15:43:05.664Z",
"token": "830d36f6-a5e3-4455-9600-3a55b63e2fc2",
"scriptUrl": "https://api.nexiopaysandbox.com/apm/v3/script?token=b61ca2a9-b804-4a28-a00e-b794c8975dee",
"expressIFrameUrl": "https://www.api.nexiopaysandbox.com/v3?token=79001ef6-fb40-4917-b8ae-2294fdfe1cf2",
"redirectUrls": [
{
"paymentMethod": "nihaoPayAliPay",
"url": "https://www.api.nexiopaysandbox.com/v3/popup?token=79001ef6-fb40-4917-b8ae-2294fdfe1cf2&paymentMethod=nihaoPayAliPay"
},
{
"paymentMethod": "payPal",
"url": "https://www.api.nexiopaysandbox.com/v3/popup?token=79001ef6-fb40-4917-b8ae-2294fdfe1cf2&paymentMethod=payPal"
}
],
"buttonIFrameUrls": [...]
}
A successful request will return an array of redirectUrls
.
This array is a list of all APMs currently enabled on your merchant account.
Copy the URL associated with the payPal
payment method.
-
Complete the Payment Process
Follow steps 4-6 of the Redirect URLs Integration tutorial. A successful auth only transaction will return a status of
success
PayPal (with Braintree)
To run an auth only transaction through PayPal (with Braintree), follow the steps below.
-
Prepare Your Cart or Checkout Page
Follow steps 1-5 of the Button Iframe URLs tutorial.
In making the one-time-use token request, include
isAuthOnly: true
in the body of your request. If you want to save a recurring token for a future merchant-initiated transaction, includeprocessingOptions.saveRecurringToken
in the body of your request and set it equal totrue
.
Example Request
curl -X POST https://api.nexiopaysandbox.com/apm/v3/token \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Basic <Your Basic Auth>'
-d '{
"data": {
"amount": 29.99,
"currency": "USD",
"customer": {
"firstName": "Maria",
"lastName": "Velasquez",
"email": "mvelaquez@fake.email",
"orderNumber": "210058A"
}
},
"isAuthOnly": true,
"processingOptions": {
"saveRecurringToken": true
},
"customerRedirectUrl": "https://your-ecommerce-website.example.com"
}'
Example 200 Response
{
"expiration": "2018-09-18T15:43:05.664Z",
"token": "830d36f6-a5e3-4455-9600-3a55b63e2fc2",
"scriptUrl": "https://api.nexiopaysandbox.com/apm/v3/script?token=b61ca2a9-b804-4a28-a00e-b794c8975dee",
"expressIFrameUrl": "https://www.api.nexiopaysandbox.com/v3?token=79001ef6-fb40-4917-b8ae-2294fdfe1cf2",
"redirectUrls": [...],
"buttonIFrameUrls": [
{
"paymentMethod": "nihaoPayAliPay",
"url": "https://www.api.nexiopaysandbox.com/v3/popup?token=79001ef6-fb40-4917-b8ae-2294fdfe1cf2&paymentMethod=nihaoPayAliPay"
},
{
"paymentMethod": "braintreePayPal",
"url": "https://www.api.nexiopaysandbox.com/v3/popup?token=79001ef6-fb40-4917-b8ae-2294fdfe1cf2&paymentMethod=braintreePayPal"
},
{
"paymentMethod": "payPal",
"url": "https://www.api.nexiopaysandbox.com/v3/popup?token=79001ef6-fb40-4917-b8ae-2294fdfe1cf2&paymentMethod=payPal"
}
]
}
A successful request returns an array of buttonIFrameUrls
.
This array is a list of all APMs currently enabled on your merchant account.
Copy the url
associated with the braintreePayPal
payment method.
-
Complete the Payment Process
Follow steps 6-7 of the Button Iframe URLs tutorial.
A successful auth only transaction returns a status of
success
.NOTE: If the customer selected PayPal (with Braintree) as the payment method, then, in the event posted to your window, the response includes an
apm.token
parameter. Save the apm.token value somewhere in order to use it again (probably similar to how you save TokenEx tokens already).
Apple Pay and Google Pay
To run an auth only transaction through Apple Pay or Google Pay, follow the steps below.
-
Prepare Your Checkout Page
Follow steps 1-3 of the Button Iframe URLs tutorial.
-
Request the APM Button Iframe URLs
Follow step 4 of the Redirect URLs Integration tutorial. Include
isAuthOnly: true
in the body of your request.
Example Request
curl -X POST https://api.nexiopaysandbox.com/apm/v3/token \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Basic <Your Basic Auth>'
-d '{
"data": {
"amount": 29.99,
"currency": "USD",
"customer": {
"firstName": "Maria",
"lastName": "Velasquez",
"email": "mvelaquez@fake.email",
"orderNumber": "210058A"
}
},
"isAuthOnly": true,
"customerRedirectUrl": "https://your-ecommerce-website.example.com"
}'
Example 200 Response
{
"expiration": "2018-09-18T15:43:05.664Z",
"token": "830d36f6-a5e3-4455-9600-3a55b63e2fc2",
"scriptUrl": "https://api.nexiopaysandbox.com/apm/v3/script?token=b61ca2a9-b804-4a28-a00e-b794c8975dee",
"expressIFrameUrl": "https://www.api.nexiopaysandbox.com/v3?token=79001ef6-fb40-4917-b8ae-2294fdfe1cf2",
"redirectUrls": [...],
"buttonIFrameUrls": [
{
"paymentMethod": "applePayAuthNet",
"url": "https://api.nexiopaysandbox.com/apm/v3?token=b61ca2a9-b804-4a28-a00e-b794c8975dee&paymentMethod=applePayAuthNet"
},
{
"paymentMethod": "googlePayAuthNet",
"url": "https://api.nexiopaysandbox.com/apm/v3?token=b61ca2a9-b804-4a28-a00e-b794c8975dee&paymentMethod=googlePayAuthNet"
}
]
}
A successful request will return an array of buttonIFrameUrls
.
This array is a list of all APMs currently enabled on your merchant account.
Copy the url
associated with the Apple Pay or Google Pay payment method.
(Or both the Apple Pay and Google Pay url
s.)
-
Complete the Payment Process
Follow steps 5-7 of the Button Iframe URLs tutorial. A successful auth only transaction will return a status of
success
Klarna
You can run an auth only transaction through Klarna using any of these integration methods:
Express APM for Auth Only with Klarna
To run an auth only transaction through Klarna using Express APM, follow the steps below.
-
Prepare Your Checkout Page
Follow steps 1-2 of the Express APM with Klarna tutorial.
-
Request an Express Iframe URL
Follow step 3 of the Express APM with Klarna tutorial.
Include
isAuthOnly: true
in the body of your request.
Example Request
curl -X POST https://api.nexiopaysandbox.com/apm/v3/token \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Basic <Your Basic Auth>'
-d '{
"data": {
"amount": 4.00,
"currency": "USD",
"customer": {
"orderNumber": "12345678",
"firstName": "John",
"lastName": "Doe",
"email": "john@doe.com",
"billToCountry": "US"
},
"totalTaxAmount": 0,
"cart": {
"items": [
{
"item": "E200",
"description": "Platinum set",
"quantity": 2,
"price": 2
}
]
}
},
"customerRedirectUrl": "https://www.yourwebsite.com",
"uiOptions": {
"displaySubmitButton": true
},
"isAuthOnly": true
}'
A successful response will include the expressIFrameUrl
. Copy or store this for use in step 3.
Example 200 Response
{
"expiration": "2021-07-22T20:49:50.000Z",
"token": "54a0106y-7750-45b1-961e-29ad95763a23",
"expressIFrameUrl": "https://api.nexiopaysandbox.com/apm/v3?token=54a0106y-7750-45b1-961e-29ad95763a23",
"redirectUrls": [
{
"paymentMethod": "klarna",
"url": "https://api.nexiopaysandbox.com/apm/v3/popup?token=54a0106b-7750-45b1-961e-29ad95763a23&paymentMethod=klarna"
}
],
"buttonIFrameUrls": [
{
"paymentMethod": "klarna",
"url": "https://api.nexiopaysandbox.com/apm/v3?token=54a0106b-7750-45b1-961e-29ad95763a23&paymentMethod=klarna"
},
{
"paymentMethod": "braintreePayPal",
"url": "https://api.nexiopaysandbox.com/apm/v3?token=54a0106b-7750-45b1-961e-29ad95763a23&paymentMethod=braintreePayPal"
}
],
"scriptUrl": "https://api.nexiopaysandbox.com/apm/v3/scripts?token=54a0106y-7750-45b1-961e-29ad95763a23"
}
-
Complete the Payment Process
Follow steps 4-6 of the Express APM with Klarna tutorial.
A successful auth only transaction will return a status of
authOnlyPending
orauthOnly
.
Button Iframe URLs for Auth Only with Klarna
To run an auth only transaction through Klarna using the button iframe URLs, follow the steps below.
-
Prepare Your Checkout Page
Follow steps 1-3 of the Button Iframe URLs with Klarna tutorial.
-
Request the APM Button Iframe URLs
Follow step 4 of the Button Iframe URLs with Klarna tutorial. Include
isAuthOnly: true
in the body of your request.
Example Request
curl -X POST https://api.nexiopaysandbox.com/apm/v3/token \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Basic <Your Basic Auth>'
-d '{
"data": {
"amount": 4.00,
"currency": "USD",
"customer": {
"orderNumber": "12345678",
"firstName": "John",
"lastName": "Doe",
"email": "john@doe.com",
"billToCountry": "US"
},
"totalTaxAmount": 0,
"cart": {
"items": [
{
"item": "E200",
"description": "Platinum set",
"quantity": 2,
"price": 2
}
]
}
},
"customerRedirectUrl": "https://www.yourwebsite.com",
},
"isAuthOnly": true
}'
A successful request will return an array of buttonIFrameUrls
. This array is a list of all APMs currently enabled on your merchant account. Copy the url
associated with the klarna
payment method.
Example 200 Response
{
"expiration": "2021-07-22T20:49:50.000Z",
"token": "54a0106y-7750-45b1-961e-29ad95763a23",
"expressIFrameUrl": "https://api.nexiopaysandbox.com/apm/v3?token=54a0106y-7750-45b1-961e-29ad95763a23",
"redirectUrls": [
{
"paymentMethod": "klarna",
"url": "https://api.nexiopaysandbox.com/apm/v3/popup?token=54a0106b-7750-45b1-961e-29ad95763a23&paymentMethod=klarna"
}
],
"buttonIFrameUrls": [
{
"paymentMethod": "klarna",
"url": "https://api.nexiopaysandbox.com/apm/v3?token=54a0106b-7750-45b1-961e-29ad95763a23&paymentMethod=klarna"
},
{
"paymentMethod": "braintreePayPal",
"url": "https://api.nexiopaysandbox.com/apm/v3?token=54a0106b-7750-45b1-961e-29ad95763a23&paymentMethod=braintreePayPal"
}
],
"scriptUrl": "https://api.nexiopaysandbox.com/apm/v3/scripts?token=54a0106y-7750-45b1-961e-29ad95763a23"
}
-
Complete the Payment Process
Follow steps 5-7 of the Button Iframe URLs with Klarna tutorial.
A successful auth only transaction will return a status of
authOnlyPending
orauthOnly
.
Webhooks For APM Transactions
All of Nexio's available APMs process transactions asynchronously. In order to receive updates about the status of an APM transaction, you must configure webhooks for each expected event type. The table below lists the possible events that can occur for each APM.
For further explanation of the webhook event types, see the Webhook Event Types table.
APM | Possible Webhook Event Types |
---|---|
Alipay | TRANSACTION_SETTLED, TRANSACTION_REFUNDED |
Apple Pay | TRANSACTION_SETTLED, TRANSACTION_REFUNDED |
Google Pay | TRANSACTION_SETTLED, TRANSACTION_REFUNDED |
Klarna | TRANSACTION_AUTHORIZED, TRANSACTION_CAPTURED, TRANSACTION_REFUNDED, TRANSACTION_SETTLED |
Paynet | TRANSACTION_SETTLED, TRANSACTION_PENDING |
SPEI | TRANSACTION_SETTLED, TRANSACTION_PENDING |
PayPal | TRANSACTION_AUTHORIZED, TRANSACTION_CAPTURED, TRANSACTION_REFUNDED, TRANSACTION_SETTLED, TRANSACTION_VOIDED |
PayPal (with Braintree) | TRANSACTION_AUTHORIZED, TRANSACTION_CAPTURED, TRANSACTION_REFUNDED, TRANSACTION_SETTLED, TRANSACTION_VOIDED |
UnionPay | TRANSACTION_SETTLED, TRANSACTION_REFUNDED |
WeChat Pay | TRANSACTION_SETTLED, TRANSACTION_REFUNDED |
Pay Later Messaging
You can present customers with Pay Later messaging that provides information about financing options. Depending on the available payment methods, this messaging indicates whether customers can pay later or in installments.
Pay Later messaging is only supported for the following alternative payment methods:
- Klarna
- PayPal (for more information about the messaging, see PayPal Pay Later Messaging)
To enable any desired APMs on your merchant account, contact integration support.
Note: Pay Later messaging can be shown for only one payment method on the merchant account. If you need to change which payment method is enabled for Pay Later messaging, contact integration support.
Use Pay Later Messaging
You can use Pay Later messaging on any relevant page within your workflow, such as the product details or checkout pages.
In order to present customers with Pay Later messaging, complete the following steps:
-
Configure Your Account
Contact integration support to enable any desired APMs on your merchant account.
Note: Pay Later messaging can be shown for only one payment method on the merchant account. If you need to change which payment method is enabled for Pay Later messaging, contact integration support.
-
Add DIV to Page
Add a
div
tag with a unique class (for example, "nexio-installments-div") to any relevant web pages in your workflow. The value is case-sensitive and cannot contain any spaces.You can include multiple different DIV sections and script references on the same page for different Pay Later messaging. This allows the promotion of several products on the same page with differing amounts, so the message is customized to the product amount.
Put the DIV element where you want the Pay Later messaging to display on the page.
For example:
<html>
<body>
...
<div class="nexio-installments-div" />
...
</body>
</html>
-
Add Script to Page
Add the Pay Later messaging script to any relevant web pages in your workflow.
The URL for the script must include a Nexio username, the total amount, the three-character ISO currency code, and optionally the DIV class to reference (if left out, the system uses the default of "nexio-installments-div").
The script takes the following form:
https://{nexio_environment_base_URL}/apm/v3/installment/{username}/{total_amount}/{currency_code}/script.js?divId={unique-div-id}
Substitute the relevant text above with the appropriate values or your own variables. For example, where the environment is the sandbox, the Nexio user is jdoe@example.com, the amount is 104.55, the currency is USD, and the DIV ID is my-div-id, the script would look like the following example:
<script src="https://api.nexiopaysandbox.com/apm/v3/installment/jdoe@example.com/104.55/USD/script.js?divId=my-div-id" />
Use different divIDs in different script tags to reference each unique message you want and which DIV to show it in.
-
Verify
Open your site in a browser to verify the Pay Later wording displays as expected.
The exact messaging text varies, depending on the available payment methods.
Examples:
- Pay in 4 interest-free payments of $26.14
- Pay in 4 interest-free payments on qualifying purchases
- No Interest if paid in full in 6 months
Troubleshooting Klarna Pay Later Messaging
Nexio provides a couple error messages in the response to assist in troubleshooting problems.
Status 400
The 400 message code indicates that the format used for the divId
is not valid. For example, if there are spaces in the name.
Remove any spaces or other problem characters and retry the request.
Status 500
The 500 message code indicates that there is no matching DIV on the page with the specified divId
.
Change the divId
in the script to match one on the page, or add a DIV to the page and use the divId
indicated in the script as the ID of the DIV.
Decline Recovery (BETA)
Note: This feature is in beta. Decline Recovery is a dynamic tool that helps ensure you don't lose revenue due to payment declines. When the Decline Recovery service is enabled, Nexio will automatically retry declined transactions at a more desirable date and time or with more complete customer information as available (for example, a billing address). You can use Nexio's Decline Recovery service when running card transactions with the API or card transactions run through the subscription service.
Notes:
- Decline Recovery does not immediately determine whether the payment will go through at a later date. It should not be used for payments for which the customer will be waiting for payment confirmation, such as through the payment iframe or your own form.
- Decline Recovery will not attempt to retry transactions classified as hard declines. In general, hard declines require the issuer or cardholder to rectify outstanding issues. (See FlexPay's documentation for more information regarding hard and soft declines.)
With The API
You may enable Decline Recovery on transactions run directly through the Nexio API.
-
Configure Your Account
Contact integration support to enable Decline Recovery on your merchant account.
-
Configure Webhooks
In order to be notified when a previously declined transaction is successfully processed, you must configure webhooks for
TRANSACTION_AUTHORIZED
,TRANSACTION_CAPTURED
andTRANSACTION_SETTLED
events. See the Webhooks tutorial for instructions on how to configure and receive webhooks. You may also wish to configure webhooks for other transaction events at this time.(Skip this step if you have already configured webhooks for all desired events on your account.)
-
Post Card Information to Nexio
Post payment details along with a previously saved card token to the Run Card Transaction endpoint. Include the object
"processingOptions": { "retryOnSoftDecline": true }
in the body of your request.If desired you may also choose to run an auth only transaction.
Example Request
curl -X POST https://api.nexiopaysandbox.com/pay/v3/process \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Basic <Your Basic Auth>'
-d '{
"data": {},
"tokenex": {
"token": "6ee140a0-05d1-4958-8325-b38a690dbb9d"
},
"processingOptions": {
"retryOnSoftDecline": true
}
}'
Now, any successful transactions will be run as usual. Soft declines will be scheduled to be rerun at a later time.
-
Await Success Confirmation
Each time a transaction is retried Nexio will send a webhook (see step 2) with one of the following event types:
TRANSACTION_AUTHORIZED
,TRANSACTION_CAPTURED
andTRANSACTION_SETTLED
. The webhook body will include the transaction status (data.transactionStatus
), letting you know whether the transaction was successful.
Through the Subscription Service
You may enable Decline Recovery on transactions run through the Nexio Subscription Service.
-
Configure Your Account
Contact integration support to enable Decline Recovery on your merchant account.
-
Configure Webhooks
In order to be notified when a previously declined transaction is successfully processed, you must configure webhooks for
TRANSACTION_AUTHORIZED
,TRANSACTION_CAPTURED
andTRANSACTION_SETTLED
events. See the Webhooks tutorial for instructions on how to configure and receive webhooks. You may also wish to configure webhooks for other transaction events at this time. -
Create a Subscription or Pay Plan
Follow steps 1-2 of the Create a Subscription or Create a Pay Plan tutorial. Set the parameter
payment.processingOptions.retryOnSoftDecline
totrue
in the body of your request.
Example Request
curl -X POST https://api.nexiopaysandbox.com/subscription/v3 \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Basic <Your Basic Auth>'
-d '{
"payment": {
"data": {
"amount": 19.99,
"currency": "USD",
"customer": {
"customerRef": "RP006"
}
},
"tokenex": {
"token": "6ee140a0-05d1-4958-8325-b38a690dbb9d"
},
"processingOptions": {
"retryOnSoftDecline": true
}
},
"schedule": {
"interval": "week",
"intervalCount": 2
}
}'
If the initial transaction is declined, the subscription will not be created. It must be re-created with corrected information (such as new card token, corrected billing information, etc.) Any future transactions that are declined will be rerun at a later date and time. (Up to 11 times within a 30 day period.)
Note: Subscriptions run with Decline Recovery have a minimum interval of 29 days.
-
Monitor Webhooks
Each time a transaction is retried Nexio will send a webhook (see step 2) with one of the following event types:
TRANSACTION_AUTHORIZED
,TRANSACTION_CAPTURED
andTRANSACTION_SETTLED
. The webhook body will include the transaction status (data.transactionStatus
), letting you know whether the transaction was successful.
Retrieve Transactions from Decline Recovery
You can obtain a list of declined and recovered transactions and their recovery status for a specified date range.
To retrieve transactions by recovery status, do the following:
-
Retrieve recovery status
Perform a
GET
request for the declined transactions with the/recovery/v3
endpoint.You can specify a start and end date as part of the request. You can also specify to retrieve transactions of a specific recoveryStatus. The following table shows the possibilities for recoveryStatus and what they mean.
recoveryStatus Status Description 10 Disabled No retry attempt made. Can be enabled if merchant is configured for Decline Recovery service. 20 In progress Transaction request has been sent to the gateway for processing. This is a temporary status. 30 Scheduled The retry attempt has been scheduled. 40 Unrecoverable The declined transaction cannot be retried. 50 Recovered The transaction has been successfully retried. For details on other options with this request, see Recovery Status in the Reporting API.
For example, in the following, the request is to retrieve all declined or recovered transactions regardless of status for the second quarter of 2021, starting with the first one and showing only 10 at a time.
Example Request
curl -X GET 'https://api.nexiopaysandbox.com/recovery/v3?startDate=2021-03-01&endDate=2021-06-30&offset=0&limit=10' \
-H 'Authorization: Basic <Your Basic Auth>'
-
Note the recoveryStatus of the transactions in the response
The response includes a
rows
array with each transaction that matches the request parameters. The information for each item in the array includes a recoveryStatus.This example response shows 3 resulting transactions. Note that the first one has a
recoveryStatus
of 30, indicating that the retry attempt is scheduled. The second one has arecoveryStatus
of 50, indicating that the retry of the transaction was successful. The third one has arecoveryStatus
of 40, indicating that the declined transaction cannot be retried.
Example 200 Response
{
"offset": 0,
"limit": 10,
"rows": [
{
"id": 62641,
"retryDate": "2021-06-08T19:00:00.000Z",
"transactionDate": "2021-05-25T14:08:20.000Z",
"originalAmount": 77.65,
"originalDeclinePaymentId": "eyJuYW1lIjoiIiwibWVyY2hhbnRJZCI6IjEwMDI2MCIsInJlZk51bWJlciI6IjQwMDY1OTkyNDM3IiwicmFuZG9tIjowLCJjdXJyZW5jeSI6InVzZCJ9",
"orderNumber": "210058A",
"recoveryStatus": 30,
"retryCount": 13,
"merchantId": "100260",
"userName": "jbanks@cmsonline.com",
"isEnabledForRecovery": true,
"updatedAt": "2021-06-07T19:01:28.000Z",
"declineMessage": "This transaction has been declined."
},
{
"id": 61829,
"retryDate": "2021-05-24T15:13:26.000Z",
"transactionDate": "2021-05-24T21:09:22.000Z",
"originalAmount": 77.58,
"originalDeclinePaymentId": "eyJuYW1lIjoiIiwibWVyY2hhbnRJZCI6IjEwMDI2MCIsInJlZk51bWJlciI6IjQwMDY1OTM3MzAyIiwicmFuZG9tIjowLCJjdXJyZW5jeSI6InVzZCJ9",
"orderNumber": "210058A",
"recoveryStatus": 50,
"retryCount": 5,
"merchantId": "100039",
"userName": "api-test-sandbox@cmsonline.com",
"isEnabledForRecovery": true,
"updatedAt": "2021-05-27T21:15:26.000Z",
"declineMessage": "This transaction has been declined."
},
{
"id": 35343,
"retryDate": null,
"transactionDate": "2021-04-09T16:00:48.000Z",
"originalAmount": 109.33,
"originalDeclinePaymentId": "eyJuYW1lIjoiIiwibWVyY2hhbnRJZCI6IjEwMDI2MCIsInJlZk51bWJlciI6ImNoXzFJVDd6SUtHTVRlYmRqQjR2bm5RbkVPWCIsInJhbmRvbSI6MCwiY3VycmVuY3kiOiJhdWQifQ==",
"orderNumber": "1234567",
"recoveryStatus": 40,
"retryCount": 0,
"merchantId": "100039",
"userName": "api-test-sandbox@cmsonline.com",
"isEnabledForRecovery": false,
"updatedAt": "2021-04-09T16:01:25.000Z",
"declineMessage": "Your card was declined. This transaction requires authentication."
}
],
"hasMore": false
}
Fraud Tools
Address Verification Service
The Address Verifcation Service (AVS) compares the address and postal code provided with the information on file with the credit card issuer. Nexio interprets these results and returns them concisely back to you, making it easy for you to determine which cards to save, giving you greater control over your risk management. You can use AVS while saving a card token with the Nexio iframe, with your own form, or through the API.
Contact Integrations Support if you have questions about address verification.
Enable AVS
With the Nexio Iframe
-
Determine the Correct Setting
Use the AVS Settings table to determine which AVS setting best suits your needs.
-
Prepare the Iframe
Follow steps 1-2 of the Create a Save Card Page With the Nexio Iframe tutorial.
-
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
}
}'
-
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
-
Determine the Correct Setting
Use the AVS Settings table to determine which AVS setting best suits your needs.
-
Prepare the Iframe
Follow steps 1-6 of the Create a Save Card Page With Your Own Form tutorial.
-
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
}
}'
-
Post Card Information to Nexio
Follow step 7b of the Create a Save Card Page With Your Own Form tutorial.
-
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
-
Determine the Correct Setting
Use the AVS Settings table to determine which AVS setting best suits your needs.
-
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
}
}'
-
Post Card Information to Nexio
Follow step 3 of the Save a Card Token with the Nexio API.
The AVS Response
When you check AVS your response will include an object called avsResults
.
See the example below.
Example 200 Response
{
"token": {...},
"card": {...},
"data": {...},
"avsResults": {
"matchAddress": true,
"matchPostal": true,
"gatewayResponse": {...}
},
"cardType": "visa"
}
Match Address
The results of the address check.
- True: The address provided matches the address on file with the credit card issuer.
- False: The address provided does not match the address on file with the credit card issuer.
(In this case, 'address' refers to the street address portion of the billing address.
For example, if the address provided were 123 Sesame St. Manhattan, NY 10128,
matchAddress
would compare '123 Sesame St.' with the address on file.)
Note: Card issuers may handle address checks differently.
For your convenience, Nexio returns a simple true
or false
regardless of the card issuer.
Match Postal
The results of the postal code check.
- True: The postal code provided matches the postal code on file with the credit card issuer.
- False: The postal code provided does not match the postal code on file with the credit card issuer.
(Using the example address above, matchPostal
would compare '10128' with the postal code on file.)
Gateway Response
This part of the response includes raw details from the gateway's response to the AVS check. Format may vary by gateway.
Note: A gateway AVS error will not prevent the card token from being saved. If you received a gateway error during an address verification check, you may wish to delete the card token.
Test AVS
In the sandbox environment you may trigger matchAddress
and matchPostal
values by using the following postal codes:
Postal Code | matchAddress result |
matchPostal result |
---|---|---|
56649 | true |
true |
39601 | true |
false |
53574 | false |
true |
49802 | false |
false |
Please be sure to use only the test postal codes provided in the table above.
AVS Settings
verifyAvs set to: |
Purpose |
---|---|
0 | Do not perform AVS check |
1 | Always save card regardless of result |
2 | Do not save card if the address match fails |
3 | Do not save card if the postal code match fails |
4 | Do not save the card if either the address match fails OR the postal code match fails |
5 | Do not save the card if both the address match AND the postal code match fail |
When verifyAvs
is set to 0
You will not receive an avsResponse
object.
When verifyAvs
is set to 1
addressMatch | postalMatch | What will happen: |
---|---|---|
true | true | Card will be saved |
true | false | Card will be saved |
false | true | Card will be saved |
false | false | Card will be saved |
When verifyAvs
is set to 2
addressMatch | postalMatch | What will happen: |
---|---|---|
true | true | Card will be saved |
true | false | Card will be saved |
false | true | Card will not be saved |
false | false | Card will not be saved |
When verifyAvs
is set to 3
addressMatch | postalMatch | What will happen: |
---|---|---|
true | true | Card will be saved |
true | false | Card will not be saved |
false | true | Card will be saved |
false | false | Card will not be saved |
When verifyAvs
is set to 4
addressMatch | postalMatch | What will happen: |
---|---|---|
true | true | Card will be saved |
true | false | Card will not be saved |
false | true | Card will not be saved |
false | false | Card will not be saved |
When verifyAvs
is set to 5
addressMatch | postalMatch | What will happen: |
---|---|---|
true | true | Card will be saved |
true | false | Card will be saved |
false | true | Card will be saved |
false | false | Card will not be saved |
Device Fingerprinting
Device fingerprinting helps detect fraudulent behavior even when a user changes their IP address, device, account information or other identifying information.
You can enable device fingerprinting while saving a card token or running a transaction.
Enable Device Fingerprinting
With the Nexio Iframe
-
Prepare the Iframe
Follow steps 1-3 of the Create a Save Card Page With the Nexio Iframe or the Create a Checkout Page With the Nexio Iframe tutorial.
Successful completion of step 3 will return the following:
Example One-time-use Token Response
{
"expiration": "2018-09-18T15:43:05.664Z",
"fraudUrl": "https://api.nexiopaysandbox.com/pay/v3/fingerprint?token=01080f80-76b8-4363-845d-67e8623bf170",
"token": "830d36f6-a5e3-4455-9600-3a55b63e2fc2"
}
-
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'ssrc
tag.
Example
<script type='text/javascript' src='https://api.nexiopaysandbox.com/pay/v3/fingerprint?token=01080f80-76b8-4363-845d-67e8623bf170'></script>
-
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
-
Prepare the Form
Follow steps 1-2 of the Create a Save Card Page With Your Own Form tutorial.
-
Add the Device Fingerprinting Script to Your Web Page
a. Request a one-time-use token. A successful request will return a response with the following keys:
Example 200 Response
{
"expiration": "2018-09-18T15:43:05.664Z",
"fraudUrl": "https://api.nexiopaysandbox.com/pay/v3/fingerprint?token=01080f80-76b8-4363-845d-67e8623bf170",
"token": "830d36f6-a5e3-4455-9600-3a55b63e2fc2"
}
b. Copy the fraudUrl
from the above response and add it as a script to your web page.
Example
<script type='text/javascript' src='https://api.nexiopaysandbox.com/pay/v3/fingerprint?token=01080f80-76b8-4363-845d-67e8623bf170'></script>
c. Copy and store the token
from the above response, we will use it in step 5.
-
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
. -
Send Card Data To Your Server
Follow steps 4-5 of the Create a Save Card Page With Your Own Form tutorial.
-
Post Card Information to Nexio
POST
thetoken
from step 2 and the card information to Nexio.
Example Request
curl -X POST https://api.nexiopaysandbox.com/pay/v3/saveCard \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Basic <Your Basic Auth>'
-d '{
"card": {
"cardHolderName": "John H Doe",
"encryptedNumber": "cu3yRktaYFK2LUC6DpNK289tYDsGRCi7cO+GeG0hkeYFvT7Y8/oY5r53obMz6Q/BZ38gk2u2Ufwy8ojBcX2sfNjG5jplGTXA4NNlSIUjMFfiHe1sff1JFpThoiW/IIlifGlbWu+S1/9pqWPTzJ2+DcjwohbHzsDahhYewFhXgC8qsK0ypi/Shlp+CwRITyIvbVXESD0xz3YOTRHeZLlChvVqN8z4ZzN8nm0MXkmT1wcpYI73bH4KdnPwNU3s7XxvP/ernQP73SHHAOKSLlz4F6AEHFjJiCoXzeLF7LwEjRdxDJ0sKVXbRk3i9BGh+8Nle2VYgjpUWtk2763QkvZiQQ==",
"expirationMonth": "12",
"expirationYear": "20"
},
"token": "eb50a022-d6de-4244-a1e6-dcb8522b2d19"
}'
-
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
-
Prepare the Form
Follow steps 1-2 of the Create a Checkout Page With Your Own Form tutorial.
-
Add the Device Fingerprinting Script to Your Web Page
a. Request a one-time-use token. Do not include any of the transaction data. This step is only required so that you can get the
fraudUrl
for use in the next step.A successful request will return a response with the following keys:
Example 200 Response
{
"expiration": "2018-09-18T15:43:05.664Z",
"fraudUrl": "https://api.nexiopaysandbox.com/pay/v3/fingerprint?token=01080f80-76b8-4363-845d-67e8623bf170",
"token": "830d36f6-a5e3-4455-9600-3a55b63e2fc2"
}
b. Copy the fraudUrl
from the above response and add it as a script to your web page.
Example
<script type='text/javascript' src='https://api.nexiopaysandbox.com/pay/v3/fingerprint?token=01080f80-76b8-4363-845d-67e8623bf170'></script>
-
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
. -
Send Payment Data To Your Server
Follow steps 4-5 of the Create a Checkout Page With Your Own Form tutorial.
Send the transaction information to your server.
-
Post Payment Information to Nexio
POST
the transaction information to Nexio.
Example Request
curl -X POST https://api.nexiopaysandbox.com/pay/v3/process \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Basic <Your Basic Auth>'
-d '{
"data": {
"amount": 29.99,
"currency": "USD"
},
"tokenex": {
"token": "6ee140a0-05d1-4958-8325-b38a690dbb9d"
}
}'
-
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
-
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.
-
Create a Checkout Page Using the API
Follow steps 1-4 of the Create a Checkout Page With Your Own Form tutorial. Include the card token in the body of your request when you
POST
payment information to Nexio.
Example Request
curl -X POST https://api.nexiopaysandbox.com/pay/v3/process \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Basic <Your Basic Auth>'
-d '{
"data": {
"amount": 29.99,
"currency": "USD"
},
"tokenex": {
"token": "6ee140a0-05d1-4958-8325-b38a690dbb9d"
}
}'
-
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
-
Configure Your Account
Contact integration support to ensure Kount is enabled on your merchant account.
-
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.
-
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
}
}'
-
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
-
Configure Your Account
Contact integration support to ensure Kount is enabled on your merchant account.
-
Prepare the Iframe
Follow steps 1-6 of the Create a Save Card Page Using the Iframe tutorial.
-
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 '{}'
-
Post Card Information to Nexio
Follow step 7b of the Create a Save Card Page Using the Iframe tutorial. Include the object
"processingOptions": { "checkFraud": true }
in the body of your request.
Example Request
curl -X POST https://api.nexiopaysandbox.com/pay/v3/saveCard \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Basic <Your Basic Auth>'
-d '{
"card": {
"cardHolderName": "John H Doe",
"encryptedNumber": "cu3yRktaYFK2LUC6DpNK289tYDsGRCi7cO+GeG0hkeYFvT7Y8/oY5r53obMz6Q/BZ38gk2u2Ufwy8ojBcX2sfNjG5jplGTXA4NNlSIUjMFfiHe1sff1JFpThoiW/IIlifGlbWu+S1/9pqWPTzJ2+DcjwohbHzsDahhYewFhXgC8qsK0ypi/Shlp+CwRITyIvbVXESD0xz3YOTRHeZLlChvVqN8z4ZzN8nm0MXkmT1wcpYI73bH4KdnPwNU3s7XxvP/ernQP73SHHAOKSLlz4F6AEHFjJiCoXzeLF7LwEjRdxDJ0sKVXbRk3i9BGh+8Nle2VYgjpUWtk2763QkvZiQQ==",
"expirationMonth": "12",
"expirationYear": "20"
},
"token": "eb50a022-d6de-4244-a1e6-dcb8522b2d19",
"processingOptions": {
"checkFraud": true
}
}'
-
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
-
Configure Your Account
Contact integration support to ensure Kount is enabled on your merchant account.
-
Prepare the Iframe
Follow steps 1-5 of the Create a Checkout Page With Your Own Form tutorial.
-
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
}
}'
-
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
-
Configure Your Account
Contact integration support to ensure Kount is enabled on your merchant account.
-
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 '{}'
-
Post Card Information to Nexio
Send a
POST
request to the Save Card Token endpoint. Include thetoken
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
-
Configure Your Account
Contact integration support to ensure Kount is enabled on your merchant account.
-
Post Card Information to Nexio
Post payment and the previously saved card token to the Run Card Transaction endpoint.
Include the object
"processingOptions": { "checkFraud": true }
in the body of your request.
Example Request
curl -X POST https://api.nexiopaysandbox.com/pay/v3/process \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Basic <Your Basic Auth>'
-d '{
"data": {},
"tokenex": {
"token": "6ee140a0-05d1-4958-8325-b38a690dbb9d"
},
"processingOptions": {
"checkFraud": true
}
}'
The Kount Response
When you perform a Kount verification your response will include an object called kountResponse
.
It consists of two parts: status
and rules
.
Kount Response Example
{
"token": {...},
"card": {...},
"data": {...},
"kountResponse": {
"status": "success",
"rules": "{\"VERS\":\"0630\",\"MODE\":\"Q\"}"
},
"cardType": "visa"
}
Status
There are three possible statuses. The status indicates what action will be taken. The action will differ based on the endpoint. See below for more information:
- Success:
- Run Credit Card Transaction: Based on the Kount rule(s) configured, the transaction will be processed with no further action required.
- Save Card: The card will be saved with no further action required.
- Review:
- Run Credit Card Transaction: Based on the Kount rule(s) triggered, the transaction has been run as an Auth Only, meaning the transaction has been authorized but is pending further action. You can manually approve or decline these transactions in the Fraud tab of Nexio Dashboard. (Please note that these transactions will auto-approve after 48 hours if no action is taken.)
- Save Card: A 'Review' status will not prevent the card from being saved.
- Decline:
- Run Credit Card Transaction: Based on the Kount rule(s) triggered, the transaction will not be processed with no further action required.
- Save Card: The card will not be saved.
- Error:
- Run Credit Card Transaction: Based on the Kount rule(s) triggered, the transaction will not be processed with no further action required.
- Save Card: The card will not be saved.
Rules
This part of the response will include Kount-specific information including Kount version, mode, transaction ID, and a brief description of each rule that was triggered.
Kount Rules Example
"kountResponse": {
"status": "success",
"rules": "{
"VERS": "0630",
"MODE": "W",
"TRAN": "79970C4SYHL2",
"SESS": "61504d7500d44f67bba921474750f90f",
"ORDR": "456",
"AUTO": "A",
"SCOR": "76",
"RULES_TRIGGERED": 2,
"RULE_ID_0": "1004064",
"RULE_DESCRIPTION_0": "Scorecard: Distance from Device to Billing > 1000km (1)",
"RULE_ID_1":"1004066",
"RULE_DESCRIPTION_1":"Scorecard: Billing Country not equal to BIN Country (Visa/MC)
}"
}
Test Kount Verification
While testing Kount in your sandbox account you may force a status of review
or decline
by using the values listed below.
Any other combination will result in a status of success
.
Value | Result |
---|---|
Address 1 or Address 2 contains '456' | review |
Amount between 6.00 and 6.99 | review |
Amount = 7.00 | decline |
The examples below show how to test Kount verification on the Run Card Transaction endpoint.
Example Request: Triggers Status of Review
curl -X POST https://api.nexiopaysandbox.com/pay/v3/process \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Basic <Your Basic Auth>'
-d '{
"data": {
"customer": {
"billToAddressOne": "456"
}
},
"tokenex": {
"token": "6ee140a0-05d1-4958-8325-b38a690dbb9d"
},
"processingOptions": {
"checkFraud": true
}
}'
Example Request: Triggers Status of Decline
curl -X POST https://api.nexiopaysandbox.com/pay/v3/process \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Basic <Your Basic Auth>'
-d '{
"data": {
"amount": 7
},
"tokenex": {
"token": "6ee140a0-05d1-4958-8325-b38a690dbb9d"
},
"processingOptions": {
"checkFraud": true
}
}'
To test the Save Card Token endpoint use any of the values listed in the table above in your request for a One-time-use Token (E-commerce), then use the token to request a Save Card Token iframe.
Security Code Verification
The Nexio security code (CVC) verification feature allows you to save only those cards that pass a CVC check, helping you reduce your risk of fraud. You can enable CVC verification while saving a card token with the Nexio iframe, with your own form, or through the API.
Enable Security Code Verification
With the Nexio Iframe
-
Prepare the Iframe
Follow steps 1-2 of the Create a Save Card Page With the Nexio Iframe tutorial.
-
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
andhideCvc
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
}
}'
-
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
-
Prepare the Iframe
Follow steps 1-6 of the Create a Save Card Page With Your Own Form tutorial.
-
Request a One-time-use Token
Request an e-commerce one-time-use token. Include the object
"processingOptions": { "verifyCvc": true }
in the body of your request. (This is part of step 7a of the Create a Save Card Page With Your Own Form tutorial, with the addition of the verifyCvc parameter in the processingOptions object.)
Example Request
curl -X POST https://api.nexiopaysandbox.com/pay/v3/token \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Basic <Your Basic Auth>'
-d '{
"processingOptions": {
"verifyCvc": true
}
}'
-
Post Card Information to Nexio
Follow step 7b of the Create a Save Card Page With Your Own Form tutorial.
In the request,, be sure to also include the CVC (as the securityCode parameter) as entered by the user.
Example Request
{
curl -X POST https://api.nexiopaysandbox.com/pay/v3/saveCard \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Basic <Your Basic Auth>'
-d '{
"token": "eb50a022-d6de-4244-a1e6-dcb8522b2d19",
"card": {
"cardHolderName": "John H Doe",
"encryptedNumber": "cu3yRktaYFK2LUC6DpNK289tYDsGRCi7cO+GeG0hkeYFvT7Y8/oY5r53obMz6Q/BZ38gk2u2Ufwy8ojBcX2sfNjG5jplGTXA4NNlSIUjMFfiHe1sff1JFpThoiW/IIlifGlbWu+S1/9pqWPTzJ2+DcjwohbHzsDahhYewFhXgC8qsK0ypi/Shlp+CwRITyIvbVXESD0xz3YOTRHeZLlChvVqN8z4ZzN8nm0MXkmT1wcpYI73bH4KdnPwNU3s7XxvP/ernQP73SHHAOKSLlz4F6AEHFjJiCoXzeLF7LwEjRdxDJ0sKVXbRk3i9BGh+8Nle2VYgjpUWtk2763QkvZiQQ==",
"expirationMonth": "12",
"expirationYear": "20",
"securityCode": 111
}
}'
-
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
-
Request a One-time-use Token
Request an e-commerce one-time-use token. Include the object
"processingOptions": { "verifyCvc": true }
in the body of your request.
Example Request
curl -X POST https://api.nexiopaysandbox.com/pay/v3/token \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Basic <Your Basic Auth>'
-d '{
"processingOptions": {
"verifyCvc": true
}
}'
-
Post Card Information to Nexio
Send a
POST
request to the Run Card Transaction endpoint. Include thetoken
returned from step 1 and the card information (including the CVC securityCode) in the body of your request.
Example Request
curl -X POST https://api.nexiopaysandbox.com/pay/v3/process \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Basic <Your Basic Auth>'
-d '{
"data": {
"amount": "29.99",
"currency": "USD"
},
"tokenex": {
"token": "6ee140a0-05d1-4958-8325-b38a690dbb9d"
},
"card": {
"cardHolderName": "John H Doe",
"encryptedNumber": "cu3yRktaYFK2LUC6DpNK289tYDsGRCi7cO+GeG0hkeYFvT7Y8/oY5r53obMz6Q/BZ38gk2u2Ufwy8ojBcX2sfNjG5jplGTXA4NNlSIUjMFfiHe1sff1JFpThoiW/IIlifGlbWu+S1/9pqWPTzJ2+DcjwohbHzsDahhYewFhXgC8qsK0ypi/Shlp+CwRITyIvbVXESD0xz3YOTRHeZLlChvVqN8z4ZzN8nm0MXkmT1wcpYI73bH4KdnPwNU3s7XxvP/ernQP73SHHAOKSLlz4F6AEHFjJiCoXzeLF7LwEjRdxDJ0sKVXbRk3i9BGh+8Nle2VYgjpUWtk2763QkvZiQQ==",
"expirationMonth": "12",
"expirationYear": "20",
"securityCode": 927
}
}'
The CVC Response
When you check the CVC your response will include an object called cvcResults
.
See the examples below.
Note: A gateway error will not prevent the card token from being saved.
The only time a card will not be saved is when the matchCvv parameter returns false
.
If you received a gateway error during a CVC check,
you may wish to delete the card token.
Example 200 Response
{
"token": {...},
"card": {...},
"data": {...},
"cvcResults": {
"matchCvv": true,
"error": false,
"gatewayMessage": {
"cvvresponse": "M",
"message": "CVV2/CVC2 match"
}
},
"cardType": "visa"
}
Example 400 Response
{
"error": 437,
"message": "Verify CVC Failed",
"cvcResults": {
"matchCvv": false,
"error": false,
"gatewayMessage": {
"cvvresponse": "N",
"message": "CVV2/CVC2 no match"
}
}
}
Test Security Code Verification
You can test the CVC Verification Service using the Nexio Sandbox Tester, Postman, or your own code base.
The following values can be used while testing:
Card Number | CVC | Result |
---|---|---|
Any number provided here | 111 | Success |
Any number provided here | 222 | Failure |
Security Code Verification Settings
verifyCvc | hideCvc | requireCvc | Result |
---|---|---|---|
true |
false |
true |
The user will be required to input the CVC field and the card will only be saved if the CVC is verified. |
true |
false |
false |
The card will only be saved if the provided CVC is verified, but users will also have the option of ignoring the CVC field. |
Please also note the following:
verifyCvc | hideCvc | requireCvc | Result |
---|---|---|---|
true |
true |
true , false |
You will receive a 400 error, because the CVC cannot be verified when the field is hidden. |
Iframe Customization
Label Translation
Nexio provides the option to customize the labels on your e-commerce or retail iframe. This feature is particularly helpful for localization, allowing you to translate your checkout or save card page.
You may use this feature in two ways:
- To translate or localize your iframes by using our out of the box translation files
- To translate, localize or customize your iframes by providing your own custom labels
Out of the Box Translations
Nexio currently provides out of the box localization files for the following languages/regional dialects:
- English (Canada): https://customerassets.nexiopay.com/CMSLabels_en_ca.json
- French: https://customerassets.nexiopay.com/CMSLabels_fr.json
- French (Canada): https://customerassets.nexiopay.com/CMSLabels_fr_ca.json
- French (United States): https://customerassets.nexiopay.com/CMSLabels_fr_us.json
- Japanese: https://customerassets.nexiopay.com/CMSLabels_jp.json
- Spanish: https://customerassets.nexiopay.com/CMSLabels_es.json
- Spanish (Mexico): https://customerassets.nexiopay.com/CMSLabels_es_mx.json
- Spanish (United States): https://customerassets.nexiopay.com/CMSLabels_es_us.json
- Turkish: https://customerassets.nexiopay.com/CMSLabels_tr.json
To use our translation files to customize your iframe, follow steps below:
-
Request a One-time-use Token
Send a
POST
request for a one-time-use token.- Include a
uiOptions
object in the body of your request - Within the
uiOptions
object, include the keycustomTextUrl
- Set the value to the URL of the desired language file listed above
- Include a
Example Request
curl -X POST https://api.nexiopaysandbox.com/pay/v3/token \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Basic <Your Basic Auth>'
-d '{
"uiOptions": {
"customTextUrl": "https://customerassets.nexiopay.com/CMSLabels_es.json"
}
}'
Example 200 Response
{
"expiration": "2018-09-18T15:43:05.664Z",
"fraudUrl": "https://api.nexiopaysandbox.com/pay/v3/fingerprint?token=01080f80-76b8-4363-845d-67e8623bf170",
"token": "830d36f6-a5e3-4455-9600-3a55b63e2fc2"
}
-
Request the Iframe
Use the
token
from the response in step 1 to send aGET
request for the desired iframe. You may wish to customize any of the following:
For example, the following request will return the HTML for a save card page, with the labels from the out of the box translation file you specified in step 1.
Example Request
curl -X GET https://api.nexiopaysandbox.com/pay/v3/saveCard?token=830d36f6-a5e3-4455-9600-3a55b63e2fc2 \
-H 'Accept: application/json' \
-H 'One-time-use Token: API_KEY'
Custom Labels
If you would like to completely customize your iframe's labels, or if you would like to translate them into a language that is not currently included in Nexio's out of the box translations, follow the steps below:
-
Create a Custom Label File
Create a JSON file with the same keys as shown below. (Click here to download a copy.)
Custom Text File Example
{
"Card Information": "",
"Name": "",
"as it appears on card": "",
"Card Number": "",
"Card number is invalid": "",
"We only accept": "",
"Expiration Date": "",
"Select a date in the future": "",
"Security Code": "",
"Security code is invalid, must be 3-4 digits": "",
"Billing Information": "",
"Country": "",
"Address 1": "",
"Address 2": "",
"City": "",
"State / Province": "",
"Postal Code": "",
"eCheck Information": "",
"Routing Number": "",
"Routing Number is invalid, must be 9 digits": "",
"Account Number": "",
"Account number is invalid": "",
"Submit": "",
"You are now being redirected to Alipay for payment.": "",
"Cancel": "",
"Confirm": "",
"Required": "",
"Establishing secure connection to payment engine.": "",
"Failed to connect to secure server. Please check your internet connection.": ""
}
-
Add the Custom Labels
Replace any values you would like to customize. If any value is an empty string, or the property is left out, the default value will be used.
-
Host the Custom Label File
Host the JSON file. This step varies based on the environment:
-
Sandbox: You may host the file anywhere. (For instuctions on how to host your custom JSON file on GitHub, see this FAQ.) Take note of the URL for use in step 4
-
Production: You must send the file to integrations@nexiopay.com for approval. Important: The URL used in sandbox will not be used on the production server
Once approved, we will host it on our secure servers and provide you with the URL to use in step 4
-
-
Request a One-time-use Token
Send a
POST
request for a one-time-use token.- Include a
uiOptions
object in the body of your request - Within the
uiOptions
object, include the keycustomTextUrl
- Set the value to the URL of the JSON file from step 3
- Include a
Example Request
curl -X POST https://api.nexiopaysandbox.com/pay/v3/token \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Basic <Your Basic Auth>'
-d '{
"data": {
"amount": 29.99,
"currency": "USD"
},
"uiOptions": {
"customTextUrl": "https://your-webpage.com/custom-labels.json"
}
}'
Example 200 Response
{
"expiration": "2018-09-18T15:43:05.664Z",
"fraudUrl": "https://api.nexiopaysandbox.com/pay/v3/fingerprint?token=01080f80-76b8-4363-845d-67e8623bf170",
"token": "830d36f6-a5e3-4455-9600-3a55b63e2fc2"
}
-
Request the Iframe
Use the
token
from the response in step 4 to send aGET
request for the desired iframe. You may wish to customize any of the following:
Example Request
curl -X GET https://api.nexiopaysandbox.com/pay/v3?token=830d36f6-a5e3-4455-9600-3a55b63e2fc2 \
-H 'Accept: application/json' \
-H 'One-time-use Token: API_KEY'
Once the iframe is loaded, the labels will be replaced with values you provided.
Custom CSS
Nexio provides the option to provide a custom CSS file so that you can match your site's style.
To do so, follow steps below:
-
Host Your CSS File
Host your CSS file, available publicly.
-
Request a One-time-use Token
Send a
POST
request to the E-commerce One-time-use Token. Include the URL of your CSS file as a UI Option in the body of your request. See the example below.
Example Request
curl -X POST https://api.nexiopaysandbox.com/pay/v3/token \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Basic <Your Basic Auth>'
-d '{
"uiOptions": {
"css": "https://tester.nexiopaysandbox.com/static/ecom-example1.css"
}
}'
Example 200 Response
{
"expiration": "2018-09-18T15:43:05.664Z",
"fraudUrl": "https://api.nexiopaysandbox.com/pay/v3/fingerprint?token=01080f80-76b8-4363-845d-67e8623bf170",
"token": "830d36f6-a5e3-4455-9600-3a55b63e2fc2"
}
-
Load the Iframe
You may wish to customize a:
For example, the following request will return the HTML for a checkout page, with the style from the CSS file you specified in step 2.
Example Request
curl -X GET https://api.nexiopaysandbox.com/pay/v3?token=830d36f6-a5e3-4455-9600-3a55b63e2fc2 \
-H 'Accept: application/json' \
-H 'One-time-use Token: API_KEY'
Lodging Data
Merchants in the lodging industry can pass certain parameters. The entire lodging object is optional. However, the following are all the supported parameters:
-
Advanced Deposit (
lodging.advanceDeposit
) -
Check-in Date (
lodging.checkInDate
) -
Check-out Date (
lodging.checkOutDate
) -
No Show (
lodging.noShow
) -
Room Number (
lodging.roomNumber
) -
Room Rate (
lodging.roomRate
) -
Folio Number (
customer.orderNumber
)
Send Lodging Parameters
With the Nexio Iframe
-
Prepare the Iframe
Follow steps 1-2 of the Create a Checkout Page with the Nexio Iframe tutorial.
-
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, labeledorderNumber
.
Example Request
curl -X POST https://api.nexiopaysandbox.com/pay/v3/token \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Basic <Your Basic Auth>'
-d '{
"data": {
"amount": 29.99,
"currency": "USD",
"lodging": {
"advanceDeposit": true,
"checkInDate": "2018-12-31",
"checkOutDate": "2019-01-05",
"roomNumber": 14,
"roomRate": 143.99
},
"customer": {
"orderNumber": 4566
}
}
}'
-
Load the Iframe
Follow steps 4-6 of the Create a Checkout Page with the Nexio Iframe tutorial.
With Your Own Form
-
Prepare the Iframe
Follow steps 1-5 of the Create a Checkout Page With Your Own Form tutorial.
-
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, labeledorderNumber
.
Example Request
curl -X POST https://api.nexiopaysandbox.com/pay/v3/process \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Basic <Your Basic Auth>'
-d '{
"data": {
"lodging": {
"advanceDeposit": true,
"checkInDate": "2018-12-31",
"checkOutDate": "2019-01-05",
"roomNumber": 14,
"roomRate": 143.99
},
"customer": {
"orderNumber": 4566
}
},
"tokenex": {
"token": "6ee140a0-05d1-4958-8325-b38a690dbb9d"
}
}'
-
Create a Receipt for the Customer
Follow step 6 of the Create a Checkout Page With Your Own Form tutorial.
With the API
-
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, labeledorderNumber
.
Example Request
curl -X POST https://api.nexiopaysandbox.com/pay/v3/process \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Basic <Your Basic Auth>'
-d '{
"data": {
"lodging": {
"advanceDeposit": true,
"checkInDate": "2018-12-31",
"checkOutDate": "2019-01-05",
"roomNumber": 14,
"roomRate": 143.99
},
"customer": {
"orderNumber": 4566
}
},
"tokenex": {
"token": "6ee140a0-05d1-4958-8325-b38a690dbb9d"
}
}'
Payment Routing (BETA)
Nexio allows you to customize the payment flow for consumer purchases. Previously, you could customize the payment flow only through assigning different currencies to each merchant account (MID), running transactions through different API users, using a specific MID, or specifying a specific tag for payment options on each MID.
You can now route transactions based on items in the transaction, monthly gross of authorized transactions (also known as transaction volume), or with an advanced payment routing flow.
This section details how to customize the payment routing based on what you want to accomplish:
- I want to keep 'relationshipA' active at nn% - 'relationshipA' refers to the relationship you have with a merchant account provider, a processor, or an acquirer (bank). The 'nn%'' is a specific percentage of transaction volume
- I want all orders with xxx to go to 'relationshipB' - 'relationshipB' refers to the relationship you have with a merchant account provider, a processor, or an acquirer (bank). The 'xxx' represents an item that is part of a transaction
- I want to do something more complicated
How do I keep a relationship active at a specific transaction percentage?
There may be cases where you want to keep a relationship (with a merchant account provider, a processor, or an acquirer/bank) active or to keep to a contractual monthly gross of authorized transactions (also known as transaction volume).
You do this by setting up target allocations at the level of the Nexio merchant account (MID) for MIDs that support the transaction currency.
Before you begin setting up target allocations, Nexio recommends that you understand the following notes.
Important:
- If you want routing to be equal for all the API user's MIDs that support the transaction currency, you do not need to create a target allocation rule because that is the default behavior
- For target allocation, your Nexio account must be configured with a single API user account for all the transactions
- The transaction volume only includes card and e-check transactions. Transactions using alternative payment methods (APMs) are not included in this volume amount
- The transaction volume does not get modified for transactions that were successful but then later voided or refunded
- The transaction volume amount includes the amount for an auth only transaction at the time of the transaction (rather than when the transaction is actually captured)
- If you change the target allocations, the change is effective from that change date. Thereafter, the system attempts to send transactions based on the new target allocation percentages and based on where the current monthly transaction amount is for each MID. If the change in allocation percentages is large, or if the change happens late in the month, then one MID will get 100% of the transactions for a time during the remainder of the month. Therefore, use caution when making changes in the middle of the month
- In general, the Nexio system does what it can to allow payments to succeed
Setting up payment routing by target allocation
After you understand the complexities of target allocation (see How do I keep a relationship active at a specific transaction percentage?), you are ready to set it up.
To set up payment routing by target allocation
-
Work with integration support to set up your Nexio account and merchant accounts so that they are optimized for payment routing by target allocation.
In general, this means having a single API user with two or more MIDs that support the same transaction currency.
-
Open the Nexio Dashboard and log in.
For the sandbox: https://dashboard.nexiopaysandbox.com
For production: https://dashboard.nexiopay.com -
Navigate to Settings > Payment Routing (Beta).
The tab shows user accounts and the types of rules.
-
Locate the user account that you want to add to or modify payment routing rules for. Click that row in the table.
The Payment Routing Rules page displays.
-
Click Add New Rule.
The Add Routing Rule dialog displays.
-
Select the currency you want to add this rule to and then select Target Allocation as the rule type.
For example, select the USD currency.
-
Provide values for the Target Allocation fields to match your desired percentages.
For example, assuming you have two MIDs for your user account and the first one needs to remain at 10% allocation every month, type
10
in the Target Allocation field for MID #1 and type90
in the Target Allocation field for MID #2. -
When you are done creating the rule, click Save.
-
For the transaction request, configure the API as follows.
Each payment request must include the following parameters:
data.amount
data.currency
What happens after you set up target allocation?
The allocation happens over a calendar month and is based on the current monthly volume of authorized transactions for each target and the monetary amount of the transactions. Allocation is not a back and forth ordering, but instead favors the MID that is currently farthest from the target allocation percentage at the time of the transaction. Therefore, if MID #1 is set for 75% and MID #2 is 25%, the system does not necessarily send four transactions to MID #1 and then one transaction to MID #2. The monetary amount of a transaction (and the amount of previous transactions that month) impact which MID the payment is routed to. It is important to note that there is no current way to split a single transaction across two or more MIDs.
Note: A potential unexpected consequence of this method for allocation may happen if there are multiple small transaction amounts throughout the month and then a single large transaction amount that occurs at the end of the month, resulting in the system using the MID with the lower allocation percentage for that transaction and thus putting that MID well above the expected allocation percentage.
After you configure payment routing by target allocation, the following process happens for each transaction for the transaction currency:
-
A consumer submits payment for a transaction using the target allocation currency.
For example, the USD currency.
-
The Nexio system determines the MID with the lowest monthly gross of authorized transactions (also known as transaction volume).
For example, suppose MID #1, MID #2, and MID #3 can support the currency and MID #4 does not. Only the first 3 are considered.
Then, if MID #1 has a current volume of $4,500, MID #2 is $10,300, and MID #3 is $8,000, the system prioritizes them as follows:
- MID #1
- MID #3
- MID #2
In this case, MID #1 has the lowest transaction volume.
-
The system checks to see if there are target allocation rules that match for this transaction.
If there are not any target allocation rules, the system skips to step 5 in this sequence.
-
The system takes the target allocations and re-sorts the list so that the MID that is farthest away from its target allocation is at the top.
For the following examples, the target allocation is 10% for MID #1, 90% for MID #2, and 0% for MID #3.
Example 1: Current total transaction volume of $5,600.
MID #1 has a current volume of $300 and 10% allocation, so it is at 5.4% and thus 4.6% away from the target for the month.
MID #2 has a current volume of $4,800 and 90% allocation, so it is at 85.7% and thus 4.3% away from the target for the month.
MID #3 has a current volume of $500 but 0% target allocation, so it is at 8.9%. However, the target is 0%, so no transactions will go to this MID.
The MIDs would be prioritized as follows:
- MID #1
- MID #2
- (MID #3)
Example 2: Current total transaction volume of $22,800
MID #1 has a current volume of $4,500 and 10% allocation, so it is at 19.7% currently and thus 9.7% over the target for the month.
MID #2 has a current volume of $10,300 and 90% allocation, so it is at 45.2% and thus 44.8% away from the target for the month.
MID #3 has a current volume of $8,000 but 0% target allocation, so it is at 35.1%. However, the target is 0%, so no transactions will go to this MID.
The MIDs would be prioritized as follows:
- MID #2
- MID #1
- (MID #3)
- The system routes the payment to the MID at the top of the list.
The following image shows a high-level view of the payment flow from above when you are using target allocation with multiple MIDs.
How do I route all transactions with a specific item to a relationship?
For cases where a transaction contains a certain item that you want to route to a specific relationship (with a merchant account provider, a processor, or an acquirer/bank), use Nexio's item routing feature.
You do this by setting up item routing at the level of the Nexio merchant account (MID) for an item based on the attributes of item
, description
, or type
from the data.cart.items
object.
Before you begin setting up item-based payment routing, Nexio recommends that you understand the following notes.
Important:
- For routing by item, your Nexio account must be configured with a single API user account for all the transactions
- If you add, change, or delete an item routing rule, the change becomes effective for transactions after that change date
- In general, the Nexio system does what it can to allow payments to succeed
Setting up payment routing by item
After you understand the complexities of payment routing by item (see How do I route all transactions with a specific item to a relationship?), you are ready to set it up.
To set up payment routing by item
-
Work with integration support to set up your Nexio account and merchant accounts (MIDs) so that they are optimized for payment routing by item.
In general, this means having a single API user with a MID that contains the specific relationship (merchant account provider, processor, or acquirer/bank) that applies for the item routing as well as one or more additional relationships for cases where that item is not in the request.
-
Open the Nexio Dashboard and log in.
For the sandbox: https://dashboard.nexiopaysandbox.com
For production: https://dashboard.nexiopay.com -
Navigate to Settings > Payment Routing (Beta).
The tab shows user accounts and the types of rules.
-
Locate the user account that you want to add to or modify item routing rules for. Click that row in the table.
The Payment Routing Rules page displays.
-
Click Add New Rule.
The Add Routing Rule dialog displays.
-
Select Item Routing as the rule type and then select the MID you want to add this rule to.
For example, select MID #1.
-
Specify one or more attributes for the item routing rule.
For example, if you have a CBD item in your catalog (where
data.cart.items[n].item
contains the text 'CBD') and want to route any transactions with that item to a specific gateway that is associated with MID #1, do the following:Example Rule 1a:
If
`Item`
`Contains`
`CBD`
You may also want to add a second rule in case the text is lowercase:
Example Rule 1b:
If
`Item`
`Contains`
`cbd`
Alternately, you can create only one rule if you use a regular expression that matches on the letters "cbd" in the item, regardless of the case of any of the letters, such as the following:
Example Rule 2:
If
`Item`
`RegEx(ECMAScript)`
`[c|C][b|B][d|D]`
-
You can then add more attributes if you want. For a rule with multiple attributes, the system only matches when ALL the specified attributes match.
-
When you are done creating the rule, click Save.
-
For the transaction request, configure the API as follows.
Each payment request must include the following parameters for item routing:
data.amount
data.currency
data.cart.items[n]
What happens after you set up item routing?
After you configure payment routing by item, the following process happens for each transaction (using CBD as the example):
-
A consumer adds an item to the shopping cart where the
type
is 'CBD' and submits payment.For example,
data.cart.items[1].type
equals 'CBD' and the transaction currency is 'USD'. -
The Nexio system determines the merchant account (MID) with the lowest monthly gross of authorized transactions (also known as transaction volume).
For example, suppose MID #1, MID #2, and MID #3 can support the currency and MID #4 does not. Only the first 3 are considered.
Then, if MID #1 has a current volume of $4,500, MID #2 is $10,300, and MID #3 is $8,000, the system prioritizes them as follows:
- MID #1
- MID #3
- MID #2
In this case, MID #1 has the lowest transaction volume.
-
The system checks whether there are any item routing rules with any of the applicable MIDs.
For example, MID #1 has a rule about the type being 'CBD', MID #2 has a rule about the description containing 'CBD', and MID #3 has a rule about the type and item containing 'CBD'.
If there are not any item routing rules, the system skips to step 5 in this sequence.
-
Based on the items in the cart and the item routing rules, the system identifies which of the MIDs can process the transaction.
For the following examples, MID #1 has a rule about the type being 'CBD', MID #2 has a rule about the description containing 'CBD', and MID #3 has a rule about the type and item containing 'CBD'.
Example 1:
Filtering when only type is 'CBD'
The MIDs would be prioritized as follows:
- MID #1
Example 2:
Filtering when both type and item are 'CBD'
The MIDs would be prioritized as follows:
- MID #1
- MID #3
Example 3:
Filtering when type is 'CBD' and description and item both contain 'CBD'
The MIDs would be prioritized as follows:
- MID #1
- MID #3
- MID #2
Example 4:
If applying the item routing rules results in no possible MIDs to process the transaction, the system ignores the rules.
Filtering when description is exactly 'CBD'
The list is empty, therefore the system removes the rule filtering, resulting in the following priorities for the MIDs:
- MID #1
- MID #3
- MID #2
- The system routes the payment to the MID at the top of the list.
The following image shows a high-level view of the payment flow from above when you are using item routing with multiple MIDs.
How do I set up a more complex payment routing flow?
More complex payment routing flows are also possible with Nexio.
This section provides information about the following complex options:
- I want to use both item routing and target allocation together
- I want to use a paymentOptionTag with payment routing (with or without target allocation and/or item routing)
- I want to send the transaction to a specific payment option for a specific MID
- I want to send a transaction to a specific MID
How do I use both item routing and target allocation together?
You can set up rules for both item routing and target allocation to create a complex payment routing flow when you have more than one merchant account (MID).
Before setting up rules, see the Important Notes in the following topics:
- How do I keep a relationship active at a specific transaction percentage?
- How do I route all transactions with a specific item to a relationship?
To set up payment routing by item and target allocation
-
Complete steps 1-9 in Setting up payment routing by target allocation
-
Complete steps 5-10 in Setting up payment routing by item
What happens after you set up both target allocation and item routing?
After you complete the steps for creating rules for both target allocation and item routing, the following process happens for each transaction (using 'CBD' as the item for routing):
-
A consumer adds an item to the shopping cart where the
type
is 'CBD' and submits payment.For example,
data.cart.items[1].type
equals 'CBD' and the transaction currency is 'USD'. -
The Nexio system determines the merchant account (MID) with the lowest monthly gross of authorized transactions (also known as transaction volume).
For example, suppose MID #1, MID #2, and MID #3 can support the currency and MID #4 does not. Only the first 3 are considered.
Then, if MID #1 has a current volume of $4,500, MID #2 is $10,300, and MID #3 is $8,000, the system prioritizes them as follows:
- MID #1
- MID #3
- MID #2
In this case, MID #1 has the lowest transaction volume.
-
The system checks whether there are any item routing rules with any of the applicable MIDs.
For example, MID #1 has a rule about the type being 'CBD', MID #2 has a rule about the description containing 'CBD', and MID #3 has a rule about the type and item containing 'CBD'.
If there are not any item routing rules, the system skips to step 5 in this sequence.
-
Based on the items in the cart and the item routing rules, the system identifies which of the MIDs can process the transaction.
For the following examples, MID #1 has a rule about the type being 'CBD', MID #2 has a rule about the description containing 'CBD', and MID #3 has a rule about the type and item containing 'CBD'.
Example 1:
Filtering when only type is 'CBD'
The MIDs would be prioritized as follows:
- MID #1
Example 2:
Filtering when both type and item are 'CBD'
The MIDs would be prioritized as follows:
- MID #1
- MID #3
Example 3:
Filtering when type is 'CBD' and description and item both contain 'CBD'
The MIDs would be prioritized as follows:
- MID #1
- MID #3
- MID #2
Example 4:
If applying the item routing rules results in no possible MIDs to process the transaction, the system ignores the rules.
Filtering when description is exactly 'CBD'
The list is empty, therefore the system removes the rule filtering, resulting in the following priorities for the MIDs:
- MID #1
- MID #3
- MID #2
-
The system checks to see if there are target allocation rules that match for this transaction.
If there are not any target allocation rules, the system skips to step 7 in this sequence.
-
The system takes the target allocations and re-sorts the list so that the MID that is farthest away from its target allocation is at the top.
For the following examples, the target allocation is 10% for MID #1, 90% for MID #2, and 0% for MID #3.
Example 1: Current total transaction volume of $5,600.
MID #1 has a current volume of $300 and 10% allocation, so it is at 5.4% and thus 4.6% away from the target for the month.
MID #2 has a current volume of $4,800 and 90% allocation, so it is at 85.7% and thus 4.3% away from the target for the month.
MID #3 has a current volume of $500 but 0% target allocation, so it is at 8.9%. However, the target is 0%, so no transactions will go to this MID.
The MIDs would be prioritized as follows:
- MID #1
- MID #2
- (MID #3)
Example 2: Current total transaction volume of $22,800
MID #1 has a current volume of $4,500 and 10% allocation, so it is at 19.7% currently and thus 9.7% over the target for the month.
MID #2 has a current volume of $10,300 and 90% allocation, so it is at 45.2% and thus 44.8% away from the target for the month.
MID #3 has a current volume of $8,000 but 0% target allocation, so it is at 35.1%. However, the target is 0%, so no transactions will go to this MID.
The MIDs would be prioritized as follows:
- MID #2
- MID #1
- (MID #3)
- The system routes the payment to the MID at the top of the list.
The following image shows a high-level view of the payment flow from above for when you are using both target allocation and item routing with multiple MIDs.
What effect does the use of a paymentOptionTag have on payment routing?
You can limit the routing by specifying processingOptions.paymentOptionTag
in the transaction request (such as in POST /pay/v3/process).
The paymentOptionTag
parameter is a custom value used to route transactions to a specific gateway or merchant account. In order to use the paymentOptionTag
for routing, contact integration support to designate one or more tags for your merchant account.
Before you begin setting up a paymentOptionTag, Nexio recommends that you understand the following notes.
Important:
- If the value provided for
paymentOptionTag
in the transaction request is invalid for the account, Nexio sends an error rather than attempt the transaction - If the transaction would be disqualified because of the specified parameter, Nexio responds with an error message and does not attempt to process the transaction further
- If you specify a value for the
paymentOptionTag
in the request and that tag has been assigned to multiple merchant IDs (MIDs) for your API user account, Nexio checks for target allocation or item routing rules as well. If there are not any rules, the system uses the MID with the current lowest monthly gross of authorized transactions (also known as transaction volume) - In addition, if you want to use target allocation or routing based on item with the paymentOptionTag, see the Important Notes in the appropriate topics:
Along with the paymentOptionTag, you can also make the payment routing flow more complex with either or both target allocation and item routing.
To set up paymentOptionTags
-
Contact integration support to designate one or more tags for your merchant account (MID).
Example 1: paymentOptionTags for USD as official currency in different countries
MID #1 - USD currency for United States: usa - USD currency for Puerto Rico: pri - USD currency for Ecuador: ecu
Example 2: paymentOptionTags for CBD
MID #1 - Gateway that allows transactions with CBD: CBD - Gateway to use for all other transactions: NoCBD
-
Make note of the tags that are created for your MIDs. These are not visible in the Dashboard.
Note: If you later need to find out what paymentOptionTags have been enabled, contact integration support.
-
If necessary, complete the steps in Setting up payment routing by target allocation
-
If necessary, complete the steps in Setting up payment routing by item
-
For the transaction request, configure the API as follows:
Each payment request must include the following parameters for payment routing with the paymentOptionTag:
data.amount
data.currency
processingOptions.paymentOptionTag
To customize payment routing with the paymentOptionTag and item routing, also include the following parameter:
data.cart.items[n]
What happens after you set up paymentOptionTags?
After you complete the steps for setting up one or more paymentOptionTags (and potentially also either or both target allocation and item routing), the following process happens for each transaction:
-
A consumer adds an item to the shopping cart and submits payment with a specific transaction currency.
For example, The consumer adds a CBD item and uses a card to pay in USD.
The
data.cart.items[1].type
parameter is set to 'CBD' and the transaction currency is 'USD'.Also, the
processingOptions.paymentOptionTag
parameter is set to 'CBD'.If the consumer instead had a cart of one or more items and none are CBD, then the paymentOptionTag would be 'NoCBD'.
-
The Nexio system determines the merchant account (MID) with the lowest monthly gross of authorized transactions (also known as transaction volume).
Example 1: Suppose MID #1, MID #2, and MID #3 can support the currency and paymentOptionTag of CBD and NoCBD and MID #4 does not have any paymentOptionTags. Only the first 3 MIDs are considered.
Then, if MID #1 has a current volume of $4,500, MID #2 is $10,300, and MID #3 is $8,000, the system prioritizes them as follows: - MID #1 - MID #3 - MID #2 In this case, MID #1 has the lowest transaction volume.
Example 2: Suppose only MID #1 and MID #3 can support the currency and paymentOptionTag and MID #2 only supports the currency and MID #4 does not have any paymentOptionTags. Only MIDs #1 and #3 are considered.
Then, if MID #1 has a current volume of $10,300, and MID #3 is $8,000, the system prioritizes them as follows: - MID #3 - MID #1 In this case, MID #3 has the lowest transaction volume.
-
The system checks to see if any routing rules have been configured and that apply.
For example, all three MIDs have item routing and target allocation rules.
-
The system checks whether there are any item routing rules with any of the applicable MIDs.
For example, MID #1 has a rule about the type being 'CBD', MID #2 has a rule about the description containing 'CBD', and MID #3 has a rule about the type and item containing 'CBD'.
If there are not any item routing rules, the system skips to step 6 in this sequence.
-
Based on the items in the cart and the item routing rules, the system identifies which of the MIDs can process the transaction.
For the following examples, MID #1 has a rule about the type being 'CBD', MID #2 has a rule about the description containing 'CBD', and MID #3 has a rule about the type and item containing 'CBD'.
Example 1:
Filtering when only type is 'CBD' The MIDs would be prioritized as follows: - MID #1
Example 2:
Filtering when both type and item are 'CBD' The MIDs would be prioritized as follows: - MID #1 - MID #3
Example 3:
Filtering when type is 'CBD' and description and item both contain 'CBD' The MIDs would be prioritized as follows: - MID #1 - MID #3 - MID #2
Example 4:
If applying the item routing rules results in no possible MIDs to process the transaction, the system ignores the rules.{.indent} Filtering when description is exactly 'CBD' The list is empty, therefore the system removes the rule filtering, resulting in the following priorities for the MIDs: - MID #1 - MID #3 - MID #2
-
The system checks to see if there are target allocation rules that match for this transaction.
If there are not any target allocation rules, the system skips to step 8 in this sequence.
-
The system takes the target allocations and re-sorts the list so that the MID that is farthest away from its target allocation is at the top.
For the following examples, the target allocation is 10% for MID #1, 90% for MID #2, and 0% for MID #3.
Example 1: Current total transaction volume of $5,600.
MID #1 has a current volume of $300 and 10% allocation, so it is at 5.4% and thus 4.6% away from the target for the month. MID #2 has a current volume of $4,800 and 90% allocation, so it is at 85.7% and thus 4.3% away from the target for the month. MID #3 has a current volume of $500 but 0% target allocation, so it is at 8.9%. However, the target is 0%, so no transactions will go to this MID. The MIDs would be prioritized as follows: - MID #1 - MID #2 - (MID #3)
Example 2: Current total transaction volume of $22,800
MID #1 has a current volume of $4,500 and 10% allocation, so it is at 19.7% currently and thus 9.7% over the target for the month.
MID #2 has a current volume of $10,300 and 90% allocation, so it is at 45.2% and thus 44.8% away from the target for the month.
MID #3 has a current volume of $8,000 but 0% target allocation, so it is at 35.1%. However, the target is 0%, so no transactions will go to this MID.
The MIDs would be prioritized as follows:
- MID #2
- MID #1
- (MID #3)
- The system routes the payment to the MID at the top of the list.
The following image shows a high-level view of the payment flow from the above process when you are using paymentOptionTags along with the potential for target allocation and item routing with multiple MIDs.
How do I send a transaction to a specific MID and paymentOptionTag based on transaction currency?
There may be cases where you don't want to use Nexio's smart routing feature and you want to send all transactions for a specific transaction currency to one specific merchant account (MID) and payment option for that MID.
You can limit the routing by specifying both a processingOptions.merchantId
and processingOptions.paymentOptionTag
in the transaction request (such as in POST /pay/v3/process).
The merchantId
parameter is a unique code that Nexio assigns to each MID on your account.
The paymentOptionTag
parameter is a custom value used to route transactions to a specific gateway or merchant account. In order to use the paymentOptionTag
for routing, contact integration support to designate one or more tags for your merchant account.
Before you begin setting up a paymentOptionTag and using merchantId, Nexio recommends that you understand the following notes.
Important:
-
When you specify a value for both of these parameters (
processingOptions.merchantId
andprocessingOptions.paymentOptionTag
), Nexio uses only this information to process the transaction. The system will not attempt to use any other possible merchant IDs (MIDs) or payment option tagsTherefore, using a specific value for both of these parameters means that Nexio does not attempt any other routing, even if other routing rules have been specified in the account
-
If the value provided for either
merchantId
orpaymentOptionTag
in the transaction request is invalid for the account, Nexio sends an error rather than attempt the transaction -
If the transaction would be disqualified because of the specified parameter, Nexio responds with an error message and does not attempt to process the transaction further
To set up paymentOptionTag and merchantId
-
Contact integration support to learn the
merchantId
for each MID on your account and to designate one or more paymentOptionTags for your merchant account.Example 1: paymentOptionTags for USD as official currency in different countries
MID #1 - merchantId is 100000000039 - USD currency for United States: usa - USD currency for Puerto Rico: pri - USD currency for Ecuador: ecu MID #2 - merchantId is 100000000041 - USD currency for Ecuador: ecu
-
Make note of the tags that are created for your MIDs. These are not visible in the Dashboard.
You can see the
merchantId
for each of your MIDs by going to the Dashboard, then Settings > Merchant Management.Note: To get a list of all paymentOptionTags for which a currency is enabled for a given merchant ID, contact integration support.
-
For the transaction request, configure the API as follows:
Each payment request must include the following parameters for payment routing with the paymentOptionTag and merchantId:
- `data.amount`
- `data.currency`
- `processingOptions.paymentOptionTag`
- `processingOptions.merchantId`
What happens when a transaction request includes a paymentOptionTag and merchantId?
After you complete the steps for setting up one or more paymentOptionTags and know the merchantId you want to use, the following process happens for each transaction:
-
A consumer adds an item to the shopping cart and submits payment with a specific transaction currency.
For example, The consumer with an address in Ecuador uses a card to pay in USD.
Also, the
processingOptions.paymentOptionTag
parameter is set to 'ecu' and theprocessingOptions.merchantId
parameter is set to '100000000041'. -
The Nexio system checks for the specific MID and if it has support for the transaction currency and the paymentOptionTag.
Example 1:
For address in Ecuador and MID of 100000000041 MID #2 is the only option because it has the correct merchantId and paymentOptionTag.
Example 2:
For address in Puerto Rico and MID of 100000000041 Nexio returns an error message because that MID does not include that paymentOptionTag.
-
The system routes the payment to the MID or responds with an error message.
How do I send a transaction to a specific MID based on transaction currency?
There may be cases where you don't want to use Nexio's smart routing feature and you want to send all transactions for a specific transaction currency to one specific merchant account (MID).
You can limit the routing by specifying the processingOptions.merchantId
in the transaction request (such as in POST /pay/v3/process).
The merchantId
parameter is a unique code that Nexio assigns to each MID on your account.
Before you begin using merchantId, Nexio recommends that you understand the following notes.
Important:
-
When you specify a value for
processingOptions.merchantId
, Nexio uses only this information to process the transaction. The system will not attempt to use any other possible merchant IDs (MIDs)Therefore, using a specific value for this parameter means that Nexio does not attempt any other routing, even if other routing rules or paymentOptionTags have been specified in the account
-
If the value provided for
merchantId
in the transaction request is invalid for the account, Nexio sends an error rather than attempt the transaction -
If the transaction would be disqualified because of the specified parameter, Nexio responds with an error message and does not attempt to process the transaction further
To set up merchantId
-
Contact integration support to learn the
merchantId
for each MID on your Nexio account.Example 1:
paymentOptionTags for USD as official currency in different countries MID #1 - merchantId is 100000000039 - USD currency for United States: usa - USD currency for Puerto Rico: pri - USD currency for Ecuador: ecu MID #2 - merchantId is 100000000041 - USD currency for Ecuador: ecu
-
Open the Nexio Dashboard and log in.
For the sandbox: https://dashboard.nexiopaysandbox.com
For production: https://dashboard.nexiopay.com -
Go to Settings > Merchant Management.
A list displays of all merchant accounts for your account, including the merchant ID value.
Make note of the merchant ID value that you want to use.
-
For the transaction request, configure the API as follows:
Each payment request must include the following parameters for payment routing with the
merchantId
:data.amount
data.currency
processingOptions.merchantId
What happens when a transaction request includes a merchantId?
After you know and assign the merchantId you want to use to transaction rerquests, the following process happens for each transaction:
-
A consumer adds an item to the shopping cart and submits payment with a specific transaction currency.
For example, The consumer with an address in Ecuador uses a card to pay in USD.
Also, the
processingOptions.merchantId
parameter is set to '100000000041'. -
The Nexio system checks that the MID has support for the transaction currency.
Example 1:
For address in Ecuador and MID of 100000000041 MID #2 is valid because it has support for the currency.
Example 2:
For address in Puerto Rico and MID of 100000000041 Nexio returns an error message because that MID does not support that currency for that country.
-
The system routes the payment to the MID or responds with an error message.
Nexio Dashboard
The Nexio Dashboard provides access to transactions, reports, account information, and settings.
You can perform the following tasks in the Dashboard for Payment Routing:
The following section has information about fields on Payment Routing pages in the Dashboard:
Payment Routing by Item
Nexio allows you to specify payment routing rules for an item at the level of the Nexio merchant account (MID) for an item based on the attributes of item
, description
, or type
from the data.cart.items
object.
After you understand the complexities of payment routing by item (see How do I route all transactions with a specific item to a relationship?), you are ready to set it up. For information about how the routing rules are prioritized and for a tutorial based on your desired outcome, see the Payment Routing (Beta) section.
Note: If you add, change, or delete an item routing rule, the change becomes effective for transactions after that change date.
To set up payment routing by item
-
Open the Nexio Dashboard.
For the sandbox: https://dashboard.nexiopaysandbox.com
For production: https://dashboard.nexiopay.com -
Navigate to Settings > Payment Routing (Beta).
The tab shows user accounts and the types of rules. For information about this tab, see Fields: Payment Routing (Beta).
-
Locate the user account that you want to add to or modify payment routing rules for. Click that row in the table.
The Payment Routing Rules page displays. For information about this page, see Fields: Payment Routing Rules.
-
Add or modify rules for one or more MIDs:
- To add a rule, click Add New Rule. The Add New Rule dialog displays
- To edit an existing rule, locate and select the rule in the table. The Edit New Rule dialog displays
- To delete an existing rule, open the rule, click Delete and then confirm that deletion
- To add a rule, click Add New Rule. The Add New Rule dialog displays
-
For a new rule, select Item Routing as the rule type and then select the MID you want to add this rule to.
For example, select MID #1.
-
Specify one or more attributes for the item routing rule.
For more information about the options in this dialog, see the item routing information in Fields: Add/Edit Routing Rule.
-
You can then add more attributes if you want. For a rule with multiple attributes, the system only matches when ALL the specified attributes match.
-
When you are done creating the rule, click Save.
Payment Routing by Target Allocation
When you have multiple merchant IDs (MIDs) for an account and want to have Nexio route payments based on the total amount processed for each MID for a currency, you can set up routing by target allocation percentage.
After you understand the complexities of target allocation (see How do I keep a relationship active at a specific transaction percentage?), you are ready to set it up. For information about how the routing rules are prioritized and for a tutorial based on your desired outcome, see the Payment Routing (Beta) section.
Note: If you change the target allocations, the change is effective from that change date. Thereafter, the system attempts to send transactions based on the new target allocation percentages and based on where the current monthly transaction amount is for each MID. If the change in allocation percentages is large, or if the change happens late in the month, then one MID will get 100% of the transactions for a time during the remainder of the month. Therefore, use caution when making changes in the middle of the month
To set up payment routing by allocation
-
Open the Nexio Dashboard.
For the sandbox: https://dashboard.nexiopaysandbox.com
For production: https://dashboard.nexiopay.com -
Navigate to Settings > Payment Routing (Beta).
The tab shows user accounts and the types of rules. For information about this tab, see Fields: Payment Routing (Beta).
-
Locate the user account that you want to add to or modify payment routing rules for. Click that row in the table.
The Payment Routing Rules page displays. For information about this page, see Fields: Payment Routing Rules.
-
Add or modify rules for one or more MIDs:
- To add a rule, click Add New Rule. The Add Routing Rule dialog displays
- To edit an existing rule, locate and select the rule in the table. The Edit Routing Rule dialog displays
- To delete an existing rule, open the rule, click Delete and then confirm that deletion
- To add a rule, click Add New Rule. The Add Routing Rule dialog displays
-
For a new rule, select the currency you want to add this rule to and then select Target Allocation as the rule type.
For more information about the options in this dialog, see the target allocation information in Fields: Add/Edit Routing Rule.
-
When you are done creating the rule, click Save.
Dashboard Fields
This section provides information about the fields on the following pages:
Fields: Payment Routing (Beta)
PATH: Settings > Payment Routing (Beta) tab
The Payment Routing tab shows all user accounts for your login, the Merchant IDs (MIDs) associated with each one, and the types of rules associated with each user account.
Refresh (icon)
Lets you refresh the table display.
User and Routing List
Displays a list of the user accounts and what kinds of routing rules (if any) are associated with that account.
Click anywhere in a row to go to the Payment Routing Rules page.
The list displays the following information:
Option | Description |
---|---|
User E-mail | Displays the email address associated with the user account. Start typing an email address or any part thereof to dynamically filter the list. Click the heading to sort the account list in alphabetical order. Click the heading again to sort the account list in reverse-alphabetical order. |
Merchants | Displays the merchant ID (MID) or merchant IDs that are associated with the user account. |
Routing Rule Type | Displays the type of routing rule associated with the user account. Options are "None" "Item Rule", and "Target Allocation". |
**+ (plus sign)** (icon)
Lets you select which columns display in the table.
List Navigation
Lets you move to specific locations in the list of user accounts.
The navigation has the following controls:
- < First - Go to the first page of accounts
- Previous - Go to the previous page of accounts
- x-y of z - Displays the current location in the list of accounts
- Next - Go to the next page of accounts
- Last > - Go to the last page of accounts
Fields: Payment Routing Rules
PATH: Settings > Payment Routing (Beta) tab > [user account]
The Payment Routing Rules page lets you create and modify existing routing rules for a selected user account.
User email
Displays the email address of the currently selected user account.
Add New Rule
Lets you add a payment routing rule for the user account. Clicking the button opens the Add New Rule dialog.
Refresh (icon)
Lets you refresh the table display.
Routing Rules List
Displays a list of the merchant accounts for the user and routing rules (if any) associated with each merchant account.
Click anywhere in a row to go to the Edit Routing Rule dialog.
The list displays the following information:
Option | Description |
---|---|
Merchant | Displays the name of the merchant account. Or, for Target Allocation routing rules, displays "Multiple". Start typing a merchant name or any part thereof to dynamically filter the list. Click the heading to sort the list in alphabetical order by merchant name. Click the heading again to sort the list in reverse-alphabetical order. |
Merchant ID | Displays the merchant ID (MID) associated with the merchant account. Or, for Target Allocation routing rules, displays "Multiple". |
Currency | Displays the three-character code for the currency associated with a Target Allocation routing rule. |
Routing Rule Type | Displays the type of routing rule associated with the user account. Options are "Item Rule" or "Target Allocation". |
**+ (plus sign)** (icon)
Lets you select which columns display in the table.
Fields: Add/Edit Routing Rule
PATH: Settings > Payment Routing (Beta) tab > [user account] > Add New Rule
PATH: Settings > Payment Routing (Beta) tab > [user account] > [rule name]
Lets you create or edit the routing rule.
For the steps on how to set up a rule, see Payment Routing (BETA).
Rule Type
For a new rule, lets you select the type of routing rule to create, either Item Routing or Target Allocation. Target Allocation is the default selection.
For editing an existing rule, displays the type of routing rule.
Rule Info
For Item Routing, the following fields display:
Option | Description |
---|---|
Merchant | Lets you select the merchant account for the item routing rule. You must select the MID for the remaining fields to display. |
Attributes | The attributes section lets you configure the settings of the item routing rule. Each attribute rule starts with an "If" statement. The fields are the following: - Attribute - Specifies the attribute of an item to use for the rule. The values come from the parameters of the items[] object. Options are "Item", "Description", or "Type".- Type - Specifies the type of search or filter to use with the selected attribute. Options are "RegEx (ECMAScript)", "Contains", "Does Not Contain", "Matches Exactly", or "Does Not Match Exactly". - Enter text - Specifies the text to use for the search or filter of this rule. This value is case sensitive. |
Add Another Attribute | Lets you add one or more additional attributes as part of this item routing rule. When you have more than two attributes, they are joined by the Boolean AND, so that all attributes must apply for the rule to be used for item routing. |
For Target Allocation, the following fields display:
Option | Description |
---|---|
Currency | Lets you select the currency to set up a target allocation for with the user account. You must select the currency for the remaining fields to display. |
Merchant list | The merchant list shows the possible merchant accounts that can be allocated for the specified currency. The list displays the merchant account name and merchant ID (MID) as well as the current Target Allocation (if any). Specify the allocation percentage that you want to assign to each MID in the Target Allocations fields. You can specify a 0 for one or more MIDs or 100 for only one MID, however the total must add up to 100% for the allocation across all MIDs before you can save the rule. |
**Delete**
Lets you completely remove an existing routing rule from this merchant account.
Save
Click this button to save the routing rule.
Payouts
Payouts Overview
A common recipient payout experience is logging into a payout provider portal and claiming funds.
Nexio has integrated several payout providers while continuing to provide the same portal experience to recipients, including email notifications and a reporting interface.
What is a recipient?
A recipient is the individual or business receiving payments. Before paying out to a recipient, a recipient profile must first be created either as a separate step or simultaneously with the payout request.
What is a payout?
A payout is the request from the payer (merchant or business, for example) to fund a recipient’s balance, wallet, or account.
What is the recipient's experience?
Depending on the chosen payout provider, the payout experience for recipients does not have to change at all.
What is the payer's experience?
The payer (merchant or business, for example) can keep the exact same experience with the payout provider portal, including manual uploads to the provider's portal.
Nexio adds the option for payers to send payouts to recipients through an integration, and gives them a centralized location to track payouts and access reports in the Nexio Dashboard.
What is the integration experience?
An integrator can leverage Nexio's API to do the following:
- Create a recipient profile to which payments will be sent
- Retrieve information for one or multiple recipient profiles
- Create a request to process one or more payout transactions
- Retrieve details for one or more payout transactions
The overall payout experience is as follows:
-
Your application creates a recipient profile (before or during a payout request).
For details about using the API to create a profile, see the Create a Recipient, Submit Payouts, or Submit Payouts using Batch File endpoint.
-
Your application submits a payout request.
For details about using the API to submit a payout request, see the Submit Payouts or Submit Payouts using Batch File endpoint.
-
The recipient receives an email notification from the payout provider prompting them to log in and accept the payment.
-
The recipient activates their payout account and selects their preferred transfer method.
-
The recipient’s transfer method is funded.
-
The payer (merchant or business, for example) views payout information in the Nexio Dashboard (or using the payout provider portal).
For details about using the API to retrieve information for one or more recipient profiles, see the View a Recipient or View Recipients endpoint.
For details about using the API to retrieve information for one or more payouts, see the View a Payout or View Payouts endpoint.
For details about configuring and using webhooks to retrieve payout event information, see Webhooks.
Subscriptions
Nexio's subscription service allows you to run recurring transactions. These can be in the form of basic subscriptions or pay plans.
Subscriptions
Subscriptions set transactions to run for a specified amount on a predefined schedule. When you create a subscription you will set the following parameters:
-
Amount: (
payment.data.amount
) The amount that will be charged during each transaction -
Interval: (
schedule.interval
) The schedule's time period. May be days, weeks, months or years -
Interval count: (
schedule.intervalCount
) The number of intervals that will pass between transactions. See the table below for examples of how the interval and interval count create the subscription schedule -
Initial billing period (optional): If desired, you may set an initial billing period during which the transactions will be run for an amount different than the subscription amount. (For example, during a discounted trial period.) To set an initial billing period, include the following parameters:
- Initial Billing Period End Date: (
schedule.dateInitialBillingEnd
) The date at which the initial billing period will end. Transactions prior to this date will be run for the initial billing amount. Transactions after this date will be run for the subscription amount. - Initial billing Amount: (
schedule.initialBillingAmount
) The transaction amount during the initial billing period
- Initial Billing Period End Date: (
Subscription Schedule Examples
Interval Count | Interval | Explanation |
---|---|---|
30 | Day | Transactions will run every 30 days |
4 | Week | Transactions will run every 4 weeks |
2 | Month | Transactions will run every other month |
Create a Subscription
-
Determine your Settings
Determine whether to include an initial billing period and the proper subscription settings. (These will generally be pre-determined by the shopper's selections on your checkout page.)
-
Send a Request to Nexio
Send a POST request to the Create Subscription endpoint. Include the billing amounts and subscription settings as determined in step 1.
The example below will create a recurring subscription that will run a transaction for 19.99 USD every other week.
Basic Subscription
curl -X POST https://api.nexiopaysandbox.com/subscription/v3 \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Basic <Your Basic Auth>'
-d '{
"payment": {
"data": {
"amount": 19.99,
"currency": "USD",
"customer": {
"customerRef": "RP006"
}
},
"tokenex": {
"token": "6ee140a0-05d1-4958-8325-b38a690dbb9d"
}
},
"schedule": {
"interval": "week",
"intervalCount": 2
}
}'
The example below will create a recurring subscription that will run a transaction once a month. The transaction amount will be 15 USD until October 5, 2021. After that the transaction amount will be 25 USD.
Subscription with Initial Billing Period
curl -X POST https://api.nexiopaysandbox.com/subscription/v3 \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Basic <Your Basic Auth>'
-d '{
"payment": {
"data": {
"amount": 25,
"currency": "USD",
"customer": {
"customerRef": "RP006"
}
},
"tokenex": {
"token": "6ee140a0-05d1-4958-8325-b38a690dbb9d"
}
},
"schedule": {
"interval": "month",
"intervalCount": 1,
"dateInitialBillingEnd": "2021-10-05",
"initialBillingAmount": 15
}
}'
Note: If the initial transaction is declined, the subscription will not be created. It must be re-created with a new card token.
-
Configure Webhooks (Optional)
If desired, you may configure webhooks to be sent every time a transaction is run through the subscription service. See the Webhooks tutorial for step-by-step instructions on how to configure and receive webhooks.
Note: You will continue to receive webhooks for any previously configured transaction events.
Example Request
curl -X POST https://api.nexiopaysandbox.com/webhook/v3/config \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Basic <Your Basic Auth>'
-d '{
"merchantId": "100039",
"webhooks": {
"SUBSCRIPTION_DETAILS": {
"url": "https://your-company-webhook-url-here.com"
}
}
}'
Pay Plans
Pay plans set recurring transactions to run until the pre-specified balance is paid in full. To create a pay plan, create a subscription and include the following parameters in your request:
- Balance: (
schedule.balance
) The total amount to be charged over the course of the pay plan - Interval: (
schedule.interval
) The pay plans's time period. May be days, weeks, months or years - Interval count: (
schedule.intervalCount
) The number of intervals that will pass between transactions. See the table below for examples of how the interval and interval count create the subscription schedule - Amount (optional): (
payment.data.amount
) The amount to be charged during each transaction - Duration (optional): (
schedule.duration
) The duration of the subscription. This is the number of transactions that will run before the pay plan terminates. If amount is not provided the duration will also be used to calculate the amount to be charged during each transaction
Note: You must provide either an amount or a duration. If you provide both, amount will be used, duration will be ignored.
Create a Pay Plan
-
Determine your Settings
Determine the pay plan balance and schedule. Also determine whether you would like to provide an amount or a duration (not both). These may be pre-determined by the shopper's selections on your checkout page.
-
Send a Request to Nexio
Send a POST request to the Create Subscription endpoint. Include the balance, schedule and amount/duration as determined in step 1.
The example below will create a pay plan with a balance of 100 USD. It will run a transaction once a month for 10 USD. After the 10th transaction, the balance will be paid in full and the pay plan with terminate.
Pay Plan with Transaction Amount
curl -X POST https://api.nexiopaysandbox.com/subscription/v3 \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Basic <Your Basic Auth>'
-d '{
"payment": {
"data": {
"amount": 10,
"currency": "USD",
"customer": {
"customerRef": "RP006"
}
},
"tokenex": {
"token": "6ee140a0-05d1-4958-8325-b38a690dbb9d"
}
},
"schedule": {
"balance": 100,
"interval": "month",
"intervalCount": 1
}
}'
The example below will create a pay plan with a balance of 100 USD that will run every month for 5 months. In order for the balance to be paid in full, each transaction will automatically be run for 20 USD.
PAY PLAN WITH DURATION
curl -X POST https://api.nexiopaysandbox.com/subscription/v3 \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Basic <Your Basic Auth>'
-d '{
"payment": {
"data": {
"currency": "USD",
"customer": {
"customerRef": "RP006"
}
},
"tokenex": {
"token": "6ee140a0-05d1-4958-8325-b38a690dbb9d"
}
},
"schedule": {
"balance": 100,
"duration": 5,
"interval": "month",
"intervalCount": 1
}
}'
-
Configure Webhooks (Optional)
If desired, you may configure webhooks to be sent every time a transaction is run through the subscription service. See the Webhooks tutorial for step-by-step instructions on how to configure and receive webhooks.
Note: You will continue to receive webhooks for any previously configured transaction events.
Example Request
curl -X POST https://api.nexiopaysandbox.com/webhook/v3/config \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Basic <Your Basic Auth>'
-d '{
"merchantId": "100039",
"webhooks": {
"SUBSCRIPTION_DETAILS": {
"url": "https://your-company-webhook-url-here.com"
}
}
}'
Dev Tools
Handling Errors and Declines
For most situations you will encounter a handful of HTTP response status codes for error and success -- including 200, 401, 404, 400, and 500.
The most common responses will be:
-
200: Operation was successful
-
4xx: Operation failed (In the case of payments, a 4xx status code means the payment was not processed)
Note: Due to PCI regulations error messages may often be intentionally ambiguous. Please contact us if you wish to discuss your error messages, or see our list of common errors.
Errors in the payment forms can be handled by adding an event listener to the window.
Example
window.addEventListener('message', function messageListener(event) {
if (event.origin === iframeDomain) {
if (event.data.event === 'error' || event.data.event === 'success' || event.data.event === 'processed') {
// handle success or error messages
}
if (event.data.event === 'loaded') {
//handle form loaded state
}
if (event.data.event === 'cardSaved') {
//handle cardSaved
}
console.log(event.data.event);
}
});
Common Errors
Nexio Error Code | Description | HTTP Status Code |
---|---|---|
404 | The requested item is not found | 404 |
404 | Merchant not found or invalid merchant configuration | 404 |
408 | Payment gateway timeout | 400 |
409 | No merchants enabled for processing on this account for selected currency | 409 |
418 | Unsupported action or browser, or device does not support Apple Pay | 400 |
431 | Kount has identified a possible risk with the transaction | 400 |
432 | Invalid currency | 400 |
433 | Invalid gateway | 400 |
434 | Invalid TokenEx configuration | 400 |
435 | Unable to process with gateway | 400 |
436 | Unable to capture void or refund | 400 |
436 | Missing required fields | 400 |
437 | Failed CVC check | 400 |
438 | Invalid request | 400 |
439 | Unable to load TokenEx | 500 |
440 | Insufficient access | 401 |
441 | Amount needs to be a number | 400 |
443 | Verify AVS Failed | 400 |
5xx | Generic server error | 500 |
Gateway Declines
If a card transaction is declined by the gateway, Nexio will return an HTTP status code and a Nexio error code. The payment will not be processed.
The response will be shaped as shown in the example below.
Example Gateway Decline
{
"error": 435,
"message": "Declined for CVV failure",
"gatewayResponse": {
"gatewayName": "yourGateway",
"refNum": "3113320943",
"status": "pending"
},
"merchantId": "100100"
}
Common Gateway Declines
See the table below for a list of the most common gateway declines.
Nexio Error Code | Message | HTTP Status Code |
---|---|---|
435 | Declined | 400 |
435 | Pickup Card | 400 |
435 | Do not Honor | 400 |
435 | Invalid Transaction | 400 |
435 | Invalid Issuer | 400 |
435 | Unable to locate Record | 400 |
435 | Insufficient funds | 400 |
435 | Invalid Pin | 400 |
435 | Transaction Not Permitted | 400 |
435 | Restricted Card | 400 |
435 | Excess withdrawal count | 400 |
435 | Allowable number of pin tries exceeded | 400 |
435 | No checking account | 400 |
435 | Declined for CVV failure | 400 |
CVC Verification Failures
There are two main reasons that a verifyCvc
check while saving a card token can fail.
- Incorrect card security code or similar problem
- Error with some part of the CVC process outside of Nexio
Incorrect Card Security Code or Card Problem
If you submit a save card transaction where you have verifyCvc
enabled and the specified card security code is not correct, then the matchCvv
response returns as false
and the cvvresponse
returns as N
. Although the verifyCvc check completed successfully, because the card security code was invalid, the system returns an HTTP status code of 400 and a Nexio error code of 437. In addition, the card token is not saved.
Other card problems from submitting this transaction also return the matchCvv
as false
and the card token does not get saved. The cvvresponse
in the gateway message is also N
for these cases. The message from the gateway provides additional detail about the specific problem, such as expired card or insufficient funds.
The response will be shaped as shown in the example below.
Example CVC Verification Failure
{
"error": 437,
"message": "Verify CVC Failed",
"cvcResults": {
"matchCvv": false,
"error": false,
"gatewayMessage": {
"cvvresponse": "N",
"message": "CVV2/CVC2 no match"
}
},
"merchantId": "100100"
}
Error with a Verification Provider During the Check
In addition to the card security code being incorrect, there may be a problem with doing the verification process. The error
parameter will be set to true
.
After getting any of these errors, you may want to delete the card token.
The following table lists of the most common card CVC verification errors.
CVV Response Code | Message | Description |
---|---|---|
P | Not processed | This error indicates a general error that caused the verification check to not run at all. The card token is still saved. |
S | Merchant has indicated that CVV2/CVC2 is not present on card | This error indicates that the merchant had a problem when doing the verification check, such as when a card security code is given but no code is associated with that card. The card token is still saved. |
U | Issuer is not certified and/or has not provided Visa encryption keys | This error indicates that the bank had a problem when doing the verification check. The card token is still saved. |
X | unknown | This error indicates that no CVC data was available. |
The response will be shaped as shown in the example below for the S
cvvresponse.
Example Provider Verification Error
{
"token": {...},
"data": {...},
"card": {...},
"merchantId": "100100",
"shouldUpdateCard": true,
"kountResponse": {...},
"cvcResults": {
"error": true,
"gatewayMessage": {
"cvvresponse": "S",
"message": "Merchant has indicated that CVV2/CVC2 is not present on card"
}
},
"cardType": "visa"
}
Frequently Asked Questions
Error Codes
Q: I keep receiving the error: '442 Invalid one time use token'. Why is my token not working?
Once a one-time-use token has been used to submit an iframe it cannot be used to load another. You must request a new one-time-use token prior to submitting each iframe.
Q: Why am I getting a 403 error when I send a request for a one-time-use token? I know my credentials are correct.
To request a one-time-use token you must send a POST
request.
Sending a GET
request will result in a 403 Forbidden
error.
Q: I'm getting a 440 error when I try to specify which merchant to process with.
To troubleshoot this issue, follow the steps below:
- Make sure there are no typos when you enter the merchant ID.
- 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
- Make sure you are sending the variable
merchantId
as a string and not as an integer.
Q: Why do I keep receiving a 431 'Error from Kount' error while testing?
Please note that Kount verification will be performed by default when saving a card token or running a card transaction. To solve for unexpected 431 errors while testing your integration, try either of the following solutions:
- Make sure your tests do not include any of the values shown here
- Disable Kount verification by including the parameter
"processingOptions": { "checkFraud": false }
in the body of your request. (See the Enable Kount Verification tutorial for reference.)
Q: Why am I getting an error saying Authorization header requires 'Credential' parameter
?
The following is a common AWS error:
{ "message": "Authorization header requires 'Credential' parameter. Authorization header requires 'Signature' parameter. Authorization header requires 'SignedHeaders' parameter. Authorization header requires existence of either a 'X-Amz-Date' or a 'Date' header. Authorization=Basic Og==" }
To debug it, please try the following:
- Check that your HTTP method is correct. (For example, if the HTTP method is set to PUT when it should be POST you may receive this error)
- Check that your request includes all required path and query parameters
- Check your request for typos in the URL
If you still cannot resolve the error, please contact integration support.
Testing
Q: Can I test the iframes before integrating?
Yes! Once you have a Nexio account, you can use our Sandbox Tester.
Q: Are there any cards I can test with?
Yes. Test cards vary by implementation. Contact integration support for test cards specific to your needs.
Note: If you are testing with the Processing Option verifyCvc: true
you must set the CVC equal to 111,
otherwise you will receive a 437 Invalid CVC
error.
Other
Q: All payments are coming back as pending
, are these actually successful? Can I mark the order as paid and ship product?
The status of pending
means the transaction is approved but the batch has not yet settled.
Settled transactions will show a status of authorized
.
You can be assured that any pending
/authorized
transactions will settle without any issue.
Note: Batch close time is typically at 11pm PDT.
See the Transaction Status table for more information.
Q: Is there a joint auth & capture method?
Yes! The endpoint is called Run Card Transaction. When you send a request to this endpoint, by default the transaction will be authorized and captured.
If you wish to run an auth only transaction, send isAuthOnly: true
in the body of your request.
Q: I see two custom field entries, what are those for?
The two custom fields provided are optional for partners to use for reconciliation and/or reporting purposes.
Q: Is it possible to run an auth only using the iframe and then capture through the API?
Yes, you can use the Nexio iframe in AuthOnly mode then capture the sale later if that is best for your workflow.
To run an auth only in the iframe,
include isAuthOnly: true
the body of your request when you retrieve a one-time-use token.
You can then capture using the Capture Transaction endpoint of the API or through Nexio dashboard.
Q: Can I host my localization/translation JSON file as a GitHub gist?
Yes, you can host your sandbox localization/translation file anywhere you choose.
To use a GitHub gist to host your translation file, follow the steps below:
-
Create a GitHub gist containing your translation JSON file
- Note: The gist must be public in order for Nexio to access it
-
Copy the gist's URL. It will look like this:
https://gist.github.com/your-github-username/8bdeaf3e8bc8c473d06b82ad56dd1c7d
-
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
-
Proceed to step 4 of the Iframe Label Translation tutorial
Note: These steps do not apply to the production environment. Production translation/localization files must be hosted by Nexio. See step 3 of the Iframe Label Translation tutorial for more information.
Glossary
Authorize
A card transaction is authorized when the issuing bank approves the transaction. Funds are not moved during authorization. A transaction may be run as an auth only and captured at a later time or authorized and captured simultaneously.
Auth Only
An auth only transaction is a transaction that is only authorized. It must be captured in order for funds to be moved.
Authorize and Capture
A transaction is processed once it has been authorized and captured. By default, all card transactions run through Nexio are authorized and captured simultaneously.
Capture
A transaction is captured when the funds are moved.
Card Transaction
A card transaction refers to either a credit or debit card transaction.
Merchant ID
Each merchant account will be assigned a merchant ID upon signing a contract with Nexio. (Also called MID.)
Processed
Reference Tables
Iframe Events
The following events may be emitted by various Nexio iframes.
For an example of how to create an event listener for one or more of these, see Event Listener Example below.
The 'Iframe' column lists the iframe(s) that may emit that event. If 'All' is listed that event applies to all of the following iframes:
- Save Card Token
- Run Card Transaction
- Save E-check Token
- Run e-check Transaction
- Retail Save Card
- Retail Run Card Transaction
- Alternative Payment Methods (APMs)
Event | Iframe | Description | Example Event Response |
---|---|---|---|
cardSaved |
Save Card, Retail Save Card | The card token has successfully been saved | |
eCheckProcessed |
Run E-check Transaction | The e-check has successfully been processed | |
eCheckSaved |
Save E-check | The e-check token has successfully been saved | |
error |
All | An error has occurred | eventName: error { Â Â "error": 481, Â Â "message": "User canceled 3DS" } |
fingerprintPosted |
All | Device fingerprinting information | eventName: fingerprintPosted { Â Â "data": { Â Â Â Â "key": "31b0441b-6b5d-43c6-9d03-33b7b2ea1203", Â Â Â Â "kount": "31b0441b6b5d43c69d0333b7b2ea1203" Â Â } } |
formValidations |
All | Indicates form validation success or error per form field and for the form overall. You can check for true for one or more individual form fields or check for true for only isFormValid to know that all fields have been validated |
eventName:formValidations {   billToAddressOneValid: true   billToAddressTwoValid: true   billToCityValid: true   billToCountryValid: true   billToPostalValid: true   billToStateValid: true   cardExpirationValid: true   cardHolderNameValid: true   cardNumberValid: false   cardSecurityCodeValid: false   cardTypeValid: false   isFormValid: false } |
loaded |
All | The iframe has finished loading | eventName: loaded {} |
initiate |
APMs | The user clicks 'confirm' to be redirected to the APM | eventName: initiate {   message: ‘user initiated 3ds’ } |
processed |
Run Card Transaction | The credit card transaction has been processed | |
submit |
All | The form has been submitted | eventName: submit { Â Â "cardHolderName": "Default Test", Â Â "customer": { Â Â Â Â "billToCity": "Testerville", Â Â Â Â "billToState": "UT", Â Â Â Â "billToCountry": "US", Â Â Â Â "billToAddressTwo": "Suite 123", Â Â Â Â "billToAddressOne": "123 Test St", Â Â Â Â "billToPostal": "12345" Â Â } } |
success |
Retail Run Card Transaction | The credit card transaction has been processed |
Event Listener Example
The following is an example of how to create an event listener.
This listener is checking that the iframe has finished loading and that the entire form has been validated. You could use something like this to make your submit button inactive so that users cannot click on it until the form errors are corrected.
window.addEventListener('message', function messageListener(event) {
if (event.origin === iframeUrl) {
const eventData = event.data?.data;
const eventType = event.data?.event;
if (eventType === ‘loaded’) {
// iframe successfully loaded.
}
if (eventType === ‘formValidations’) {
const jsonData = JSON.parse(eventData);
if (jsonData.isFormValid) {
// form is ready to submit.
}
}
// switch on event.data properties
// (e.g. loaded, formValidations, error)
}
});
Constant Values
When querying transaction data, the following numerical values are returned which represent the corresponding constant value.
Transaction Status (transactionStatus
)
The tables below describe the transaction statuses for card and e-check transactions.
Please note that:
- The
transactionStatus
returned by the Payment Service, including the Alternative Payment Service, will be a string - The
transactionStatus
returned by the Transaction Service will be an integer
Card Transaction Status
Status | Description | Nexio Dashboard Status | Transaction Service transactionStatus |
Payment Service transactionStatus |
---|---|---|---|---|
Auth Only Pending | The payment is asynchronous and may receive a webhook notice with a status of authOnly in the future |
AUTHONLYPENDING | 3 | authOnlyPending |
Authorized Pending | The payment is asynchronous. The payment is pending and may receive a webhook notice with status of settled in the future |
AUTHORIZEDPENDING | 9 | authorizedPending |
Authorized | The transaction has been successfully authorized and is pending settlement | AUTHORIZED | 10 | pending |
Auth Only | The payment is Auth Only and capturing is required to receive the funds. The transaction can also be voided | AUTHONLY | 11 | authOnly |
Declined | The transaction was declined | DECLINED | 30 | declined |
Fraud Reject | The transaction was declined by Kount prior to being submitted to the gateway | FRAUDREJECT | 32 | fraudReject |
Settled | The transaction is settled. It can be refunded but not voided | SETTLED | 20 | settled |
Void Pending | The payment is asynchronous and may receive a webhook notice with a status of voided in the future |
VOIDPENDING | 39 | voidPending |
Voided | The payment has been voided | VOIDED | 40 | voided |
Error | An error has occurred | ERROR | 50 | error |
E-check Transaction Status
Status | Description | Nexio Dashboard Status | Transaction Service transactionStatus |
Payment Service transactionStatus |
---|---|---|---|---|
Pending | The transaction is pending | PENDING | 12 | pending |
Settled | The transaction is settled | SETTLED | 20 | settled |
Submitted | The payment was submitted to the bank for authorization | SUBMITTED | 13 | submitted |
Rejected | The transaction was rejected | REJECTED | 33 | rejected |
Transaction Type (transactionType
)
Name | Value |
---|---|
Sale | 10 |
Refund | 20 |
Card Type (cardType
)
Name | Value |
---|---|
Visa | 10 |
MasterCard | 20 |
Discover | 30 |
American Express | 40 |
Unknown | null |
Process Method (processMethod
)
Name | Value |
---|---|
Card | 10 |
Card Present | 11 |
Card Not Present | 12 |
APM (Alternative Payment Method) | 20 |
E-check | 40 |
Credit | 50 |
Cash | 60 |
Currency (currency
)
Name | Value |
---|---|
Australian Dollar | 036 |
Canadian Dollar | 124 |
Yuan | 156 |
Yen | 392 |
Won | 410 |
Mexican Peso | 484 |
Pound Sterling | 826 |
US Dollar | 840 |
Euro | 978 |
ACH
For e-check transactions, the following values are used.
Standard Entry Class code (secCode
)
The Standard Entry Class (SEC) code (secCode
) is for e-check transactions. These values can be sent in the following requests as the data.secCode
parameter:
- One-time-use Token (for the Run E-check Transaction Iframe)
- Run E-check Transaction
The following table displays the commonly used codes. Contact your e-check processor for the codes that you can use for your account.
secCode | Description |
---|---|
ARC | Accounts Receivable Entry |
BOC | Back Office Conversion |
CCD | Corporate Credit or Debit |
CIE | Customer-Initiated Entry |
CTX | Corporate Trade Exchange |
IAT | International ACH Transaction |
POP | Point-of-Purchase Entry |
POS | Point-of-Sale |
PPD | Prearranged Payment and Deposit |
RCK | Re-presented Check Entry |
TEL | Telephone-Initiated Entry |
WEB | Internet-Initiated/Mobile Entry |
XCK | Destroyed Check Entry |
Payouts
When querying payouts data, the following numerical values are returned which represent the corresponding constant value.
Payout Status (payoutStatus
)
The following table displays the commonly used codes for the payout status.
payoutStatus | Status Name | Description |
---|---|---|
10 | pendingProviderAction | The payout request is being processed by the provider. No further action is required at this time. |
11 | pendingMerchantAction | The payout request is pending until the merchant takes action. |
12 | pendingRecipientAction | The payout request is pending until the recipient takes action. |
20 | completed | The payout request has been completed. Funds are available for the recipient. No further action is required. |
30 | expired | The payout request has expired. The payout is no longer available for the recipient. |
40 | canceled | The payout request has been canceled. The payout is no longer available for the recipient. |
50 | returned | The payout request has failed, most commonly due to rejection by the recipient’s bank. The payout is no longer available for the recipient. |
90 | failed | The payout request has failed. For more details about what failed, see the providerResponse parameter in the API response. |
Transfer Status (transferStatus
)
The following table displays the commonly used codes for the transfer status.
transferStatus | Status Name | Description |
---|---|---|
10 | available | Payout money has been transferred. No further action is required at this time. |
20 | completed | The recipient has claimed available funds. Note: This status is not available for all payout providers. |
90 | failed | An error occurred during the transfer. |
Test Cards
Test transactions can be submitted using the following card numbers:
Issuer | Number |
---|---|
Visa | 4111111111111111 |
Mastercard | 5431111111111111 |
Discover | 6011601160116611 |
American Express | 341111111111111 |
Release Notes
2020
June 9, 2020
- Update to the
token
object in the response of the Save Card Token API endpoint. Thetoken
object will always include the following keys. (Previously, some keys were not included in the response unless provided in the request):firstSix
lastFour
token
success
sesssionId
customerReferenceNumber
April 22, 2020
- New Processing Option available:
shouldUseFingerprint
(default:true
). Allows you to enable or disable the use of the saved fingerprint while processing a transaction. Check out theprocessingOptions
object in the Parameters table of the Run Card Transaction API reference section for a full description.
March 25, 2020
- Express APM now available.
March 24, 2020
- Option to dynamically change the descriptor that shows up on the customer's credit card statement is now available.
To do so, include the parameter
data.descriptor
in the body of your request for a one-time-use token or when you run a card transaction directly through the API. - New
hidePhone
UI Option for the Run E-check Transaction Iframe. To use, include the following parameter in the body of your request for a One-time-use Token.
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
- Now accepting Paynet as an alternative payment method.
September 11, 2019
-
All transaction endpoints now accepting
billToPhone
andshipToPhone
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 nowdata.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 accepttrue
andfalse
if you wish to hide all billing fields. (Default continues to befalse
)"
May 22, 2019
- Webhook events
TRANSACTION_AUTHORIZED
andTRANSACTION_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.
- If the saved expiration date is better than the provided expiration date:
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
tofalse
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.)
- To do so, set
- 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 yourGET
request.
- To use this option, send
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
- Customer created at date (
November 7, 2018
- New processing option allows users to choose which merchant to use to process a transaction.
October 10, 2018
- AVS results (
avsResults
) returned in response object. - EnsureBill account updater now available.
- Nexio Dashboard:
- Merchant ID selector filtering: you may now filter merchants by name, merchant ID, and currency code.
October 3, 2018
- Address Verification Service (AVS) now enabled.
- Nexio Dashboard:
- Chargeback widget added.
- Currency selector changes all charts and widgets.
- Column filtering on tables can now search for partial amounts.
- Merchant ID selector widens to fit merchant name.
- Now importing Customer ID from Gateway responses.
- Chargeback page now shows Cardholder Name when linked to a transaction.
September 26, 2018
- Additional Authorize.Net features now available in Nexio Dashboard: ability to void transactions, approve or decline auth only transactions, and refund settled transactions.
- Processor Management: Clients with multiple merchants can now choose which merchants to process with, or to balance their processing equally across all merchants. This feature works by checking each merchant's processing volume at the time of the transaction and then running the transaction against whichever merchant has less volume.
- Nexio Dashboard:
- Merchant ID selector now accommodates long merchant names.
- Merchant ID selector now lists merchant names alphabetically.
- New widgets: Transactions, Salesf, Approvals & Declines.
September 12, 2018
- Gateway Failover: Merchants set up with more than one gateway are now able to choose a backup gateway in case of primary gateway failure
- Option to limit country list in the Make Payment and Save Card iframes
- Option to choose default country in the Make Payment and Save Card iframes
- Nexio Dashboard:
- New Reserve Tab for merchants with a reserve account
September 5, 2018
- Integration with Authorize.Net
- Refund disabled on transactions with pending chargeback
August 22, 2018
- Added Order ID to Refunds in the Transactions Tab of Nexio
- Added the ability to delete tokens in the API
July 16, 2018
- Fixed bug where View Only users were able to run transactions. This functionality is now limited to Admin and Standard users
Supported Browsers
In order to provide the best user experience, we test our payment iframes on the following browsers:
- Chrome
- Edge
- Firefox
- Safari 12
- Internet Explorer 11
If you are having a browser-related issue, please contact integration support.
Filtering Results and Including Additional Parameters for an API Request
Some Nexio API endpoints allow the use of query parameters as a way to filter (or limit) the results returned from the request. You can also use query parameters to request that those specific parameters be included in the response.
The following APIs allow filtering and additional parameters with certain endpoints:
Using Query Parameters
When searching for report data or payouts data, you may request additional parameters to be returned. This is useful for parameters that are not returned by default. You can also filter the response to only include records that match a specific value for one or more parameters.
You may request additional parameters or filter the results for any of the following API endpoints:
- Transactions (Reporting)
- Chargebacks (Reporting)
- Statements and Adjustments (Reporting)
- View Recipients (Payouts)
- View Payouts (Payouts)
Request Additional Parameters
The response for the reporting APIs (for transactions, chargebacks, and statements and adjustments) and payouts APIs (for view recipients and view payouts) returns a default set of parameters. For example, transactionDate
and cardType
in the reporting API or recipientIdNumbers
in the payouts API. For a full list of parameters, see the specific endpoint in the Reporting API Reference or Payouts API Reference.
You can also specify in the request that the system returns one or more additional parameters in the response. To do this, you only need to include, in the GET
request, the name of the query parameter followed by a dot. When you use a parameter from one of these as a filter, the entire object automatically gets included in the response. Combine multiple additional parameters by including an ampersand (&) between each one.
For example, the following Reporting request returns only the default parameters for up to 20 transactions:
Transaction List with Filter
curl -X GET https://api.nexiopaysandbox.com/transaction/v3?limit=20 \
-H 'Accept: application/json' \
-H 'Authorization: Basic <Your Basic Auth>'
To request an additional parameter, include an empty query parameter in your GET
request followed by a dot.
For example, the following returns a standard list of up to 20 transactions along with the customer object for each one:
Transaction List with Filter and Customer Object
curl -X GET https://api.nexiopaysandbox.com/transaction/v3?limit=20&customer. \
-H 'Accept: application/json' \
-H 'Authorization: Basic <Your Basic Auth>'
Now, the same request for the same 20 transactions with the default parameters, but also requesting that the response include additional information about Kount, our payment plugins, customer, processor, and gateway:
Transaction List with Filter and Additional Parameters
curl -X GET https://api.nexiopaysandbox.com/transaction/v3?limit=20&kount.&plugin.&customer.&processor.&gateway. \
-H 'Accept: application/json' \
-H 'Authorization: Basic <Your Basic Auth>'
For the list of additional parameters, see the Transactions Filtering and Additional Parameters and Payouts Filtering and Additional Parameters tables.
Filter Using Query Parameters
Path parameters that you include in a regular endpoint request already act like a filter for the response. But, for the Reporting endpoints of Transactions, Chargebacks, and Statements and Adjustments and the Payouts endpoints of View Recipients and View Payouts, there is an additional method for creating a filter, using query parameters.
For these endpoints in the Reporting or Payouts API, you can also filter query parameters by specifying the desired parameter to filter on, an equals ( = ) sign, and the value to use for the filter. For parameters in an object, use the object name, a dot, and the parameter name before the equals. You can combine multiple filters by including an ampersand (&) between each one.
Use this feature, along with requesting additional parameters, to limit the scope of the response and to get back the specific parameters that you want.
For example, the following request returns all transactions (made in the Nexio Payment API) for the specified zip code where the gateway status is 'Approved' and where the response includes all the default parameters plus the content for the customer
and gateway
objects.
Transaction List with Additional Filters
curl -X GET https://api.nexiopaysandbox.com/transaction/v3?customer.postalCode=12345&gateway.message=Approved \
-H 'Accept: application/json' \
-H 'Authorization: Basic <Your Basic Auth>'
As another example, the following searches for a transaction made in the Nexio Payment API with the to-be-specified payment ID, and also includes its Kount information in the results.
Transaction List with Additional Filters
curl -X GET https://api.nexiopaysandbox.com/transaction/v3?kount.&plugin.originalId={payment_ID} \
-H 'Accept: application/json' \
-H 'Authorization: Basic <Your Basic Auth>'
Reference Tables
The following tables show all the fields that you can use for filtering with the additional query parameters. (The default fields can also be used for filtering. See the API reference documentation for each endpoint for details).
Transactions Filtering and Additional Parameters
For information about each field, see the specific endpoint in the Reporting API Reference.
Name | Additional Parameter | Filtering Field |
---|---|---|
Customer | customer. |
id firstName lastName postalCode phone email company customerRef transactionId |
Kount | kount. |
id status rules refNumber merc score ruleCount warningCount counterCount wasDeviceFingerprinted mode velo vmax transactionId |
Bank Transfer | bankTransfer. |
id account routing checkNumber transactionId |
Plugin | plugin. |
id originalId invoice orderNumber description userId pluginType paymentOptionTag transactionId |
Foreign Processing Currency | foreignProcessingCurrency. |
id amount currencyId transactionId |
Gateway | gateway. |
id merchantId batchRef refNumber additionalRefNumber trackingCode gatewayType message transactionId |
Processor | processor. |
id transactionRef batchRef originalId processorType transactionId |
Customer Addresses | customerAddresses. |
id billingAddressOne billingAddressTwo billingCity billingState billingPostalCode billingCountry billingPhone shippingAddressOne shippingAddressTwo shippingCity shippingState shippingPostalCode shippingCountry shippingPhone transactionId |
Transaction Details | transactionDetails. |
id description clientIp userName shoppingCart customFields retryCount paymentType paymentToken transactionId |
Subscription | subscription. |
id remainingBalance initialBalance interval intervalCount subscriptionRef accountId scheduleType transactionId |
Payouts Filtering and Additional Parameters
For information about each field, see the specific endpoint in the Payouts API Reference.
Name | Additional Parameter | Filtering Field |
---|---|---|
Recipient ID Numbers | recipientIdNumbers. |
governmentId passportId driversLicenseId employerIId |
Find a Transaction
To query for a transaction created through the Nexio Payment iframe or API, follow the steps below:
- Run a payment using the Run Card Transaction iframe or the Nexio Payment API.
Example 200 Response
{
"amount": 34.25,
"authCode": "035410",
"card": {...},
"currency": "USD",
"data": {...},
"gatewayResponse": {...},
"id": "eyJuYW1lIjoidXNhZXBheSIsInJlZk51bWJlciI6IjMxMDA5MDc4MTkiLCJtZXJjaGFudElkIjoiMTAwMDM5IiwicmFuZG9tIjoiMzEwMDkwNzgxOSIsImN1cnJlbmN5IjoiVVNEIn0=",
"kountResponse": {...},
"merchantId": "100039",
"token": {...},
"transactionDate": "2019-01-15T13:19:39.329Z",
"transactionStatus": "pending",
"transactionType": "sale"
}
-
Save the
id
from the response. This is the Payment ID. -
Use the Payment ID to query the transaction service.
Example Request
curl -X GET https://api.nexiopaysandbox.com/transaction/v3?plugin.originalId=eyJuYW1lIjoidXNhZXBheSIsInJlZk51bWJlciI6IjMxMDA5MDc4MTkiLCJtZXJjaGFudElkIjoiMTAwMDM5IiwicmFuZG9tIjoiMzEwMDkwNzgxOSIsImN1cnJlbmN5IjoiVVNEIn0 \
-H 'Accept: application/json' \
-H 'Authorization: Basic <Your Basic Auth>'
You may also request to have additional query parameters returned or filter the request based on fields of the query parameters.
Note: Transactions from the Payment Service are added to the Transaction Service every minute and not in real time. Attempting to query the Transaction Service sooner than one minute after running a transaction may return no results.
Webhooks
Configure webhooks to retrieve real-time information about payment events.
When webhooks are set up, Nexio will send a POST
request with event information to the specified endpoint.
You may also choose to receive a signature header—allowing you to verify the webhook's authenticity.
Configure Webhooks
To configure webhooks for a merchant, follow the steps below:
-
Check Your Merchant's Role (Optional)
In order to configure webhooks for a merchant you must have administrator access to that merchant account. If you know that your user has sufficient rights, skip to step 2.
To check your account's access rights, send a request to the Who Am I endpoint in the User Management Service. In the example below, the user has authorization to configure webhooks for merchant ID 100039 only.
Example Access Rights
{
"accessRights": {
"merchantIds": {
"100039": "A", // Admin access
"100040": "W", // Write access
"100068": "R" // Read-only access
},
"role": "A"
}
}
-
Determine the Event Types
See our Event Types table below and note the event types you would like to trigger a webhook.
-
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"
}
}
}'
-
Check the Webhook's Configuration (Optional)
To check the webhook configuration you completed in step 4, send a
GET
request to the Merchant Configuration endpoint.
Example Request
curl -X GET https://api.nexiopaysandbox.com/webhook/v3/config/100039 \
-H 'Accept: application/json' \
-H 'Authorization: Basic <Your Basic Auth>'
Example 200 Response
{
"dateCreated": "2019-03-22T16:58:51.957Z",
"webhooks": {
"TRANSACTION_AUTHORIZED": {
"url": "https://your-company-webhook-url-here.com"
},
"TRANSACTION_CAPTURED": {
"url": "https://your-company-webhook-url-here.com"
}
},
"merchantName": "My Company",
"dateLastModified": "2019-04-04T18:54:58.011Z",
"merchantId": "100039"
}
-
Configure the Merchant Secret (Optional)
For additional security you may set up a merchant secret. When configured, you will be provided with a merchant secret and each webhook will include a header containing a signature. These can be used to verify that all data received is authentic.
To configure the merchant secret, send a
POST
request to the Create Merchant Secret endpoint. Include the merchant ID to be configured in the body of your request.
Example Request
curl -X POST https://api.nexiopaysandbox.com/webhook/v3/secret \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Basic <Your Basic Auth>'
-d '{
"merchantId": "100039"
}'
A successful request will return a response object containing the merchant secret.
Store the secret
in a secure location.
You will use it later for signature verification.
Example Merchant Secret
{
"secret": "446946d5-bdd9-48c7-9504-0459d19c08e5"
}
Once you have configured the merchant secret, each webhook will include a signature header.
Event Types
Below are the possible values for webhook event types.
Event Type | Description | Example Webhook Body |
---|---|---|
ACCOUNT_UPDATER_ACCOUNT_CLOSED |
Webhook will be sent when the account associated with the card has been closed | Account Closed Example |
ACCOUNT_UPDATER_CONTACT_CARDHOLDER |
Webhook will be sent when the card brand advises you to contact the cardholder | Contact Cardholder Example |
CARD_DATA_UPDATED |
Webhook will be sent when card data has been updated | Card Updated Example |
CARD_SAVED |
Webhook will be sent when card data has been saved | Card Saved Example |
ECHECK_SAVED |
Webhook will be sent when e-check data has been saved | E-check Saved Example |
PAYOUT |
Webhook will be sent when a recipient has accepted a payout through the Interchecks payout provider. For information about payout events with other payout providers, contact Integrations Support. | Payout Event Example |
SUBSCRIPTION_DETAILS |
Webhook will be sent when a subscription has been processed | Subscription Example |
TRANSACTION_AUTHORIZED |
Webhook will be sent when a transaction is authorized | Transaction Event Example |
TRANSACTION_CAPTURED |
Webhook will be sent when a transaction is captured | Transaction Event Example |
TRANSACTION_PENDING |
Webhook will be sent when a transaction is marked as pending | Transaction Event Example |
TRANSACTION_REFUNDED |
Webhook will be sent when a transaction is refunded | Transaction Event Example |
TRANSACTION_SETTLED |
Webhook will be sent when a transaction is settled | Transaction Event Example |
TRANSACTION_VOIDED |
Webhook will be sent when a transaction is voided | Transaction Event Example |
Receive Webhooks
Once you have configured webhooks,
listen for Nexio's POST
requests on the URL you provided in step 3 of the Configure Webhooks tutorial.
The body of the request will include the eventType
and a data
object, with information about the event.
See the webhook body examples for more information.
If you configured the merchant secret (step 5 of the Configure Webhooks tutorial), the request will include a header, which you will use to to verify the merchant signature.
See the tutorial below for instructions.
Verify the Signature
-
Listen for Nexio's POST Request
-
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';
-
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": {...}
}
}';
-
Create the Payload
Concatenate timestamp and body with a . character in between and save it as a variable.
Example
var payload = ${timestamp}.${body};
-
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 aGET
request to Nexio's merchant secret endpoint. -
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 valuesdata
: (object) Information about the event
Transaction Events
The data
object will be shaped the same for any transaction event.
To see full examples of the values contained in the data
object,
see the example 200 response in the Run Card Transaction reference section.
Transaction Event Example Body
{
"eventType": "TRANSACTION_CAPTURED",
"data": {
"id": "2eruYW1lIjoidXNhZXBheSIZYXABCiOiIxMDAwMzkiLCJyZWZOdW1iZXIiOiZYXABCcmFuZG9tIjowLCJjdXJyZW5jeSI6InVzZCJ9",
"shouldUpdateCard": true,
"merchantId": "100039",
"transactionDate": "2019-12-23T20:50:23.060Z",
"authCode": "458399",
"transactionStatus": "pending",
"amount": 1.15,
"transactionType": "sale",
"currency": "USD",
"gatewayResponse": {...},
"data": {
"amount": 1.15,
"currency": "USD",
"settlementCurrency": "USD",
"customFields": {...},
"customer": {...},
"cart": {...},
"lodging": {...}
},
"card": {...},
"kountResponse": {...},
"token": {...}
}
}
Card Events
Account Closed
Account Closed Example Body
{
"eventType": "ACCOUNT_UPDATER_ACCOUNT_CLOSED",
"data": {
"updateCode": "203",
"reportDate": "2021-09-09T16:44:41.000Z",
"merchantId": "101039",
"originalCard": {
"lastFour": "2223",
"firstSix": "400060"
},
"tokenex": {
"lastFour": "2223",
"token": "192b8c0f-ef3a-4e13-8465-2b41971db046",
"firstSix": "400060"
},
"card": {
"expirationYear": "02",
"expirationMonth": "02"
},
"cardNumber": "400060******2223",
"updateType": 30
}
}
Card Updated
To see full examples of the values contained in the data
object,
see the example 200 response in the Save Card Token reference section.
The following example shows that the expiration date has been updated.
Card Saved Example 1 Body
{
"eventType": "CARD_DATA_UPDATED",
"data": {
"updateCode": "201",
"reportDate": "2021-09-09T16:12:32.000Z",
"merchantId": "101039",
"originalCard": {
"lastFour": "2222",
"firstSix": "400020"
},
"tokenex": {
"lastFour": "2222",
"token": "ac719225-cb55-4605-a673-8f0ccb822c4c",
"firstSix": "400020"
},
"card": {
"expirationYear": "2033",
"expirationMonth": "02"
},
"cardNumber": "400020******2222",
"updateType": 20
}
}
The following example shows that both the expiration date and the card number have been updated.
Card Saved Example 2 Body
{
"eventType": "CARD_DATA_UPDATED",
"data": {
"updateCode": "202",
"reportDate": "2021-09-09T16:44:41.000Z",
"merchantId": "101039",
"originalCard": {
"lastFour": "2224",
"firstSix": "400010"
},
"tokenex": {
"lastFour": "2229",
"token": "7f657119-a7e6-47cb-a0b5-153db253512a",
"firstSix": "400010"
},
"card": {
"expirationYear": "2033",
"expirationMonth": "02"
},
"cardNumber": "400010******2229",
"updateType": 10
}
}
Card Saved
To see full examples of the values contained in the data
object,
see the example 200 response in the Save Card Token reference section.
Card Saved Example Body
{
"eventType": "CARD_SAVED",
"data": {
"data": {
"customer": {...}
},
"merchantId": "101040",
"shouldUpdateCard": true,
"cardType": "masterCard",
"kountResponse": {...},
"card": {
"expirationYear": "2021",
"cardType": "masterCard",
"expirationMonth": "10",
"cardHolderName": "Jane Doe"
},
"token": {
"lastFour": "5100",
"cardType": "masterCard",
"firstSix": "510510",
"token": "b01bfaee-31b2-4222-8d89-24d1a42fd50e"
}
}
}
Contact Cardholder
Contact Cardholder Example Body
{
"eventType": "ACCOUNT_UPDATER_CONTACT_CARDHOLDER",
"data": {
"updateCode": "204",
"reportDate": "2021-09-09T16:46:41.000Z",
"merchantId": "101039",
"originalCard": {
"lastFour": "2221",
"firstSix": "400070"
},
"tokenex": {
"lastFour": "2221",
"token": "269c3057-4f7d-47a2-80cd-3196f803631e",
"firstSix": "400070"
},
"card": {
"expirationYear": "02",
"expirationMonth": "02"
},
"cardNumber": "400070******2221",
"updateType": 40
}
}
E-check Events
E-check Saved
To see full examples of the values contained in the data
object,
see the example 200 response in the Save E-check Token reference section.
E-check Saved Example Body
{
"eventType": "ECHECK_SAVED",
"data": {
"data": {
"key": "871446789.5292712865664733",
"merchantId": "100039",
"data": {
"customer": {...},
"customFields": {...}
},
"tokenex": {
"success": true,
"error": null,
"token": "871446789",
"sesssionID": "fca21ef9067d4f009e58e302dbc115a4",
"customerRefNumber": "b210bad6-a013-4e91-b5bf-0",
"characterCount": 9,
"lastFour": "6789"
},
"dateCreated": "2019-12-30T18:06:15.188Z",
"dateLastModified": "2019-12-30T18:06:15.193Z",
"bank": {
"accountHolderName": "Todd Smitherton",
"routingNumber": "123456789"
}
}
}
}
Payout Event
After configuring webhooks for payouts, a webhook will be sent every time a recipient accepts your payout to them through the Interchecks payout provider. For information about payout events with other payout providers, contact Integrations Support.
After the recipient accepts the payout, the data.transferStatus
changes to 20
.
For more information about the parameters returned in the data
object, see the specific Response parameters in the View a payout or View payouts endpoint.
Note: For payouts, the body of the webhook contains only a small subset of the possible parameters for a payout. To view the values for all the available parameters, use the View a payout or View payouts endpoint.
Payout Example Body
{
"eventType": "PAYOUT",
"data": {
"payoutStatus": 20,
"eventType": "PAYOUT",
"transferStatus": 20,
"payoutId": 2437652
}
}
Subscription Event
Once configured, webhooks will be sent every time a recurring payment is run through the subscription service. You will also receive webhooks for all transaction events that have previously been configured.
To see full examples of the values contained in the data.paymentResult
object,
see the example 200 response in the Run Card Transaction
or Run E-check Transaction reference section.
The payment
object will contain the values provided when the subscription was created.
Subscription Example Body
{
"eventType": "SUBSCRIPTION_DETAILS",
"data": {
"dateCreated": "2020-09-21T17:27:46.836Z",
"accountId": "6862a4dc-490e-4eec-9a23-a3fec25979b6",
"customerRef": "metest2",
"paymentResult": {
"id": "eyJuYW1lIjoidXNhZXBheSIsIm1lcmNoYW50SWQiOiIxMDEwMzkiLCJyZWZOdW1iZXIiOiIzMTEzMjc5MDI0IiwicmFuZG9tIjowLCJjdXJyZW5jeSI6InVzZCJ9",
"merchantId": "101039",
"transactionDate": "2020-09-21T17:31:49.680Z",
"authCode": "026252",
"transactionStatus": "pending",
"amount": 10,
"transactionType": "sale",
"currency": "USD",
"gatewayResponse": {...},
"data": {
"amount": 10,
"currency": "USD",
"settlementCurrency": "USD",
"customer": {...},
"cart": {...}
},
"card": {...},
"kountResponse": {...},
"token": {...}
},
"dateLastModified": "2020-09-21T17:32:11.016Z",
"userName": "kkacprzynski@cmsonline.com",
"dateNextRun": "2020-10-21",
"active": true,
"schedule": {
"duration": 5,
"dateInitialBillingEnd": "2020-09-21",
"initialBillingAmount": null,
"balance": 30,
"scheduleType": 20,
"intervalCount": 1,
"initialBalance": 50,
"interval": "month"
},
"lastPaymentStatus": "success",
"dateLastRun": "2020-09-21T17:31:28.699Z",
"payment": {
"data": {
"amount": 10,
"currency": "USD",
"cart": {...},
"customer": {...}
},
"tokenex": {...},
"isProcessedFromServer": true,
"clientIp": "10.0.0.1"
},
"id": "cdd9d4b2-bf86-445b-8b54-59861a9ad3ae",
"accessRights": {
"merchantIds": {
"101039": "A"
}
}
}
}
Full API Reference
Payments API Reference
E-commerce
One-time-use Token
Example request
curl -X POST https://api.nexiopaysandbox.com/pay/v3/token \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Basic <Your Basic Auth>'
-d '{
"card": {
"businessNumber": "1234567890",
"cardHolderName": "John H Doe",
"classification": "business",
"expirationMonth": "12",
"expirationYear": "20",
"password": "12"
},
"data": {
"allowedCardTypes": [
"visa"
],
"currency": "USD",
"customer": {
"billToAddressOne": "2147 West Silverlake Drive",
"billToAddressTwo": "Apt 42",
"billToCity": "Scranton",
"billToCountry": "US",
"billToPhone": "1555555555",
"billToPostal": "18503",
"billToState": "PA",
"birthDate": "1990-12-05",
"createdAtDate": "2005-03-01",
"customerRef": "RP006",
"email": "jdoe@yourwebsite.com",
"firstName": "John",
"invoice": "IN0001",
"lastName": "Doe",
"orderDate": "2021-08-26",
"orderNumber": "210058A",
"phone": "1555555555",
"shipToAddressOne": "1725 Slough Avenue",
"shipToAddressTwo": "Suite 200",
"shipToCity": "Scranton",
"shipToCountry": "US",
"shipToPhone": "1555555555",
"shipToPostal": "18505",
"shipToState": "PA"
},
"customFields": {
"exampleKey": "Example string"
}
},
"processingOptions": {
"checkFraud": false,
"verboseResponse": true,
"verifyAvs": 2,
"verifyCvc": false,
"webhookFailUrl": "https://your-company-webhook-fail-url-here.com",
"webhookUrl": "https://your-company-webhook-url-here.com"
},
"shouldUpdateCard": true,
"uiOptions": {
"css": "https://tester.nexiopaysandbox.com/example1.css",
"customTextUrl": "",
"displaySubmitButton": true,
"hideBilling": {
"hideAddressOne": false,
"hideAddressTwo": false,
"hideCity": false,
"hideCountry": false,
"hidePostal": false,
"hidePhone": false,
"hideState": false
},
"hideCvc": true,
"limitCountriesTo": [
"US"
],
"requireCvc": false
}
}'
curl -X POST https://api.nexiopaysandbox.com/pay/v3/token \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Basic <Your Basic Auth>'
-d '{
"bank": {
"accountHolderName": "John Doe",
"routingNumber": "231375151"
},
"data": {
"customer": {
"billToAddressOne": "2147 West Silverlake Drive",
"billToAddressTwo": "Apt 42",
"billToCity": "Scranton",
"billToCountry": "US",
"billToPhone": "1555555555",
"billToPostal": "18503",
"billToState": "PA",
"birthDate": "1990-12-05",
"createdAtDate": "2005-03-01",
"customerRef": "RP006",
"email": "jdoe@yourwebsite.com",
"firstName": "John",
"invoice": "IN0001",
"lastName": "Doe",
"orderDate": "2021-08-26",
"orderNumber": "210058A",
"phone": "1555555555",
"shipToAddressOne": "1725 Slough Avenue",
"shipToAddressTwo": "Suite 200",
"shipToCity": "Scranton",
"shipToCountry": "US",
"shipToPhone": "1555555555",
"shipToPostal": "18505",
"shipToState": "PA"
},
"customFields": {
"exampleKey": "Example string"
}
},
"processingOptions": {
"verboseResponse": true,
"webhookFailUrl": "https://your-company-webhook-fail-url-here.com",
"webhookUrl": "https://your-company-webhook-url-here.com"
},
"uiOptions": {
"css": "https://tester.nexiopaysandbox.com/example1.css",
"customTextUrl": "",
"displaySubmitButton": true,
"hideBilling": {
"hideAddressOne": false,
"hideAddressTwo": false,
"hideCity": false,
"hideCountry": false,
"hidePostal": false,
"hidePhone": false,
"hideState": false
},
"hideCvc": true,
"limitCountriesTo": [
"US"
],
"requireCvc": false
}
}'
curl -X POST https://api.nexiopaysandbox.com/pay/v3/token \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Basic <Your Basic Auth>'
-d '{
"data": {
"amount": 29.99,
"currency": "USD",
"allowedCardTypes": [
"visa"
],
"cart": {
"items": [
{
"item": "913261",
"description": "Hammermill Premium 8.5 x 11 Color Copy Paper, 28 lbs. 500/Ream",
"quantity": 8,
"price": 16.49,
"type": "sale"
}
]
},
"customer": {
"billToAddressOne": "2147 West Silverlake Drive",
"billToAddressTwo": "Apt 42",
"billToCity": "Scranton",
"billToCountry": "US",
"billToPhone": "1555555555",
"billToPostal": "18503",
"billToState": "PA",
"birthDate": "1990-12-05",
"createdAtDate": "2005-03-01",
"customerRef": "RP006",
"email": "jdoe@yourwebsite.com",
"firstName": "John",
"invoice": "IN0001",
"lastName": "Doe",
"orderDate": "2021-08-26",
"orderNumber": "210058A",
"phone": "1555555555",
"shipToAddressOne": "1725 Slough Avenue",
"shipToAddressTwo": "Suite 200",
"shipToCity": "Scranton",
"shipToCountry": "US",
"shipToPhone": "1555555555",
"shipToPostal": "18505",
"shipToState": "PA"
},
"customFields": {
"exampleKey": "Example string"
},
"description": "test purchase",
"descriptor": "",
"lodging": {
"advanceDeposit": true,
"checkInDate": "2018-12-31",
"checkOutDate": "2019-01-05",
"noShow": false,
"roomNumber": 14,
"roomRate": 143.99
}
},
"card": {
"businessNumber": "1234567890",
"cardHolderName": "John H Doe",
"classification": "business",
"expirationMonth": "12",
"expirationYear": "20",
"password": "12"
},
"installment": {
"period": 10
},
"isAuthOnly": false,
"processingOptions": {
"checkFraud": false,
"customerRedirectUrl": "https://your-ecommerce-website.example.com",
"merchantId": "100039",
"paymentOptionTag": "switch",
"saveCardToken": true,
"shouldUseFingerprint": true,
"verboseResponse": true,
"webhookFailUrl": "https://your-company-webhook-fail-url-here.com",
"webhookUrl": "https://your-company-webhook-url-here.com"
},
"uiOptions": {
"css": "https://tester.nexiopaysandbox.com/example1.css",
"customTextUrl": "",
"displaySubmitButton": true,
"hideBilling": {
"hideAddressOne": false,
"hideAddressTwo": false,
"hideCity": false,
"hideCountry": false,
"hidePostal": false,
"hidePhone": false,
"hideState": false
},
"hideCvc": true,
"limitCountriesTo": [
"US"
],
"requireCvc": false
}
}'
curl -X POST https://api.nexiopaysandbox.com/pay/v3/token \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Basic <Your Basic Auth>'
-d '{
"data": {
"amount": 29.99,
"currency": "USD",
"cart": {
"items": [
{
"item": "913261",
"description": "Hammermill Premium 8.5 x 11 Color Copy Paper, 28 lbs. 500/Ream",
"quantity": 8,
"price": 16.49,
"type": "sale"
}
]
},
"customer": {
"billToAddressOne": "2147 West Silverlake Drive",
"billToAddressTwo": "Apt 42",
"billToCity": "Scranton",
"billToCountry": "US",
"billToPhone": "1555555555",
"billToPostal": "18503",
"billToState": "PA",
"birthDate": "1990-12-05",
"createdAtDate": "2005-03-01",
"customerRef": "RP006",
"email": "jdoe@yourwebsite.com",
"firstName": "John",
"invoice": "IN0001",
"lastName": "Doe",
"orderDate": "2021-08-26",
"orderNumber": "210058A",
"phone": "1555555555",
"shipToAddressOne": "1725 Slough Avenue",
"shipToAddressTwo": "Suite 200",
"shipToCity": "Scranton",
"shipToCountry": "US",
"shipToPhone": "1555555555",
"shipToPostal": "18505",
"shipToState": "PA"
},
"customFields": {
"exampleKey": "Example string"
},
"description": "test purchase",
"descriptor": "",
"secCode": "IAT"
},
"bank": {
"accountHolderName": "John Doe",
"routingNumber": "231375151"
},
"processingOptions": {
"merchantId": "100039",
"verboseResponse": true,
"webhookFailUrl": "https://your-company-webhook-fail-url-here.com",
"webhookUrl": "https://your-company-webhook-url-here.com"
},
"uiOptions": {
"css": "https://tester.nexiopaysandbox.com/example1.css",
"customTextUrl": "",
"displaySubmitButton": true,
"hideBilling": {
"hideAddressOne": false,
"hideAddressTwo": false,
"hideCity": false,
"hideCountry": false,
"hidePostal": false,
"hidePhone": false,
"hideState": false
},
"hideCvc": true,
"limitCountriesTo": [
"US"
],
"requireCvc": false
}
}'
curl -X POST https://api.nexiopaysandbox.com/pay/v3/token \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Basic <Your Basic Auth>'
-d '{
"data": {
"currency": "USD"
},
"processingOptions": {
"checkFraud": false,
"verboseResponse": true,
"verifyAvs": 2,
"verifyCvc": false,
"webhookFailUrl": "https://your-company-webhook-fail-url-here.com",
"webhookUrl": "https://your-company-webhook-url-here.com"
}
}'
curl -X POST https://api.nexiopaysandbox.com/pay/v3/token \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Basic <Your Basic Auth>'
-d '{
"processingOptions": {
"verboseResponse": true,
"webhookFailUrl": "https://your-company-webhook-fail-url-here.com",
"webhookUrl": "https://your-company-webhook-url-here.com"
}
}'
POST /pay/v3/token
A token from this endpoint is necessary prior to loading any e-commerce iframe. The available and required parameters differ based on the iframe to be loaded. See the dropdown below to see which parameters are available and required for each iframe. All processing options and UI options for your iframes must be sent in the body of this request. Any data (ex. card or customer information) you wish to be pre-filled in your iframe forms must also be sent in this request. Any parameter included here will be overwritten if the same parameter is included in the iframe’s event body.
Note: Once a token has been used to submit an iframe it cannot be used to load another. You must request a new one-time-use token prior to submitting each iframe.
Parameters
Name | Type | Description | ||||
---|---|---|---|---|---|---|
card | object | Credit card information | ||||
data | object | Additional optional data | ||||
processingOptions | object | Processing Options | ||||
shouldUpdateCard | boolean | The card's account updater enrollment tag When true, the card or e-check token is tagged for registration with account updater Note: The card or e-check will not be registered until the merchant account is enrolled. See this table for more information Default: true |
||||
uiOptions | object | Used to customize the iframe's user interface |
Example responses
200 Response
{
"expiration": "2018-09-18T15:43:05.664Z",
"fraudUrl": "https://api.nexiopaysandbox.com/pay/v3/fingerprint?token=01080f80-76b8-4363-845d-67e8623bf170",
"token": "830d36f6-a5e3-4455-9600-3a55b63e2fc2"
}
401 Response
{
"message": "Unauthorized"
}
Responses
Status | Meaning | Description | ||||
---|---|---|---|---|---|---|
200 | OK | Success | ||||
401 | Unauthorized | Unauthorized |
Response Schema
Status Code 200
Name | Type | Description | ||||
---|---|---|---|---|---|---|
expiration | string | The date and time at which the one-time-use token will expire, in ISO 8601 format. | ||||
fraudUrl | string | The URL to be used for device fingerprinting | ||||
token | string | Your one-time-use token |
Status Code 401
Name | Type | Description |
---|
Save Card Token
Example request
curl -X POST https://api.nexiopaysandbox.com/pay/v3/saveCard \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Basic <Your Basic Auth>'
-d '{
"card": {
"cardHolderName": "John H Doe",
"encryptedNumber": "cu3yRktaYFK2LUC6DpNK289tYDsGRCi7cO+GeG0hkeYFvT7Y8/oY5r53obMz6Q/BZ38gk2u2Ufwy8ojBcX2sfNjG5jplGTXA4NNlSIUjMFfiHe1sff1JFpThoiW/IIlifGlbWu+S1/9pqWPTzJ2+DcjwohbHzsDahhYewFhXgC8qsK0ypi/Shlp+CwRITyIvbVXESD0xz3YOTRHeZLlChvVqN8z4ZzN8nm0MXkmT1wcpYI73bH4KdnPwNU3s7XxvP/ernQP73SHHAOKSLlz4F6AEHFjJiCoXzeLF7LwEjRdxDJ0sKVXbRk3i9BGh+8Nle2VYgjpUWtk2763QkvZiQQ==",
"expirationMonth": "12",
"expirationYear": "20",
"cardType": "visa",
"securityCode": 927,
"firstSix": "479300",
"lastFour": "3313"
},
"token": "eb50a022-d6de-4244-a1e6-dcb8522b2d19",
"data": {
"currency": "USD",
"customer": {
"billToAddressOne": "2147 West Silverlake Drive",
"billToAddressTwo": "Apt 42",
"billToCity": "Scranton",
"billToCountry": "US",
"billToPhone": "1555555555",
"billToPostal": "18503",
"billToState": "PA",
"birthDate": "1990-12-05",
"createdAtDate": "2005-03-01",
"customerRef": "RP006",
"email": "jdoe@yourwebsite.com",
"firstName": "John",
"invoice": "IN0001",
"lastName": "Doe",
"orderNumber": "210058A",
"phone": "1555555555",
"shipToAddressOne": "1725 Slough Avenue",
"shipToAddressTwo": "Suite 200",
"shipToCity": "Scranton",
"shipToCountry": "US",
"shipToPhone": "1555555555",
"shipToPostal": "18505",
"shipToState": "PA"
},
"customFields": {
"exampleKey": "Example string"
}
},
"shouldUpdateCard": true,
"tokenex": {
"token": "6ee140a0-05d1-4958-8325-b38a690dbb9d",
"firstSix": "479300",
"lastFour": "3313"
},
"merchantId": "100039"
}'
POST /pay/v3/saveCard
Allows you to securely save a card token without a browser or using your own form.
You may save a new card by including the card
object or add existing TokenEx card token for use in Nexio by including the token
object.
Note: Processing options must be sent in the request for a one-time-use token.
Parameters
Name | Type | Description | ||||
---|---|---|---|---|---|---|
card Required |
object | Credit card information | ||||
token Required |
string | A one-time-use token. | ||||
data | object | Additional optional data | ||||
shouldUpdateCard | boolean | The card's account updater enrollment tag When true, the card or e-check token is tagged for registration with account updater Note: The card or e-check will not be registered until the merchant account is enrolled. See this table for more information Default: true |
||||
tokenex | object | A previously saved TokenEx card token. (Use this option if you have pre-existing TokenEx tokens you would like to start using through Nexio.) Conditionally Required if the card.encryptedNumber is not included |
||||
merchantId | string | The merchant ID (MID). |
Example responses
200 Response
{
"card": {
"expirationMonth": "12",
"expirationYear": "20",
"cardHolderName": "John H Doe",
"cardType": "visa"
},
"data": {
"customer": {
"billToAddressOne": "2147 West Silverlake Drive",
"billToAddressTwo": "Apt 42",
"billToCity": "Scranton",
"billToCountry": "US",
"billToPhone": "1555555555",
"billToPostal": "18503",
"billToState": "PA",
"birthDate": "1990-12-05",
"createdAtDate": "2005-03-01",
"customerRef": "RP006",
"email": "jdoe@yourwebsite.com",
"firstName": "John",
"invoice": "IN0001",
"lastName": "Doe",
"orderNumber": "210058A",
"phone": "1555555555",
"shipToAddressOne": "1725 Slough Avenue",
"shipToAddressTwo": "Suite 200",
"shipToCity": "Scranton",
"shipToCountry": "US",
"shipToPhone": "1555555555",
"shipToPostal": "18505",
"shipToState": "PA"
}
},
"kountResponse": {
"status": "success",
"rules": "{\"VERS\":\"0630\",\"MODE\":\"Q\",\"TRAN\":\"7V7D0V1BMKPX\",\"MERC\":\"717000\",\"SESS\":\"3bbb89edcd5742f18e2502ebb2bbb18b\",\"ORDR\":\"14233\",\"AUTO\":\"A\",\"SCOR\":\"29\",\"GEOX\":\"US\",\"BRND\":\"VISA\",\"REGN\":null,\"NETW\":\"N\",\"KAPT\":\"N\",\"CARDS\":\"1\",\"DEVICES\":\"1\",\"EMAILS\":\"1\",\"VELO\":\"0\",\"VMAX\":\"0\",\"SITE\":\"DEFAULT\",\"DEVICE_LAYERS\":\"....\",\"FINGERPRINT\":null,\"TIMEZONE\":null,\"LOCALTIME\":\" \",\"REGION\":null,\"COUNTRY\":null,\"PROXY\":null,\"JAVASCRIPT\":null,\"FLASH\":null,\"COOKIES\":null,\"HTTP_COUNTRY\":null,\"LANGUAGE\":null,\"MOBILE_DEVICE\":null,\"MOBILE_TYPE\":null,\"MOBILE_FORWARDER\":null,\"VOICE_DEVICE\":null,\"PC_REMOTE\":null,\"RULES_TRIGGERED\":0,\"COUNTERS_TRIGGERED\":0,\"REASON_CODE\":null,\"MASTERCARD\":\"\",\"DDFS\":null,\"DSR\":null,\"UAS\":null,\"BROWSER\":null,\"OS\":null,\"PIP_IPAD\":null,\"PIP_LAT\":null,\"PIP_LON\":null,\"PIP_COUNTRY\":null,\"PIP_REGION\":null,\"PIP_CITY\":null,\"PIP_ORG\":null,\"IP_IPAD\":null,\"IP_LAT\":null,\"IP_LON\":null,\"IP_COUNTRY\":null,\"IP_REGION\":null,\"IP_CITY\":null,\"IP_ORG\":null,\"WARNING_COUNT\":0}"
},
"merchantId": "100100",
"shouldUpdateCard": true,
"token": {
"firstSix": "479300",
"lastFour": "3313",
"token": "6ee140a0-05d1-4958-8325-b38a690dbb9d",
"cardType": "visa"
},
"cvcResults": {
"matchCvv": true,
"error": true,
"gatewayMessage": {
"cvvresponse": "S",
"message": "Merchant has indicated that CVV2/CVC2 is not present on card"
}
},
"cardType": "visa"
}
400 Response
{
"error": 0,
"message": "string",
"cvcResults": {...},
"merchantId": "100039"
}
401 Response
{
"message": "Unauthorized"
}
Responses
Status | Meaning | Description | ||||
---|---|---|---|---|---|---|
200 | OK | Success | ||||
400 | Bad Request | Bad Request | ||||
401 | Unauthorized | Unauthorized |
Response Schema
Status Code 200
Name | Type | Description | ||||
---|---|---|---|---|---|---|
card | object | Card information | ||||
data | object | Additional data, if provided in the request | ||||
kountResponse | object | Fraud data and rules | ||||
merchantId | string | The merchant ID (MID) | ||||
shouldUpdateCard | boolean | The card's account updater enrollment tag When true, the card or e-check token is tagged for registration with account updater Note: The card or e-check will not be registered until the merchant account is enrolled. See this table for more information |
||||
token | object | Card token information | ||||
cvcResults | object | If `verifyCvc` was specified in the request for a one-time use token, then the Save Card Token endpoint includes this object in the response. | ||||
cardType | string | The card type. May be any of the following: - visa - mastercard - discover - amex |
Status Code 400
Name | Type | Description | ||||
---|---|---|---|---|---|---|
error | number | The Nexio error code. For an HTTP status code of 400, this value is 437. | ||||
cvcResults | object | The results of the verification of the card security code. | ||||
merchantId | string | The merchant ID (MID). |
Status Code 401
Name | Type | Description |
---|
Save Card Token Iframe
Example request
curl -X GET https://api.nexiopaysandbox.com/pay/v3/saveCard?token=830d36f6-a5e3-4455-9600-3a55b63e2fc2 \
-H 'Accept: application/json' \
-H 'One-time-use Token: API_KEY'
GET /pay/v3/saveCard
Returns an iframe that can be used to securely save a credit card token.
Parameters
Name | Type | Description | ||||
---|---|---|---|---|---|---|
token Required |
string | Your one-time-use token |
Example responses
200 Response
"<html>A save card form</html>"
401 Response
{
"message": "Unauthorized"
}
Responses
Status | Meaning | Description | ||||
---|---|---|---|---|---|---|
200 | OK | Success | ||||
401 | Unauthorized | Unauthorized |
Response Schema
Status Code 401
Name | Type | Description |
---|
Run Card Transaction
Example request
curl -X POST https://api.nexiopaysandbox.com/pay/v3/process \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Basic <Your Basic Auth>'
-d '{
"data": {
"amount": 29.99,
"currency": "USD",
"cart": {
"items": [
{
"item": "913261",
"description": "Hammermill Premium 8.5 x 11 Color Copy Paper, 28 lbs. 500/Ream",
"quantity": 8,
"price": 16.49,
"type": "sale"
}
]
},
"customer": {
"billToAddressOne": "2147 West Silverlake Drive",
"billToAddressTwo": "Apt 42",
"billToCity": "Scranton",
"billToCountry": "US",
"billToPhone": "1555555555",
"billToPostal": "18503",
"billToState": "PA",
"birthDate": "1990-12-05",
"createdAtDate": "2005-03-01",
"customerRef": "RP006",
"email": "jdoe@yourwebsite.com",
"firstName": "John",
"invoice": "IN0001",
"lastName": "Doe",
"orderDate": "2021-08-26",
"orderNumber": "210058A",
"phone": "1555555555",
"shipToAddressOne": "1725 Slough Avenue",
"shipToAddressTwo": "Suite 200",
"shipToCity": "Scranton",
"shipToCountry": "US",
"shipToPhone": "1555555555",
"shipToPostal": "18505",
"shipToState": "PA"
},
"customFields": {
"exampleKey": "Example string"
},
"description": "test purchase",
"descriptor": "",
"lodging": {
"advanceDeposit": true,
"checkInDate": "2018-12-31",
"checkOutDate": "2019-01-05",
"noShow": false,
"roomNumber": 14,
"roomRate": 143.99
}
},
"tokenex": {
"token": "6ee140a0-05d1-4958-8325-b38a690dbb9d",
"firstSix": "479300",
"lastFour": "3313"
},
"card": {
"businessNumber": "1234567890",
"cardHolderName": "John H Doe",
"cardType": "visa",
"classification": "business",
"expirationMonth": "12",
"expirationYear": "20",
"password": "12",
"securityCode": 927
},
"installment": {
"period": 10
},
"isAuthOnly": false,
"processingOptions": {
"checkFraud": false,
"customerRedirectUrl": "https://your-ecommerce-website.example.com",
"merchantId": "100039",
"paymentOptionTag": "switch",
"saveCardToken": true,
"shouldUseFingerprint": true,
"verboseResponse": true,
"webhookFailUrl": "https://your-company-webhook-fail-url-here.com",
"webhookUrl": "https://your-company-webhook-url-here.com"
}
}'
POST /pay/v3/process
Allows you to securely process a card transaction without a browser.
Parameters
Name | Type | Description | ||||
---|---|---|---|---|---|---|
data Required |
object | Transaction data | ||||
tokenex Required |
object | A previously saved card token. | ||||
card | object | Credit card information | ||||
installment | object | Creates an installment associated with the transaction. For a list of supported gateways, contact integration support. | ||||
isAuthOnly | boolean | Set to true to run an auth only transactionDefault: false |
||||
processingOptions | object | Processing Options |
Example responses
200 Response
{
"amount": 34.25,
"authCode": "035410",
"card": {
"expirationMonth": "12",
"expirationYear": "20",
"cardType": "visa",
"cardHolder": "John H Doe"
},
"currency": "USD",
"data": {
"amount": 29.99,
"currency": "USD",
"settlementCurrency": "CAD",
"customer": {
"customerRef": "RP006",
"firstName": "John",
"lastName": "Doe",
"invoice": "IN0001",
"orderNumber": "210058A",
"birthDate": "1990-12-05",
"createdAtDate": "2005-03-01",
"email": "jdoe@yourwebsite.com",
"phone": "1555555555",
"billToAddressOne": "2147 West Silverlake Drive",
"billToAddressTwo": "Apt 42",
"billToCity": "Scranton",
"billToState": "PA",
"billToPostal": "18503",
"billToCountry": "US",
"billToPhone": "1555555555",
"orderDate": "2021-08-26",
"shipToAddressOne": "1725 Slough Avenue",
"shipToAddressTwo": "Suite 200",
"shipToCity": "Scranton",
"shipToState": "PA",
"shipToPostal": "18505",
"shipToCountry": "US",
"shipToPhone": "1555555555"
},
"cart": {
"items": [
{
"item": "913261",
"description": "Hammermill Premium 8.5 x 11 Color Copy Paper, 28 lbs. 500/Ream",
"quantity": 8,
"price": 16.49,
"type": "sale"
}
]
},
"lodging": {
"advanceDeposit": true,
"checkInDate": "2018-12-31",
"checkOutDate": "2019-01-05",
"noShow": false,
"roomNumber": 14,
"roomRate": 143.99
},
"customFields": {
"exampleKey": "Example string"
}
},
"gatewayResponse": {
"gatewayName": "nmi",
"refNumber": "3107885809"
},
"id": "eyJuYW1lIjoidXNhZXBheSIsInJlZk51bWJlciI6IjMxMDA5MDc4MTkiLCJtZXJjaGFudElkIjoiMTAwMDM5IiwicmFuZG9tIjoiMzEwMDkwNzgxOSIsImN1cnJlbmN5IjoiVVNEIn0=",
"kountResponse": {
"status": "success",
"rules": "{\"VERS\":\"0630\",\"MODE\":\"Q\",\"TRAN\":\"7V7D0V1BMKPX\",\"MERC\":\"717000\",\"SESS\":\"3bbb89edcd5742f18e2502ebb2bbb18b\",\"ORDR\":\"14233\",\"AUTO\":\"A\",\"SCOR\":\"29\",\"GEOX\":\"US\",\"BRND\":\"VISA\",\"REGN\":null,\"NETW\":\"N\",\"KAPT\":\"N\",\"CARDS\":\"1\",\"DEVICES\":\"1\",\"EMAILS\":\"1\",\"VELO\":\"0\",\"VMAX\":\"0\",\"SITE\":\"DEFAULT\",\"DEVICE_LAYERS\":\"....\",\"FINGERPRINT\":null,\"TIMEZONE\":null,\"LOCALTIME\":\" \",\"REGION\":null,\"COUNTRY\":null,\"PROXY\":null,\"JAVASCRIPT\":null,\"FLASH\":null,\"COOKIES\":null,\"HTTP_COUNTRY\":null,\"LANGUAGE\":null,\"MOBILE_DEVICE\":null,\"MOBILE_TYPE\":null,\"MOBILE_FORWARDER\":null,\"VOICE_DEVICE\":null,\"PC_REMOTE\":null,\"RULES_TRIGGERED\":0,\"COUNTERS_TRIGGERED\":0,\"REASON_CODE\":null,\"MASTERCARD\":\"\",\"DDFS\":null,\"DSR\":null,\"UAS\":null,\"BROWSER\":null,\"OS\":null,\"PIP_IPAD\":null,\"PIP_LAT\":null,\"PIP_LON\":null,\"PIP_COUNTRY\":null,\"PIP_REGION\":null,\"PIP_CITY\":null,\"PIP_ORG\":null,\"IP_IPAD\":null,\"IP_LAT\":null,\"IP_LON\":null,\"IP_COUNTRY\":null,\"IP_REGION\":null,\"IP_CITY\":null,\"IP_ORG\":null,\"WARNING_COUNT\":0}"
},
"merchantId": "100039",
"token": {
"firstSix": "479300",
"lastFour": "3313",
"token": "6ee140a0-05d1-4958-8325-b38a690dbb9d"
},
"transactionDate": "2019-01-15T13:19:39.329Z",
"transactionStatus": "pending",
"transactionType": "sale"
}
400 Response
{
"error": 435,
"message": "Declined for CVV failure",
"gatewayResponse": {...},
"merchantId": "100100"
}
401 Response
{
"message": "Unauthorized"
}
Responses
Status | Meaning | Description | ||||
---|---|---|---|---|---|---|
200 | OK | Success | ||||
400 | Bad Request | Bad Request | ||||
401 | Unauthorized | Unauthorized |
Response Schema
Status Code 200
Name | Type | Description | ||||
---|---|---|---|---|---|---|
amount | number | The transaction amount | ||||
authCode | string | The authorization code | ||||
card | object | Credit card information | ||||
currency | string | The three-character ISO currency code for the transaction. | ||||
data | object | Transaction data | ||||
gatewayResponse | object | Gateway-specific information. Details will vary by gateway. Do NOT code to any information included in this object | ||||
id | string | Nexio Payment ID | ||||
kountResponse | object | Fraud data and rules | ||||
merchantId | string | The merchant ID through which the transaction was processed | ||||
token | object | The card token used to process the transaction | ||||
transactionDate | string | The transaction date and time | ||||
transactionStatus | string | The transaction status | ||||
transactionType | string | The transaction type |
Status Code 400
Name | Type | Description | ||||
---|---|---|---|---|---|---|
error | integer | Nexio's error code | ||||
gatewayResponse | object | The failure response from the gateway. Details will vary by gateway | ||||
merchantId | string | The merchant ID |
Status Code 401
Name | Type | Description |
---|
Run Card Transaction Iframe
Example request
curl -X GET https://api.nexiopaysandbox.com/pay/v3?token=830d36f6-a5e3-4455-9600-3a55b63e2fc2 \
-H 'Accept: application/json' \
-H 'One-time-use Token: API_KEY'
GET /pay/v3
Returns an iframe that can be used to securely run a credit or debit card transaction.
Parameters
Name | Type | Description | ||||
---|---|---|---|---|---|---|
token Required |
string | Your one-time-use token. This is a query parameter. |
Example responses
200 Response
"<html>A run transaction form</html>"
401 Response
{
"message": "Unauthorized"
}
Responses
Status | Meaning | Description | ||||
---|---|---|---|---|---|---|
200 | OK | Success | ||||
401 | Unauthorized | Unauthorized |
Response Schema
Status Code 401
Name | Type | Description |
---|
Save E-check Token
Example request
curl -X POST https://api.nexiopaysandbox.com/pay/v3/saveECheck \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Basic <Your Basic Auth>'
-d '{
"bank": {
"accountHolderName": "John Doe",
"routingNumber": "231375151",
"encryptedBankAccountNumber": "cu3yRktaYFK2LUC6DpNK289tYDsGRCi7cO+GeG0hkeYFvT7Y8/oY5r53obMz6Q/BZ38gk2u2Ufwy8ojBcX2sfNjG5jplGTXA4NNlSIUjMFfiHe1sff1JFpThoiW/IIlifGlbWu+S1/9pqWPTzJ2+DcjwohbHzsDahhYewFhXgC8qsK0ypi/Shlp+CwRITyIvbVXESD0xz3YOTRHeZLlChvVqN8z4ZzN8nm0MXkmT1wcpYI73bH4KdnPwNU3s7XxvP/ernQP73SHHAOKSLlz4F6AEHFjJiCoXzeLF7LwEjRdxDJ0sKVXbRk3i9BGh+8Nle2VYgjpUWtk2763QkvZiQQ=="
},
"token": "830d36f6-a5e3-4455-9600-3a55b63e2fc2",
"data": {
"customer": {
"billToAddressOne": "2147 West Silverlake Drive",
"billToAddressTwo": "Apt 42",
"billToCity": "Scranton",
"billToState": "PA",
"billToPostal": "18503",
"billToCountry": "US",
"billToPhone": "1555555555",
"companyName": "Green Thumb Lawn Care",
"createdAtDate": "2005-03-01",
"customerRef": "RP006",
"email": "jdoe@yourwebsite.com",
"firstName": "John",
"invoice": "IN0001",
"lastName": "Doe",
"orderNumber": "210058A",
"phone": "1555555555",
"shipToAddressOne": "1725 Slough Avenue",
"shipToAddressTwo": "Suite 200",
"shipToCity": "Scranton",
"shipToState": "PA",
"shipToPostal": "18505",
"shipToCountry": "US",
"shipToPhone": "1555555555"
},
"customFields": {
"exampleKey": "Example string"
}
},
"tokenex": {
"token": "585436789",
"customerRefNumber": "74771a19-3c28-4c27-83c6-9",
"lastFour": "1111"
}
}'
POST /pay/v3/saveECheck
Allows you to securely save bank account information without a browser or using your own form.
You may save a new e-check by including the card
object or add existing TokenEx e-check token for use in Nexio by including the token
object.
Note: Processing options must be sent in the request for a one-time-use token.
Parameters
Name | Type | Description | ||||
---|---|---|---|---|---|---|
bank Required |
object | Bank account information | ||||
token Required |
string | Your one-time-use token | ||||
data | object | Additional optional data | ||||
tokenex | object | The TokenEx e-check token. (Use this option if you have pre-existing TokenEx tokens you would like to start using through Nexio). Conditionally Required if the bank.encryptedBankAccountNumber is not included. |
Example responses
200 Response
{
"token": {
"lastFour": "1111",
"token": "aafb1033-599a-4392-859e-f98033fc37f5"
},
"data": {
"customer": {
"billToAddressOne": "2147 West Silverlake Drive",
"billToAddressTwo": "Apt 42",
"billToCity": "Scranton",
"billToCountry": "US",
"billToPhone": "1555555555",
"billToPostal": "18503",
"billToState": "PA",
"companyName": "Green Thumb Lawn Care",
"createdAtDate": "2005-03-01",
"customerRef": "RP006",
"email": "jdoe@yourwebsite.com",
"firstName": "John",
"invoice": "IN0001",
"lastName": "Doe",
"orderNumber": "210058A",
"phone": "1555555555",
"shipToAddressOne": "1725 Slough Avenue",
"shipToAddressTwo": "Suite 200",
"shipToCity": "Scranton",
"shipToCountry": "US",
"shipToPhone": "1555555555",
"shipToPostal": "18505",
"shipToState": "PA"
}
},
"bank": {
"accountHolderName": "John Doe",
"routingNumber": "231375151"
},
"merchantId": "100100"
}
401 Response
{
"message": "Unauthorized"
}
Responses
Status | Meaning | Description | ||||
---|---|---|---|---|---|---|
200 | OK | Success | ||||
401 | Unauthorized | Unauthorized |
Response Schema
Status Code 200
Name | Type | Description | ||||
---|---|---|---|---|---|---|
token | object | E-check token information | ||||
data | object | Additional data, if provided in the request | ||||
bank | object | Bank information | ||||
merchantId | string | The merchant ID (MID) |
Status Code 401
Name | Type | Description |
---|
Save E-check Token Iframe
Example request
curl -X GET https://api.nexiopaysandbox.com/pay/v3/saveECheck?token=830d36f6-a5e3-4455-9600-3a55b63e2fc2 \
-H 'Accept: text/html' \
-H 'One-time-use Token: API_KEY'
GET /pay/v3/saveECheck
Returns an iframe that can be used to securely save a bank account information.
Parameters
Name | Type | Description | ||||
---|---|---|---|---|---|---|
token Required |
string | Your one-time-use token. This is a query parameter. |
Example responses
200 Response
"<html>A save e-check form</html>"
401 Response
{
"message": "Unauthorized"
}
Responses
Status | Meaning | Description | ||||
---|---|---|---|---|---|---|
200 | OK | Success | ||||
401 | Unauthorized | Unauthorized |
Response Schema
Status Code 401
Name | Type | Description |
---|
Run E-check Transaction
Example request
curl -X POST https://api.nexiopaysandbox.com/pay/v3/processECheck \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Basic <Your Basic Auth>'
-d '{
"data": {
"amount": 29.99,
"currency": "USD",
"cart": {
"items": [
{
"item": "913261",
"description": "Hammermill Premium 8.5 x 11 Color Copy Paper, 28 lbs. 500/Ream",
"quantity": 8,
"price": 16.49,
"type": "sale"
}
]
},
"customer": {
"billToAddressOne": "2147 West Silverlake Drive",
"billToAddressTwo": "Apt 42",
"billToCity": "Scranton",
"billToState": "PA",
"billToPostal": "18503",
"billToCountry": "US",
"billToPhone": "1555555555",
"companyName": "Green Thumb Lawn Care",
"createdAtDate": "2005-03-01",
"customerRef": "RP006",
"email": "jdoe@yourwebsite.com",
"firstName": "John",
"invoice": "IN0001",
"lastName": "Doe",
"orderNumber": "210058A",
"phone": "1555555555",
"shipToAddressOne": "1725 Slough Avenue",
"shipToAddressTwo": "Suite 200",
"shipToCity": "Scranton",
"shipToState": "PA",
"shipToPostal": "18505",
"shipToCountry": "US",
"shipToPhone": "1555555555"
},
"customFields": {
"exampleKey": "Example string"
},
"secCode": "IAT",
"settlementCurrency": "CAD"
},
"tokenex": {
"token": "aafb1033-599a-4392-859e-f98033fc37f5",
"customerRefNumber": "74771a19-3c28-4c27-83c6-9",
"lastFour": "1111"
},
"bank": {
"accountHolderName": "John Doe",
"routingNumber": "231375151"
},
"processingOptions": {
"merchantId": "100039",
"verboseResponse": true,
"webhookFailUrl": "https://your-company-webhook-fail-url-here.com",
"webhookUrl": "https://your-company-webhook-url-here.com"
}
}'
POST /pay/v3/processECheck
Allows you to securely process an e-check transaction without a browser.
Parameters
Name | Type | Description | ||||
---|---|---|---|---|---|---|
data Required |
object | Transaction data | ||||
tokenex Required |
object | The e-check token. | ||||
bank | object | Bank account information | ||||
processingOptions | object | Processing Options |
Example responses
200 Response
{
"amount": 34.25,
"authCode": "035410",
"bank": {
"accountHolderName": "John Doe",
"routingNumber": "******6789",
"accountNumber": "***********6789"
},
"currency": "USD",
"data": {
"amount": 29.99,
"cart": {
"items": [
{
"item": "913261",
"description": "Hammermill Premium 8.5 x 11 Color Copy Paper, 28 lbs. 500/Ream",
"quantity": 8,
"price": 16.49,
"type": "sale"
}
]
},
"currency": "USD",
"customFields": {
"exampleKey": "Example string"
},
"customer": {
"billToAddressOne": "2147 West Silverlake Drive",
"billToAddressTwo": "Apt 42",
"billToCity": "Scranton",
"billToCountry": "US",
"billToPhone": "1555555555",
"billToPostal": "18503",
"billToState": "PA",
"companyName": "Green Thumb Lawn Care",
"createdAtDate": "2005-03-01",
"customerRef": "RP006",
"email": "jdoe@yourwebsite.com",
"firstName": "John",
"invoice": "IN0001",
"lastName": "Doe",
"orderNumber": "210058A",
"phone": "1555555555",
"shipToAddressOne": "1725 Slough Avenue",
"shipToAddressTwo": "Suite 200",
"shipToCity": "Scranton",
"shipToCountry": "US",
"shipToPhone": "1555555555",
"shipToPostal": "18505",
"shipToState": "PA"
},
"lodging": {
"advanceDeposit": true,
"checkInDate": "2018-12-31",
"checkOutDate": "2019-01-05",
"noShow": false,
"roomNumber": 14,
"roomRate": 143.99
},
"settlementCurrency": "CAD"
},
"gatewayResponse": {
"gatewayName": "nmi",
"refNumber": "3107885809"
},
"id": "eyJuYW1lIjoidXNhZXBheSIsInJlZk51bWJlciI6IjMxMDA5MDc4MTkiLCJtZXJjaGFudElkIjoiMTAwMDM5IiwicmFuZG9tIjoiMzEwMDkwNzgxOSIsImN1cnJlbmN5IjoiVVNEIn0=",
"merchantId": "100039",
"transactionDate": "2019-01-15T13:19:39.329Z",
"transactionStatus": "pending",
"transactionType": "sale"
}
401 Response
{
"message": "Unauthorized"
}
Responses
Status | Meaning | Description | ||||
---|---|---|---|---|---|---|
200 | OK | success | ||||
401 | Unauthorized | Unauthorized |
Response Schema
Status Code 200
Name | Type | Description | ||||
---|---|---|---|---|---|---|
amount | number | The transaction amount | ||||
authCode | string | The authorization code | ||||
bank | object | Bank account information | ||||
currency | string | The three-character ISO currency code for the transaction. | ||||
data | object | Transaction data |