Secure Payments API – Update Transaction Status


You may need to update Secure Payments (formerly PCI Wallet) transaction statuses based on a returns file received from a bank or other ACH processor. This article will cover the ways to do this using the Secure Payments API.

Status Update Endpoint

To update the status of a Secure Payments transaction, you can use the following endpoint:


Your payload should look something like:

"message":"Transaction Failed",
"reason_code": "R01"
  • message - The message should help you remember the reason for changing the transaction's status. This value is a string, and can be whatever you'd like.
  • status - the status can potentially be any of the following: PROCESSING, FAILED, or SETTLED SUCCESSFULLY. For transactions, the status can also be VOIDED.
  • reason_code - this can be a NACHA R-Code or a CPA-005 return reason code. If a reason code is not needed, leave it out of the body
Voiding a transaction relies on the integrated processor's ability to void it. If the payment processor is unable to void the transaction, you will be unable to change the transaction to the VOIDED status in Secure Payments.

Here's a sample response:


"transaction": {

"message": "Transaction was approved",




You can try it either on the example below or on our ReadMe page: Update Tx Status

If you need to search for a transaction, the example below will illustrate how this is done.

CSV Import

Create the File

You also have the option to use a CSV import to change the status of transactions. The first thing you will need to do is create the file.

You can create the CSV file that will be used to update transaction statuses either from a NACHA returns file, a CPA-005 return reasons file, or based on your own data. Make sure the file is in comma separated values (CSV) format.

The file you upload needs the headers "id",  "newStatus", "nachaRcode", and "comments". The rows beneath should contain transaction IDs for transactions from Secure Payments. If you are creating a plain text file, it should look like this:

1642834,FAILED,R01,Insufficient Funds

If you are creating the file in a spreadsheet program, it should look like this:














Insufficient Funds

This information should help you create the file properly:



Value Options


This is the transaction ID from Secure Payments. Each row represents a separate transaction.

Numeric Value


This is the status the transaction is changing to.



This is the NACHA return code (usually included on the returns file from the institution that processed the payments).

This is typically R and an integer value (e.g. R01). For a list of supported return codes, see this article.


This includes any comments you want to make. Comments are usually the reason for the status change. Comments will be added as the TX History Note for the transaction inside Secure Payments.

Alphanumeric and special characters.

Note: If no R-code is available or applicable for a transaction, you may use the code R100. This will allow the file to be validated and imported without any errors. This return code may also be used when updating transactions through the API endpoint.

Import Process

Once the file is created, the basic process for uploading, validating, and importing the file will look like this:

Get a URL

The first step in the process is to get the URL where the file will be uploaded. The URL will be to Amazon's simple storage service (S3) within the Simnang account. The URL will contain paramaters that authorize the upload. The URL will expire a few minutes from the time it is generated, so only generate the URL if you are planning to use it immediately.

The URL can be generated by sending a POST request to the endpoint:

The URL it returns will look something like this:

The example below demonstrates how to generate a URL:

Upload a File & Validate

Now that you have a URL, you can upload your file. Send a PUT request to the generated URL with your file as the body. Uploading the file to the endpoint will also start the validation process. Once the validation is complete, you will receive an email with the validation results. The email will be sent to the primary email for the Secure Payments account. Validation results will be delivered in a CSV file in the same order as transactions in your uploaded file. The validation errors will look something like this: {:errors {:transaction "Transaction with specified ID does not exist", :new_status #{"can't be blank"}}}.

Fix any errors and re-upload the file.

Import the File

Once the file is error free, you can import it. In order to import the file, you will first need to know the ID of the file. The ID is used in the import endpoint. To find the file ID, send a GET request to the endpoint:

This should return results that look similar to this:

"id": 2461,
"import_key": "",
"verify_key": "",
"source_key": "",
"imported": false,
"verified": false,
"created": "2019-07-15 17:00:03",
"updated": "2019-07-15 17:00:03"
"id": 2462,
"import_key": "",
"verify_key": "",
"source_key": "",
"imported": false,
"verified": false,
"created": "2019-07-15 17:08:12",
"updated": "2019-07-15 17:08:12"

The example below demonstrates how to get the file information:

Once you have the ID, set a POST request to the endpoint:{import-id}

Replace the {import-id} piece of the URL with the ID of your import file. The final URL will look something like this:

The example below demonstrates how to do this. Remember to replace the {import-id} piece of the URL with a valid file ID.

Once the file has been imported, you will get an email notifying you of the import's completion. The email will contain a link to a CSV that will show the results of your import including the IDs of each transaction and a success message for each.

How did we do?

Powered by HelpDocs (opens in a new tab)