Contents

Best practices

 

This section assumes you have already read the “Getting started” section and understand how to submit a basic request to us. If you haven’t already, we recommend reading this before you continue.

 

When receiving our response, your system will need to perform the following checks on the values returned (where applicable) to ensure the request was processed successfully.

 

Error code

The errorcode is a fundamentally important field as it displays the outcome of the submitted request. It is returned in every response from Secure Trading.

Status good

If the errorcode is “0”, this indicates the request was processed successfully.

 

It is imperative that you have a process in place to check the final status of the processed request, by looking at the values of the other fields returned. 

Status attention

If the errorcode is “30000”, this indicates a field error.

If you look at the errordata field returned, this typically contains the name of the field that was deemed invalid. You will need to retry the request, ensuring all required fields have been submitted, and that all submitted field values follow our specification.

Status attention

If the errorcode is “70000”, this indicates a payment was declined by your bank.

We recommend that you show an error message to the customer and allow them to try a different method of payment.

Status bad

If the errorcode is “60010”, “60034” or “99999”, there has been a problem processing the request and the final status is not known.

 

This can be due to a communication problem with a bank or third party. In such cases, we recommend informing the customer of the problem and to contact you to query the issue. You will need to contact our Support team, providing a copy of the entire request submitted and response returned, and we will contact the relevant parties to establish the status of the request. In the interest of security, ensure you omit or mask sensitive field values, such as card details.

If the errorcode is not listed above, please refer to our full list of errorcodes for assistance. If you need further help, please contact our Support team.

 

Settle status

It is important to check the value of the settlestatus when processing an AUTH or REFUND request, as this indicates if Settlement will be performed. Here are the basics:

Status good

If the settlestatus is “0”, “1” or “10”, you do not need to take any further actions.

The transaction is currently scheduled to settle.

Status good

If the settlestatus is “100”, the transaction has been settled.

You cannot perform any further updates to the transaction.

Status attention

If the settlestatus is “2”, the transaction has been suspended.

Funds will not be settled without your intervention. Please refer to our settlement documentation for further information.

Status bad

If the settlestatus is “3”, the transaction has been cancelled.

Funds will not be settled and you will need to investigate the problem and try again. In this scenario, it is useful to look at the accompanying errorcode as this will often inform you of the reason behind the transaction failing.

If you haven’t already, we recommend you read our settlement documentation for further detail on how settlement is performed.

 

Security response

If the AVS and Security Code Checks are performed as part of the request (as is the case for most AUTH and ACCOUNTCHECKs), you will need to check the three security response fields returned, which are defined as follows:

Status good

If the value is “2”, the customer entered the correct details.

If all values are “2”, there is no reason here to prevent the transaction from settling.

Status attention

If the value is “1”, the bank was unable to check the customer’s details.

This may be because the customer has a card issued by a foreign country, and your bank was therefore unable to check their address. You may need to consider suspending transactions that fall into this category to allow you to investigate before proceeding with the payment.

Status attention

If the value is “0”, the customer’s details were not sent to the bank.

This is because the customer didn’t enter any of the details at all, or that these details were not submitted in your request. You may need to consider suspending transactions that fall into this category to allow you to investigate before proceeding with the payment.

Status bad

If the value is “4”, the customer entered incorrect details.

By default, we will suspend transactions where the security code entered by the customer fails to match the value on their card. Depending on your preferences, you may also prefer to suspend transactions where the address details do not match (disabled by default).

You can request that Secure Trading automatically cancels transactions when the security response fields have a certain value. As mentioned above, we suspend all transactions where the security code entered by the customer fails to match the value on their card. You can specify the circumstances under which transactions are suspended to match your own preferences (you can even disable such checks entirely). This is achieved by modifying your Security Policy. To discuss changes to your account’s security policy, please contact our Support team.

 

Request type description

Each response will contain a requesttypedescription. The value of this field returned in the response should always match the value submitted in the request.

e.g. If you are sending an “AUTH” request, ensure the requesttypedescription returned is “AUTH”.

If you receive requesttypedescription with value “ERROR”, the request may not have been processed successfully and you will need to investigate.

 

Live status

Check the live status value returned is “0” while testing and “1” when processing live payments.

 

Amount & currency

When submitting an amount and currency, check that the same values are returned in the response.