Tutorials

Check out our new documentation for additional tutorials. Recently added tutorials include:



Authentication



Basic Authentication

Basic Authentication is a simple and secure way to access our API endpoints. To use:

  1. Base 64 encode your Nexio username and password with no spaces, separated by a colon.
                                        
    myname@cmsonline.com:mypassword
                                    
  2. Prefix the value from Step 1 with the string "Basic " and include in the Authorization Header of each API request. Ex:
                                        
    Authorization: Basic QWxhZGRpbjpPcGVuU2VzYW1l
                                    

Using Nexio Iframes



Nexio’s secure hosted iframes allow you to save cards/eChecks and run transactions in ecommerce as well as in-store or in-office environments (retail,MOTO, card-present, EMV). Sensitive cardholder data is collected and tokenized completely within our secure iframe reducing your PCI compliance scope. A card or eCheck payment token is returned which your server will use to make payment requests to our API.

Click here to see how it works.


Using iframes for ecommerce


Used for cardholder-facing interactions (sign-ups, shopping cart checkout, patient portal, etc.)

Each ecommerce iframe requires the retrieval and usage of a One-time Use Token. Payment information (such as amount, currency and customer information) may be required at the time you retrieve a One Time Use Token. That information will be used to process the payment or save a card when the form is submitted.

Nexio's Ecommerce Iframes:

Save Card/eCheck

Used to Save a card or an eCheck to be used in recurring billing or one-time payments. You can perform fraud checks, AVS, and CVC verification when saving payment information.

Run Transaction

Process a one-time, keyed credit card or eCheck transaction. You can perform fraud checks, AVS, and CVC verification when running transactions.

To create and use an ecommerce iframe:

Step 1: Create the Iframe

Create an iframe on your checkout page.

Step 2: Create an Event Listener

Create an event listener to monitor actions in the iframe. This listener will keep your code updated on what is happening inside the iframe. You should handle the success, error, and loading states here. See our 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)
    }
});
                                

Step 3: Authenticate Using a One-time Use Token

To get a One-time Use Token follow the steps below:
  1. Send a POST request to the One-time Use Token endpoint. For example:
                                        
    curl --request POST \
        --url 'http://api.nexiopaysandbox.com/pay/v3/token' \
        --header 'Authorization: <Your Basic Auth>' \
        --data '{
        "data": {
            "currency":"USD",
            "amount": 5,
            "uiOptions": {
                "hideCvc": false
            },
            "processingOptions": {
                "checkFraud": true
            }
        }
    }'
                                    

    A successful response will return an object containing the following:

    {
        "expiration": "2019-02-26T18:43:51.205Z",
        "token": "ec53cd46-cee5-44db-a20f-f5c373a44fd2",
        "fraudUrl": "https://tst.kaptcha.com/collect/sdk?m=717000&s=ec53cd46cee544dba20ff5c373a44fd2"
    }
    
  2. Copy or store the token from the above response. This will be used in Step 4.

Notes:

  • Each One-time Use Token can be used only once and expires after one hour.
  • Any iframe uiOptions or processingOptions must be included in this step.

Step 4: Load the Iframe

Append your One-time Use Token as a query parameter called token. Assign the result to your iframe's src tag. The new URL allows you to load an iframe once.

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;
                            
                

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

Step 5: 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 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
});
                            
                                

Using an iframe for retail/MOTO transactions



Used in merchant-facing interactions for in-store or in-office environments (retail, MOTO, card-present EMV, etc.).

To create and use a retail/MOTO iframe:

Step 1: Authenticate Using Simple Login

Simple Login allows trusted users to proceed directly to the iframe without the necessity of entering in 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 with each use.

