Update transaction status via import

How to update the status of multiple transactions with a file import.

Introduction

Transactions within batch files sometimes fail—most commonly due to a bank account with insufficient funds to complete a transfer. When this happens, the financial institution that processed the transfers will issue a file that contains returned or "failed" transactions and includes a return code (also referred to as an R-Code). This file from your bank can then be formatted and uploaded to Secure Payments to change the status of the returned transactions en masse.

In this guide, we explain how to use Secure Payments' import tool to update the statuses of multiple transactions that were submitted via a NACHA or CPA-005 batch.

Updating transactions via import

Complete the following steps to update the transactions returned from the financial institution.

1. Format the .csv file

After receiving the returns file from the financial institution, the information needs to be reformatted for Secure Payments' import tool. Secure Payments expects information presented in a .csv file formatted like the following:

idnewStatusnachaCodecomments
1194582FAILEDR01Insufficient Funds
2194594FAILEDR01Insufficient Funds

Download a sample file ↗

2. Generate an upload URL

Next, generate an upload URL to submit the formatted .csv file. To generate an upload URL, send a POST request to the following endpoint:

POST  https://securepayments.loanpro.io/api/transactions/status-update-validate
Authorization: {token}
Secret: {token}

Please note: the upload URL will expire 15 minutes from the time it is generated.

An upload URL will be included in the response:

https://easypay-import.s3.amazonaws.com/input/4004/2024-06-14/import-source-transactions-1718380676638%28afc75a86-7f57-4f43-b306-7e2f378ab5a4%29transactions_validate.csv?X-Amz-Security-Token=IQoJb3JpZ2luX2VjEBAaCXVzLWVhc3QtMSJHMEUCIDKgfvLele3j8MDhA7FbEaV0azW1L3lyODd9RO52pNGwAiEA2emAQf5w6UXTOD6XrCl8Gr5NmEXiPRbXJttjyyckFcAqxAUIqf%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FARAFGgwyMjMyNDQxMTgwNDciDC2JrGhUp2O1pfFnZCqYBejN2DmG1A1up%2B3l%2BncZ6O9XdNqaonnG5DQtrJ2AUcKRzWwjp1iJD1EHMnA62AgxfFyB7c2T0xKb%2BDIPrb1pL5fYOWJEkHprnDzwWXz802fIkTuniMaJl59JBkDZ%2FRM%2FakUDLtqvVHu0%2Bnc84Dodfh1RkQxgXqEgip4r4ToLvA00Ibar9ESkeADBezTIjgulY0wDR%2BWCNqH3D0qTOzmNmRVwXmsKmEj56zOW1bNV4kB3B8lKuJ%2Fldxde5UyT7hKfFeZ0qJIEs1rHDFf53nm8dQf%2B0fEGD%2FpV5uzA%2BgzceMKFWuNDP3a3JGzqcL9KaU%2BVIEe5vK2F2rlFl3mjV0E8h5njv0Vs1bqLK3vrpwt8FoOH%2BnHnzStsS2MEJ0G%2BCLoj4el9UN3gkSxRaAFCAj2mHTwQgw1uzeEqaqjawi%2FfjwbXGcNM5%2BeD%2Fl9ye%2F6%2FXDC8itasXdDoQ8qVFuAXV%2BhAxA1yCVRNiAqSqYbjNmu5poaynyZipkrcybtLfn4wGAKNSnCeCnETpAFZHmuGysZJwpZqxJI8nZTfwp%2BGy%2BaCDU9%2F5pWpxjIkunIujomXMDFD55XAKeWbFYFKt5E11fucfxJuX7AyFd8jhsls2%2FYOMvsf915dmsSeKvr9KGDC28m85wjF8SQiX63pb8f0bBXIid4NRSMY%2BbAq%2F5IWSWouLXks%2BsjQ%2FtthSNBuTQEm%2FFQ%2BBIbmEW1c5g%2BtHTyevOBfuyH2zG3B5kv1yk4rJxwAn%2Fb%2BGd76XnqB%2FHccn4h%2Br%2FGn%2FDYe5p%2BpGxw26cb3PWsCxF1IfaOmC0iEHjnyQcGERp6bk9TuiyOoQ1bbUpU9tzPaHtuC4rzSG%2BsLFG8CkaKWfXv%2FVCE8MtIP5F6Z67FFes3xfPm4EvH8P8gwzsyxswY6sQHHBHdEdLvZdDO7SgSJP4eNy0gV%2FSizecdZ3X%2BDFzVf36%2BOt0%2BIVs2TKeK14EiLw7GxMuV84AAKxYiy8e2%2FffuFqa6nCsLw8X%2FmZkW9cMiPMwPpVgQrXQLKBRSRgXaJRvc2mMPZjf67ow66cEkkgNu5MJ%2Fp%2FqGuqi4IElo7BCGBYkT9tnlyVeXbTDLCis%2Fq8pRLA1kAzdL6ReedL0YM%2B%2BFMXOvyh07H2v5dx3gaRt%2BkobA%3D&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20240614T155756Z&X-Amz-SignedHeaders=host&X-Amz-Expires=900&X-Amz-Credential=ASIATH6TC5AP7A2OCV3S%2F20240614%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Signature=65909d372eb466f38d2dd5119531a75254943d8eed995b92924048cda3345416

Store the URL for the next step.

3. Upload and verify the file

Each file that's imported into Secure Payments has three status values that signify its progress in the import process:

  1. Uploaded
  2. Verified
  3. Imported

In this step, the file will be uploaded; and if the file has formatted correctly, the system will automatically verify it as well.

