Secure Payments API Update Transaction Status

General

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 in which this can be done using the Secure Payments API.

Status Update Endpoint

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

PUT https://pciwallet.simnang.com/api/transactions/{transaction-id}

Your payload should look something like:

{  
"transaction":{
"message":"Transaction Failed",
"status":"FAILED",
"reason_code": "R01"
}
}
  • message - the message should help you remember the reason for changing the transaction's status.
  • status - the status can potentially be any of the following: PROCESSING, FAILED, or SETTLED SUCCESSFULLY. For Authorize.net transactions, the status can also be VOIDED.
  • reason_code - this can be a NACHA R-Code or a CPA-005 return reason code.

Note: If a reason code is not needed, leave it out of the body:

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

{
"transaction": {
"message": "Transaction was approved",
"status": "SETTLED SUCCESSFULLY"
}
}

The example below illustrates how to update a transaction 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:

id,newStatus,nachaRcode,comments
1642834,FAILED,R01,Insufficient Funds

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

A

B

C

D

1

id

newStatus

nachaCode

comments

2

1642834

FAILED

R01

Insufficient Funds

This information should help you create the file properly:

Header

Description

Value Options

id

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

Numeric Value

newStatus

This is the status the transaction is changing to.

FAILED, PROCESSING, SETTLED SUCCESSFULLY

nachaRcode

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.

comments

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 https://pci-wallet.simnang.com/api/transactions 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: https://pci-wallet.simnang.com/api/transactions/status-update-validate

The URL it returns will look something like this:

https://s3.amazonaws.com/easypay-import/prod/input/798/2019-07-15/import-source-transactions-1563210003608%28454787bb-9bf5-4e03-90bf-7807567bb4a5%29transactions_validate.csv?X-Amz-Security-Token=AgoJb3JpZ2luX2VjELH%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEaCXVzLWVhc3QtMSJHMEUCIQC%2FvW7A2QQcp8bEj8fiddNO9YUs34RVwv%2FW%2F%2FGGHcoQugIgU3dIOmfrqPGgODcGwXzr2EGXjCcfkR57P%2B3g7jxYLb4q2gMIGRACGgwyMjMyNDQxMTgwNDciDO4MI06dm8ksnpsctCq3A%2FBqyEwGXcGgoKXOvUmHH1Ph8HN3cH2%2B%2B4oVUlX1TFqXKL%2FfSWm8vrqomfO%2Bqs1%2Bb%2FdiJ3WJYlRbg0Em2%2BgQGcKql5tZW1t8iwakII6ZwTaCLDKerAS2DLCfHC%2FWZ%2FTK7zylqv%2FTru8SF4ltc9Z9ruLOKSMsdWCqbCJ1bzkGgrrDaB1b4Dz%2F2tOQTR95PuxmQZcScB4BGCTDK2gZ0dcQIqplViHPTFlW1arzohiv8IdmgMsn982BIj2NB4qFSbz8YIktCbHvQZKO%2BNtH9PZh77DQbakuD9QWTLllUpQXOO1YUNptZq904KTD4NMVyvJl%2F%2F8UqwoQb1muqfCg9vTjtXbDmrXfZvLuY37bdBExHX0pPC%2BcrA%2F0MkeHH93a9AvN6uLk8vcltwjBvAiwjBFvhaPLZ%2F3NiAV5KIZCwNmAtiJDLrWTHckuVUwMIL1ZGYv0Q1l8qL1hiNvtPuOkqqI8MlSGNOMQxPwzskh2n8AvzuNbOshyifILdDh0poMaIFLmkLzz4Fm7NCSSPeVRJexn1wXe7EAtD5FsymsuokS1C7QtWcMywDF%2BeiBUzs67kPuLjYQxM%2BPkO0swt86y6QU6tAFuavuBxCBjSbozvdS%2F2QmGgg4IBcRG4jmKDdN9siYyVS%2Fy56ak2buQT753mWRt71uU1YjhyWGfor4xs4Q9btmcqN%2B9xm9a5l4BCaoR%2FsAdLM0vMRFOZWsXH4lAt8MCCBj5NpdN7lSk6KfbKqGavgQiXCylDY9243xRyiqlFbnjZN0Kdu6kPSJZQMQrwVvUqcCKyurq0AWy2wkfJMoLO35OuwAUfmABZJiIHr%2BdraLkwqCjv5E%3D&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20190715T170003Z&X-Amz-SignedHeaders=host&X-Amz-Expires=900&X-Amz-Credential=ASIATH6TC5AP6SGA4XIX%2F20190715%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Signature=352ab0952fe3e004a86ba46269e03e29be398a657ce661f44e7c9dbc16c9c10a

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: https://pci-wallet.simnang.com/api/import/all

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:

https://pci-wallet.simnang.com/api/transactions/status-update/{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:

https://pci-wallet.simnang.com/api/transactions/status-update/2025.

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)