To use Simple Login follow the steps below:
  1. Send a POST request to the Simple Login endpoint. For example:
                                        
    curl --request POST \
        --url 'https://api.nexiopaysandbox.com/auth/v3/createSimpleLogin' \
        --header 'Authorization: <Your Basic Auth>' \
                                    

    A successful response will return an object containing the following:

    {
        "username": "youremail@cmsonline.com",
        "key": "4f211fde-d135-4c91-afbc-bcdb73c0c504",
        "jwt": "t3jraWQiOiI3V2JrOFdSVVliMVljR2p3Mlhwd2swR3lIRWt6THcwVDRqckVhNVVVTjBnPSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiI4YWYzZTQwZC02Y2I0LTQ0ZWQtOWRlZS0yN2Y3NmNmNDc0YmMiLCJlbWFpbF92ZXJpZmllZCI6dHJ1ZSwiaXNzIjoiaHR0cHM6XC9cL2NvZ25pdG8taWRwLnVzLWVhc3QtMS5hbWF6b25hd3MuY29tXC91cy1lYXN0LTFfVlVEN21MeWNqIiwiY3VzdG9tOmFjY291bnRJZCI6ImVjN2NiOWJhLWQwMmQtNDhkYS1hY2I3LWI2ZWQ3YmJiZWQwMiIsImNvZ25pdG86dXNlcm5hbWUiOiJscm9ibGVkb0BjbXNvbmxpbmUuY29tIiwiYXVkIjoiNDBtZWQ2YnNybDZ1aWpnMmpmZzQwcmJzOGkiLCJldmVudF9pZCI6IjE0YmU5MWFjLTM0NjctMTFlOS9iNDZjLWMxMjdjYTkzZjA3NCIsInRva2VuX3VzZSI6ImlkIiwiYXV0aF90aW1lIjoxNTUwNTk1Mjk0LCJleHAiOjE1NTA1OTg4OTRsImN1c3RvbTphY2Nlc3NSaWdodHMiOiJ7XCJtZXJjaGFudElkc1wiOntcIjEwMDAzOVwiOlwiQVwiLFwiMTAwMDQxXCI6XCJBXCIsXCI1MTU3OTQwMDAwMTM1MDRcIjpcIkFcIixcIjkyMzYwMDAwMTEyNDUwM1wiOlwiQVwiLFwiOTIzNTAwMDAxNDMyNzQyXCI6XCJBXCIsXCI1MTM0ODUwMDAwMDAwMThcIjpcIkFcIixcIjkyMzYwMDAwODEyNjYxMFwiOlwiQVwiLFwiOTIzNjAwMDAzMTYzODEwXCI6XCJBXCJ9LFwicm9sZVwiOlwiQVwifSIsImlhdCI6MTU1MDU5NTI5NCwiZW1haWwiOiJscm9ibGVkb0BjbXNvbmxpbmUuY29tIn0.OEEZarSzbSLpxUM55UKmycYtAAWEtm__XUJdqBJ9QPSF_8sdLIL9EXBF8cLarhv3DoLqeWKUpieNgfcME2IsIc8amDXitvJtJe3STQtI_zaJwAibBxJhFKQRLRCrIe3kpslVJPuw3OeST54QcseifLlA64bxNaveXygja7aejwINueE4_Nj0NEzcFGZoYHgNB6br6Ksbjgx-z_SiFIZ1XHS-eOMnBoCIVWjFr3FY9IbfnQf4v0c0AFWKt9mOpjYracSqOHHmSER7GuaMBNrHxfbe0kHVh6hvnrzh10SEnTsF573qbP1R_aZA_Uh80MOLB0UvPWWFzzyP4GniNc3zLw",
        "refreshToken": "t3jjdHkiOiJKV1QiLCJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiUlNBLU9BRVAifQ.CejuLZHvZcrISuiwE7N4xg7EYq6ArivbyNwDVE2X7eTdr7CTO4l5udgc9ZUV1byTe1r3eLN_szbte1nlaimbQj5ZcJpim1zmW5pkk7aFVF-WcnLjIBVPilp6bLW8gsZaB04WErDjwzt4r7Bxnz6YnmLM7e3V15ZVkY6GLFqgrUF9Tb9UOFbCDD_H8qe1AdFktVeeVgefekJew3RuZ8p2BnKWejt1BcyMUnYY-QgaLm3TzUpd14PRbdvOfBG3D9KmJCnZ_6H9sQ5FUirqsF_U6eXNppE1QXZdjhFg4oic791Kq5rXU2xbMI9ggeFoGIjLLP0Keb0iT66NwXpf50-h4w.eUOjohgz3zXTJWHH.IBQMMiNKtbAZ02r0QGXJXw_zM2c3epH5LGtdZxIVUReMRr5CLm-ptE7zaFTK0D1tpUHcVonqiDuXyc09IN0IO4jL32QqQjgeG-V9LBYgpr1xV3qyc5TR-L2VNHjJt3A3SbJsIzxHDqKLucJw2N0WaiOgLb577q8B8lu0pLCpOV_POlUiT4BLAvycMCKkgUCDrejyjzR39ofCUqtZKuMglXanUfVE3hC0OaNOMpl65N_utjuf9vzklyZZRQMTgokQ7V0yp0VSpCC6D_zNBvwTPUKHVFyMrzEC4wJZ9uOtIS9h9rv_HywpwrPqHYajsGYNrv7QvHE1Kg80I73CbL0owW-J5bKEbgImqkahNVhBoFJejnvN3PEr9zthNey15Q_utOUFUkR0Po9GH6fnXFXxQnIC7c2hQ4lgjV2wR3WGzEiE5L0aNLF1Cnjyn-t1VZxQHG2uiyiT1aIUFBPbItTkVPjKhkFKf7AfXqOTAl52VFdBPpFdbG5Ecwfm_4ZGgO_4KJnLcb7qMQuEI6G20xelkPD2NHIpdS9gHx7XIlyfiBPkvq3YEKMtOQQbRAQ_Hcy7leeZnSyPgq65Bnsn22xZ4NG5bSshSEEMlq5lbOV4-dzBGV8SA6dOeNHR7GeQvSr1XQ89sBloJlMKJLe9WL0fYhkY6u-MbmecvMoU1OrC4mvIv-0l53TIeeGDMtn8UkcaSxQG7HBEqcQlvaFAxGaol7kiDPlAMxdp11lnk0ix3G0M74xHRFpZalIFtUAPm2xEVFJLWlwLqalRgJpO70asiw9QJ_pi0HERT5N_wCXraxeQyNrknNmi157ih5yP7SGm7MXrSVUOHu6GIBZktAfP8IURhJNQZfSk3Do_up1vUBPN7yLNumqPq2PWH3CgFXle3nDaQYCVsVkGU-FZTy7KLIbKc2EStkOFOCPiYYSoD8h1-C8kclCeIKFLDFQIo7weJyIGjQqV_pY9HEPQivgXw6X1ti711x0YZ2bhl9tPuUEtXeja7hGAxLnrU4QqHr2iS58J9F5NMVc6LlK_NcExLzrlnQBJws7urmDkV_yoOtCRadxVuAxVCYqfAh8X4gzQ7LQMT27pFeV98iCvAmkhWx4RpAmFYHmacUJIXUVXKe6eTlN27gsYir1H9SrkbFgjOjvoUBj5p-mn-mMathsdAbRtlryJEjfCzAfBWis-7d4GsxCZGQnCJ0NezIP50_2dCPyzpgYcUwt4E4kHIA5-SBOLWneULDPz7VpRJxKv8BaYxOZuotnV2zz2nwB3vlDWK1h6cgRfMT8o8iphcUMxdZdjd-FElzNCdQ.SDQXbyIYZu6_jdCeAzTzoA",
        "exp": 1550600014
    }
    
  2. Copy or store the key from the above response. This will be used in Step 2.

Notes:

  • Each Simple Login key expires after one hour and can only be used once.
  • You may also choose to authenticate using your Nexio credentials rather than through Simple Login by going to https://retail.nexiopaysandbox.com and entering in your Nexio credentials where prompted

Step 2: Load the Iframe

There are two iframe options: Save Card and Run Transaction.

The Run Transaction iframe will load by default. You can choose to load the Save Card by changing a query parameter, called settings.

You may also select additional UI or processing options as shown in the table below.

Save Card

Receive payment tokens for use in recurring billing or one-time payments. You can perform fraud checks, AVS, and CVC verification when saving payment information.

To load the Save Card iframe:
  1. Append the following settings as a query parameter to the retail/MOTO iframe URL:
    {
        "uiOptions" : {
            "saveCard": true
        }
    }
    

    For example:

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