Using the URL generated via the previous step, upload the formatted import .csv file by sending a PUT request to the URL. This request uses no headers:

PUT https://easypay-import.s3.amazonaws.com/input/4004/2024-06-14/import-source-transactions-1718380676638%28afc75a86-7f57-4f43-b306-7e2f378ab5a4%29transactions_validate.csv?X-Amz-Security-Token=IQoJb3JpZ2luX2VjEBAaCXVzLWVhc3QtMSJHMEUCIDKgfvLele3j8MDhA7FbEaV0azW1L3lyODd9RO52pNGwAiEA2emAQf5w6UXTOD6XrCl8Gr5NmEXiPRbXJttjyyckFcAqxAUIqf%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FARAFGgwyMjMyNDQxMTgwNDciDC2JrGhUp2O1pfFnZCqYBejN2DmG1A1up%2B3l%2BncZ6O9XdNqaonnG5DQtrJ2AUcKRzWwjp1iJD1EHMnA62AgxfFyB7c2T0xKb%2BDIPrb1pL5fYOWJEkHprnDzwWXz802fIkTuniMaJl59JBkDZ%2FRM%2FakUDLtqvVHu0%2Bnc84Dodfh1RkQxgXqEgip4r4ToLvA00Ibar9ESkeADBezTIjgulY0wDR%2BWCNqH3D0qTOzmNmRVwXmsKmEj56zOW1bNV4kB3B8lKuJ%2Fldxde5UyT7hKfFeZ0qJIEs1rHDFf53nm8dQf%2B0fEGD%2FpV5uzA%2BgzceMKFWuNDP3a3JGzqcL9KaU%2BVIEe5vK2F2rlFl3mjV0E8h5njv0Vs1bqLK3vrpwt8FoOH%2BnHnzStsS2MEJ0G%2BCLoj4el9UN3gkSxRaAFCAj2mHTwQgw1uzeEqaqjawi%2FfjwbXGcNM5%2BeD%2Fl9ye%2F6%2FXDC8itasXdDoQ8qVFuAXV%2BhAxA1yCVRNiAqSqYbjNmu5poaynyZipkrcybtLfn4wGAKNSnCeCnETpAFZHmuGysZJwpZqxJI8nZTfwp%2BGy%2BaCDU9%2F5pWpxjIkunIujomXMDFD55XAKeWbFYFKt5E11fucfxJuX7AyFd8jhsls2%2FYOMvsf915dmsSeKvr9KGDC28m85wjF8SQiX63pb8f0bBXIid4NRSMY%2BbAq%2F5IWSWouLXks%2BsjQ%2FtthSNBuTQEm%2FFQ%2BBIbmEW1c5g%2BtHTyevOBfuyH2zG3B5kv1yk4rJxwAn%2Fb%2BGd76XnqB%2FHccn4h%2Br%2FGn%2FDYe5p%2BpGxw26cb3PWsCxF1IfaOmC0iEHjnyQcGERp6bk9TuiyOoQ1bbUpU9tzPaHtuC4rzSG%2BsLFG8CkaKWfXv%2FVCE8MtIP5F6Z67FFes3xfPm4EvH8P8gwzsyxswY6sQHHBHdEdLvZdDO7SgSJP4eNy0gV%2FSizecdZ3X%2BDFzVf36%2BOt0%2BIVs2TKeK14EiLw7GxMuV84AAKxYiy8e2%2FffuFqa6nCsLw8X%2FmZkW9cMiPMwPpVgQrXQLKBRSRgXaJRvc2mMPZjf67ow66cEkkgNu5MJ%2Fp%2FqGuqi4IElo7BCGBYkT9tnlyVeXbTDLCis%2Fq8pRLA1kAzdL6ReedL0YM%2B%2BFMXOvyh07H2v5dx3gaRt%2BkobA%3D&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20240614T155756Z&X-Amz-SignedHeaders=host&X-Amz-Expires=900&X-Amz-Credential=ASIATH6TC5AP7A2OCV3S%2F20240614%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Signature=65909d372eb466f38d2dd5119531a75254943d8eed995b92924048cda3345416

If you're using Postman to test this process, set the body of your request to binary and select the .csv file from the 'Select file' dropdown menu.

A successful request will result in a 200 response code with no response body. At this point in the process, a file has been uploaded to Secure Payments and its data has been verified. Next, the file needs to be imported to be added to your account.

4. Import the verified file

Secure Payments assigns all uploaded files an ID, and the ID of the upload is required to complete the import process. Before importing the file, first pull the file upload ID.

To find the ID of the file upload, send the following request:

GET https://securepayments.loanpro.io/api/import/all
Authorization: {token}
Secret: {token}

A successful request will result in a response formatted like the following:

[
    {
        "id": 8701,
        "import_key": "",
        "verify_key": "output/4004/2024-06-14/-transaction-update-verify-1718380717066.csv",
        "source_key": "input/4004/2024-06-14/import-source-transactions-1718380676638(afc75a86-7f57-4f43-b306-7e2f378ab5a4)transactions_validate.csv",
        "imported": false,
        "verified": true,
        "created": "2024-06-14 15:57:56",
        "updated": "2024-06-14 15:58:37"
    }
]

This response lists the import progress of the file, when it was created and last updated, and its ID. Please note that this request will list all Using the value stored within the "id" field, next send the following request to import the file:

POST https://securepayments.loanpro.io/api/transactions/status-update/8701
Authorization: {token}
Secret: {token}
Transaction update scheduled

If successful, the file import will be scheduled and, once the import is completed, a notification will be sent to the email address associated with your Secure Payments account.