support@protx.com
 
Step 1 Step 2 Step 3 Step 4 Step 5 Step 6 Step 7 Step 8 Step 9

VSP Direct Custom Integration: Step 9

Step 9: PROTX reply to the payment registration POST

(N.B: ALL code examples and references to integration kit files within this document are related
to the ASP kit ONLY. To download kits in other languages please visit the Downloads page.)









Irrespective of the Status being returned, VSP Direct always replies to the page that made the POST from your server and is handled by the Response section on that page. This will either be in response to the transaction registration POST made for non-3D-authenticated transactions (i.e. the 'vsp_purchase.asp' page), or in the response to the Terminal URL POST if 3D-Authentication was attempted (i.e. the 'callback.asp' page).

Please see below example ASP code from the 'vsp_purchase.asp' page in our ASP VSP Direct Integration Kit - the example only handles the 'OK' Status response and only extract the VPSTxId, Security Key and TxAuthNo values from the Protx reponse data.







Please see below example ASP code from the 'callback.asp' page in our ASP VSP Direct Integration Kit - the example only handles the 'OK' Status response and only extract the VPSTxId, Security Key, TxAuthNo and CAVV values from the Protx reponse data.






Please see below the Response values returned by Protx - this can also be found on Appendix A2 (Pages 37/38) of the VSP Direct Protocol and Integration Guideline document (please visit our Downloads section to obtain a copy).


Appendix A2 : Protx Response to the Transaction Registration

Name Format Values Comments
VPSProtocol Alphanumeric (Fixed 4 characters)
2.22 in this release

This will match the protocol version supplied in Appendix A1 : Payment Registration Protocol.
Status Alphanumeric (Max 15 characters)

"OK" - The transaction was authorised by the bank and funds have been taken from the customer
"MALFORMED" - Input message was missing fields or badly formatted - normally will only occur during development and vendor integration.
"INVALID" - Transaction was not registered because although the POST format was valid, some information supplied was invalid. E.g. incorrect vendor name or currency.
"ERROR" - A code-related error occurred which prevented the process from executing successfully.
"NOTAUTHED" - The transaction was not authorised by the acquiring bank. No funds could be taken from the card.
"REJECTED" - The VSP System rejected the transaction because of the rules you have set on your account.
"3DAUTH" - The VSP System rejected the transaction because of the rules you enabled.

If the status is not OK, the StatusDetail field will give more information about the status.

Please notify PROTX if a Status report of ERROR is seen, together with your VendorTxCode and the StatusDetail text. 3DAUTH is only returned if 3D-Authentication is available on your account AND the card and card issuer are part of the scheme.

A Status of 3DAUTH only returns the StatusDetail, MD, PAReq, 3DSecureStatus and ACSURL fields. The other fields are returned with other Status codes only.
StatusDetail Alphanumeric (Max 255 characters)
Human-readable text providing extra detail for the Status message

Always check StatusDetail if the Status is not OK.
VPSTxId Alphanumeric (Max 38 characters)
Protx ID to uniquely identify the Transaction on our system

You should store this value and quote it to us if you have a query about the transaction. Not present when Status is 3DAUTH.
SecurityKey Alphanumeric (Max 10 characters)
Security key which VSP uses to generate an MD5 Hash to sign the transaction

Should be kept secret from the Customer but stored in your database. Not present when Status is 3DAUTH.
TxAuthNo Numeric (Long integer)

The Protx authorisation code (also called VPSAuthCode) for this transaction

Only present if Status is OK.

AVSCV2 Alphanumeric (Max 50 characters)

Response from AVS and CV2 checks. Will be one of the following: "ALL MATCH", "SECURITY CODE MATCH ONLY", "ADDRESS MATCH ONLY", "NO DATA MATCHES" or "DATA NOT CHECKED"

Should be kept secret from the Customer but stored in your database. Not present when Status is 3DAUTH..
AddressResult Alphanumeric (Max 20 characters)

"NOTPROVIDED",
"NOTCHECKED",
"MATCHED",
"NOTMATCHED"

The specific result of the checks on the cardholder's address numeric from the AVS/CV2 checks. Not present when Status is 3DAUTH.
PostCodeResult Alphanumeric (Max 20 characters)

"NOTPROVIDED",
"NOTCHECKED",
"MATCHED",
"NOTMATCHED"

The specific result of the checks on the cardholder's post code numeric from the AVS/CV2 checks. Not present when Status is 3DAUTH.
CV2Result Alphanumeric (Max 20 characters)