Additional Settings:
UI Options (Save Card)
Field
Type
Description
saveCard
boolean
Set to true to show the Save Card iframe. (Default: false)
merchantIdSet
boolean
A merchant ID included here will pre-populate the Processing Account dropdown. The user will not be able to select a different account.
merchantIdDefault
string
A merchant ID included here will pre-populate the Processing Account dropdown. The user will be able to select a different account.
hideBilling
object
You may include any of the following keys if you wish to hide that field:
  • hidePostal
  • hideCountry
  • hideAddressOne
  • hideAddressTwo
  • hideCity
  • hideState

Note: You may continue to pass true or false to hide or display all fields.

If the object is not included all fields will be displayed by default.

limitCountriesTo
array of strings
Allows you to indicate which countries to display in the Country dropdown.

Processing Options (Save Card)
Field
Type
Description
checkFraud
boolean
If set to true, a fraud check will be performed. See the tutorial for more information.
verifyCvc
boolean
If set to true, the security code (CVC) will be verified. See the tutorial for more information.
verifyAvs
integer

Run Transaction

Process credit card transactions by:

  • Keying in the credit card number
  • Using an EMV terminal

This iframe will load by default. You may also select additional UI or processing options as shown in the table below.

To process a keyed payment:
  1. Load the iframe using your Simple Login key from Step 1. For example:

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

  2. Select ‘Card (keyed)’ in the Payment Method dropdown (selected by default).
  3. Enter or confirm the amount.
  4. Key in card information.
  5. Click ‘Pay $X.XX’ button to complete the transaction.
  6. The iframe will display a simple ‘Success’ page.

    Note: The iframe does not generate a default receipt. You will use our response to create a success/confirmation page and your own receipt.

To process a payment using a terminal:

Our iframe automatically identifes available terminals based on the Nexio credentials used to load the iframe. Terminals are registered directly within a merchant’s gateway account.

  1. Load the iframe using your Simple Login key from Step 1. For example:

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

  2. Select ‘Card (terminal)’ in the Payment Method dropdown.
  3. Enter or confirm the amount.
  4. Select the terminal to be used in the Terminal dropdown.
  5. Click ‘Submit’ button to initiate the transaction.
  6. Complete the transaction on the terminal by following the on-screen prompts.
  7. The iframe will display a simple ‘Success’ page.

    Note: The iframe does not generate a default receipt. You will use our response to create a success/confirmation page and your own receipt. See an example successful response below:


success2019-04-02T19:13:32.147Z
{
  "gatewayResponse": {
    "result": "APPROVAL",
    "gatewayType": 110,
    "batchRef": "10",
    "gatewayName": "zeamster",
    "refNumber": "11e9557b670f514a8b2c62bb"
  },
  "currency": "USD",
  "transactionStatus": "authorized",
  "terminalRequestId": "c16fdd48-cdcd-4858-ac74-7f1c73e16cbb",
  "authCode": "557b67",
  "transactionType": "sale",
  "card": {
    "cardType": "visa",
    "cardHolder": "Visa ES Card 1",
    "cardNumber": "442780****3337"
  },
  "processingOptions": {
    "merchantId": "101039"
  },
  "terminalRequestStatus": "success",
  "data": {
    "lodging": {
      "advanceDeposit": true,
      "roomRate": 52,
      "roomNumber": "101",
      "checkOutDate": "2019-04-07",
      "checkInDate": "2019-04-02"
    },
    "amount": 54.98,
    "customFields": {
      "custom1": "Blue",
      "custom2": "Leave on porch"
    },
    "description": "test purchase",
    "currency": "USD",
    "cart": {
      "items": {
        "0": {
          "description": "Electric Socks",
          "item": "E100",
          "quantity": 2,
          "type": "sale",
          "price": 5
        }
      }
    },
    "customer": {
      "lastName": "Wild",
      "shipToAddressOne": "123 Ship Street",
      "orderNumber": "order456",
      "shipToCountry": "US",
      "shipToAddressTwo": "Suite 323",
      "billToState": "TX",
      "billToCity": "Amarillo",
      "firstName": "Buck",
      "shipToCity": "Amarillo",
      "customerRef": "customer123",
      "phone": "8015551234",
      "billToAddressOne": "123 Bill Street",
      "shipToPostal": "56649",
      "billToCountry": "US",
      "billToPostal": "56649",
      "invoice": "invoice123",
      "billToAddressTwo": "Suite 232",
      "email": "buck.wild@email.fake",
      "shipToState": "TX"
    }
  },
  "amount": 54.98,
  "transactionDate": "2019-04-02T19:13:30.000Z",
  "id": "eyJuYW1lIjoiemVhbXN0ZXIiLCJtZXJjaGFudElkIjoiMTAxMDM5IiwicmVmTnVtYmVyIjoiMTFlOTU1N2I2NzBmNTE0YThiMmM2MmJiIiwicmFuZG9tIjoiMTFlOTU1N2I2NzBmNTE0YThiMmM2MmJiIiwiY3VycmVuY3kiOiJ1c2QifQ=="
}
                        

Additional Settings:
UI Options (Run Transaction)
Field
Type
Description
amountSet
string
Pre-populates the amount field. The user will not be able to change the amount.
amountDefault
string
Pre-populates the amount field. The user will be able to change the amount.
amountMax
string
Prevents any amount over the max from being processed.
merchantIdSet
string
A merchant ID included here will pre-populate the Processing Account dropdown. The user will not be able to select a different account.
merchantIdDefault
string
A merchant ID included here will pre-populate the Processing Account dropdown. The user will be able to select a different account.
hideBilling
object
You may include any of the following keys if you wish to hide that field:
  • hidePostal
  • hideCountry
  • hideAddressOne
  • hideAddressTwo
  • hideCity
  • hideState

Note: You may continue to pass true or false to hide or display all fields.

If the object is not included all fields will be displayed by default.


Processing Options (Run Transaction)
Field
Type
Description
checkFraud
boolean
If set to true, a fraud check will be performed. See the tutorial for more information.
paymentOptionTag
string
References a specific payment option configured in the merchant’s Nexio account

Process a Payment



Processing using the API

