Guides

Creating a save echeck page with your own form

Background
Before starting this tutorial, make sure you understand the following topics from the Quick start section:

A save echeck page allows you to gather echeck information (also known as tokenization) from a customer for use in a future transaction.

While Nexio recommends that you use the iframe for saving the echeck information, you can instead use your own form. This option allows you to more easily customize the look and feel of the form even if your PCI liability is increased.

📘

Note

Although bank data never touches your servers, using your own form changes your PCI liability from SAQ A to SAQ A-EP.

To create a save echeck page that uses your own form, do the following:

  1. Create a form on your web page, as in the following example:

    <html>
  <body>
    <form id="myForm">
    </form>
  </body>
</html>

  2. Add fields to your form to capture any information you need and want to capture echeck information to save.

    The following fields are required by Nexio:

    • Account holder name (bank.accountHolderName)
    • Routing number (bank.routingNumber)
    • Account number (bank.encryptedBankAccountNumber)
      (Your form should accept the full account number, which you will then encrypt prior to sending it to Nexio—see step 5)

    You may include any additional fields listed in the Save echeck token endpoint.

    Create a Form on Your Web Page

    <html>
    <form id="myForm">
    </form>
</html>

  3. Send a POST request to the Create one-time-use token endpoint.
    Any processingOptions must be included in this request. (See the endpoint reference for more information about this object.)

    If you do not need any parameters, you can pass nothing in the body, as in the following example:

    curl -X POST https://api.nexiopaysandbox.com/pay/v3/token \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H 'Authorization: Basic [Base64_encoded_login]'
    -d '{}'


    {
    "expiration": "2022-03-14T15:43:05.664Z",
    "fraudUrl": "https://api.nexiopaysandbox.com/pay/v3/fingerprint?token=830d36f6-a5e3-4455-9600-3a55b63e2fc2",
    "token": "830d36f6-a5e3-4455-9600-3a55b63e2fc2"
}

    You will use the token in step 6.

    👍

    Try it out . . .

    1. Go to the Create one-time-use token endpoint.
    2. In the main content area, click the "SAVE CARD TOKEN API REQUEST" option.
    3. In the right pane, type your API username and password.
    4. Select the coding language you want to use (or leave the default selection).
    5. Click the Try It! button.
      See the token in the Response area.

    Add code to your page that captures the information that the customer types in the form fields, especially the card number.

  4. Prior to sending the bank information to Nexio, you must encrypt it using browser-based encryption, as in the following steps:

    a. While testing in the sandbox environment, use the sandbox public key indicated below.
    For the production environment, contact us to obtain the 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 page 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. Echeck tokens can be used to process through any MID on your account. They are not restricted to a specific merchant account or currency.

    🚧

    Important

    If you do not perform browser-based encryption in the account holder's browser, you have full PCI liability. If you use a server-based system for encryption, you can use RSA-SHA256/SHA512 for the encryption.


  5. Send the encrypted bank account number and other echeck information from your form fields to your backend server.

  6. When the customer accesses the save echeck page, completes the form, and submits the information, send a POST request from your backend server to the Save echeck token endpoint with the one-time-use token from step 3 (as the token parameter) and any card information you want to include, as in the following example:

    curl -X POST https://api.nexiopaysandbox.com/pay/v3/saveECheck \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic [Base64_encoded_login]'
  -d '{
  "bank": {
    "accountHolderName": "John Doe",
    "routingNumber": "231375151",
    "encryptedBankAccountNumber": "cu3yRktaYFK2LUC6DpNK289tYDsGRCi7cO+GeG0hkeYFvT7Y8/oY5r53obMz6Q/BZ38gk2u2Ufwy8ojBcX2sfNjG5jplGTXA4NNlSIUjMFfiHe1sff1JFpThoiW/IIlifGlbWu+S1/9pqWPTzJ2+DcjwohbHzsDahhYewFhXgC8qsK0ypi/Shlp+CwRITyIvbVXESD0xz3YOTRHeZLlChvVqN8z4ZzN8nm0MXkmT1wcpYI73bH4KdnPwNU3s7XxvP/ernQP73SHHAOKSLlz4F6AEHFjJiCoXzeLF7LwEjRdxDJ0sKVXbRk3i9BGh+8Nle2VYgjpUWtk2763QkvZiQQ=="
  },
  "token": "[one-time-use-token]"
}'

    👍

    Try it out . . .

    1. Go to the endpoint.

    2. Type your username and password in the Authentication section.

    3. Type the token you got in step 3 above in the token field.

    4. Use the main area with the objects and parameters to replace any content in the body that you want. For example, with the encryptedNumber for your own test card.

      For example:

      "bank": {
     "accountHolderName": "John Doe",
     "encryptedBankAccountNumber": "cu3yRktaYFK2LUC6DpNK289tYDsGRCi7cO+GeG0hkeYFvT7Y8/oY5r53obMz6Q/BZ38gk2u2Ufwy8ojBcX2sfNjG5jplGTXA4NNlSIUjMFfiHe1sff1JFpThoiW/IIlifGlbWu+S1/9pqWPTzJ2+DcjwohbHzsDahhYewFhXgC8qsK0ypi/Shlp+CwRITyIvbVXESD0xz3YOTRHeZLlChvVqN8z4ZzN8nm0MXkmT1wcpYI73bH4KdnPwNU3s7XxvP/ernQP73SHHAOKSLlz4F6AEHFjJiCoXzeLF7LwEjRdxDJ0sKVXbRk3i9BGh+8Nle2VYgjpUWtk2763QkvZiQQ==",
     "routingNumber": "231375151"
   },
   "token": "[one-time-use-token]"
 }

    5. Click the Try It! button.
      The response shows the HTML returned to the iframe.

  7. Listen for Nexio's response with an event listener or webhook.
    If Nexio returns a 200 status:

    • Save the echeck token (token.token). You will need this echeck token to run a transaction as well as to view, edit or delete the echeck token.
    • Display a success page to the customer.

    If Nexio returns a non-200 status:

Contact Integrations Support if you need additional help.

Updated about 1 month ago