Guides

Authentication

The Nexio API requires authentication for certain endpoints.

These endpoints ask for one of the following types of authentication:

Basic authentication

To authenticate with basic authentication you need a Nexio API username and password.
To get this information, go to the Dashboard. Then, navigate to Settings > User Management to view and add users. For the API user, click it. Copy the username and the API key (this is the password).

After you have a username and password for use with the API, you need to encode it into Base64 so you can use it in the necessary API requests:

  1. Get your username and password.

  2. Open a Unix prompt, such as Cygwin (on Windows) or Terminal (on Mac OS X).

  3. Encode your Nexio username and password into Base64.

    Type echo -n, then your username and a colon and your password, then a pipe ( | ), and finally base64.

    For example, if your username is user_e32bae8627c612ab8e92a629d57f75fb and your password is apiKey_Bq3wxtDRT2Jn0b, type the following and press Enter:

    $ echo -n user_e32bae8627c612ab8e92a629d57f75fb:apiKey_Bq3wxtDRT2Jn0b | base64

    Copy the resulting Base64-encoded string to a secure location so that you can use it in any necessary Nexio API requests.

  4. Create the Authorization header for your request by appending your encoded string from step 3.

    The header takes the following form Authorization: Basic [encoded_string], as in the following example:

    Authorization: Basic bXluYW1lQG5leGlvaHViLmNvbTpteXBhc3N3b3Jk

  5. Include the Authorization header when sending a request that requires "Basic Auth".

    For example, a request of the Save card token endpoint using cURL could look similar to the following:

    curl --request POST \
  --url https://api.nexiopaysandbox.com/pay/v3/saveCard \
  --header 'Authorization: Basic bXluYW1lQG5leGlvaHViLmNvbTpteXBhc3N3b3Jk' \
  --header 'Content-Type: application/json' \
  --data '{
    "card": {
      "cardHolderName": "John H Doe",
      "encryptedNumber": "cu3yRktaYFK2LUC6DpNK289tYDsGRCi7ctk2763QkvZiQQ==",
      "expirationMonth": 12,
      "expirationYear": 24
    },
    "token": "eb50a022-d6de-4244-a1e6-dcb8522b2d19"
  }'

    And a successful response looks similar to the following:

    {
"token": {
    "firstSix": "400010",
    "lastFour": "1222",
    "token": "f2a368c9-d3cb-4f12-9561-eff4395429f7"
},
"data": {
    "customer": {...}
},
"card": {
    "expirationYear": "24",
    "expirationMonth": "12",
    "cardHolderName": "John H Doe"
},
"merchantId": "100039",
"shouldUpdateCard": true,
"avsResults": {...}
}

See also

One-time-use tokens

📘

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 from a browser, you will receive an error.
  • One-time-use tokens for ecommerce 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.

Ecommerce

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

To get a one-time-use token, do the following:

  1. Send a request to the ecommerce one-time-use token endpoint.
  2. Authenticate using basic authentication.
  3. Include any information you want to pass along to the applicable iframe or window in the body of your request. See the ecommerce one-time-use token API reference for a complete list of parameters.

Requesting a one-time-use token

A good place to start getting familiar with our API is by sending a request to the Create one-time-use token endpoint.

A successful request to this endpoint returns a token that you use in making many Nexio API requests.

For the following request, you are requesting a one-time-use token to load an ecommerce iframe for running a card transaction. To do this, complete the following steps:

  1. Generate your Authorization header by completing steps 1-4 in the Basic authentication tutorial.

    You will use this header in step 2.

  2. Send a POST request to the "Create one-time-use token" endpoint.

    Include the Authorization header from step 1 in the request.

    The available and required parameters for the --data element in the request differ based on the iframe to be loaded. For the iframe to run a card transaction (runCardTransactionIframe), you only need to include the data.currency and data.amount parameters. For this example, let's use USD as the currency and the amount of 12.95.

    The following example uses cURL for sending the request:

    curl --location --request POST 'https://api.nexiopaysandbox.com/pay/v3/token' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Basic bXluYW1lQG5leGlvaHViLmNvbTpteXBhc3N3b3Jk' \
  --data '
    "data": {
      "currency": "USD",
      "amount": 12.95
    }
  '




    {
  "expiration": "2022-11-14T23:28:55.000Z",
  "token": "0d36478c-d7ec-4b22-bd81-5c4606bad779",
  "fraudUrl": "https://api.nexiopaysandbox.com/pay/v3/fingerprint?token=0d36478c-d7ec-4b22-bd81-5c4606bad779"
}

    Use the resulting token for any Nexio API requests that require an "API key", such as Run card transaction with iframe.

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, do the following:

  1. Send a request to the one-time-use token (APM) endpoint.
  2. Authenticate using basic authentication.
  3. Include any information you wish to pass along to the iframe in the body of your request. See the specific payment method in the Alternative Payment Methods section for a complete list.

See Also

Updated 8 months ago