The Payment Service allows you to process, void, refund or capture a payment. This service must be enabled on your account before you can use it.

  1. Contact integrations@nexiopay.com to ensure your merchantId and account have access to the Payment Service. (You may be asked to provide additional information such as Gateway, TokenEx or Kount credentials.)
  2. Post payment details with tokenized card information to the Run Transaction API
                                        
    curl --request POST \
        --url 'https://api.nexiopaysandbox.com/pay/v3/process' \
        --header 'Authorization: <Your Basic Auth>' \
        --data '{
        "tokenex":{
             "token":"7ae7d57c-cd9f-4c00-ad14-bfdf060fe011"
        },
        "card":{
            "expirationMonth":"1",
            "expirationYear":"20",
            "cardHolderName": "Captin Hammer",
            "lastFour":"1111"
        },
        "data": {
           "currency":"USD",
           "amount": 5
        }
    }'
                                    

Error Handling



Error Handling

Error handling can be made very simple, for most situations one will encounter a handful of error and success codes including 200, 401, 404, 400 and 500. The most common responses will be:

200: Payment was successful

4xx: Payment was not processed. (Due to gateway decline or another reason.) See below for more information.

Note: Due to PCI regulations error messages may often be intentionally ambiguous. Please contact us if you wish to discuss your error messages.

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

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


Common Errors
Error
Description
Status Code
404
The requested item is not found
404
404
Merchant not found or invalid merchant configuration
404
409
No merchants enabled for processing on this account for selected currency
409
431
Kount has identified a possible risk with the transaction
400
432
Invalid currency
400
433
Invalid gateway
400
434
Invalid TokenEx configuration
400
435
Unable to process with gateway
400
436
Unable to capture void or refund
400
436
Missing required fields
400
437
Invalid CVC
400
438
Invalid request
400
439
Unable to load TokenEx
500
440
Insufficient access
401
441
Amount needs to be a number
400
443
Verify AVS Failed
400
Generic server error
500

Constant Values



Constant Values

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



Transaction Status
Name
Value
Authorized
10
Auth Only
11
Pending
12
Submitted
13
Settled
20
Declined
30
Voided
40
Error
50
Transaction Type
Name
Value
Sale
10
Refund
20
Card Type
Name
Value
Visa
10
MasterCard
20
Discover
30
American Express
40
Unknown
null
Process Method
Name
Value
Card
10
Card Present
11
Card Not Present
12
AliPay
20
CUP
30
eCheck
40
PayPal
50
Cash
60
ACH
70
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

Query Parameters



Searching For Transactions

In the Transaction, Chargeback and ACH Services, you may request additional fields from GET responses by adding an empty query parameter with the name of the desired object followed by a dot.

For example, the following return a standard list of transactions:

                        
/transaction/v3
                    

While the following will return the same list of transactions with information about Kount, our payment iframes/plugins, customer, processor and gateway:

                        
/transaction/v3?kount.&plugin.&customer.&processor.&gateway.
                    


You may also filter by specifying the desired field to filter after the dot. For example:

                        
/transaction/v3?kount.&plugin.originalId=PAYMENT_ID
                    

The above request will find a transaction made in the Nexio Pay API with the specified payment ID and include its Kount results.



Fraud Check



Overview

Nexio utilizes Kount for fraud and risk management. Fraud checks can be performed both when saving a card and at the time of processing a transaction.

Nexio will run one of two Risk Inquiry Service (RIS) requests depending on whether customer information (specifically 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.

Performing Fraud Checks

To check fraud using the Nexio iframe:
  1. Ensure Kount is enabled for your merchant account by contacting CMS customer support.
  2. Include the object
                                        
    "processingOptions": { "checkFraud": true }
                                    
    in your request to the One-time Use Token endpoint.
  3. Use the token in the response from Step 2 to load either the Save Card or Run Credit Card Transaction iframe.


To check fraud using the Nexio API:
  1. Ensure Kount is enabled for your merchant account by contacting CMS customer support.
  2. Include the object
                                        
    "processingOptions": { "checkFraud": true }
                                    
    in your request to the Run Credit Card Transaction endpoint.


Fraud Check Response

When you check fraud your response will include an object called kountResponse. The kountResponse consists of two parts, status and rules. See the example and explanation below:

                            
"kountResponse": {
    "status": "success",
    "rules": "{
        "VERS": "0630",
        "MODE": "W",
        "TRAN":"79970C4SYHL2"
        }"
}
                        

Status

There are three possible statuses. The status helps you know what action will be taken. The action will differ based on the endpoint. See below for more information:

  • Success:
    • Run Credit Card Transaction: Based on the Kount rule(s) configured, the transaction will be processed with no further action required.
    • Save Card: The card will be saved with no further action required.
  • Review:
    • Run Credit Card Transaction: Based on the Kount rule(s) triggered, the transaction has been run as an Auth Only, meaning the transaction has been authorized but is pending further action. You can manually approve or decline these transactions in the Fraud tab of Nexio Dashboard. (Please note that these transactions will auto-approve after 48 hours if no action is taken.)
    • Save Card: A 'Review' status will not prevent the card from being saved.
  • Decline:
    • Run Credit Card Transaction: Based on the Kount rule(s) triggered, the transaction will not be processed with no further action required.
    • Save Card: The card will not be saved.

Rules

This part of the response will include Kount-specific information including Kount version, mode, transaction ID, and brief descriptions of any rules that were triggered.

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


Testing Fraud Check

While testing our fraud check service 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

Examples:

The examples below show how to test Nexio's fraud check on the Run Credit Card Transaction endpoint.

This request will return a kountResponse with a status of 'review':

                            
curl --request POST \
  --url https://api.nexiopaysandbox.com/pay/v3/process \
  --header <Your Basic Auth> \
    --data '{
        "tokenex":{
            "token": <A previously saved Card Token>
        },
        "card":{
            "expirationMonth":"1",
            "expirationYear":"20"
        },
        "data": {
           "currency":"USD",
           "amount": 5,
           "customer": {
               "billToAddressOne": "456 Slough Avenue"
           }
        },
        "processingOptions":{
          "checkFraud": true
        }
    }'
                        

This request will return a kountResponse with a status of 'decline':

                            
curl --request POST \
  --url https://api.nexiopaysandbox.com/pay/v3/process \
    --header <Your Basic Auth> \
    --data '{
        "tokenex":{
            "token": <A previously saved Card Token>
        },
        "card":{
            "expirationMonth":"1",
            "expirationYear":"20"
        },
        "data": {
           "currency":"USD",
           "amount": 7,
           "customer": {
               "billToAddressOne": "1725 Slough Avenue"
           }
        },
        "processingOptions":{
          "checkFraud": true
        }
    }'
                        