"NOTPROVIDED",
"NOTCHECKED",
"MATCHED",
"NOTMATCHED"

The specific result of the checks on the cardholder's CV2 code from the AVS/CV2 checks. Not present when Status is 3DAUTH.
3DSecureStatus Alphanumeric (Max 20 characters)

"NOTCHECKED" - No 3D Authentication was attempted for this transaction. Always returned if 3D-Secure is not active on your account. "OK" - The 3D-Authentication step completed successfully. If the Status field is 3DAUTH, this means the card is part of the scheme. If the Status field is OK too, then this indicates that the authorized transaction was also 3D-authenticated and a CAVV will be returned. Liability shift occurs. "NOAUTH" - Returned with a Status of 3DAUTH. This means the card is not in the 3D-Secure scheme. "CANTAUTH" - Returned with a Status of 3DAUTH. This normally means the card Issuer is not part of the scheme. "NOTAUTHED" - The cardholder failed to authenticate themselves with their Issuing Bank. "ATTEMPTONLY" - The cardholder attempted to authenticate themselves but the process did not complete. A CAVV is returned anyway and liability shift occurs for Visa cards only. Check VSP Admin."MALF ORMED","INVALID","ERROR" - These statuses indicate a problem with creating or receiving the 3D-Secure data. These should not occur on the live environment

This field holds the results of the 3D-Authentication steps carried out by VSP Direct and the Protx MPI. If 3D-Secure is not active on your account, this field will always contain the value NOTCHECKED.
MD Alphanumeric (Max 20 characters)

A unique reference for the 3D-Authentication attempt

Only present if the Status field is 3DAUTH.
CAVV Alphanumeric (Max 32 characters)

The encoded result code from the 3D-Secure checks. Holds the Visa CAVV or the MasterCard UCAF depending on the card type used in the transaction

Only present if the 3DSecureStatus field is OK AND the Status field is OK.



Within this Response POST you will receive a Security key which is a 10-digit alphanumeric code that is used in digitally signing the transaction. This value (security key) MUST be stored in your database, as it will be required if you needed to REFUND the payment.

If the transaction was authorised, the Status field containing "OK" there will also be a field called 'TxAuthNo'. This is not the authorisation code from the bank but instead a unique reference number to that authorisation, called the VPSAuthCode.

This is the transaction ID sent to the bank during settlement (we cannot use your VendorTxCode because it is too long and might contain letters) so the bank will use this value to refer to your transaction if they need to contact you about it. You should store this value in your database along with all the other values returned to you.

The TxAuthNo field is ONLY present if the transaction was authorised by the bank. All other messages are authorisation failures of one type or another (see Appendix A2 above for full details of the fields and errors returned by VSP Direct) and you should inform your customer that their payment was not accepted.

If you do receive an "OK" status and a TxAuthNo, you should display a completion page for your shopper thanking them for their order.

Having stored the relevant transaction ids in your database, your payment processing is now complete.


IMPORTANT

Once again, we would point out that it is crucial that you store these details in your database alongside the shopper and order details for this transaction. This is very important for your own records so you can match the transaction details to your shopper and their purchase from your online store. The Protx Admin area does contain basic information on the Shoppers transaction, like the billing address, Shopper name etc. but having your own database is far more comprehensive and can be tailored to your needs.


Another very important fact for storing the VPSTxId, SecurityKey and VendorTxCode is you can automate more than payments. VSP Direct and VSP Server place you in control of your transactions. Because you will have your own secure database servers and web servers on which you store details of your shoppers and their transactions, you may well wish to automate many of the daily procedures, such as RELEASING and ABORTING DEFERRED transactions, REPEATING regular payments or issuing REFUNDS to customers.

The processes of RELEASING a payment, or REFUNDING a transaction, are essentially the same as registering a VSP Server or VSP Direct payment. Your server sends an HTTPS POST containing a collection of Name=Value pairs directly to the VSP system, which validates the information and either carries out the instruction returning an OK status and any relevant transaction Ids and authorisation codes for you to store in your database, or generates an INVALID, MALFORMED, NOTAUTHED or ERROR Status with a description of the error in the StatusDetail field.

For Further information please go to payment types section on our website - you should use this section in conjunction with our VSP Server and Direct Shared Protocol document which can be downloaded here.

Back to top

 © Copyright 2008 Protx Limited (a division of Sage (UK) Limited)    Terms of Use | Security Policy | Privacy Policy | General Feedback | Webmaster