While this request will return a kountResponse with a status of 'success':

                            
curl --request POST \
  --url https://api.nexiopaysandbox.com/pay/v3/process \
    --header <Your Basic Auth> \
    --data '{
        "tokenex":{
            "token": <A previously saved Card Token>
        },
        "card":{
            "expirationMonth":"1",
            "expirationYear":"20"
        },
        "data": {
           "currency":"USD",
           "amount": 5,
           "customer": {
               "billToAddressOne": "1725 Slough Avenue"
           }
        },
        "processingOptions":{
          "checkFraud": true
        }
    }'
                        

To test the Save Card endpoint, use any of the values listed in the table above in your request for a One-time Use Token. Then use the token to send a Save Card request.

Browser-based Encryption



Browser-based Encryption

Browser-based encryption gives you the ability to encrypt card numbers prior to tokenizing and storing them through Nexio.

  1. Contact integrations@nexiopay.com to obtain the public key.

  2. Request a One-time Use Token.

  3. Generate your page that contains the card number field.

  4. Accept the full credit card number through your form.

  5. Encrypt the card number using the provided public key.

  6. Submit the encrypted card number to Nexio via the Save Card endpoint using a client-side or server-side call.

    Nexio will then tokenize the card and store it. The card token will be included in the response.

    Below is an example of Steps 5 & 6, written in JavaScript:

<html>
//This example uses the JSEncrypt library.
//You may use any library you want for standard RSA encryption.
<script src="./jsencrypt.js"></script>
<script>
    //the full card number accepted through your form
    const cardNumber = '4111111111111111';
    //this is the sandbox public key provided by Nexio, contact integration support for a production key
    const publicKey = 'MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAvWpIQFjQQCPpaIlJKpeg irp5kLkzLB1AxHmnLk73D3TJbAGqr1QmlsWDBtMPMRpdzzUM7ZwX3kzhIuATV4Pe 7RKp3nZlVmcrT0YCQXBrTwqZNh775z58GP2kZs+gVfNqBampJPzSB/hB62KkByhE Cn6grrRjiAVwJyZVEvs/2vrxaEpO+aE16emtX12RgI5JdzdOiNyZEQteU6zRBRJE ocPWVxExaOpVVVJ5+UnW0LcalzA+lRGRTrQJ5JguAPiAOzRPTK/lYFFpCAl/F8wt oAVG1c8zO2NcQ0Pko+fmeidRFxJ/did2btV+9Mkze3mBphwFmvnxa35LF+Cs/XJHDwIDAQAB';

    const crypt = new JSEncrypt();
    crypt.setKey(publicKey);
    //the encrypted card number
    const encryptedNumber = crypt.encrypt(cardNumber);

    //Send a POST request to Nexio.
    fetch('https://api.nexiopaysandbox.com/pay/v3/saveCard', {
        method: 'POST',
        body: JSON.stringify({
            token: '<Your One-time Use Token>',
            card: {
                encryptedNumber: encryptedNumber,
                expirationMonth: '1',
                expirationYear: '2021',
                cardHolderName: 'Test Card'
            }
        })
    }).then((response) => {
        return response.json();
    }).then((response) => {
        //This response will contain the card token.
        console.log('response', response);
    }).catch((error) => {
        console.log('error', error);
    });
</script>
</html>
                        

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.

Although card data never touches your servers, this option changes your PCI liability from SAQ A to SAQ A-EP.

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

See this JSFiddle for an example of how to encrypt data to be tokenized: Fiddle

Find a Transaction



Finding a transaction created through the Nexio Payment iframe or Nexio Payment API

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

  1. Run a payment using the Nexio Payment iframe or the Nexio Payment API. The following is an example response:
                                        
    {
        "id": "eyJuYW1lIjoidXNhZXBheSIsInJlZk51bWJlciI6IjMwOTgzMzUyNDMiLCJtZXJjaGFudElkIjoiMTAwMDM5IiwicmFuZG9tIjoiMzA5ODMzNTI0MyIsImN1cnJlbmN5IjoiVVNEIn0=",
        "transactionDate": "2018-09-28T15:20:14.716Z",
        "transactionType": "sale",
        "transactionStatus": "pending",
        "amount": 1.15,
        "currency": "USD",
        "gatewayResponse": {
        "result": "Approved",
        "message": "Approved"
    }
    }
                                    
  2. Save the ID from the response. (This is called the original plugin ID. It may also be called the Payment ID on Nexio Dashboard.)
  3. Query the Transaction Service.
    Example request:
                                        
    curl --request GET \
        --url 'https://api.nexiopaysandbox.com/transaction/v3?plugin.originalId=eyJuYW1lIjoidXNhZXBheSIsInJlZk51bWJlciI6IjMwOTgzMzUyNDMiLCJtZXJjaGFudElkIjoiMTAwMDM5IiwicmFuZG9tIjoiMzA5ODMzNTI0MyIsImN1cnJlbmN5IjoiVVNEIn0=' \
        --header 'Authorization: <Your Basic Auth>''
                                        
                                    

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.

Address Verification Service (AVS)



Overview

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. This makes it easy for you to determine which cards to save, giving you greater control over your risk management.

Contact Integrations Support if you have questions about Address Verification.


Using AVS

To check AVS using the Nexio iframe:
  1. Use the table below to determine which AVS setting best suits your needs.
  2. Include the object
                                    
    "processingOptions": { "verifyAvs": yourAvsSetting }
                                
    in your data object when you send a request to the One-time Use Token endpoint.
  3. Use your One-time Use Token to load the Save Card iframe.

To check AVS using the Nexio API:
  1. Use the table below to determine which AVS setting best suits your needs.
  2. Include the object
                                    
    "processingOptions": { "verifyAvs": yourAvsSetting }
                                
    in your data object when you send a request to the Save Card endpoint.


AVS Response

When you check AVS your response will include an object in following format:

                        
"avsResults": {
    "matchAddress": true,
    "matchPostal": true,
    "gatewayResponse": { ... }
}
                    

Match Address

The results of the address check.

(In this case, 'address' refers to the street address portion of the billing address. Ex: 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.

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

Match Postal

The results of the postal code check.

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

  • 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.
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. In this case, you may wish to delete the card token using the Delete Card endpoint.



Testing AVS

In sandbox, address AND postal code match results are both triggered by specific postal codes. Please be sure to use only the test postal codes provided in the table here:

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


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
verifyAvs=0

You will not receive an avsResponse object.

verifyAvs=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
verifyAvs=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
verifyAvs=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
verifyAvs=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
verifyAvs=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

Security Code (CVC) Verification



Overview

The Nexio security code (CVC) verification feature allows you to save only those cards that pass a CVC check which helps to reduce your risk of fraud.


Using CVC Verification

To check CVC using the Nexio iframe:
  1. Include the following in your data object when you send a request to the One-time Use Token endpoint:
                                    
    "processingOptions": {
        "verifyCvc": true
    }
                                

    Note: The following uiOptions will be selected by default. You may adjust them as desired.

                                        
    "uiOptions": {
        "hideCvc": false,
        "requireCvc": true
    }
                                        
    See the CVC Verification Settings table for an explanation of how changing these settings will affect your iframe.

  2. Use your One-time Use Token to load the Save Card iframe.

To check CVC using the Nexio API:
  1. Include the following in your data object when you send a request to the Save Card endpoint:
                                    
    "processingOptions": {
        "verifyCvc": true
    },
    "card": {
        "securityCode": 111
    }
                                


Testing CVC 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


Response

Example Success Response
                            
{
  "token": {
    "firstSix": "411111",
    "lastFour": "1111",
    "success": true,
    "error": null,
    "cardType": "visa",
    "token": "9faacf0b-7198-4e93-b814-5f8448541474"
  },
  "card": {
    "expirationYear": "2021",
    "expirationMonth": "01",
    "cardHolderName": "George Washington",
    "cardType": "visa"
  },
  "data": {
    "customer": {
      "billToAddressOne": "123 Street",
      "billToAddressTwo": "Suite 232",
      "billToCity": "Amarillo",
      "billToState": "TX",
      "billToPostal": "56649",
      "billToCountry": "US",
      "firstName": "buck",
      "lastName": "wild",
      "orderNumber": "456",
      "invoice": "123",
      "customerRef": "123"
    },
    "customFields": {
      "custom1": "hi mom",
      "custom2": "P#dfk1234kdf"
    }
    "cvcResults": {
      "matchCvv": true,
      "error": false,
      "gatewayMessage": {
        "cvvresponse": "M",
        "message": "CVV2/CVC2 match"
      }
    },
  },
  "cardType": "visa"
}
                        

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


CVC 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
N/A
You will receive a 400 error, because the CVC cannot be verified when the field is hidden.

Test Cards



Test transactions can be submitted using the following information:

Issuer
Number
Visa
4111111111111111
Mastercard
5431111111111111
Discover
6011601160116611
American Express
341111111111111

Lodging Data



Overview

Merchants in the lodging industry can pass certain parameters that help qualify lodging transactions.

Sending Lodging Parameters

While the entire lodging object is optional, the following are the minimum required parameters to qualify lodging transactions:

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

  • Check-in Date
  • Check-out Date
  • Room Rate
  • Folio Number (Referred to as Order Number in Nexio)
  • Either of the following flags:
    • Advanced Despoit
    • No Show
To send lodging data using the Nexio iframe:
  1. Include the lodging object and the folio number, as shown below:
                                        
    "data": {
        "lodging": {
            "advanceDeposit": true,
            "checkInDate": "2018-12-31",
            "checkOutDate": "2019-01-05",
            "roomNumber": "14",
            "roomRate": 143.99,
            "noShow": false
        },
        "customer": {
            "orderNumber": 4567 //this is the folio number
        }
    }
                                    
    in your request to the One-time Use Token endpoint.

    Note: Folio number must be sent in the customer object, labeled 'orderNumber'.

  2. Use the token in the response from Step 1 to load the Run Credit Card Transaction iframe.


To send lodging data using the Nexio API:
  1. Include the lodging object and the folio number, as shown below:
                                        
    "data": {
        "lodging": {
            "advanceDeposit": true,
            "checkInDate": "2018-12-31",
            "checkOutDate": "2019-01-05",
            "roomNumber": "14",
            "roomRate": 143.99,
            "noShow": false
        },
        "customer": {
            "orderNumber": 4567 //this is the folio number
        }
    }
                                    
    in your request to the Run Credit Card Transaction iframe.

    Note: Folio number must be sent in the customer object, labeled 'orderNumber'.

Iframe Events

The following events may be emitted by various Nexio iframes.

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

Event
Description
Iframe
cardSaved
The card token has successfully been saved
Save Card, Retail Save Card
eCheckProcessed
The eCheck has successfully been processed
Run eCheck Transaction
eCheckSaved
The eCheck token has successfully been saved
Save eCheck
error
An error has occurred
All
formValidations
There are form validation errors
All
loaded
The iframe has finished loading
All
initiate
The user clicks 'confirm' to be redirected to the APM
APMs
processed
The credit card transaction has been processed
Run CC Transaction
submit
The form has been submitted
All
success
The credit card transaction has been processed
Retail Run CC Transaction

Using Webhooks



Overview

Nexio's Webhook Service allows you to configure webhooks to retrieve real-time information regarding events that occur in the Payment Service (iframes and/or direct API calls).

When the Webhook Service is set up, Nexio will send a POST request with event information to the specified endpoint. You may additionally choose to receive a signature header—allowing you to verify the webhook's authenticity.

Configuring Webhooks

Webhooks are configured on a merchant-by-merchant basis. Your user must have administrator rights to a merchant in order to configure webhooks.

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

Step 1:

Ensure your account has admin access to the Merchant ID you would like to configure.

Tip: You can see your access rights by sending a request to the Who Am I endpoint in the User Management Service.

Step 2:

Send a POST request to the Configure Merchant endpoint.

This request must include:

  • The merchant ID
  • The event type(s) that will trigger the webhooks
  • The endpoint to which the data will be sent

For example:


curl --location --request POST "https://api.nexiopaysandbox.com/webhook/v3/config" \
  --header "Authorization: <Your Basic Auth>" \
  --data "{
	"merchantId": "200039",
	"webhooks": {
		"TRANSACTION_AUTHORIZED": {
			"url": "https://your-company-webhook-url-here.com"
		},
		"TRANSACTION_CAPTURED": {
			"url": "https://your-company-webhook-url-here.com"
		}
	}
    }"

The example above will:

  • Configure the webhooks for merchant ID 200039
  • Send a POST request with event data to https://your-company-webhook-url-here.com when a transaction is authorized
  • Send a POST request with event data to https://your-company-webhook-url-here.com when a transaction is captured

Event Types

Below are the possible keys that can be included in the webhooks object.

Key
Description
TRANSACTION_AUTHORIZED
Webhook will be sent when a transaction is authorized
TRANSACTION_CAPTURED
Webhook will be sent when a transaction is captured
TRANSACTION_VOIDED
Webhook will be sent when a transaction is voided
TRANSACTION_REFUNDED
Webhook will be sent when a transaction is refunded
CARD_DATA_UPDATED
Webhook will be sent when card data has been updated

Configuring the Merchant Secret

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 set up a merchant secret:

Step 1:

Set up the Webhook Service for a merchant.

Tip: You can check a merchant's webhook configuration by sending a GET request to the Merchant Configuration endpoint.

Step 2:

Send a POST request to the Merchant Secret endpoint. Include the merchant ID to be configured in the body of your request.

Example:


curl --location --request POST "https://api.nexiopaysandbox.com/webhook/v3/secret" \
  --header "Authorization: <Your Basic Auth>" \
  --data "{
	"merchantId": "200039"
    }"

A successful request will return a response object containing the merchant secret. For example:

{
    "secret": "446946d5-bdd9-48c7-9504-0459d19c08e5"
}
Step 3:

Store the secret from the response in Step 2 in a secure location. You will use it later for signature verification.

Step 4:

When you receive webhook data, Nexio will include a signature in the header called Nexio-signature. This header will also include a timestamp.

Example:


Nexio-signature: t=1554146049,v1=f66f6c47e7288e4922629ffe87819678b793944c60668d8695804e4a2b9f90d1
                            

Use the Nexio-signature along with the shared secret and the response body to verify the authenticity of the data.


Verifying Webhook Signatures

Once you have set up the merchant secret, each webhook request from Nexio will include a header called Nexio-signature. This header include a timestamp and a signature.

Example:


Nexio-signature: t=1554146049,v1=f66f6c47e7288e4922629ffe87819678b793944c60668d8695804e4a2b9f90d1
                            

To verify a signature you will need the following:

  • The shared secret
  • The Nexio-signature header
  • The request body

See the steps below to get started, or jump to the Node.js example below.

Step 1:

Extract the signature and timestamp from Nexio-signature:

  1. Split the header string at the , character.
  2. Split each of the two strings at the = characters.
  3. Save the data following the t= as a variable. (For this example, we'll call it timestamp.)
  4. var timestamp = 1554146049;
  5. Save the data following the s= as a variable. (For this example, we'll call it signature.)
  6. var signature = f66f6c47e7288e4922629ffe87819678b793944c60668d8695804e4a2b9f90d1;
Step 2:

Save the request body as a variable—we'll call it body.

Step 3:

Create the payload:

  1. Concatenate timestamp and body with a . character in between.
  2. Save the above as a variable—we'll call it payload.
  3. 
    var payload = '1554146049.<JSON request body>'
                                        
Step 4:

Create an HMAC using the SHA256 hash function. Use the secret as the key and the payload as the message.

This is the expected signature.

Step 5:

Compare the expected signature from Step 4 with the signature you received.


Below is an example of Steps 1-5 written in Node.js:


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

PayPal



Accept payments from consumers using PayPal in two steps:

Step 1: Obtain a one-time use token

Step 2: Redirect shopper to PayPal to complete payment

You can perform the following transaction types:

  • Sale: simultaneous authorization and capture (settles automatically)
  • Auth only: authorize a transaction to be captured at a later time
  • Capture: capture a previously authorized transaction
  • Void: void/cancel an auth only transaction
  • Refund: fully or partially refund captured or settled transactions

Sale

To perform a sale, set isAuthOnly to false when requesting the one-time use token or omit isAuthOnly from the request completely. See Step 1: Obtain a one-time use token below.

Auth only

To perform an auth only to be captured at a later time, set isAuthOnly to true when requesting the one-time use token. See Step 1: Obtain a one-time use token below.

Step 1: Obtain a one-time use token

Send a GET request to the One-Time Use Token endpoint.

https://api.nexiopaysandbox.com/apm/v3/token

See Get One-Time Use Token under Alternative Payment Methods for a list of body parameters.

Example body (sale):

{
    "isAuthOnly": false,
    "data": {
    "amount": 25.2,
    "currency": "USD",
    "paymentMethod": "payPal",
    "description": "test purchase",
    "customer": {
    "orderNumber": "1029384756",
    "firstName": "Buck",
    "lastName": "Wild",
        "customerRef": "12345",
        "email": "buck.wild@email.fake",
        "billToAddressOne": "123 Bill Street",
        "billToAddressTwo": "Suite 232",
        "billToCity": "Amarillo",
        "billToState": "TX",
        "billToPostal": "56649",
        "billToCountry": "US",
        "shipToAddressOne": "123 Ship Street",
        "shipToAddressTwo": "Suite 323",
        "shipToCity": "Amarillo",
        "shipToState": "TX",
        "shipToPostal": "56649",
        "shipToCountry": "US"
    }
  },
  "processingOptions": {
      "webhookUrl": null,
      "webhookFailUrl": null,
      "merchantId": “100100”
  }
}

Example body (auth only):

{
    "isAuthOnly": true,
    "data": {
    "amount": 25.2,
    "currency": "USD",
    "paymentMethod": "payPal",
    "description": "test purchase",
    "customer": {
    "orderNumber": "1029384756",
    "firstName": "Buck",
    "lastName": "Wild",
        "customerRef": "12345",
        "email": "buck.wild@email.fake",
        "billToAddressOne": "123 Bill Street",
        "billToAddressTwo": "Suite 232",
        "billToCity": "Amarillo",
        "billToState": "TX",
        "billToPostal": "56649",
        "billToCountry": "US",
        "shipToAddressOne": "123 Ship Street",
        "shipToAddressTwo": "Suite 323",
        "shipToCity": "Amarillo",
        "shipToState": "TX",
        "shipToPostal": "56649",
        "shipToCountry": "US"
    }
  },
  "processingOptions": {
      "webhookUrl": null,
      "webhookFailUrl": null,
      "merchantId": “100100”
  }
}

Example response:


{
  "expiration": "2019-07-12T22:19:58.000Z",
  "token": "76721796-05a9-4d3e-b295-3f38612157dd"
}

Step 2: Redirect shopper to PayPal to complete payment

The can be done by either:

Both options will create a popup window in which the user will be able to complete the payment via PayPal.

We recommend using Nexio's redirect iframe as it will:

  • Create the new popup within the correct time frame (as required by popup blockers)
  • Provide an error message if the user closes the popup prematurely
If you choose to redirect using your own button you will need to handle the above in your own code base.

If using Nexio’s redirect iframe:

  1. Create an iframe on your checkout page.
  2. Append the one-time use token from Step 1 to the Alternative Payment Method iframe URL as a query parameter called token.

    The result will look like this:

    https://api.nexiopaysandbox.com/apm/v3?token=477d626c-9d29-46cf-8a41-abab04874eac

  3. Assign the URL above to your iframe's src tag. For example:
    
    var iframeBaseUrl = "https://api.nexiopaysandbox.com/apm/v3";
    var oneTimeUseToken = "?token=477d626c-9d29-46cf-8a41-abab04874eac";
    
    var url = iframeBaseUrl + oneTimeUseToken;
    window.document.getElementById('myIframe').src = url;
                                    

Shoppers will be asked to confirm whether to proceed with the redirect for payment. The PayPal login page will be opened in a new tab in the browser where the shopper will complete the payment.

Note: This iframe will emit events, alerting you when the transaction has been submitted, processed, etc. You will also receive an error event if the user closes the popup window prior to completing the transaction.

If using your own button:

  1. Create a button on your checkout page.
  2. Append the one-time use token from Step 1 to the Alternative Payment Method popup URL as a query parameter called token.

    The result will look like this:

    https://api.nexiopaysandbox.com/apm/v3/popup?token=477d626c-9d29-46cf-8a41-abab04874eac

  3. Use the button to trigger the creation of a popup window directing the user to the above URL. For example:
    
    window.popup = window.open('https://api.nexiopaysandbox.com/apm/v3/popup?token=477d626c-9d29-46cf-8a41-abab04874eac', '_blank');
    window.popup.parent = window;
                                    

Shoppers will be redirected to the PayPal login page in a new tab in the browser where the shopper will complete the payment.

Note: If you use this option Nexio will be unable to alert you if the user closes the popup window prior to completing the transaction.

Transaction response

Once transactions are completed, the PayPal window will be closed automatically.

We recommend using the events emitted by the iframe or popup to display your own success or failure page to the shopper.

Example response (sale):

{
  "id": "eyJuYW1lIjoicGF5UGFsIiwibWVyY2hhbnRJZCI6IjEwMDAzOSIsInJlZk51bWJlciI6IjBLWDc4MjMwVUM3Nzg4NDRNIiwicmFuZG9tIjowLCJjdXJyZW5jeSI6InVzZCJ9",
  "merchantId": "100100",
  "transactionDate": "2019-07-12T20:25:58.711Z",
  "transactionStatus": "settled",
  "amount": 25.2,
  "transactionType": "sale",
  "currency": "USD",
  "gatewayResponse": {
    "result": 201,
    "refNumber": "0KX78230UC778844M",
    "gatewayName": "payPal",
    "message": 201
  },
  "data": {
    "amount": 25.2,
    "currency": "USD",
    "settlementCurrency": "USD",
    "customer": {
      "lastName": "Wild",
      "shipToAddressOne": "123 Ship Street",
      "orderNumber": "1029384756",
      "shipToCountry": "US",
      "shipToAddressTwo": "Suite 323",
      "billToState": "TX",
      "billToCity": "Amarillo",
      "firstName": "Buck",
      "shipToCity": "Amarillo",
      "customerRef": "12345",
      "billToAddressOne": "123 Bill Street",
      "shipToPostal": "56649",
      "billToCountry": "US",
      "billToPostal": "56649",
      "billToAddressTwo": "Suite 232",
      "email": "buck.wild@email.fake",
      "shipToState": "TX"
    }
  }
}

Example response (auth only):

{
  "id": "eyJuYW1lIjoicGF5UGFsIiwibWVyY2hhbnRJZCI6IjEwMDAzOSIsInJlZk51bWJlciI6IjJZTTUzNzU2OUMyMTkyMTFKIiwicmFuZG9tIjowLCJjdXJyZW5jeSI6InVzZCJ9",
  "merchantId": "100100",
  "transactionDate": "2019-07-12T20:22:26.936Z",
  "transactionStatus": "authOnly",
  "amount": 25.2,
  "transactionType": "sale",
  "currency": "USD",
  "gatewayResponse": {
    "result": 201,
    "refNumber": "2YM537569C219211J",
    "gatewayName": "payPal",
    "message": 201
  },
  "data": {
    "amount": 25.2,
    "currency": "USD",
    "settlementCurrency": "USD",
    "customer": {
      "lastName": "Wild",
      "shipToAddressOne": "123 Ship Street",
      "orderNumber": "1029384756",
      "shipToCountry": "US",
      "shipToAddressTwo": "Suite 323",
      "billToState": "TX",
      "billToCity": "Amarillo",
      "firstName": "Buck",
      "shipToCity": "Amarillo",
      "billToAddressOne": "123 Bill Street",
      "shipToPostal": "56649",
      "billToCountry": "US",
      "billToPostal": "56649",
      "billToAddressTwo": "Suite 232",
      "email": "buck.wild@email.fake",
      "shipToState": "TX"
    }
  }
}

Capture an auth only PayPal transaction

Send a POST request to the Capture APM Transaction endpoint to capture a previously authorized (auth only) transaction.

https://api.nexiopay.com/apm/v3/capture

See Capture APM Transaction for an example request and response.

Void an auth only PayPal transaction

Send a POST request to the Void APM Transaction endpoint to void or cancel a previously authorized (auth only) transaction. Captured and settled transactions cannot be voided and must be refunded.

https://api.nexiopaysandbox.com/apm/v3/void

See Void APM Transaction for an example request and response.

Refund a PayPal transaction

Send a POST request to the Refund APM Transaction endpoint to refund a previously captured or settled transaction.

https://api.nexiopaysandbox.com/apm/v3/refund

See Refund APM Transaction for an example request and response.