{"mock":"https://private-anon-8c48a4dd06-purepaypayments.apiary-mock.com/","production":"https://gateway.purepay.eu/","proxy":"https://private-anon-8c48a4dd06-purepaypayments.apiary-proxy.com/"}

FORMAT: 1A HOST: https://gateway.purepay.eu # PurePay Gateway Integration # 1 HTTP Integrations ## 1.1 About This Guide This guide provides the information required to integrate with the PurePay Gateway and gives a very basic example of code for doing so. It is expected that you have some experience in server side scripting with languages such as PHP or ASP, or that an off-the-shelf software package is being used that has in-built or plug-in support for the Gateway. If you do require programming assistance related to your integration, please contact your support representative via support@purepay.eu. --- ### 1.1.1 Direct Integration The Direct HTTP integration works by allowing you to keep the Customer on your system through the checkout process while processing the transactions via the Gateway in the background. This allows you to provide a smoother, more complete checkout process to the Customer. If you wish to take card details on your website, or style your payment pages, then you either need to use the Direct integration or use the Hosted integration and request a Custom Hosted Payment Page for your website. To use the Direct integration your website must have an SSL Certificate. You will also need to consider the Payment Card Industry Data Security Standard (PCI:DSS) when capturing card details. For more information, please see https://www.pcisecuritystandards.org/. In addition to transaction processing, the Direct integration can be used to perform other actions such as refunds and cancellations which can provide a more advanced integration with the Gateway. Refer to section [1.7](#1.7) for more information. ### 1.1.2 Hosted Integration The Hosted HTTP integration works by redirecting the Customer to the Gateway’s Hosted Payment Page, which will gather the Customer’s payment details and send them to the Gateway on your behalf. This allows you the quickest path to integrating with the Gateway. If you wish to take card details on your website, or style your payment pages, then you either need to use the Direct integration or use the Hosted integration and request a Custom Hosted Payment Page for your website. Unlike the Direct method, your website does not need to have an SSL Certificate, and PCI compliance becomes more straightforward. ## 1.2 Integration Disclaimer We provide all integration documentation necessary for enabling Merchants to process payments via our Payment Gateway. Whilst every effort has been made to ensure these guides are accurate and complete, we expect Merchants undertaking any integration to test all their technical work fully and satisfy their own standards. We are not responsible or liable for any Merchant or Third Party integration. --- ## 1.3 Terminology The following terms are used throughout this guide; + **Gateway** + The PurePay Payment Gateway. + **Merchant** + The Merchant using the Gateway’s services. + **Acquirer** + The bank or financial institution used by the Merchant. + **Customer** + A customer of the Merchant making a payment etc. + **Cardholder** + The person who owns the payment card, normally the Customer. + **Merchant Account** + An account on the Gateway mapped to an Acquirer issued account. + **You/your** + The Merchant or their representative performing the integration. --- ## 1.4 Pre-Requisites You will need the following information to integrate with the Payment Gateway using the Direct integration method; > | | | > | :-- | :-- | > | **Merchant ID** | Your Merchant ID enables you to access and communicate with the Payment Gateway. Please note that these details will differ to the login supplied to access the administration panel. You should have received these details when your account was set up. You may also use test Merchant IDs (if you have been issued with a test ID) and swap these for your live account details when you receive them. | > | **Integration URL** | https://gateway.purepay.eu/direct/ | New Merchants who have not yet received their live Merchant ID can still perform an integration for testing purposes. Simply enter one of the test Merchant IDs below and use the test cards provided in appendix [A-10](#A-10) to run a test transaction. For non 3-D Secure testing use Merchant ID **100001** For 3-D Secure Testing use Merchant ID **100856** --- ## 1.5 Integration Details A request can be sent to the Gateway by submitting an HTTP POST request to the integration URL provided. The request should be URL encoded as name=value fields separated by ‘&’ characters. The response will be received in the same format. For more information on the URL encoded format refer to RFC 1738 and the `application/x-www-form-urlencoded` media type. **Please note that the field names are cAsE sEnSiTiVe.** ### 1.5.1 Direct Requests Example URL encoding: ``` merchantID=100001&action=SALE&type=1&amount=1001&currencyCode=826&countryCode=826&transactionUnique=55f6db1c81d95&orderRef=Test+purchase&customerPostcode=NN17+8YG&responseCode=0&responseMessage=AUTHCODE%3A350333&state=captured&xref=15091702MG47WN32MM88LPK ``` The response will return the request fields in addition to any dedicated response field. If the request contains a field that is also intended as a response field then any incoming request value will be overwritten by the correct response value. ### 1.5.2 Hosted Requests Hosted requests are sent from the Customer’s web browser. The response will be a HTML Hosted Payment Page requesting the Customer to enter their card details, address, name, etc. The normal way to achieve this is to send the request data as hidden form fields as per the example code provided in appendix [A-17](#A-17). The browser will then automatically encode the request correctly as per the application/x-www-form-urlencoded format. Once the payment page has been complete the Customer’s browser will be automatically redirected to the URL provided via the redirectURL field. The response will be returned to this page using an HTTP POST request. The response will return the request fields in addition to any dedicated response field. If the request contains a field that is also intended as a response field then any incoming request value will be overwritten by the correct response value. The **`redirectURL`** must be a fully qualified URL containing at least the scheme and host components. ### 1.5.3 Handling Errors When the Gateway is uncontactable due to a communications error, or problem with the internet connection, you may receive an HTTP status code in the 500 to 599 range. In this situation you may want to retry the transaction. If you do choose to retry a transaction, then we recommend you perform a limited number of attempts with an increasing delay between each attempt. If the Gateway is unavailable during a scheduled maintenance period, you will receive an HTTP status code of 503 ‘Service Temporarily Unavailable’. In this situation you should retry the transaction after the scheduled maintenance period has expired. You will be notified of the times and durations of any such scheduled maintenance periods in advance, by email, and given a time when transactions can be reattempted. <br/><br/>We recommend considering the following steps if you are experiencing these errors: + Ensure the request is being sent to HTTPS and not HTTP. HTTP is not supported and is not redirected. + Send transactions sequentially rather than concurrently. + Configure your integration code with try/catch loops around individual transactions to determine if they were successful or not and retry if required based on the return code or HTTP status returned. + Configure the integration so that if one transaction does fail, the entire batch does not stop at that point– i.e. log the failure to be checked and then skip to the next transaction rather than stopping entirely. <a name="1.5.4"></a> ### 1.5.4 Callback URL You can request that the Gateway sends a copy of the response to an alternative URL using the **`callbackURL`** request field. In this case each response will then be POSTed to that URL in addition to the normal response. This allows you to specify a URL on a secure shopping cart or backend order processing system which will then fulfil any order, request, query etc. related to the transaction. The **`callbackURL`** must be a fully qualified URL containing at least the scheme and host components. --- ## 1.6 Authentication All requests must specify which Merchant Account they are for using the **`merchantID`** request field. In addition to this the following security measures can be used; <a name="1.6.1"></a> ### 1.6.1 Password Authentication **Direct Only**<br> You can configure a password for each Merchant Account under the preferences tab in the Merchant Management System (MMS). This password must then be sent in the **`merchantPwd`** field in each request. If an incorrect password is received by the Gateway then the transaction will be aborted and an error response returned. >*Warning: Use of a password is discouraged in any integration where the transaction is posted from a form in the client browser as the password may appear in plain text in code.* <a name="1.6.2"></a> ### 1.6.2 Message Signing Message signing offers a quick and simple way to ensure that the message has come from an authorised source and has not been tampered with during transmission. It requires you to generate a hash of the request message being sent and then send this hash along with the original request in the **`signature`** field. The gateway will then re-generate the hash on the request message received and compare it with the one sent. If the two hashes are different then it means that the request received is not the same as that sent and the transaction will be aborted and an invalid signature error response will be returned. The gateway will also return a hash of the response message in the **`signature`** field allowing you to create your own hash of the response (minus the **`signature`** field) and verify that the hashes match. If message signing is enabled, then the data POSTed to any callback URL will also be signed. See appendix [A-11](#A-11) for information on how to create the hash. ### 1.6.3 Allowed IP addresses You can configure a list of IP addresses under the preferences tab in the Merchant Management System (MMS). Two different address lists can be configured, one for standard requests, such as sales, and one for advanced requests, such as refunds and cancellations. If a request is received from an address other than those configured, then it will be aborted and an error response returned. <a name="1.7"></a> --- ## 1.7 Supported Action All requests must specify what action they require the Gateway to perform using the **`action`** request field. **All** HTTP integrations allow the following actions to be specified; ### 1.7.1 SALE This will create a new transaction and attempt to seek authorisation for a sale from the Acquirer. A successful authorisation will reserve the funds on the Cardholder’s account until the transaction is settled. The **`captureDelay`** field can be used to state if the transaction should be authorised only and settled at a later date. For more details on delayed capture refer to appendix [A-8](#A-8). ### 1.7.2 VERIFY This will create a new transaction and attempt to verify that the card account exists with the Acquirer. The transaction will result in no transfer of funds and no hold on any funds on the Cardholder’s account. It cannot be captured and will not be settled. The transaction amount must always be zero. This transaction type is the preferred method for validating that the card account exists and is in good standing, however it cannot be used to validate that it has sufficient funds. ### 1.7.3 PREAUTH This will create a new transaction and attempt to seek authorisation for a sale from the Acquirer. If authorisation is approved, then it is immediately voided (where possible) so that no funds are reserved on the Cardholder’s account. The transaction will result in no transfer of funds. It cannot be captured and will not be settled. This transaction type can be used to check whether funds are available and that the account is valid. However due to the problem highlighted below it is recommended that Merchants use the VERIFY when supported by their Acquirer. > Warning: If the transaction is to be completed then a new authorisation needs to be sought using the SALE action. If the PREAUTH authorisation could not be successfully voided then this will result in the funds being authorised twice effectively putting 2 holds on the amount on the Cardholder’s account and thus requiring twice the amount to be available in the Cardholder’s account. It is therefore recommended to only PREAUTH small amounts such as £1 to mainly check account validity. --- In addition to those above, the **direct** integration can also perform the following actions; --- ### 1.7.4 REFUND_SALE This will create a new transaction and attempt to seek authorisation for a refund of a previous SALE from the Acquirer. The transaction will then be captured and settled if and when appropriate. It can only be performed on transactions that have been successfully settled. Up until that point, a CANCEL or partial CAPTURE can be done to refund or partially refund the original SALE transaction. The previous SALE transaction should be specified using the **`xref`** field. Partial refunds are allowed by specifying the **`amount`** to refund, any amount must not be greater than the original received amount minus any already refunded amount. Multiple partial refunds may be made while there is still a portion of the originally received amount un-refunded. The **`captureDelay`** field can be used to state if the transaction should be authorised only and settled at a later date. For more details on delayed capture refer to appendix [A-8](#A-8). ### 1.7.5 REFUND This will create a new transaction and attempt to seek authorisation for a refund from the Acquirer. The transaction will then be captured and settled if and when appropriate. This is an independent refund and need not be related to any previous SALE. The amount is therefore not limited by any original received amount. The **`captureDelay`** field can be used to state if the transaction should be authorised only and settled at a later date. For more details on delayed capture refer to appendix [A-8](#A-8). ### 1.7.6 CAPTURE This will capture an existing transaction, identified using the **`xref`** request field, making it available for settlement at the next available opportunity. It can only be performed on transactions that have been authorised but not yet captured. An amount to capture may be specified but must not exceed the original amount authorised. The original transaction must have been submitted with a **`captureDelay`** value that prevented immediate capture and settlement leaving the transaction in an authorised but un-captured state. For more details on delayed capture refer to appendix [A-8](#A-8). ### 1.7.7 CANCEL This will cancel an existing transaction, identified using the **`xref`** request field, preventing it from being settled. It can only be performed on transactions, which have been authorised but not yet settled, and it is not reversible. Depending on the Acquirer it may not reverse the authorisation and release any reserved funds on the Cardholder’s account, in such cases authorisation will be left to expire as normal, releasing the reserved funds. This may take up to 30 days from the date of authorisation. <a name="1.7.8"></a> ### 1.7.8 QUERY This will query an existing transaction, identified using the **`xref`** request field, returning the original response. This is a simple transaction lookup action. --- # 2 New Transactions You can perform a new transaction, such as a sale, by sending a request with the required action and relevant order details. <a name="2.1"></a> ## 2.1 Request Fields | Field Name | Mandatory? | Integration Type | Description | | :---------- | :--------- | :----------: | :---------- | | **merchantID** | <center>Yes<center/> | <center>Both<center/> | Your Gateway Merchant ID | | **merchantPwd** | <center>No^{<a name="2.1-1">[<span title="A password is not recommended if using the Hosted Integration, use a signature instead.">1</span>](#2.1-f1)</a>}<center/> | <center>Direct<center/> | Any password used to secure this account. Refer to section [1.6.1](#1.6.1) for details. ***Direct only***| | **signature** | <center>Yes^{<a name="2.1-2">[<span title="A signature is recommended if using the Hosted Integration.">2</span>](#2.1-f2)</a>}<center/> | <center>Both<center/> | Any hash used to sign this request. Refer to section [1.6.2](#1.6.2) for details. | | **action** | <center>Yes<center/> | <center>Both<center/> | The action requested. Refer to section [1.7](#1.7) for supported actions. | | **amount** | <center>Yes^{<a name="2.1-3">[<span title="Optional if an xref is provided as the value will be taken from the cross referenced transaction.">3</span>](#2.1-f3)</a>}<center/> | <center>Both<center/> | The amount of the transaction in minor currency. For the UK, this is pence, so £10.99 should be sent as 1099. **Numeric values only - no decimal points or currency symbols.** | | **type^{<a name="2.1-4">[<span title="If type is not sent, it will default to ECOM for a Hosted integration whereas the transaction will be rejected for a Direct integration.">4</span>](#2.1-f4)</a>}** | <center>Yes^{[<span title="Optional if an xref is provided as the value will be taken from the cross referenced transaction">3</span>](#2.1-f3)}<center/> | <center>Both<center/> | The type of transaction. Refer to appendix [A-13](#A-13) for details. | | **countryCode** | <center>Yes^{[<span title="Optional if an xref is provided as the value will be taken from the cross referenced transaction.">3</span>](#2.1-f3)}<center/> | <center>Both<center/> | Merchant's Location. **Valid ISO-3166 alpha or numeric code.** | | **currencyCode** | <center>Yes^{[<span title="Optional if an xref is provided as the value will be taken from the cross referenced transaction.">3</span>](#2.1-f3)}<center/> | <center>Both<center/> | Transaction currency. **Valid ISO-3166 alpha or numeric code.** | | **cardNumber^{<a name="2.1-5">[<span title="It is highly recommended that this field never be sent for a Hosted Integration because sending plain text card numbers over a request presents a potential security risk.">5</span>](#2.1-f5)</a>}** | <center>Yes^{[<span title="Optional if an xref is provided as the value will be taken from the cross referenced transaction.">3</span>](#2.1-f3)}<center/> | <center>Both<center/> | The primary account number (PAN) as printed on the front of the payment card. **Numeric values only (spaces allowed).** | | **cardExpiryMonth** | <center>Yes^{[<span title="Optional if an xref is provided as the value will be taken from the cross referenced transaction.">3</span>](#2.1-f3)}<center/> | <center>Both<center/> | Payment card's expiry month as a number from 1 to 12. **Numeric values only.** | | **cardExpiryYear** | <center>Yes^{[<span title="Optional if an xref is provided as the value will be taken from the cross referenced transaction.">3</span>](#2.1-f3)}<center/> | <center>Both<center/> | Last two digits of the payment card's expiry year as a number from 00 to 99. **Numeric values only.** | **cardCVV** | <center>Yes^{[<span title="Optional if an xref is provided as the value will be taken from the cross referenced transaction.">3</span>](#2.1-f3)}<center/> | <center>Both<center/> | Payment card’s security number. The 3 digit number printed on the payment cards signature strip^{<a name="2.1-6">[<span title="For American Express cards this is a 4 digit number printed flat on the front of the card.">6</span>](#2.1-f6)</a>}. **Numeric values only.** | | **cardExpiryDate** | <center>No<center/> | <center>Direct<center/> | Payment card’s expiry date in MMYY format as an alternative to sending separate **`cardExpiryMonth`** & **`cardExpiryYear`** fields. **Numeric values only.**| | **transactionUnique** | <center>No<center/> | <center>Both<center/> | You can supply a unique identifier for this transaction. This is an added security feature to combat transaction spoofing. | | **orderRef** | <center>No<center/> | <center>Both<center/> | Free format test field to store order details, reference numbers, etc. for your records. | | **captureDelay** | <center>No<center/> | <center>Both<center/> | Number of days to wait between authorisation of a payment and subsequent settlement. Refer to appendix [A-8](#A-8) for details. | | **xref** | <center>No^{<a name="2.1-7">[<span title="Mandatory for a REFUND_SALE request to specify the original SALE transaction.">7</span>](#2.1-f7)</a>}<center/> | <center>Direct<center/> | Reference to a previous transaction. Refer to appendix [A-14](#A-14) for details. | | **callbackURL** | <center>No<center/> | <center>Both<center/> | A non-public URL which will receive a copy of the transaction result by POST. The URL must be fully qualified and include at least the scheme and host components. Refer to section [1.5.4](#1.5.4) for details. | | **remoteAddress** | <center>No<center/> | <center>Direct<center/> | IP address of client making the transaction. This should be provided where possible to aid fraud prevention. | | **formResponsive** | <center>No<center/> | <center>Hosted<center/> | Switch the hosted form to responsive mode for mobile devices?<br/><br/>Possible values are:<br/>**N** - Set to standard mode.<br/>**Y** - Set to responsive mode. | If the REFUND_SALE action is used, then the request must not attempt to change the payment details or the request will fail with a **`responseCode`** of **65542 (REQUEST MISMATCH)**. This is because the refund must be made to the original card. --- *^{<a name="2.1-f1">[1](#2.1-1)</a>} A password is not recommended if using the Hosted Integration, use a signature instead.* <br>*^{<a name="2.1-f2">[2](#2.1-2)</a>} A signature is recommended if using the Hosted Integration.* <br>*^{<a name="2.1-f3">[3](#2.1-3)</a>} Optional if an **`xref`** is provided as the value will be taken from the cross referenced transaction.* <br>*^{<a name="2.1-f4">[4](#2.1-4)</a>} If type is not sent, it will default to ECOM for a Hosted integration whereas the transaction will be rejected for a Direct integration.* <br>*^{<a name="2.1-f5">[5](#2.1-5)</a>} It is highly recommended that this field never be sent for a Hosted Integration because sending plain text card numbers over a request presents a potential security risk.* <br>*^{<a name="2.1-f6">[6](#2.1-6)</a>} For American Express cards this is a 4 digit number printed flat on the front of the card.* <br>*^{<a name="2.1-f7">[7](#2.1-7)</a>} Mandatory for a REFUND_SALE request to specify the original SALE transaction.* --- ### 2.1.1 Hosted Form Page Options You can customise the appearance of the standard Hosted Payment Page by sending additional fields in the request. Some of these fields may not work if you have a customised Hosted Payment Page. | Field Name | Mandatory? | Description | | :--------- | :--------- | :---------- | | **cardNumber^{<a name="2.1.1-1">[<span title="It is highly recommended that this field never be sent because sending plain text card numbers over a request presents a potential security risk.">1</span>](#2.1.1-f1)</a>}** | <center>No<center/> | Default value to display in the card number field. **It is highly recommended that this field never be sent!** | | **cardCVV** | <center>No<center/> | Default value to display in the CVV field. | | **cardExpiryMonth** | <center>No<center/> | Default value to display as the card expiry month. | | **cardExpiryYear** | <center>No<center/> | Default value to display as the card expiry year. | | **customerName** | <center>No<center/> | Default value to display in the Cardholder’s name field. | | **customerAddress** | <center>No<center/> | Default value to display in the Cardholder’s postal address field. | | **customerPostcode** | <center>No<center/> | Default value to display in the Cardholder’s postcode field. | | **customerEmail** | <center>No<center/> | Default value to display in the Cardholder’s email address field. | | **customerPhone** | <center>No<center/> | Default value to display in the Cardholder’s phone number field. | | **cardCVVMandatory** | <center>No<center/> | Force a CVV to be entered. | | **customerAddressMandatory** | <center>No<center/> | Force a postal address to be entered. | | **customerPostcodeMandatory** | <center>No<center/> | Force a postcode to be entered. | | **customerEmailMandatory** | <center>No<center/> | Force an email address to be entered. | | **customerPhoneMandatory** | <center>No<center/> | Force a phone number to be entered. | --- *^{<a name="2.1.1-f1">[1](#2.1.1-1)</a>} It is highly recommended that this field never be sent because sending plain text card numbers over a request presents a potential security risk.* <a name="2.2"></a> --- ## 2.2 Response Fields The response will contain all the fields sent in the request (minus any card details) plus the following; | Field Name | Returned? | Description | | :--------- | :-------- | :---------- | | **responseCode** | <center>Always<center/> | A numeric code providing the outcome of the transaction. See appendix [A-1](#A-1) for details. | | **responseMessage** | <center>Always<center/> | The message received from the Acquiring bank, or any error message. | | **transactionID** | <center>Always<center/> | A unique ID assigned by the Gateway. | | **xref** | <center>Always<center/> | You may store the cross reference for repeat transactions. Refer to appendix [A-14](#A-14) for details. | | **action^{<a name="2.2-1">[<span title="For direct integration management requests such as a capture or cancellation, this would return the requested action and the original action separated by a colon e.g. CANCEL:SALE.">1</span>](#2.2-f1)</a>}** | <center>Always<center/> | The action requested. Refer to section [1.7](#1.7) for supported actions. | | **state** | <center>Always<center/> | Transaction state. Refer to appendix [A-12.2](#A-12.2) for details. | | **timestamp** | <center>Always<center/> | Time the transaction was created or last modified. | | **transactionUnique** | <center>If supplied<center/> | Any value supplied in the initial request. | | **authorisationCode** | <center>On&nbsp;success<center/> | Authorisation code received from Acquirer. | | **amountReceived** | <center>On&nbsp;success<center/> | The amount the Acquirer authorised. This should always be the full amount requested. | | **amountRefunded** | <center>If refund<center/> | Total amount of original SALE that has so far been refunded. Returned when action is REFUND_SALE. | | **orderRef** | <center>If supplied<center/> | Any value supplied in the initial request. | | **cardNumberMask** | <center>Always<center/> | Card number masked so only the last 4 digits are visible. | | **cardTypeCode** | <center>Always<center/> | The code of card used. Refer to appendix [A-9](#A-9) for details. | | **cardType** | <center>Always<center/> | The description of the card used. Refer to appendix [A-9](#A-9) for details. | | **cardSchemeCode** | <center>Always<center/> | The code of the card scheme used. Refer to appendix [A-9](#A-9) for details. | | **cardScheme** | <center>Always<center/> | The description of the card scheme used. Refer to appendix [A-9](#A-9) for details. | | **cardIssuer** | <center>Always<center/> | The card issuer (when known). | | **cardIssuerCountry** | <center>Always<center/> | Name of card issuing country (when known). | | **cardIssuerCountryCode** | <center>Always<center/> | ISO-3166 Alpha 2 code of the card issuing country (when known). | Note: the response is also POSTed to any URL provided by the optional **`callbackURL`** field. --- *^{<a name="2.2-f1">[1](#2.2-1)</a>} For direct integration management requests such as a capture or cancellation, this would return the requested action and the original action separated by a colon e.g. **CANCEL:SALE**.* --- # 3 Direct Management Requests Using the direct integration you can perform an action on an existing transaction, such as a capture or cancellation, by sending a request with the required action along with the cross reference for the transaction to act on. ## 3.1 Request Fields | Field Name | Mandatory? | Description | | :--------- | :--------- | :---------- | | **merchantID** | <center>Yes<center/> | Your Gateway Merchant ID. | | **merchantPwd** | <center>No<center/> | Any password used to secure this account. Refer to section [1.6.1](#1.6.1) for details. | | **signature** | <center>Yes<center/> | Any hash used to sign this request. Refer to section [1.6.2](#1.6.2) for details. | | **action** | <center>Yes<center/> | The action requested. Refer to section [1.7](#1.7) for supported actions. | Possible values are: REFUND_SALE, CAPTURE, CANCEL, QUERY. | | **xref** | <center>Yes<center/> | Reference to a previous transaction. Refer to appendix [A-14](#A-14) for details. | | **amount** | <center>No^{<a name="3.1-1">[<span title="An amount is only required for partial refunds or partial captures. When using the xref for an existing transaction, the amount is optional and if provided will override that passed in from the original transaction. Not providing an amount will result in the original transaction amount being used.">1</span>](#3.1-f1)</a>}<center/> | The amount of the transaction in minor currency. For the UK, this is pence, so £10.99 should be sent as 1099. Numeric values only – no decimal points or currency symbols. | | **callbackURL** | <center>No<center/> | A non-public URL which will receive a copy of the transaction result by POST. The URL must be fully qualified and include at least the scheme and host components. Refer to section [1.5.4](#1.5.4) for details. | --- *^{<a name="3.1-f1">[1](#3.1-1)</a>} An amount is only required for partial refunds or partial captures. When using the xref for an existing transaction, the amount is optional and if provided will override that passed in from the original transaction. Not providing an amount will result in the original transaction amount being used.* --- ## 3.2 Response Fields With the exception of the fields below, the response will be the same as for a new transaction, but will contain the details of the existing transaction. | Field Name | Returned? | Description | | :--------- | :-------- | :---------- | | **responseCode** | <center>Always<center/> | A numeric code providing the outcome of the management request. Check **`responseMessage`** for more details of any error that occurred. Refer to appendix [A-1](#A-1) for details. | | **responseMessage** | <center>Always<center/> | Description of above response code. | | **action** | <center>Always<center/> | The requested action and original action separated by a colon. For example. **CANCEL:SALE** --- # 4 AVS/CV2 Checking ## 4.1 Background You are able to request AVS and CV2 fraud checking on transactions processed by the Payment Gateway. These fraud prevention checks are performed by the Acquirer while authorising the transaction. You can choose how to act on the outcome of the check (or even to ignore them altogether). ### 4.1.1 AVS Checking The Address Verification System (AVS) uses the address details that are provided by the Cardholder to verify that the address is registered to the card being used. The address and postcode are checked separately. ### 4.1.2 CV2 Checking CV2, CVV, or Card Verification Value is a 3 or 4 digit security code –The check verifies the code is the correct one for the card used. For most cards the CVV is a 3 digit number to the right of the signature strip. For American Express cards this is a 4 digit number printed, not embossed, on the front right of the card. The AVS/CV2 checking preferences can be configured per Merchant Account within the Merchant Management System (MMS). These preferences can be overridden per transaction by sending one of the preference fields documented in section [4.3](#4.3) which hold a comma separated list of the check responses that should be allowed to continue to completion. Responses not in the list will result in the transaction being declined with a **`responseCode`** of **5 (AVS/CV2 DECLINED)**. --- ## 4.2 Benefits & Limitations ### 4.2.1 Benefits + Instant: The results are available immediately and returned as part of the transaction. + Flexible: The checks can be managed independently allowing you the upmost control over how the results are used. + Automatic: The checks can be configured to automatically decline transaction where required. ### 4.2.2 Limitations + Not all countries supported: AVS is a UK scheme only. It is not possible to check AVS on non-UK issued cards. + Only Address numerics are checked: The non-numerical characters in the billing address and postcode are not checked as part of the AVS checks. + Unable to check AVS/CV2 on company cards: If you accept company credit cards you are not able to recieve results on all company cards. The is due to the Acquirers not having access to this information. <a name="4.3"></a> --- ## 4.3 Request Fields These fields should be sent in addition to basic request fields in section [2.1](#2.1). | Field Name | Mandatory?&nbsp;&nbsp; | Description | | :--------- | :--------- | :---------- | | **customerAddress** | <center>Yes - Direct^{<a name="4.3-1">[<span title="Mandatory if AVS address checking is required.">1</span>](#4.3-f1)</a>}<br/>No - Hosted<center/> | For AVS checking this must be a registered billing address for the card. | | **customerPostcode** | <center>Yes - Direct^{<a name="4.3-2">[<span title="Mandatory if AVS postcode checking is required.">2</span>](#4.3-f2)</a>}<br/>No - Hosted<center/> | For AVS checking this must be a registered postcode for the card. | | **cardCVV** | <center>Yes^{<a name="4.3-3">[<span title="Mandatory if CV2 checking is required.">3</span>](#4.3-f3)</a>}<center/> | For CVV checking this must be the Card Verification Value printed on the card. | | **avscv2CheckRequired** | <center>No^{<a name="4.3-4">[<span title="The default value is Y if AVS/CV2 checking is enabled on the Merchant Account, otherwise N.">4</span>](#4.3-f4)</a>}<center/> | Is AVS/CV2 checking required for this transaction?<br/><br/>Possible values are:<br/>**N** - Checking is not required.<br/>**Y** - Abort if checking is not enabled. | | **cv2CheckPref** | <center>No^{<a name="4.3-5">[<span title="If the value is not supplied then the default account preferences will be used.">5</span>](#4.3-f5)</a>}<center/> | List of **`cv2Check`** response values that are to be accepted, any other value will cause the transaction to be declined.<br/><br/>Value is a comma separated list containing one or more of the following: **not known, not checked, matched, not matched, partially matched**. | | **addressCheckPref** | <center>No^{[<span title="If the value is not supplied then the default account preferences will be used.">5</span>](#4.3-f5)}<center/> | List of **`addressCheck`** values that are to be accepted, any other value will cause the transaction to be declined.<br/><br/>Value is a comma separated list containing one or more of the following: **not known, not checked, matched, not matched, partially matched**.| | **postcodeCheckPref** | <center>No^{[<span title="If the value is not supplied then the default account preferences will be used.">5</span>](#4.3-f5)}<center/> | List of **`postcodeCheck`** response values that are to be accepted, any other value will cause the transaction to be declined.<br/><br/>Value is a comma separated list containing one or more of the following: **not known, not checked, matched, not matched, partially matched**. | --- *^{<a name="4.3-f1">[1](#4.3-1)</a>} Mandatory if AVS address checking is required.* <br>*^{<a name="4.3-f2">[2](#4.3-2)</a>} Mandatory if AVS postcode checking is required.* <br>*^{<a name="4.3-f3">[3](#4.3-3)</a>} Mandatory if CV2 checking is required.* <br>*^{<a name="4.3-f4">[4](#4.3-4)</a>} The default value is **Y** if AVS/CV2 checking is enabled on the Merchant Account, otherwise **N**.* <br>*^{<a name="4.3-f5">[5](#4.3-5)</a>} If the value is not supplied then the default account preferences will be used.* --- ## 4.4 Response Fields These fields will be returned in addition to the AVS/CV2 request fields in section [4.3](#4.3) the basic response fields in section [2.2](#2.2). | Field Name | Returned? | Description | | :--------- | :-------- | :---------- | | **avscv2CheckEnabled** | <center>Always<center/> | Is AVS/CV2 checking enabled for this Merchant Account?<br/><br/>Possible values are:<br/>**N** - Merchant account is not enabled.<br/>**Y** - Merchant account is enabled. | | **avscv2ResponseCode** | <center>If checks performed<center/> | The result of the AVS/CV2 check. Refer to appendix [A-2](#A-2) for details. | | **avscv2ResponseMessage** | <center>If checks performed<center/> | The message received from the Acquiring bank, or any error message with regards to the AVS/CV2 check. Refer to appendix [A-2](#A-2) for details. | | **avscv2AuthEntity** | <center>If checks performed<center/> | Textual description of the AVS/CV2 authorizing entity as described in appendix [A-2](#A-2).<br/><br/>Possible values are: **not known, merchant host, acquirer host, card scheme, issuer**. | | **cv2Check** | <center>If checks performed<center/> | Description of the AVS/CV2 CV2 check as described in appendix [A-2](#A-2).<br/><br/>Possible values are: **not known, not checked, matched, not matched, partially matched**. | | **addressCheck** | <center>If checks performed<center/> | Description of the AVS/CV2 address check as described in appendix [A-2](#A-2).<br/><br/>Possible values are: **not known, not checked, matched, not matched, partially matched**. | | **postcodeCheck** | <center>If checks performed<center/> | Description of the AVS/CV2 postcode check as described in appendix [A-2](#A-2).<br/><br/>Possible values are: **not known, not checked, matched, not matched, partially matched**. | --- # 5 3-D Secure Authentication ## 5.1 Background 3-D Secure authentication is an additional fraud prevention scheme that is available to all Merchants using the Payment Gateway. It allows Cardholder’s to assign a password to their card that is then verified whenever a transaction is processed through a site that supports the use of the scheme. The addition of password protection allows extra security on transactions that are processed online. 3-D Secure stands for 3 Domain Server, there are 3 parties that are involved in the 3-D Secure process: + The company the purchase is being made from. + The Acquiring Bank (the bank of the company). + VISA and MasterCard (the card issuers themselves). The gateway supports 3-D Secure as implemented by Visa, Mastercard and American Express and marketed under the brand names of Verified by VISA (VBV), MasterCard Secure Code (MSC) and American Express (SafeKey). Implementations by JCB (J/Secure) and DCI (ProtectBuy) are not currently supported. 3-D Secure is also the only fraud prevention scheme that is available that offers Merchants liability cover for transactions that are verified by the checks. This provides additional protection to Merchants using the scheme as opposed to those that do not. --- ## 5.2 Benefits & Limitations ### 5.2.1 Benefits + Instant: The results are available immediately and returned as part of the transaction. + Flexible: The checks can be managed independently allowing you the upmost control over how the results are used. + Automatic: The checks can be configured to automatically decline the transaction where required. + Liability Shift: The main benefit to companies using the 3-D Secure scheme is the availability of a liability shift for a successfully authenticated transaction. This offers protection by the card issuers against charge backs as the liability is assumed. Note: You will need to check with your Acquirer for the exact terms on liability shifts. + No extra cost: There are no extra costs to add 3-D Secure onto your gateway account. Your Acquirer may charge to add this onto your Merchant Account however you may also find that your transaction charges are lower as a result of using 3-D Secure. + Easy management: The 3-D Secure scheme is controlled within the Merchant Management System (MMS). ### 5.2.2 Limitations + Chargebacks can still occur: Fully authenticated 3-D Secure transactions do not guarantee a liability shift; this is decided on the discretion of your Acquirer. + Not all cards are supported: At the moment the Gateway does not support 3-D Secure for Amex, JCB or Diner’s club cards. --- ## 5.3 Direct Implementation If your Merchant Account is setup for 3-D Secure the Gateway will require further authentication details provided by the 3-D Secure system. ### 5.3.1 Initial Request (Verify Enrolment) If no 3-D Secure authentication details are provided in the initial request the Gateway will determine if the transaction is eligible for 3-D Secure by checking if the card is enrolled in the 3-D Secure scheme. If the Gateway determines that the transaction is not eligible for 3-D Secure then it will continue and process it as a normal transaction without 3-D Secure unless the **`threeDSRequired`** request field indicates that the transaction should be aborted instead. If the Gateway determines that the transaction is eligible it will respond with a **`responseCode`** of **65802 (3DS AUTHENTICATION REQUIRED)** and included in the response will be a **`threeDSACSURL`** field containing the URL required to contact the ACS on and a **`threeDSMD`** and **`threeDSPaReq`** to send to the provided URL. The latter two values must be posted to the provided ACS URL as fields **MD** and **PaReq**, along with a **TermUrl** field provided by yourself which must contain the URL of a page on your server to return to when authentication has been completed. <a name="5.3.2"></a> ###5.3.2 Continuation Request (Check Authentication & Authorise) On completion of the 3-D Secure authentication the ACS will post the original **MD** along with a **PaRes** value to the **TermUrl** provided. These values should then be sent to the Gateway in the **`threeDSMD`** and **`threeDSPaRes`** fields of a new request. This new request will check the 3-D Secure authentication and then either complete or abort the transaction depending on the authentication result and your preferences, either sent in the **`threeDSPref`** field or set in the Merchant Management System (MMS). If you would like an example of a 3-D Secure integration, please refer to our sample code Appendix **[A-17.1](#A-17).** ### 5.3.3 External Authentication Request You can choose to obtain the 3-D Secure authentication details from a third-party, in which case they should provide them as part of a standard request. If the Gateway receives valid third-party authentication details, then it will use those and not attempt to contact the 3-D Secure system itself. ## 5.4 Hosted Implementation If your Merchant Account is enabled for 3-D Secure, the default Gateway Hosted form will automatically attempt to display the 3-D Secure authentication page for the Customer’s bank. The 3-D Secure authentication form is designed and controlled by the Customer’s bank but you can change the Merchant name and website address that is displayed on the form by sending the **`merchantName`** and/or **`merchantWebsite`** request fields. Any **`merchantWebsite`** must be a fully qualified URL containing at least the scheme and host components. <a name="5.5"></a> --- ## 5.5 Request Fields ### 5.5.1 Initial Request These fields should be send in addition to basic request fields in section [2.1](#2.1). | Field Name | Mandatory? | Description | | :--------- | :--------- | :---------- | | **merchantName** | <center>No^{<a name="5.5-1">[<span title="If the value is not supplied then the default account preferences will be used.">1</span>](#5.5-f1)</a>}<center/> | Merchant name to use on 3DS form. | | **merchantWebsite** | <center>No^{[<span title="If the value is not supplied then the default account preferences will be used.">1</span>](#5.5-f1)}<center/> | Merchant website to use on 3DS form. The website must be a fully qualified URL and include at least the scheme and host components. | | **threeDSRequired** | <center>No^{<a name="5.5-2">[<span title="The default value is Y if 3-D Secure is enabled on the Merchant Account, otherwise N.">2</span>](#5.5-f2)</a>}<center/> | Is 3DS required for this transaction?<br/><br/>Possible values are:<br/>**N** - 3DS is not required.<br/>**Y** - Abort if 3DS is not enabled. | | **threeDSCheckPref** | <center>No^{[<span title="If the value is not supplied then the default account preferences will be used.">1</span>](#5.5-f1)}<center/> | List of **`threeDSCheck`** response values that are to be accepted, any other value will cause the transaction to be declined.<br/><br/>Value is a comma separated list containing one or more of the following values: **‘not known', 'not checked', ' not authenticated', 'attempted authentication', 'authenticated’**. | --- *^{<a name="5.5-f1">[1](#5.5-1)</a>} If the value is not supplied then the default account preferences will be used.* <br>*^{<a name="5.5-f2">[2](#5.5-2)</a>} The default value is **Y** if 3-D Secure is enabled on the Merchant Account, otherwise **N**.* --- In addition for Direct Implementation, the below fields can be sent; ### 5.5.2 Continuation Request (Direct Only) These fields may be sent alone. | Field Name | Mandatory? | Description | | :--------- | :--------- | :---------- | | **threeDSMD** | <center>Yes<center/> | The value of the **`threeDSMD`** field in the initial Gateway response. | | **threeDSPaRes** | <center>Yes<center/> | The value of the **`PaRes`** field POSTed back from the Access Control Server (ACS). | Note: It is only necessary to send the **`threeDSMD`** and the **`threeDSPaRes`** in the continuation request as the **`threeDSMD`** will identify the Merchant Account and initial request. The message does not need to be signed. However, you can send any of the normal request fields to modify or supplement the initial request. Any card details and transaction amount sent in the second request must match those used in the first request, or the second request will fail with a **`responseCode`** of **64442 (REQUEST MISMATCH)**. ### 5.5.3 External Authentication Request (Direct Only) These fields should be sent in addition to basic request fields from section [2.1](#2.1). | Field Name | Mandatory? | Description | | :--------- | :--------- | :---------- | | **threeDSEnrolled** | <center>If 3DS enabled<center/> | The 3DS enrolment status for the credit card. Refer to appendix [A-3](#A-3) for details. | | **threeDSAuthenticated** | <center>If 3DS enrolled<center/> | The 3DS authentication status for the credit card. Refer to appendix [A-3](#A-3b) for details. | | **threeDSXID** | <center>If 3DS authenticated<center/> | The unique identifier for the transaction in the 3DS system. | | **threeDSECI** | <center>If 3DS authenticated<center/> | The Electronic Commerce Indicator (ECI). | | **threeDSCAVV** | <center>If 3DS authenticated<center/> | The Cardholder Authentication Verification Value (CAVV). | Note: If 3-D Secure is not enabled for the Merchant Account then any 3-D Secure authentication fields sent in the request are ignored and the transaction is processed as normal without 3-D Secure. <a name="5.6.1"></a> --- ## 5.6 Response Fields ### 5.6.1 Initial Response These fields will be returned in addition to the request fields from section [5.5](#5.5) and the basic response fields in section [2.2](#2.2). | Field Name | Returned? | Integration Type | Description | | :--------- | :-------: | :----------: | :---------- | | **threeDSEnabled** | <center>Always<center/> | <center>Both<center/> | Is 3DS enabled for this Merchant Account?<br/><br/>Possible values are:<br/>**N** - Merchant account is not enabled.<br/>**Y** - Merchant account is enabled. | | **threeDSXID** | <center>If 3DS enabled<center/> | <center>Both<center/> | The unique identifier for the transaction in the 3DS system. | | **threeDSVETimestamp** | <center>If 3DS enabled<center/> | <center>Both<center/> | The time the card was checked for 3DS enrolment. | | **threeDSEnrolled** | <center>If 3DS enabled<center/> | <center>Both<center/> | The 3DS enrolment status for the credit card. Refer to appendix [A-3](#A-3) for details.<br/><br/>Possible values are:<br/>**Y** – Enrolled<br/>**N** - Not Enrolled<br/>**U** - Unable to Verify<br/>**E** - Error Verifying Enrolment | | **threeDSMD** | <center>If 3DS enabled<center/> | <center>Direct<center/> | Value to return in the continuation request. Can be sent to the Access Control Server (ACS) in its MD field or stored locally by your server. | | **threeDSACSURL** | <center>If 3DS enrolled<center/> | <center>Both<center/> | The URL of the Access Control Server (ACS) to which the Payer Authentication Request (PaReq) should be sent. | | **threeDSPaReq** | <center>If 3DS enrolled<center/> | <center>Both<center/> | Payer Authentication Request (PaReq) that is sent to the Access Control Server (ACS) in order to verify the 3DS status of the credit card. | ### 5.6.2 Continuation Response These fields will be returned in addition to the request fields from section [5.5](#5.5), the initial response fields in section [5.6.1](#5.6.1) and the basic response fields in section [2.2](#2.2). | Field Name | Returned? | Integration Type | Description | | :--------- | :-------- | :--------: | :---------- | | **threeDSPaRes** | <center>If 3DS enrolled<center/> | <center>Both<center/> | Payer Authentication Response (PaRes) that is returned from the Access Control Server (ACS) determining the 3DS status of the credit card. | | **threeDSCATimestamp** | <center>If 3DS enrolled<center/> | <center>Both<center/> | The time the card was checked for 3DS authentication. | | **threeDSAuthenticated** | <center>If 3DS enrolled<center/> | <center>Both<center/> | The 3DS authentication status for the credit card. Refer to appendix [A-3](#A-3b) for details.| | **threeDSECI** | <center>If 3DS authenticated<center/> | <center>Both<center/> | This contains a two digit Electronic Commerce Indicator (ECI) value, which is to be submitted in a credit card authorisation message. This value indicates to the processor that the Customer data in the authorisation message has been authenticated. The data contained within this property is only valid if the **`threeDSAuthenticated`** value is **Y** or **A**. | | **threeDSCAVV** | <center>If 3DS authenticated<center/> | <center>Both<center/> | This contains a 28-byte Base-64 encoded Cardholder Authentication Verification Value (CAVV). The data contained within this property is only valid if the **`threeDSAuthenticated`** value is **Y** or **A**. | | **threeDSCAVVAlgorithm** | <center>If 3DS authenticated<center/> | <center>Both<center/> | This contains the one digit value which indicates the algorithm used by the Access Control Server (ACS) to generate the CAVV. The data contained within this property is only valid if the **`threeDSAuthenticated`** value is **Y** or **A**. | | **threeDSErrorCode** | <center>If 3DS error<center/> | <center>Both<center/> | Any error response code returned by the Access Control Server (ACS) should there be an error in determining the card’s 3DS status. | | **threeDSErrorDescription** | <center>If 3DS error<center/> | <center>Both<center/> | Any error response description returned by the Access Control Server (ACS) should there be an error in determining the card's 3DS status. | ### 5.6.3 External Authentication Response These fields will be returned in addition to the request fields from section [5.5](#5.5) and the basic response fields in section [2.2](#2.2). | Field Name | Returned? | Integration Type | Description | | :--------- | :-------- | :--------: | :---------- | | **threeDSEnabled** | <center>Always<center/> | <center>Both<center/> | Is 3DS enabled for this Merchant Account?<br/><br/>Possible values are:<br/>**N** - Merchant account is not enabled.<br/>**Y** - Merchant account is enabled. | Note: If 3-D Secure is not enabled for the Merchant Account then any 3-D Secure authentication fields sent in the request are ignored and the transaction is processed as normal without 3-D Secure. --- # 6 VISA MCC6012 Merchants ## 6.1 Background Following changes implemented by VISA, any UK business falling under merchant category code 6012 must provide additional details with any transaction that is processed through their account. This mainly applies to financial institutions. According to Visa, the additional rules were brought in to protect consumers and prevent fraud. The Acquirer will inform you if they need to send this information. ### 6.1.1 Requirements This section only applies to transactions that: + Involve a Merchant with a MCC 6012 category code. + Use VISA. + Process a UK domestic payment. If any of the above three criteria do not apply, then no additional data need be supplied in the transaction. ### 6.1.2 Additional fields/information Merchants assigned the code MCC 6012 must collect the following data for the primary recipient for each UK domestic VISA transaction: + Unique account identifier for the loan or outstanding balance funded. For example, the loan account number or the PAN (Primary Account Number) if it is a credit card balance. + Last name (family name) + Date of Birth (D.O.B) + Postcode Primary recipients are the entities (people or organisations) that have a direct relationship with the financial institution. Also, these primary recipients have agreed to the terms and conditions of the financial institution. --- ## 6.2 Request Fields To comply with the rules, an MCC6012 Merchant must send these additional fields: | Field Name | Mandatory? | Description | | :--------- | :--------- | :---------- | | **merchantCategoryCode** | <center>Yes^{<a name="6.2-1">[<span title="Only required if the Merchants Category Code is not configured on their gateway account.">1</span>](#6.2-f1)</a>}<center/> | Merchant’s VISA MCC (should be 6012). | | **receiverName** | <center>Yes<center/> | Surname only - up to 6 letters allowed. | | **receiverAccountNo** | <center>Yes<center/> | Account number. If a PAN is supplied then only the first 6 and last 4 digits will be used. | | **receiverDateOfBirth** | <center>Yes<center/> | Primary recipient’s date of birth. **ISO Date Format: YYYY-MM-DD** | | **receiverPostcode** | <center>Yes<center/> | Primary recipient’s postcode. (Only the district is required but full postcodes are accepted, therefore ‘W12 8QT’ or just ‘W12’ are acceptable values). | --- *^{<a name="6.2-f1">[1](#6.2-1)</a>} Only required if the Merchants Category Code is not configured on their gateway account.* --- #7 Billing Descriptor ## 7.1 Background The Billing Descriptor is how your details appear on the Cardholder’s statement. It is set up with the Acquirer when the Merchant Account is opened. It is used by the Cardholder to identify who a payment was made to on a particular transaction. Selecting a clear Billing Descriptor is important for a Merchant to avoid a chargeback when the Cardholder does not recognise the name on the transaction. ### 7.1.1 Static Descriptor The Static Descriptor is the descriptor agreed between Merchant and Acquirer when the Merchant Account is opened. The descriptor used is typically the Merchant trading name, location and contact phone number. ### 7.1.2 Dynamic Descriptor The Dynamic Descriptor is a descriptor sent with the transaction that includes details on the goods purchased or service provided, this is often used by large companies that provide many services and where the brand of the service is more familiar than the company name. The Dynamic Descriptor usually replaces any Static Descriptor on a per transaction basis. Not all Acquirers accept Dynamic Descriptors and for those that do the format required varies. Often the Merchant name is shortened to three (3) letters, followed by an asterisk (*), followed by a short description of the service or product that the business provides. This field typically has a limit of twenty-five (25) characters including the phone number. For more information on whether your Acquirer allows Dynamic Descriptor and the format they should be sent in please contact your support representative. --- ## 7.2 Request Fields The Dynamic Descriptor is built using one or more of the following narrative fields. | Field Name | Mandatory? | Description | | :--------- | :--------- | :---------- | | **statementNarrative1** | <center>No<center/> | Merchant’s name. | | **statementNarrative2** | <center>No<center/> | Product, service or other descriptive info. | --- # 8 Purchase Data ## 8.1 Background The Gateway can be sent advanced purchase information with each transaction where required. The Gateway provides a number of fields which you can use to store advanced purchase information about the transaction including details on individual items purchased etc. These fields are only sent to the Acquirer if needed. The stored data can be obtained by sending a **QUERY** request. Refer to section [1.7](#1.7) for more information. The details may also be used for advanced purposes such as displaying shopping cart information on the MasterPass™ checkout or sending full receipt details to the eReceipts™ system. ### 8.1.1 American Express Purchases Purchases using American Express cards will send a subset of this information to the card scheme as appropriate. With American Express you can provide tax **or** discount reason (but not both). If **`taxAmount`** is provided then **`taxReason`** is used, if **`discountAmount`** is provided then **`discountAmount`** is used. If both are provided then **`taxReason`** is used. Only the first six line item details are sent to American Express and then only the **`itemXXDescription`**, **`itemXXQuantity`** and **`itemXXGrossAmount`** fields are sent. ### 8.1.2 Purchase Orders These fields along with other advanced fields as detailed in section [12](#12) can be used to send full information relating to a purchase order and related invoice indicating types, quantities and agreed prices for products or services. Details on the supplier, shipping, delivery etc. can also be included. *At present this information is not sent to the Acquirer but future enhancements to the Gateway may include sending such information as Level 2 or 3 Purchasing data as defined by the relevant card schemes.* --- ## 8.2 Request Fields | Field Name | Mandatory? | Description | | :--------- | :--------- | :---------- | | **grossAmount** | <center>No<center/> | Total gross amount of sale. | | **netAmount** | <center>No<center/> | Total net amount of sale. | | **taxRate** | <center>No<center/> | Total tax rate (percentage). | | **taxAmount** | <center>No^{<a name="8.2-1">[<span title="Amex/Diners require either tax or discount, not both.">1</span>](#8.2-f1)</a>}<center/> | Total tax amount of sale. | | **taxReason** | <center>No^{[<span title="Amex/Diners require either tax or discount, not both.">1</span>](#8.2-f1)}<center/> | Reason for above tax (i.e. VAT). | | **discountAmount** | <center>No^{[<span title="Amex/Diners require either tax or discount, not both.">1</span>](#8.2-f1)}<center/> | Total discount amount of sale. | | **discountReason** | <center>No^{[<span title="Amex/Diners require either tax or discount, not both.">1</span>](#8.2-f1)}<center/> | Reason for above discount. | | **itemXXAmount^{<a name="8.2-2">[<span title="XX is a number between 1 and 99.">2</span>](#8.2-f2)</a>}** | <center>No<center/> | Amount for XXth item purchased. | | **itemXXDescription^{[<span title="XX is a number between 1 and 99.">2</span>](#8.2-f2)}** | <center>No<center/> | Description of XXth item purchased. | | **itemXXQuantity^{[<span title="XX is a number between 1 and 99.">2</span>](#8.2-f2)}** | <center>No<center/> | Quantity of XXth item purchased. | | **itemXXGrossAmount^{[<span title="XX is a number between 1 and 99.">2</span>](#8.2-f2)}** | <center>No<center/> | Gross amount for XXth item purchased. | | **itemXXNetAmount^{[<span title="XX is a number between 1 and 99.">2</span>](#8.2-f2)}** | <center>No<center/> | Net amount for XXth item purchased. | | **itemXXTaxAmount^{[<span title="XX is a number between 1 and 99.">2</span>](#8.2-f2)}** | <center>No<center/> | Tax amount for XXth item purchased. | | **itemXXTaxRate^{[<span title="XX is a number between 1 and 99.">2</span>](#8.2-f2)}** | <center>No<center/> | Total tax rate for XXth item purchased. | | **itemXXTaxReason^{[<span title="XX is a number between 1 and 99.">2</span>](#8.2-f2)}** | <center>No<center/> | Tax reason for XXth item purchased. | | **itemXXDiscountAmount^{[<span title="XX is a number between 1 and 99.">2</span>](#8.2-f2)}** | <center>No<center/> | Total discount for XXth item purchased. | | **itemXXDiscountReason^{[<span title="XX is a number between 1 and 99.">2</span>](#8.2-f2)}** | <center>No<center/> | Discount reason for XXth item purchased. | | **itemXXProductCode^{[<span title="XX is a number between 1 and 99.">2</span>](#8.2-f2)}** | <center>No<center/> | Product code for XXth item purchased. | | **itemXXCommodityCode^{[<span title="XX is a number between 1 and 99.">2</span>](#8.2-f2)}** | <center>No<center/> | Commodity code for XXth item purchased. | | **itemXXUnitOfMeasure^{[<span title="XX is a number between 1 and 99.">2</span>](#8.2-f2)}** | <center>No<center/> | Unit of measure for XXth item purchased. | | **itemXXUnitAmount^{[<span title="XX is a number between 1 and 99.">2</span>](#8.2-f2)}** | <center>No<center/> | Unit amount for XXth item purchased. | | **items** | <center>No^{<a name="8.2-3">[<span title="Used as an alternative to itemXXField format, both formats cannot be sent together.">3</span>](#8.2-f3)</a>}<center/> | Nested array of line items. | --- *^{<a name="8.2-f1">[1](#8.2-1)</a>} Amex/Diners require either tax or discount, not both.* <br>*^{<a name="8.2-f2">[2](#8.2-2)</a>} XX is a number between 1 and 99.* <br>*^{<a name="8.2-f3">[3](#8.2-3)</a>} Used as an alternative to **`itemXXField`** format, both formats cannot be sent together.* --- Note: no attempt is made to check that any gross, net and tax amounts are correct with respect to each other. It is the sender’s responsibility to ensure alternative amount formats are correct. Line item fields can either be sent ‘flat’ using field names containing the item row number as a sequential number from 1 to 99 or using nested arrays of the form **`items[XX][field]`** where **`XX`** is the row number from 1 to 99 and **`field`** is the field name from the above table without the **`itemXX`** prefix and starting with a lowercase first letter. For example, the tax rate for item 5 can either be sent as **`item5TaxRate`** or as **`items[5][taxRate]`**. The two formats should not be mixed. If a request field of items is seen then the ‘flat’ fields are ignored. --- # 9 Receipts & Notifications ## 9.1 Background The Gateway can be configured to automatically email transaction receipts to the Customer and notifications to you the Merchant. The Gateway is also integrated into the eReceipts™ system which stores Customer receipts for access online. ### 9.1.1 Customer Email Receipts The Customer can be automatically emailed a transaction receipt each time a transaction is processed by the Gateway. Receipts are sent at the time the transaction is authorised and only for transactions where the Acquirer has approved the authorisation. Receipts are not sent for declined or referred authorisations or aborted transactions. This functionality is enabled globally on a per Merchant Account basis using the Merchant Management System (MMS). This global setting can also be overridden per transaction if required using the **`customerReceiptsRequired`** field. Customer receipts require the Customer to provide their email address; if no email address is sent in the **`customerEmail`** field then no receipt will be sent. ### 9.1.2 Merchant Email Notifications You can be automatically emailed a transaction notification each time a transaction is processed by the Gateway. Notifications are sent at the time the transaction is authorised and only for transactions where the Acquirer approved, declined or referred the authorisation. Notifications are not sent for aborted transactions. This functionality is enabled globally on a per Merchant Account basis using the Merchant Management System (MMS). This global setting can also be overridden per transaction if required using the **`notifyEmailRequired`** field. ### 9.1.3 Customer Online Receipts The Gateway is integrated with the eReceipts™ system run by Paperless Receipts Ltd. This system is used by many high street retailers and allows a Merchant to capture data allowing a far deeper understanding and insight into their Customers’ shopping habits. Receipt information is sent to eReceipts™ at the time the transaction is authorised and only for transactions where the Acquirer has approved the authorisation. Receipt information is not sent for declined or referred authorisations or aborted transactions. This functionality is enabled globally on a per Merchant Account basis using the Merchant Management System (MMS). This global setting can also be overridden per transaction if required using the **`eReceiptsRequired`** field. You must supply a unique Customer reference (using the **`eReceiptsCustomerRef`** field) or, alternatively, the use of the Customer’s email address (using the **`customerEmail`** field) to identify the Customer in the eReceipts™ system. If purchase item data is sent in a transaction, then this will be used to build an itemised electronic receipt. For more information regarding purchase data please refer to section [9.3](#9.3), for information on which fields are used to build the electronic receipt refer to section [9.2](#9.2) below. <a name="9.2"></a> --- ## 9.2 Request Fields ### 9.2.1 General Fields | Field Name | Mandatory? | Description | | :--------- | :--------- | :---------- | | **customerReceiptsRequired** | <center>No^{<a name="9.2.1-1">[<span title="Overrides any global setting configured via the Merchant Management System (MMS).">1</span>](#9.2.1-f1)</a>}<center/> | Send a Customer receipt if possible.<br/><br/>Possible values are:<br/>**N** - Don’t send a receipt.<br/>**Y** - Send if Customer’s email provided. | | **customerEmail** | <center>No<center/> | Customer’s email address. | | **notifyEmailRequired** | <center>No^{[<span title="Overrides any global setting configured via the Merchant Management System (MMS).">1</span>](#9.2.1-f1)}<center/> | Send a notification email if possible.<br/><br/>Possible values are:<br/>**N** - Don’t send a notification.<br/>**Y** - Send if notification email provided. | | **notifyEmail** | <center>No<sup>^{[<span title="Overrides any global setting configured via the Merchant Management System (MMS).">1</span>](#9.2.1-f1)}<center/> | Merchant’s notification email address. | | **eReceiptsRequired** | <center>No^{[<span title="Overrides any global setting configured via the Merchant Management System (MMS).">1</span>](#9.2.1-f1)}<center/> | Send receipt data to eReceipts™ system.<br/><br/>Possible values are:<br/>**N** - Don’t send data.<br/>**Y** - Send data if API details provided. | | **eReceiptsStoreID** | <center>No^{[<span title="Overrides any global setting configured via the Merchant Management System (MMS).">1</span>](#9.2.1-f1)}<center/> | eReceipts™ store identifier. | | **eReceiptsCustomerRef** | <center>No^{<a name="9.2.1-2">[<span title="Required if eReceipts™ is required and no customerEmail is sent.">2</span>](#9.2.1-f2)</a>}<center/> | eReceipts™ Customer reference. | | **eReceiptsApiKey** | <center>No^{[<span title="Overrides any global setting configured via the Merchant Management System (MMS).">1</span>](#9.2.1-f1)}<center/> | eReceipts™ API key. | | **eReceiptsApiSecret** | <center>No^{[<span title="Overrides any global setting configured via the Merchant Management System (MMS).">1</span>](#9.2.1-f1)}<center/> | eReceipts™ API secret. | | **eReceiptsReceiptRef** | <center>No<center/> | eReceipts™ receipt reference. | | **eReceiptsReceiptData** | <center>No^{<a name="9.2.1-3">[<span title="Allows complete eReceipts™ data to be sent rather than constructing it from the transaction.">3</span>](#9.2.1-f3)</a>}<center/> | Complete eReceipts™ data. | --- *^{<a name="9.2.1-f1">[1](#9.2.1-1)</a>} Overrides any global setting configured via the Merchant Management System (MMS).* <br>*^{<a name="9.2.1-f2">[2](#9.2.1-2)</a>} Required if eReceipts™ is required and no **`customerEmail`** is sent.* <br>*^{<a name="9.2.1-f3">[3](#9.2.1-3)</a>} Allows complete eReceipts™ data to be sent rather than constructing it from the transaction.* --- ### 9.2.2 eReceipts™ Itemised Receipt Data | Field Name | Mandatory? | Description | | :--------- | :--------- | :---------- | | **grossAmount** | <center>No<center/> | Total gross amount of sale. | | **netAmount** | <center>No<center/> | Total net amount of sale. | | **taxAmount** | <center>No<center/> | Total tax amount of sale. | | **taxRate** | <center>No<center/> | Total tax rate (percentage). | | **discountAmount** | <center>No<center/> | Total discount amount of sale. | | **discountReason** | <center>No<center/> | Reason for above discount. | | **itemXXDescription** | <center>No<center/> | Description of XXth item purchased. | | **itemXXQuantity** | <center>No<center/> | Quantity of XXth item purchased. | | **itemXXGrossAmount** | <center>No<center/> | Gross amount for XXth item purchased. | | **itemXXTaxAmount** | <center>No<center/> | Tax amount for XXth item purchased. | | **itemXXTaxRate** | <center>No<center/> | Total tax rate for XXth item purchased. | | **itemXXDiscountAmount** | <center>No<center/> | Total discount for XXth item purchased. | | **itemXXDiscountReason** | <center>No<center/> | Discount reason for XXth item purchased. | | **itemXXProductCode** | <center>No<center/> | Product code for XXth item purchased. | | **itemXXCommodityCode** | <center>No<center/> | Commodity code for XXth item purchased. | | **itemXXUnitOfMeasure** | <center>No<center/> | Unit of measure for XXth item purchased. | | **itemXXUnitAmount** | <center>No<center/> | Unit amount for XXth item purchased. | | **items** | <center>No^{<a name="9.2.2-1">[<span title="Used as an alternative to itemXXField format, both formats cannot be sent together.">1</span>](#9.2.2-f1)</a>}<center/> | Nested array of line items. | --- *^{<a name="9.2.2-f1">[1](#9.2.2-1)</a>} Used as an alternative to **`itemXXField`** format, both formats cannot be sent together.* --- Note: no attempt is made to check that any gross, net and tax amounts are correct with respect to each other. It is the sender’s responsibility to ensure alternative amount formats are correct. <a name="9.3"></a> ## 9.3 Response Fields The request fields for the required receipts and notifications are returned along with the appropriate fields from the following. | Field Name | Returned? | Description | | :--------- | :-------- | :---------- | | **customerReceiptsResponseCode** | If required | Result of sending email to Customer. Refer to appendix [A-1](#A-1) for details. | | **customerReceiptsResponseMessage** | If required | Description of above response code. | | **notifyEmailResponseCode** | If required | Result of sending email to Merchant. Refer to appendix [A-1](#A-1) for details. | | **notifyEmailResponseMessage** | If required | Description of above response code. | | **eReceiptsEnabled** | If required | Is eReceipts™ enabled for this Merchant Account?<br/><br/>Possible values are:<br/>**N** - Merchant account is not enabled.<br/>**Y** - Merchant account is enabled. | | **eReceiptsStoreID** | If&nbsp;required^{<a name="9.3-1">[<span title="Either the value sent in the request or that calculated from the default account preferences.">1</span>](#9.3-f1)</a>} | Merchant’s eReceipts™ store identifier. | | **eReceiptsReceiptRef** | If required | Unique eReceipt™ reference. | | **eReceiptsResponseCode** | If required | Result of sending details to eReceipts™. Refer to appendix [A-1](#A-1) for details. | | **eReceiptsResponseMessage** | If required | Description of above response code. | --- *^{<a name="9.3-f1">[1](#9.3-1)</a>} Either the value sent in the request or that calculated from the default account preferences.* <a name="10"></a> --- # 10 Recurring Transaction Agreements ## 10.1 Background A Recurring Transaction Agreement (RTA) is used to request that the Gateway repeat payments on your behalf using pre-agreed amounts and schedule. An RTA can be easily and quickly configured using the Merchant Management System (MMS) but can also be setup while performing the initial request by including the following integration request fields. The RTA is only setup in the transaction results in a success payment authorisation. The initial transaction should be either a normal transaction or the initial transaction in a Continuous Payment Authority agreement. This will dictate whether the subsequent repeat transactions are taken as ‘Card On File’ or ‘Continuous Authority’ transactions. Refer to appendix [A-15](#A-15) for more information on the different types of repeat or recurring transactions. ## 10.2 Request Fields | Field Name | Mandatory? | Description | | :--------- | :--------- | :---------- | | **rtName** | <center>No<center/> | Free format short name for the agreement. | | **rtDescription** | <center>No<center/> | Free format longer description for the agreement. | | **rtPolicyRef** | <center>No<center/> | Merchant Reference (MPRN). | | **rtAgreementType** | <center>No<center/> | <p>Recurring transaction agreement type.<p/><p>When provided the initial transaction will be marked as the first in a Continuous Payment Authority (CPA) agreement and subsequent scheduled repeat transactions will be made as part of that CPA.<p/>If not provided then the initial transaction will be a standard transaction and the subsequent scheduled repeat transactions will be taken as ad-hoc 'Card On File' transactions.<p/><br/>Possible values are:<br/> **not provided** - use 'Card On File'. <br/> **recurring** – use a recurring type CPA. <br/> **instalment** – use an instalment type CPA. | | **rtUnique** | <center>No<center/> | Unique id for recurring transactions, will be appended with transaction count (defaults to **`transactionUnique`**). | | **rtMerchantID** | <center>No<center/> | Merchant ID to use for the recurring transactions (defaults to **`merchantID`**). | | **rtStartDate** | <center>No<center/> | Start date of agreement (default to date request received). | | **rtInitialDate** | <center>No<center/> | Date of initial payment (defaults to rtStartDate).<br/>Format: YYYY-MM-DD HH:MM:SS | | **rtInitialAmount** | <center>No<center/> | Amount of initial payment (defaults to **`rtCycleAmount`**). | | **rtFinalDate** | <center>No<center/> | Date of final payment.<br/>Format: YYYY-MM-DD HH:MM:SS | | **rtFinalAmount** | <center>No<center/> | Amount of final payment (defaults to **`rtCycleAmount`**). | | **rtCycleAmount** | <center>No<center/> | Amount per cycle (defaults to **`amount`**). | | **rtCycleDuration** | <center>Yes<center/> | Cycle duration. | | **rtCycleDurationUnit** | <center>Yes<center/> | Cycle duration unit. One of the following values: **day**, **week**, **month** or **year**. | | **rtCycleCount** | <center>Yes<center/> | Number of cycles to repeat (defaults to repeat forever). | | **rtMerchantData** | <center>No<center/> | Free format Merchant data field. | | **rtScheduleType** | <center>No<center/> | The scheduled type of the recurring transaction. Defaults to **fixed**. <br /><br /> Accepts the following values:<br /> <br /> **fixed** - Payments are taken on fixed dates/cycles, e.g. every day, every month. <br /><br /> **variable** - Payments are taken on specified dates set by the **rtSchedule** field. | | **rtSchedule** | <center>No^{<a name="10.2-f1">[<span title="Used as an alternative to itemXXField format, both formats cannot be sent together.">1</span>](#10.2-f1)</a>}<center/> | If a type of **variable** has been passed in **rtScheduleType**, **rtSchedule** will be required to be passed to the gateway. This will determine the variable date range for when the recurring transaction agreement payments take place.<br /> <br /> This field expects a multidimensional array with a key/value pair of 'date' and 'amount', e.g. <br /> <br /> 'rtSchedule' => array( <br /> &emsp; array ( <br /> &emsp; &emsp; 'date' => '2018-06-01', <br /> &emsp; &emsp; 'amount' => '1.10', <br /> &emsp; ), <br /> &emsp; array ( <br /> &emsp; &emsp; 'date' => '2018-06-02', <br /> &emsp; &emsp; 'amount' => '1.20', <br /> &emsp; ), <br /> ),| --- ^{<a name="10.2-f1">[1](#10.2-f1)</a>} Mandatory if the value of the field **rtScheduleType** equals **variable** <a name="10"></a> --- ## 10.3 Response Fields | Field Name | Returned? | Description | | :--------- | :-------- | :---------- | | **rtID** | <center>Always<center/> | Recurring Transaction Agreement ID. | | **rtResponseCode** | <center>Always<center/> | Result of setting up RT Agreement. Refer to appendix [A-1](#A-1) for details. | | **rtResponseMessage** | <center>Always<center/> | Description of above response code. | <a name="11"></a> --- # 11 Duplicate Transaction Checking ## 11.1 Background Duplicate transaction checking prevents transaction requests from accidentally processing more than once. This can happen if a Customer refreshes your checkout page or clicks a button that issues a new transaction request. While duplicate checking can help prevent repeat transactions from going through, we recommend talking with your developers to see if changes can be made to your form to reduce the likelihood of this occurring (e.g. disabling the Submit button after it’s clicked). ## 11.2 Implementation To help prevent duplicate transactions each transaction can specify a time window during which previous transactions will be checked to see if they could be possible duplicates. This time window is specified using the **`duplicateDelay`** field. The value for this field can range from 0 to 9999 seconds (approx 2 ¾ hours). If the transaction request does not include the **`duplicateDelay`** field or specifies a value of zero, then a default delay of 300 seconds (5 minutes) is used. The following fields are used in transaction comparison and must be the same for a transaction to be regarded as a duplicate; + **`merchantID`** + **`action`** + **`type`** + **`amount`** + **`transactionUnique`** + **`currencyCode`** + **`xref`** (if provided in lieu of card details) + **`cardNumber`** (may be specified indirectly via cross reference) If a transaction is regarded as being a duplicate, then a **`responseCode`** of **65554 (REQUEST DUPLICATE**) will be returned. ## 11.3 Request Fields | Field Name | Mandatory? | Description | | :--------- | :--------- | :---------- | | **duplicateDelay** | <center>No<center/> | Duplicate transaction time window in seconds. **Numeric value between 0 and 9999**. | <a name="12"></a> --- # 12 Custom Data You may send arbitrary data with the request by appending extra fields, which will be returned in the response unmodified. These extra fields are merely ‘echoed’ back and not stored by the Payment Gateway. Caution should be made to ensure that any extra fields do not match any currently documented fields or possible future fields; one way to do this is to prefix the field names with a value unique to you the Merchant. You can also use the **`merchantData`** field to store custom data with the transaction. This stored data can then be retrieved at a later date using a QUERY request. Associative data can be serialised using the notation **`merchantData[name]=value`**. ## 12.6 Request Fields | Field Name | Mandatory? | Description | | :--------- | :--------- | :---------- | | **merchantData** | <center>No<center/> | Arbitrary data to be stored along with this transaction. | --- # 13 Advanced Integration Fields The Gateway provides a number of fields that you can use to store information about the transaction. These fields are only sent to the Acquirer if needed. The stored data can be obtained by sending a direct QUERY request. Refer to section [1.7](#1.7) for more details. <a name="13.1"></a> ## 13.1 Customer Request Fields These fields can be used to store details about the Customer and any relationship between the Customer and Merchant such as any purchase order raised etc. If AVS checks are in use, then the Customer and Cardholder are assumed to be the same person and the address and postcode fields are taken as being the registered billing address of the card. | Field Name | Mandatory? | Description | | :--------- | :--------- | :---------- | | **customerName** | <center>No<center/> | Cardholder’s name. | | **customerCompany** | <center>No<center/> | Cardholder’s company (if applicable). | | **customerAddress** | <center>No<sup><a name="13.1-1">[<span title="Mandatory if AVS checking required.">1</span>](#13.1-f1)</a><center/> | Cardholder’s address. | | **customerPostcode** | <center>No^{[<span title="Mandatory if AVS checking required.">1</span>](#13.1-f1)}<center/> | Cardholder’s postcode. | | **customerTown** | <center>No<center/> | Cardholder’s town/city. | | **customerCounty** | <center>No<center/> | Cardholder’s county/province. | | **customerCountryCode** | <center>No<center/> | Cardholder’s country. ISO-3166 alpha or numeric code. | | **customerPhone** | <center>No<center/> | Cardholder’s phone number. | | **customerMobile** | <center>No<center/> | Cardholder’s mobile phone number. | | **customerFax** | <center>No<center/> | Cardholder’s fax number. | | **customerEmail** | <center>No<center/> | Cardholder’s email address. | | **customerOrderRef** | <center>No<center/> | Customer’s reference for this order (Purchase Order Reference). | | **customerMerchantRef** | <center>No<center/> | Customer’s reference for the Merchant. | | **customerTaxRef** | <center>No<center/> | Customer’s tax reference number. | --- *^{<a name="13.1-f1">[1](#13.1-1)</a>} Mandatory if AVS checking required.* --- ## 13.2 Merchant Request Fields These fields can be used to store details about the Merchant and any relationship between the Merchant and Customer such as any invoice reference etc. | Field Name | Mandatory? | Description/Value | | :--------- | :--------- | :---------------- | | **merchantName** | <center>No<center/> | Merchant’s contact name. | | **merchantCompany** | <center>No<center/> | Merchant’s company name. | | **merchantAddress** | <center>No<center/> | Merchant’s contact address. | | **merchantTown** | <center>No<center/> | Merchant’s contact town/city. | | **merchantCounty** | <center>No<center/> | Merchant’s contact county. | | **merchantPostcode** | <center>No<center/> | Merchant’s contact postcode. | | **merchantCountryCode** | <center>No<center/> | Merchant’s contact country. **Valid ISO-3166 alpha or numeric code**. | | **merchantPhone** | <center>No<center/> | Merchant’s phone. | | **merchantMobile** | <center>No<center/> | Merchant’s mobile phone number. | | **merchantFax** | <center>No<center/> | Merchant’s fax number. | | **merchantEmail** | <center>No<center/> | Merchant’s email address. | | **merchantWebsite** | <center>No<center/> | Merchant’s website. The website must be a fully qualified URL and include at least the scheme and host components. | | **merchantOrderRef** | <center>No<center/> | Merchant’s reference for this order. (Invoice/Sales Reference) | | **merchantCustomerRef** | <center>No<center/> | Merchant’s reference for the Customer. | | **merchantTaxRef** | <center>No<center/> | Merchant’s tax reference number. | | **merchantOriginalOrderRef** | <center>No<center/> | Reference to a back order. | | **merchantCategoryCode** | <center>No<center/> | Scheme assigned Merchant Category Code (MCC). | ## 13.3 Supplier Request Fields These fields can be used to store details about the Supplier address. This is where any purchased goods are being supplied from, if different to the Merchant‘s address. | Field Name | Mandatory? | Description/Value | | :--------- | :--------- | :---------------- | | **supplierName** | <center>No<center/> | Supplier’s contact name. | | **supplierCompany** | <center>No<center/> | Supplier’s company name. | | **supplierAddress** | <center>No<center/> | Supplier’s contact address. | | **supplierTown** | <center>No<center/> | Supplier’s contact town/city. | | **supplierCounty** | <center>No<center/> | Supplier’s contact county. | | **supplierPostcode** | <center>No<center/> | Supplier’s contact postcode. | | **supplierCountryCode** | <center>No<center/> | Supplier’s contact country.<br/>**Valid ISO-3166 alpha or numeric code**. | | **supplierPhone** | <center>No<center/> | Supplier’s phone. | | **supplierMobile** | <center>No<center/> | Supplier’s mobile phone number. | | **supplierFax** | <center>No<center/> | Supplier’s fax number. | | **supplierEmail** | <center>No<center/> | Supplier’s email address. | ## 13.4 Delivery Request Fields <a name="13.4"></a> These fields can be used to store details about the delivery address. This is where any purchased goods are being delivered to if different to the Customer’s address. | Field Name | Mandatory? | Description/Value | | :--------- | :--------- | :---------------- | | **deliveryName** | <center>No<center/> | Name of person receiving the delivery. | | **deliveryCompany** | <center>No<center/> | Name of company receiving the delivery. | | **deliveryAddress** | <center>No<center/> | Delivery address. | | **deliveryTown** | <center>No<center/> | Delivery town/city. | | **deliveryCounty** | <center>No<center/> | Delivery county. | | **deliveryPostcode** | <center>No<center/> | Delivery postcode. | | **deliveryCountryCode** | <center>No<center/> | Delivery country.<br/>**Valid ISO-3166 alpha or numeric code.** | | **deliveryPhone** | <center>No<center/> | Phone number of delivery location. | | **deliveryMobile** | <center>No<center/> | Mobile phone number of delivery location. | | **deliveryFax** | <center>No<center/> | Fax number of delivery location. | | **deliveryEmail** | <center>No<center/> | Delivery email address. | ## 13.5 Receiver Request Fields These fields can be used to store details about the recipient of the purchased goods where different to the Customer’s and Delivery details. It is most commonly used by Financial Intuitions (MCC 6012 Merchants) who need to record the primary recipient of a loan etc. | Field Name | Mandatory? | Description/Value | | :--------- | :--------- | :---------------- | | **receiverName** | <center>No<center/> | Receiver’s contact name. | | **receiverCompany** | <center>No<center/> | Receiver’s company name. | | **receiverAddress** | <center>No<center/> | Receiver’s contact address. | | **receiverTown** | <center>No<center/> | Receiver’s contact town/city. | | **receiverCounty** | <center>No<center/> | Receiver’s contact county. | | **receiverPostcode** | <center>No<center/> | Receiver’s contact postcode. | | **receiverCountryCode** | <center>No<center/> | Receiver’s contact country.<br/>**Valid ISO-3166 alpha or numeric code.** | | **receiverPhone** | <center>No<center/> | Receiver’s phone. | | **receiverMobile** | <center>No<center/> | Receiver’s mobile phone number. | | **receiverFax** | <center>No<center/> | Receiver’s fax number. | | **receiverEmail** | <center>No<center/> | Receiver’s email address. | | **receiverAccountNo** | <center>No<center/> | Receiver’s account number. | | **receiverDateOfBirth** | <center>No<center/> | Receiver’s date of birth. | ## 13.6 Shipping Request Fields These fields can be used to store details about the shipping method and costs. | Field Name | Mandatory? | Description/Value | | :--------- | :--------- | :---------------- | | **shippingTrackingRef** | <center>No<center/> | Shipping tracking reference. | | **shippingMethod** | <center>No<center/> | Shipping method (e.g. Courier, Post, etc.). | | **shippingAmount** | <center>No<center/> | Cost of shipping. | | **shippingGrossAmount** | <center>No<center/> | Gross cost of shipping. | | **shippingNetAmount** | <center>No<center/> | Net cost of shipping. | | **shippingTaxRate** | <center>No<center/> | Tax rate as percentage to 2 decimal places. | | **shippingTaxAmount** | <center>No<center/> | Tax cost of shipping. | | **shippingTaxReason** | <center>No<center/> | Tax reason (i.e. VAT). | | **shippingDiscountAmount** | <center>No<center/> | Discount on shipping. | | **shippingDiscountReason** | <center>No<center/> | Reason for discount. | Note: no attempt is made to check that any gross, net and tax amounts are correct with respect to each other. It is the sender’s responsibility to ensure alternative amount formats are correct. --- # 14 PayPal Transactions ## 14.1 Background PayPal is an additional payment method that is available to all Merchants using the Payment Gateway that have a PayPal account. It allows you to offer payment via PayPal in addition to normal card payments. PayPal transactions will appear in the Merchant Management System (MMS) alongside any card payments and can be captured, cancelled and refunded in the same way as card payments. PayPal transactions can also be used for recurring billing but require you to indicate in the initial transaction that it will be a basis for recurring billing and a billing agreement will be entered into between your customer and PayPal when they agree to the payment. PayPal transactions cannot be used for ad-hoc ‘Card On File’ repeat transactions unless a billing agreement has been set up. For more information on how to accept PayPal transactions please contact your support representative. --- ## 14.2 Benefits & Limitations ### 14.2.1 Benefits + Instant: The PayPal transaction information is available immediately and returned as part of the transaction. + Flexible: Adding PayPal gives your customers the flexibility of paying using their PayPal account when this is more suitable to them than using a traditional credit or debit card. + Express Checkout: The in-context PayPal Express Checkout helps improve conversion rates with an easier way to pay without customers leaving your website. + No extra cost: There are no extra costs to add PayPal to your gateway account however you will still be liable for the PayPal transaction fees. + Easy management: The PayPal transactions are controlled within the Merchant Management System (MMS). ### 14.2.2 Limitations + You will need a PayPal account in order to process PayPal transactions as well as a normal Acquirer account to process card transactions. + Ad-hoc repeat ‘Card On File’ transactions are not supported unless part of a prearranged PayPal billing agreement. + Independent refunds which are not tied to a previous PayPal sale transaction are not supported without prior agreement with PayPal. + The PayPal checkout cannot be opened from within a browser IFRAME and so care must be taken to ensure that any PayPal checkout button is not placed within such an IFRAME. --- ## 14.3 Implementation To use PayPal you will be supplied with a separate PayPal Merchant account which can be grouped with your normal card Merchant account using the account mapping facility as documented in appendix [A-6](#A-6). This allows transactions to be sent using your main Merchant Account and then routed automatically to the PayPal Merchant Account in the same mapping group. Initial PayPal transactions require you to display the PayPal Checkout to your customer as part of the transaction flow. In this respect they work very much like 3-D Secure transactions and need to be done in two stages with the Checkout being displayed between the stages. Like 3-D Secure they can also be optionally done in three stages allowing you to display an order confirmation after the Checkout and before authorising the transaction. Unlike 3-D Secure you can change the amount at this stage to allow for shipping costs once you know the confirmed delivery address the customer selected as part of the PayPal Checkout. --- ### 14.3.1 Hosted Implementation If a transaction is sent to the Hosted Integration using a normal credit card Merchant Account which is part of a group containing a PayPal Merchant then the default hosted form will display a ‘PayPal Checkout’ button which when clicked will open the PayPal checkout and allow the customer to pay using their PayPal account. To customise the PayPal checkout experience, you may send various options in the **`payPalCheckoutOptions`** field in your initial request. Additional information available from PayPal will be made available in the **`checkoutDetails`** response field. <a name="14.3.2.1"></a> --- ### 14.3.2 Direct Implementation #### 14.3.2.1 Initial Request (Checkout Preparation) To request that a transaction be processed via PayPal the request must contain a **`paymentMethod`** of ‘paypal’ and a **`checkoutRedirectURL`** containing the URL of a page on your server to return to when the Checkout is closed. In addition, you may send **`checkoutOptions`** to customise the Checkout experience. When the Gateway receives these two fields, assuming there are no other errors with the request, it will attempt to find a suitable PayPal Merchant Account in the current account mapping group. If the Gateway is unable to find a suitable account, then the transaction will be aborted and it will respond with a **`responseCode`** of **66364 (INVALID PAYMENTMETHOD)**. Otherwise the Gateway will respond with a **`responseCode`** of **65826 (CHECKOUT REQUIRED)** and included in the response will be a **`checkoutURL`** field containing the URL required to load Checkout and a **`checkoutRequest`** containing any data required to be sent to the Checkout. The response will also contain a unique **`checkoutRef`** which needs to be echoed back in the continuation requests. At this point your server needs to either redirect to the Customer’s browser to the provided **`checkoutURL`**. Alternatively, the **`checkoutURL`** can be used in conjunction with the PayPal In-Context JavaScript code to implement an In-context checkout which allows your website to remain visible in the background. Further details on how to use the In-Context checkout are provided in the PayPal guide at https://developer.paypal.com/docs/classic/express-checkout/in-context/enable_in_context_checkout/. <a name="14.3.2.2"></a> #### 14.3.2.2 Continuation Request (Checkout Details & Authorise) On completion of the PayPal Checkout it will redirect the customer’s browser to the **`checkoutRedirectURL`** provided including a token and status URL parameters. If the checkout was successful, the status will be ‘success’ alternatively if the checkout was cancelled the status will be ‘cancel’. The received redirect request parameters inclusive of these token and status parameters should then be sent to the Gateway in the **`checkoutResponse`** fields of a new request. The **`checkoutResponse`** field can be sent either as the original URL query string received or as an array of the decoded query parameters. This new request will load the checkout details including any delivery address if required and send the transaction to PayPal for authorisation, returning the result as per a normal authorisation transaction. The new request must contain the **`checkoutRef`** received in the initial response. #### 14.3.2.3 Separate Checkout Details & Authorisation Requests You can choose to obtain the Checkout details before actually sending the transaction for authorisation by sending the **`checkoutOnly`** field in the above continuation request. If this field is sent with a value of ‘Y’ then the Gateway will load the checkout details and then return them to you without sending the request for authorisation. You can then display them and/or adjust the amount, for example, according to delivery charges dependant on the received delivery address. You should then send a new request containing the **`checkoutRef`** received to continue the transaction and authorise it. Note: this stage can be repeated multiple times by including the **`checkoutOnly`** field with a value of ‘Y’ each time. To complete the transaction, the final request must not contain the **`checkoutOnly`** field or it must not have a value of ‘Y’. --- ## 14.4 Request Fields ### 14.4.1 Initial Request These fields should be sent in addition to the basic request fields in section [2.1](#2.1) excluding any card details. | Field Name | Mandatory? | Integration Type | Description | | :--------- | :--------- | :---------: | :---------- | | **paymentMethod** | <center>Yes<center/> | <center>Both<center/> | Must contain the value ‘paypal’ in lower case letters only. For the hosted implementation this is in order to request that the PayPal checkout is displayed immediately on the hosted form and not need the customer to click the ‘PayPal Checkout’ button. | | **checkoutRedirectURL** | <center>Yes<center/> | <center>Direct<center/> | URL on Merchant’s server to return to when the PayPal Checkout is closed. | | **paypalCheckoutOptions**^{<a name="14.4.1-1">[<span title="On Direct Integrations this is just called checkoutOptions as it is established by paymentMethod that Paypal is being used.">1</span>](#14.4.1-f1)</a>}| <center>No<center/> | <center>Both<center/> | Associative array or URL encoded array of options used to customise the PayPal Checkout. Refer to section [14.4.3](#14.4.3) for values. | ^{<a name="14.4.1-f1">[1](#14.4.1-1)</a>} On Direct Integrations this is just called **`checkoutOptions`** as it is established by **`paymentMethod`** that Paypal is being used. ### 14.4.2 Continuation Request (Direct Only) For direct implementations these fields may be sent alone. | Field Name | Mandatory? | Description | | :--------- | :--------- | :---------- | | **checkoutRef** | <center>Yes<center/> | Unique reference return in the initial response. | | **checkoutResponse** | <center>Yes<center/> | The GET and or POST data received by the **`checkoutRedirectURL`** page. | | **checkoutOnly** | <center>No<center/> | Pass **Y** to complete the processing as far as the next checkout stage and then return with the loaded checkout details. | Note: It is only necessary to send the **`checkoutRef`** and the **`checkoutResponse`** in the continuation request as the **`checkoutRef`** will identify the Merchant Account and initial request. The message does not need to be signed. You can send any of the normal request fields to modify or supplement the initial request, however in this case the request should be signed. The **`checkoutRedirectURL`** and **`checkoutOptions`** fields sent in the initial request cannot be modified and any sent in the second request must match those used in the first request, or the second request will fail with a responseCode of **64442 (REQUEST MISMATCH)**. <a name="14.4.3"></a> ### 14.4.3 Checkout Options The following options may be sent in the **`(paypal)CheckoutOptions`** field to customise the PayPal checkout. The field may be sent as a URL encoded string or an array of key/value pairs. | Field Name | Mandatory? | Description | | :--------- | :--------- | :---------- | | **inContext** | <center>No<center/> | Use the in-context PayPal checkout rather than the full screen checkout when possible.<br/><br/>Possible values are:<br>**0** – use the full screen checkout.<br>**1** – use the in-context checkout if possible. | | **userAction** | <center>No<center/> | Determines whether buyers complete their purchases on PayPal or on your website.<br/><br/>Possible values are:<br>**commit** – sets the submit button text to ‘Pay Now’ on the PayPal checkout. This text lets buyers know that they complete their purchases if they click the button.<br>**continue** – sets the submit button text to ‘Continue’ on the PayPal checkout. This text lets buyers know that they will return to the Merchants cart to complete their purchases if they click the button. | | **maxAmount^{<a name="14.4.3-1">[<span title="PayPal refer to this field as MAXAMT.">1</span>](#14.4.3-f1)</a>}** | <center>No<center/> | The expected maximum total amount of the order, including shipping and taxes. | | **reqBillingAddress** | <center>No<center/> | Determines whether the buyers billing address on file with PayPal is returned. This feature must be enabled by PalPal. | | **reqConfirmShipping** | <center>No<center/> | Determines whether the buyer’s shipping address on file with PayPal must be confirmed.<br/><br/>Possible values are:<br>**0** – does not need to be confirmed.<br>**1** – must be confirmed. | | **noShipping** | <center>No<center/> | Determines whether PayPal displays the shipping address.<br/><br/>Possible values are:<br>**0** – display the shipping address.<br>**1** – do not display shipping address and remove shipping information.<br>**2** – If no **`deliveryXXX`** fields passed PayPal obtains them from the buyer's account profile. | | **addrOverride** | <center>No<center/> | Determines whether the PayPal checkout displays the shipping address sent using the **`deliveryXXX`** fields and not the shipping address on file with PayPal for this buyer. Displaying the PayPal street address on file does not allow the buyer to edit that address.<br/><br/>Possible values are:<br>**0** – PayPal should not display the address.<br>**1** – PayPal should display the address. | | **localeCode** | <center>No<center/> | Locale of the pages displayed by PayPal during Express Checkout. It is either a two-letter country code or five-character locale code supported by PayPal. | | **allowNote** | <center>No<center/> | Enables the buyer to enter a note to the merchant on the PayPal page during checkout. The note is returned in the **`checkoutDetails`** response field. | | **pageStyle** | <center>No<center/> | Name of the Custom Payment Page Style used for the PayPal checkout. It is the same name as the Page Style Name used when adding styles in the PayPal Account. | | **payflowColor** | <center>No<center/> | The HTML hex colour code for the PayPal checkout’s background colour. By default, the colour is white (FFFFFF). | | **cardBorderColor** | <center>No<center/> | The HTML hex colour code for the PayPal checkout’s principle identifying colour. The colour will be blended to white in a gradient fill that borders the cart review area. | | **hdrImg** | <center>No<center/> | URL for the image you want to appear at the top left of the payment page. The image has a maximum size of 750 pixels wide by 90 pixels high. PayPal requires that you provide an image that is stored on a secure (https) server. If you do not specify an image, the business name displays. | | **logoImg** | <center>No<center/> | A URL to your logo image. Use a valid graphics format, such as .gif, .jpg, or .png. Limit the image to 190 pixels wide by 60 pixels high. PayPal crops images that are larger. PayPal places your logo image at the top of the cart review area. | | **landingPage** | <center>No<center/> | Type of PayPal checkout to display.<br/><br/>Possible values are:<br>**Billing** – Non-PayPal account.<br>**Login** – PayPal account login. | | **channelType** | <center>No<center/> | Type of channel.<br/><br/>Possible values are:<br>**Merchant** – Non-auction seller.<br>**eBayItem** – eBay auction. | | **solutionType** | <center>No<center/> | Type of checkout flow.<br/><br/>Possible values are:<br>**Sole** – Buyer does not need to create a PayPal account to check out. This is referred to as PayPal Account Optional.<br>**Mark** – Buyer must have a PayPal account to check out. | | **totalType** | <center>No<center/> | Type declaration for the label to be displayed in MiniCart for UX.<br/><br/>Possible values are:<br>**Total**<br>**EstimatedTotal** | | **brandName** | <center>No<center/> | A label that overrides the business name in the PayPal account on the PayPal checkout. | | **customerServiceNumber** | <center>No<center/> | Merchant Customer Service number displayed on the PayPal checkout. | | **buyerEmailOptInEnable** | <center>No<center/> | Enables the buyer to provide their email address on the PayPal pages to be notified of promotions or special events.<br/><br/>Possible values are:<br>**0** – Do not enable buyer to provide email.<br>**1** – Enable the buyer to provide email. | | **noteToBuyer** | <center>No<center/> | A note from the merchant to the buyer that will be displayed in the PayPal checkout. | | **paymentAction** | <center>No<center/> | Defines how to obtain payment. This can be used to override any **`captureDelay`** setting which can also be used to indicate a Sale or Authorization only.<br/><br/>Possible values are:<br>**Sale** – sale with immediate capture.<br>**Authorization** – authorization subject to later capture.<br>**Order** – order subject to later authorization and capture. | | **allowedPaymentMethod** | <center>No<center/> | The payment method type. Specify the value **InstantPaymentOnly**. | | **insuranceOptionOffered** | <center>No<center/> | Indicates whether insurance is available as an option that the buyer can choose on the PayPal Review page.<br/><br/>Possible values are:<br>**true** – The Insurance option displays 'Yes' and the **`insuranceAmount`**. If true, the total shipping insurance for this order must be a positive number.<br>**false** – The Insurance option displays 'No'. | | **multiShipping** | <center>No<center/> | Indicates if this payment is associated with multiple shipping addresses.<br/><br/>Possible values are:<br>**0** – Single/No shipping address.<br>**1** – Multiple shipping addresses. | | **noteText** | <center>No<center/> | Note to the Merchant. | | **bucketCategoryType** | <center>No<center/> | The category of a payment.<br/><br/>Possible values are:<br>**1** – International shipping.<br>**2** – Local delivery.<br>**3** – BOPIS, Buy online pick-up in store.<br>**4** – PUDO, Pick-up drop-off. | | **locationType** | <center>No<center/> | Type of merchant location. Required if the items purchased will not be shipped, such as, BOPIS (Buy Online Pick-up In Store) or PUDO (Pick-Up Drop-Off) transactions.<br/><br/>Possible values are:<br>**1** – Consumer.<br>**2** – Store, for BOPIS transactions.<br>**3** – PickupDropoff, for PUDO transactions. | | **locationID** | <center>No<center/> | Location ID specified by the merchant for BOPIS (Buy Online Pick-up In Store) or PUDO (Pick-Up Drop-Off) transactions. | | **sellerPayPalAccountID** | <center>No<center/> | Unique identifier for the Merchant. For parallel payments, this field is required and must contain the Payer Id or the email address of the Merchant. | | **invNum** | <center>No<center/> | Merchant’s invoice or tracking number. | | **custom** | <center>No<center/> | Custom field for your own use. | | **buyerID** | <center>No<center/> | The unique identifier provided by eBay for this buyer. The value may or may not be the same as the username. In the case of eBay, it is different. | | **buyerUsername** | <center>No<center/> | The user name of the user at the marketplaces site. | | **buyerRegistrationDate** | <center>No<center/> | Date when the user registered with the marketplace. In UTC/GMT format; for example, 2013-08-24T05:38:48Z. | | **allowPushFunding** | <center>No<center/> | Indicates whether the Merchant can accept push funding.<br/><br/>Possible values are:<br>**0** – Merchant cannot accept push funding.<br>**1** – Merchant can accept push funding. | | **userSelectedFundingSource** | <center>No<center/> | This element could be used to specify the preferred funding option for a guest user. However, the **`landingPage`** checkout option must also be set to **Billing**, otherwise, it is ignored.<br/><br/>Possible values are:<br>**ChinaUnionPay**.<br>**CreditCard**.<br>**ELV**.<br>**QIWI**. | | **billingType** | <center>No<center/> | Type of billing agreement for reference transactions. You must have permission from PayPal to use this field.<br/><br/>Possible values are:<br>**MerchantInitiatedBilling** – PayPal creates a billing agreement for each transaction associated with buyer.<br>**MerchantInitiatedBillingSingleAgreement** – PayPal creates a single billing agreement for all transactions associated with buyer. Use this value unless you need per-transaction billing agreements. | | **billingAgreementDescription** | <center>No<center/> | Description of goods or services associated with the billing agreement. This field is required for each recurring payment billing agreement. PayPal recommends that the description contain a brief summary of the billing agreement terms and conditions. For example, buyer is billed at "9.99 per month for 2 years". | | **paymentType** | <center>No<center/> | Type of PayPal payment you require for the billing agreement.<br/><br/>Possible values are:<br>**Any** – The merchant accepts any payment method for the billing agreement, even if it could take a few working days for the movement of funds to the merchant account; this includes echeck, in addition to credit or debit cards and PayPal balance.<br>**InstantOnly** – The payment options accepted by the merchant are credit cards, debit cards or PayPal balance only because the merchant expects immediate payment. | | **taxIDType** | <center>No<center/> | Buyer's tax ID type. This field is required for Brazil and used for Brazil only.<br/><br/>For Brazil use only: The tax ID type is BR\_CPF for individuals and BR\_CNPJ for businesses. | | **taxID** | <center>No<center/> | Buyer's tax ID. This field is required for Brazil and used for Brazil only.<br/><br/>For Brazil use only: The tax ID is 11 single-byte characters for individuals and 14 single-byte characters for businesses. | | **returnFMFDetails** | <center>No<center/> | Flag to indicate whether you want the results returned by Fraud Management Filters when doing a recurring/reference transaction.<br/><br/>Possible values are:<br>**0** – Do not receive FMF details (default).<br>**1** – Receive FMF details. | | **riskSessionCorrelationID** | <center>No<center/> | The ID of the risk session for correlation purposes when doing a recurring/reference transaction. | | **merchantSessionID** | <center>No<center/> | The buyer session identification token when doing a recurring/reference transaction.<br> | | **buttonSource^{<a name="14.4.3-2">[<span title="The BN code is the unique button source code provided by PayPal to its partners and added by its partners to the PayPal buttons used by merchants to offer the PayPal Services that are enabled through Partner Product. The button source code provides a means of identifying and tracking referred merchants' payments.">2</span>](#14.4.3-f2)</a>}** | <center>No<center/> | PayPal Partner’s BN Code (if required).<br> | --- *^{<a name="14.4.3-f1">[1](#14.4.3-1)</a>} PayPal refer to this field as MAXAMT.* <br/>*^{<a name="14.4.3-f2">[2](#14.4.3-2)</a>} The BN code is the unique button source code provided by PayPal to its partners and added by its partners to the PayPal buttons used by merchants to offer the PayPal Services that are enabled through Partner Product. The button source code provides a means of identifying and tracking referred merchants' payments.* --- For further information on the options refer to the PayPal Express Checkout documentation: https://developer.paypal.com/docs/classic/api/merchant/SetExpressCheckout_API_Operation_NVP/. <br/><br/>The option names are case sensitive. ### 14.4.4 Purchase details The following request fields may be sent to provide information on the purchased items and to populate the cart on the PayPal checkout. | Field Name | Mandatory | Description | | :--------- | :-------- | :---------- | | **shippingAmount** | <center>No<center/> | Shipping costs. | | **shippingDiscountAmount** | <center>No<center/> | Discount applied to shipping costs. | | **handlingAmount** | <center>No<center/> | Handling costs. | | **insuranceAmount** | <center>No<center/> | Insurance costs. | | **itemXXDescription** | <center>No<center/> | Description of XXth item purchased. | | **itemXXQuantity** | <center>No<center/> | Quantity of XXth item purchased. | | **itemXXAmount** | <center>No<center/> | Gross amount for XXth item purchased. | | **itemXXTaxAmount** | <center>No<center/> | Tax amount for XXth item purchased. | | **itemXXProductCode** | <center>No<center/> | Product code for XXth item purchased. | | **itemXXProductUrl** | <center>No<center/> | Shopping cart URL for XXth item purchased. | | **itemXXSize** | <center>No<center/> | Size of XXth item purchased in the format ‘LengthxWidthxHeight Unit’. | | **itemXXWeight** | <center>No<center/> | Weight of XXth item purchased in the format ‘Weight Unit’. | | **items** | <center>No^{<a name="14.4.4-1">[<span title="Used as an alternative to itemXXField format, both formats cannot be sent together.">1</span>](#14.4.4-f1)</a>}<center/> | Nested array of line items. | --- *^{<a name="14.4.4-f1">[1](#14.4.4-1)</a>} Used as an alternative to **`itemXXField`** format, both formats cannot be sent together.* --- Note: The shopping cart items must total to the amount specified in the transaction or cart items will not be sent to the PayPal checkout. ## 14.5 Response Fields ### 14.5.1 Initial Response These fields will be returned in addition to the request fields from section [5.5](#5.5) and the basic response fields in section [2.2](#2.2) minus any card details. | Field Name | Mandatory? | Integration Type | Description | | :--------- | :--------- | :---------: | :---------- | | **checkoutRef** | <center>Yes<center/> | <center>Both<center/> | Unique reference required to continue this transaction when the PayPal Checkout has completed. | | **checkoutName** | <center>Yes<center/> | <center>Both<center/> | Unique name of the checkout. For PayPal this is the value **paypal**. | | **checkoutURL** | <center>Yes<center/> | <center>Direct<center/> | URL required to load the PayPal Checkout. | | **checkoutRequest** | <center>No<center/> | <center>Direct<center/> | Not required for PayPal. | | **checkoutOptions** | <center>No<center/> | <center>Direct<center/> | Any checkout options passed in the request. | | **checkoutDetails** | <center>Yes<center/> | <center>Hosted<center/> | Associative array or URL encoded array of options used to customise the PayPal Checkout. Refer to section [14.5.3](#14.5.3) for values. | | **customerXXXX** | <center>No^{<a name="14.5.1-1">[<span title="The response will include customer/billing address and delivery address details if provided by the PayPal Checkout.">1</span>](#14.5.1-f1)</a>}<center/> | <center>Hosted<center/> | Customer details if provided by the PayPal Checkout as documented in section [13.1](#13.1). | | **deliveryXXX** | <center>No^{[<span title="The response will include customer/billing address and delivery address details if provided by the PayPal Checkout.">1</span>](#14.5.1-f1)}<center/> | <center>Hosted<center/> | Delivery details if provided by the PayPal Checkout as documented in section [13.4](#13.4). | | **acquirerResponseDetails** | <center>Yes<center/> | <center>Both<center/> | Details about the PayPal response containing any error messages and codes. This can be used along with the normal **`responseCode`**/**`responseMessage`** response fields to further determine the reason for any failure. | --- *^{<a name="14.5.1-f1">[1](#14.5.1-1)</a>} The response will include customer/billing address and delivery address details if provided by the PayPal Checkout.* --- ### 14.5.2 Continuation Response For direct requests these fields will be returned in addition to the request fields from section [14.3.2.1](#14.3.2.1), the initial response fields in section [14.3.2.2](#14.3.2.2) and the basic response fields in section [2.2](#2.2) minus any card details. | Field Name | Mandatory? | Description | | :--------- | :--------- | :---------- | | **checkoutRef** | <center>Yes<center/> | Provided if **`checkoutOnly`** was used in the continuation response to indicate that a further request will be sent to finalise the transaction. | | **checkoutName** | <center>Yes<center/> | Unique name of the checkout. For PayPal this is the value **paypal**. | | **checkoutDetails** | <center>Yes<center/> | Associative array or URL encoded array of options used to customise the PayPal Checkout. Refer to section [14.5.3](#14.5.3) for values. | | **customerXXXX** | <center>No^{<a name="14.5.2-1">[<span title="The response will include customer/billing address and delivery address details if provided by the PayPal Checkout.">1</span>](#14.5.2-f1)</a>}<center/> | Customer details if provided by the PayPal Checkout as documented in section [13.1](#13.1). | | **deliveryXXX** | <center>No^{[<span title="The response will include customer/billing address and delivery address details if provided by the PayPal Checkout.">1</span>](#14.5.2-f1)}<center/> | Delivery details if provided by the PayPal Checkout as documented in section [13.4](#13.4). | | **acquirerResponseDetails** | <center>Yes<center/> | Details about the PayPal response containing any error messages and codes. This can be used along with the normal **`responseCode/responseMessage`** response fields to further determine the reason for any failure. | --- *^{<a name="14.5.2-f1">[1](#14.5.2-1)</a>} The response will include customer/billing address and delivery address details if provided by the PayPal Checkout.* <a name="14.5.3"></a> --- ### 14.5.3 Checkout Details The following details may be provided in the **`checkoutDetails`** field included in the response. The field will be an array of key/value pairs. | Field Name | Mandatory? | Description | | :--------- | :--------- | :---------- | | **correlationID** | <center>No<center/> | Correlation ID, which uniquely identifies the transaction to PayPal. | | **checkoutStatus** | <center>No<center/> | Status of the checkout session. If payment is completed, the transaction identification number of the resulting transaction is returned.<br/><br/>Possible values are:<br>**PaymentActionNotInitiated**<br>**PaymentActionFailed**<br>**PaymentActionInProgress**<br>**PaymentActionCompleted** | | **invNum** | <center>No<center/> | Merchant’s invoice or tracking number, as sent in the **`invNum`** request field or assigned by the Gateway. | | **custom** | <center>No<center/> | Merchant’s invoice or tracking number, as sent in the **`custom`** request field or assigned by the Gateway. | | **payPalAdjustment** | <center>No<center/> | A discount or gift certificate offered by PayPal to the buyer. This amount is represented by a negative amount. If the buyer has a negative PayPal account balance, PayPal adds the negative balance to the transaction amount, which is represented as a positive value. | | **buyerMarketingEmail** | <center>No^{<a name="14.5.3-1">[<span title="Only available if email option was enabled in the initial request using checkoutOptions.buyerEmailOptInEnable option.">1</span>](#14.5.3-f1)</a>}<center/> | Buyer's marketing email address. | | **note** | <center>No^{<a name="14.5.3-2">[<span title="Only available if the leaving of notes was enabled in the initial request using checkoutOptions.allowNote option.buyerEmailOptInEnable option.">2</span>](#14.5.3-f2)</a>}<center/> | Buyer’s note to the Merchant. | | **cartChangeTolerance** | <center>No<center/> | Indicates whether a cart's contents can be modified. If this parameter is not returned, then assume the cart can be modified. This will return **NONE** if financing was used in Germany.<br/><br/>Possible values are:<br>**NONE** – The cart cannot be changed.<br>**FLEXIBLE** – The cart can be changed. | | **payerID** | <center>No<center/> | Buyer’s PayPal Customer Account ID.<br> | | **payerStatus** | <center>No<center/> | Buyer’s PayPal status.<br/><br/>Possible values are:<br>**verified**<br>**unverified** | | **billingName** | <center>No^{<a name="14.5.3-3">[<span title="Permission is needed from PayPal to support this field.">3</span>](#14.5.3-f3)<a/>}<center/> | Buyer’s name.<br>Also returned in **`customerName`**. | | **firstName** | <center>No^{<a name="14.5.3-4">[<span title="These fields are used when no permission to use billingName.">4</span>](#14.5.3-f4)<a/>}<center/> | Buyer’s first name.<br>Also returned in **`customerName`**. | | **middleName** | <center>No^{[<span title="Permission is needed from PayPal to support this field.">3</span>](#14.5.3-f3)} | Buyer’s middle name.<br>Also returned in **`customerName`**. | | **lastName** | <center>No^{[<span title="Permission is needed from PayPal to support this field.">3</span>](#14.5.3-f3)}<center/> | Buyer’s last name.<br>Also returned in **`customerName`**. | | **suffix** | <center>No^{[<span title="Permission is needed from PayPal to support this field.">3</span>](#14.5.3-f3)}<center/> | Buyer’s name suffix.<br>Also returned in **`customerName`**. | | **business** | <center>No<center/> | Buyer's business name.<br>Also returned in **`customerCompany`**. | | **street** | <center>No<center/> | Buyer’s street first line.<br>Also returned in **`customerAddress`**. | | **street2** | <center>No<center/> | Buyer’s street second line.<br>Also returned in **`customerAddress`**. | | **city** | <center>No<center/> | Buyer’s city.<br>Also returned in **`customerTown`**. | | **state** | <center>No<center/> | Buyer’s state.<br>Also returned in **`customerCounty`**. | | **zip** | <center>No<center/> | Buyer’s postal code.<br>Also returned in **`customerPostcode`**. | | **countryCode** | <center>No<center/> | Buyer's country code. (ISO 2 char. code)<br>Also returned in **`customerCountryCode`**. | | **countryName** | <center>No<center/> | Buyer's country name. | | **phoneNum** | <center>No<center/> | Buyer's contact phone number.<br>Also returned in **`customerPhone`**. | | **email** | <center>No<center/> | Buyer’s email address.<br>Also returned in **`customerEmail`**. | | **shipToName** | <center>No<center/> | Name of person/entity to ship to.<br>Also returned in **`deliveryName`**. | | **shipToStreet** | <center>No<center/> | Ship to street first line.<br>Also returned in **`deliveryAddress`**. | | **shipToStreet2** | <center>No<center/> | Ship to street second line.<br>Also returned in **`deliveryAddress`**. | | **shipToCity** | <center>No<center/> | Ship to city.<br>Also returned in **`deliveryTown`**. | | **shipToState** | <center>No<center/> | Ship to state.<br>Also returned in **`deliveryCounty`**. | | **shipToZip** | <center>No<center/> | Ship to postal code.<br>Also returned in **`deliveryPostcode`**. | | **shipToCountryCode** | <center>No<center/> | Ship to country code. (ISO 2 char. code)<br>Also returned in **`deliveryCountryCode`**. | | **shipToCountryName** | <center>No<center/> | Ship to country name. | | **shipToPhoneNum** | <center>No<center/> | Ship to phone number.<br>Also returned in **`deliveryPhone`**. | | **shipToAddressStatus** | <center>No<center/> | Status of shipping address on file with PayPal.<br/><br/>Possible values are:<br>**none**<br>**Confirmed**<br>**Unconfirmed** | | **addressNormalizationStatus** | <center>No<center/> | The PayPal address normalization status for Brazilian addresses.<br/><br/>Possible values are:<br>**None**<br>**Normalized**<br>**Unnormalized**<br>**UserPreferred** | | **amount** | <center>No<center/> | Total amount for this order. | | **itemAmount** | <center>No<center/> | Total item amount for this order. | | **taxAmount** | <center>No<center/> | Tax amount for this order. | | **exchangeRate** | <center>No<center/> | Exchange rate for this order. | | **shippingAmount** | <center>No<center/> | Shipping amount for this order. | | **handlingAmount** | <center>No<center/> | Handling amount for this order. | | **insuranceAmount** | <center>No<center/> | Insurance amount for this order. | | **shipDiscountAmount** | <center>No<center/> | Shipping discount amount for this order. | | **desc** | <center>No<center/> | Description of items the buyer is purchasing. | | **currencyCode** | <center>No<center/> | ISO 3 character currency code. | | **isFinancing** | <center>No<center/> | Indicates if the customer ultimately was approved for and chose to make the payment using the approved installment credit.<br/><br/>Possible values are:<br>**FALSE** – financing not in use<br>**TRUE** – financing approved and used. | | **financingFeeAmount** | <center>No<center/> | The transaction financing fee associated with the payment. This will be set to the installment fee amount which is the same as the estimated cost of credit or the interest/fees amount the user will have to pay during the lifetime of the loan. This field will only be included in installment credit orders. In the case of “same as cash” or “no interest” offers, this will be set to 0. | | **financingTerm** | <center>No<center/> | The length of the financing term, in months. Example values are 6, 12, 18 and 24 months. | | **financingMonthlyPayment** | <center>No<center/> | This is the estimated amount per month that the customer will need to pay including fees and interest. | | **financingTotalCost** | <center>No<center/> | This is the estimated total payment amount including interest and fees the user will pay during the lifetime of the loan. | | **financingDiscountAmount** | <center>No<center/> | Discount amount for the buyer if paid in one installment. | | **regularTakeFeeAmount** | <center>No<center/> | Fee of the regular take rate on the transaction amount. It could be equal to **`financingDiscountAmount`** in the case of non-installment transactions. | | **noteText** | <center>No<center/> | Note to Merchant. | | **transactionID** | <center>No<center/> | PayPal transaction ID. | | **allowedPaymentMethod** | <center>No<center/> | The payment method type as specified in the initial request. | | **paymentRequestID** | <center>No<center/> | A unique identifier of the specific payment request. | | **bucketCategoryType** | <center>No<center/> | The category of a payment as specified in the initial request. | | **instrumentCategory** | <center>No<center/> | Identifies the category of the promotional payment instrument.<br/><br/>Possible values are:<br>**1** – PayPal Credit® (formerly Bill Me Later®).<br>**2** – A Private Label Credit Card (PLCC) or co-branded payment card. | | **instrumentID** | <center>No<center/> | An instrument ID (issued by the external party) corresponding to the funding source used in the payment. | | **shippingCalculationMode** | <center>No<center/> | Describes how the options that were presented to the buyer were determined.<br/><br/>Possible values are:<br>**API – Callback**<br>**API – Flatrate** | | **insuranceOptionSelected** | <center>No<center/> | The option that the buyer chose for insurance.<br/><br/>Possible values are:<br>**Yes** – opted for insurance.<br>**No** – did not opt for insurance. | | **shippingOptionIsDefault** | <center>No<center/> | Indicates whether the buyer chose the default shipping option.<br/><br/>Possible values are:<br>**true** – chose the default shipping option.<br>**false** – did not choose the default shipping option. | | **shippingOptionAmount** | <center>No<center/> | The shipping amount that the buyer chose. | | **shippingOptionName** | <center>No<center/> | The name of the shipping option, such as Air or Ground. | | **scheduledShippingDate** | <center>No<center/> | The scheduled shipping date is returned only if scheduled shipping options are passed in the request. | | **scheduledShippingPeriod** | <center>No<center/> | The scheduled shipping period is returned only if scheduled shipping options are passed in the request. | | **sellerPayPalAcountID** | <center>No<center/> | Unique identifier for the merchant. For parallel payments, this field contains either the Payer Id or the email address of the merchant. | | **taxIDType** | <center>No<center/> | Buyer's tax ID type. This field is required for Brazil and used for Brazil only.<br/><br/>For Brazil use only: The tax ID type is BR_CPF for individuals and BR_CNPJ for businesses. | | **taxID** | <center>No<center/> | Buyer's tax ID. This field is required for Brazil and used for Brazil only.<br/><br/>For Brazil use only: The tax ID is 11 single-byte characters for individuals and 14 single-byte characters for businesses. | | **billingAgreementID** | <center>No<center/> | Identification number of the billing agreement. When the buyer approves the billing agreement, it becomes valid and remains valid until it is cancelled by the buyer. | | **billingAgreementAcceptedStatus** | <center>No<center/> | Indicates whether the buyer accepted the billing agreement for a recurring payment. Currently, this field is always returned in the response for agreement based products, such as, subscriptions, reference transactions and recurring payments, as well as for regular single payment transactions.<br>**0** – Not accepted.<br>**1** – Accepted. | | **paymentStatus** | <center>No<center/> | Status of the payment.<br/><br/>Possible values are:<br>**None** – No status.<br>**Canceled-Reversal** – A reversal has been cancelled, for example, when you win a dispute and the funds for the reversal have been returned to you.<br>**Completed** – The payment has been completed, and the funds have been added successfully to your account balance.<br>**Denied** – You denied the payment. This happens only if the payment was previously pending because of possible reasons described for the **`pendingReason`** element.<br>**Expired** – The authorization period for this payment has been reached.<br>**Failed** – The payment has failed. This happens only if the payment was made from your buyer's bank account.<br>**In-Progress** – The transaction has not terminated; for example, an authorization may be awaiting completion.<br>**Partially-Refunded** – The payment has been partially refunded.<br>**Pending** – The payment is pending. See the **`pendingReason`** field for more information.<br>**Refunded** – You refunded the payment.<br>**Reversed** – A payment was reversed due to a charge back or other type of reversal. The funds have been removed from your account balance and returned to the buyer. The reason for the reversal is specified in the **`reasonCode`** element.<br>**Processed** – A payment has been accepted.<br>**Voided** – An authorization for this transaction has been voided. | | **refundStatus** | <center>No<center/> | Status of the refund.<br/><br/>Possible value are:<br>**none** – returned if the refund fails.<br>**instant** – refund was instant.<br>**delayed** – refund was delayed. | | **pendingReason** | <center>No^{<a name="14.5.3-5">[<span title="pendingReason is returned in the response only if paymentStatus is Pending.">5</span>](#14.5.3-f5)<a/>}<center/> | The reason the payment is pending.<br/><br/>Possible values are:<br>**none** – No pending reason.<br>**address** – The payment is pending because your buyer did not include a confirmed shipping address and your Payment Receiving Preferences is set such that you want to manually accept or deny each of these payments. To change your preference, go to the Preferences section of your Profile.<br>**authorization** – The payment is pending because it has been authorized but not settled. You must capture the funds first.<br>**echeck** – The payment is pending because it was made by an **`eCheck`** that has not yet cleared.<br>**intl** – The payment is pending because you hold a non-U.S. account and do not have a withdrawal mechanism. You must manually accept or deny this payment from your Account Overview.<br>**multi-currency** – You do not have a balance in the currency sent, and you do not have your Payment Receiving Preferences set to automatically convert and accept this payment. You must manually accept or deny this payment.<br>**order** – The payment is pending because it is part of an order that has been authorized but not settled.<br>**payment-review** – The payment is pending while it is being reviewed by PayPal for risk.<br>**regulatory-review** – The payment is pending while we make sure it meets regulatory requirements. You will be contacted again in 24 to 72 hours with the outcome of the review.<br>**unilateral** – The payment is pending because it was made to an email address that is not yet registered or confirmed.<br>**verify** – The payment is pending because you are not yet verified. You must verify your account before you can accept this payment.<br>**other** – The payment is pending for a reason other than those listed above. For more information, contact PayPal Customer Service. | | **reasonCode** | <center>No<center/> | The reason for a reversal if the transaction type is reversal.<br/><br/>Possible values are:<br>**none** – No reason code.<br>**chargeback** – A reversal has occurred on this transaction due to a charge back by your buyer.<br>**guarantee** – A reversal has occurred on this transaction due to your buyer triggering a money-back guarantee.<br>**buyer-complaint** – A reversal has occurred on this transaction due to a complaint about the transaction from your buyer.<br>**refund** – A reversal has occurred on this transaction because you have given the buyer a refund.<br>**other** – A reversal has occurred on this transaction due to a reason not listed above. | | **protectionEligibilityType** | <center>No<center/> | The kind of seller protection in force for the transaction.<br/><br/>Possible value are: **ItemNotReceivedEligible** – Merchant is protected by PayPal's Seller Protection Policy for Item Not Received.<br>**UnauthorizedPaymentEligible** – Merchant is protected by PayPal's Seller Protection Policy for Unauthorized Payment.<br>**Ineligible** – Merchant is not protected under the Seller Protection Policy.<br>(Multiple values are separated by commas). | | **feeAmount** | <center>No<center/> | PayPal fee amount charged for the transaction. | | **settleAmount** | <center>No<center/> | Amount deposited in your PayPal account after a currency conversion. | | **storeID** | <center>No<center/> | StoreId as entered in the transaction. | | **terminalID** | <center>No<center/> | TerminalId as entered in the transaction.<br> | --- *^{<a name="14.5.3-f1">[1](#14.5.3-1)</a>} Only available if email option was enabled in the initial request using checkoutOptions.buyerEmailOptInEnable option.* <br/>*^{<a name="14.5.3-f2">[2](#14.5.3-2)</a>} Only available if the leaving of notes was enabled in the initial request using checkoutOptions.allowNote option.buyerEmailOptInEnable option.* <br/>*^{<a name="14.5.3-f3">[3](#14.5.3-3)</a>} Permission is needed from PayPal to support this field.* <br/>*^{<a name="14.5.3-f4">[4](#14.5.3-4)</a>} These fields are used when no permission to use **`billingName`**.* <br/>*^{<a name="14.5.3-f5">[5](#14.5.3-5)</a>} **`pendingReason`** is returned in the response only if **`paymentStatus`** is **Pending**.* --- ## 14.6 Transaction Lifecycle PayPal transactions will use the normal Authorise, Capture life cycle as documented in appendix [A-12.1](#A-12.1) with the following differences. In addition, the PayPal **`paymentAction`** option can be included in the **`checkoutOptions`** field to further alter the normal payment lifecycle to allow an Order, Authorise, Capture model to be specified or a straight Sale model. ### 14.6.1 Order If a **`paymentAction`** with a value of ‘Order’ is sent, then PayPal will store the transaction but delay authorising it until instructed. To instruct PayPal to authorise the transaction a further management request can be sent to the Gateway with an action of ‘AUTHORISE’ and the **`xref`** of the transaction to authorise, alternatively the AUTHORISE command can be selected in the Merchant Management System (MMS). The transaction will be left in the ‘received’ state. ### 14.6.2 Authorise If no **`paymentAction`** is specified or a **`paymentAction`** with a value of ‘Authorize’ is sent, then PayPal will authorise the transaction on receipt as per a standard card transaction and you can capture it later if you used the **`captureDelay`** field. For the first three days (by default) of the authorisation, funds are reserved. This is known as the honour period. After the honour period, captures can still be attempted, but may be returned with insufficient funds. Authorisations have a fixed expiry period of 29 days. ### 14.6.3 Sale If a **`paymentAction`** with a value of ‘Sale’ is sent then PayPal will immediately capture the transaction after authorisation. The transaction will be regarded as having been settled and you will not be able to capture it manually and it will not be sent for settlement that evening. The transaction will be left in either the **accepted** or **rejected** terminal states depending on whether PayPal accepted or rejected the transaction. ### 14.6.4 Capture Transactions which have been authorised by PayPal and not immediately settled due to a **`paymentAction`** of ‘Sale’ will be able to be captured as normal. Captures are sent to PayPal immediately and the PayPal response and the transaction will be left in either the accepted or rejected terminal state depending on whether PayPal accepted or rejected the capture request. There is no need to wait for the nightly settlement batch to run as with normal card transactions. This means that it is not possible to change the amount to be captured or cancel the transaction once a capture has been requested. Note: PayPal allows multiple captures in a different manner to the Gateway where they sum the individual capture amounts. This mode of operation is not possible using the Gateway and only a single capture operation can be processed. ### 14.6.5 Refund PayPal transactions can be refunded the same as normal card transactions however, like capture requests, these will be sent to PayPal immediately and not batched up and sent as part of the nightly settlement process. This means the transaction will be left in either the **accepted** or **rejected** terminal state depending on whether PayPal accepted or rejected the refund request. Refunds can be made for full or partial amounts, with multiple refunds allowed up to the original authorised amount. By default, PayPal allows a Merchant up to 60 days from the original authorised transaction date to perform refunds. ### 14.6.6 Cancel You should cancel any transactions that you do not wish to capture so as to prevent ‘pending’ transactions on the Customers PayPal account. Authorisations should be cancelled when an initial authorisation was created to confirm the validity of funds during checkout, but the goods will not ship for a significant amount of time (>29 days). Cancelling the transaction will mean that you will have to contact the Customer for an alternative payment method. All transactions must be completed by being captured or cancelled. ### 14.6.7 Pending Payments PayPal may put a transaction into a pending state when flagged for additional fraud review. This state is known to PayPal as payment review or IPR. IPR transactions will be automatically cancelled by the Gateway and treated as referred transactions with a **`responseCode`** of 2 and a **`responseMessage`** indicating the reason the transaction was put into a pending state. Unlike card referred transactions an authorisation code cannot be obtained from PayPal verbally and the transaction resent. ## 14.7 Reference Transactions PayPal does not allow ad hoc ‘Card On File’ type repeat or recurring transactions using the xref of a reference transaction unless that transaction has specifically started a PayPal Billing Agreement. If you want to be able to make future repeat or recurring transactions, then the initial transaction must include the **`billingType`** and **`billingAgreementDescription`** options in the **`checkoutOptions`** so as to identify this transaction as the start of a recurring billing sequence. This will cause the Gateway to request that PayPal setup a Billing Agreement between you and the Customer. In this case the PayPal Billing Agreement ID will be returned as part of the **`checkoutDetails`** and displayed on the Merchant Management System (MMS) as part of the payment details so that you can easily see which PayPal transactions can be used for recurring billing. <a name="A-1"></a> --- # 15 PPRO Transactions ## 15.1 Background PPRO is an additional payment method that can be used by all merchants that have the appropriate payment method code. PPRO is an e-payment specialist with their own mission to help grow businesses by integrating with many international payment services and acquiring banks. They use the term “tag” to help separate what service the merchant is wishing to facilitate with during the payment process with their customers. E-wallets, SMS payments and PSP services are some of the many payment methods PPRO support (e.g. Alipay, EasyPay, Bancontact). This could allow a business to facilitate overseas transactions or alternative payment methods using a different payment method suitable for that country or business plan. All transactions created with this payment method will appear in the Merchant Management System (MMS) along with the payment method that was used to process the transaction. For more information on how to accept PPRO transactions please contact customer support. ## 15.2 Benefits & Limitations ### 15.2.1 Benefits + Multiple payment methods could be used^{<a name="15.2.1-1">[<span title="Multiple payment methods could incur unnecessary cost and could require more than one account to be setup. Contact customer support if more information is required.">1</span>](#15.2.1-f1)</a>} + Expands range of payment methods for international use (USA, Germany, Brazil, Malaysia, etc.) + Variety of e-wallets, SMS and PSP’s + Ease of use through an existing payment provider + Ability to perform refunds on supported payment methods + See all transactions from the Gateway or PPRO in one place in an easy to use and familiar Merchant Management System (MMS) + Not all payment methods require redirection through a checkout process ### 15.2.2 Limitations + PPRO payment methods can only be initiated from a Direct integration + Payment authorisation is not always instantaneous and may require additional ‘QUERY’ requests + Not all currencies or countries may be supported by PPRO and the payment methods they provide + A single payment method may only support one or a limited set of currencies or countries + Transactions through PPRO could be more expensive + Payment methods that require checkout redirection will also require a browser and will perform best in a popup window *^{<a name="15.2.1-f1">[1](#15.2.1-1)</a>}Multiple payment methods could incur unnecessary cost and could require more than one account to be setup. Contact customer support if more information is required.* ## 15.3 Implementation ### 15.3.1 List of payment methods Before a request is made to PPRO you need to know which payment method you wish to use. Please see the guide below as a reference. If you know of a payment method that is not on this list or the payment method cannot be used; please contact customer support for advice. The format of the payment method relies on the use of the prefix “ppro” followed by a full stop (period) and afterwards, suffixed with the payment method tag name. For example; to use the payment method AstroPay Card that has a tag name of “astropaycard” (all lowercase); the resulting payment method code would be “ppro.astropaycard”. This allows the Gateway to know that you’re attempting to use AstroPay Card using the PPRO payment method. <br/>**Payment Methods:** | Tag | Name | | :--------- | :--------- | | **affinbank** | Affin bank | | **alipay** | AliPay | | **ambank** | AmBank | | **argencard** | Argencard | | **astropaycard** | AstroPay Card | | **astropaydirect** | AstroPay Direct | | **aura** | Aura | | **baloto** | Baloto | | **banamex** | Banamex | | **bancodobrasil** | Banco do Brasil | | **bancodechile** | Banco de Chile | | **bancodeoccidente** | Banco de Occidente | | **bancomer** | Bancomer | | **bankislam** | Bank Islam | | **bcmc** | Bancontact | | **bitpay** | Bitpay | | **boleto** | Boleto Bancario | | **bradesco** | Bradesco | | **cabal** | Cabal | | **cartaomercadolivre** | Cartao Mercado Livre | | **carulla** | Carulla | | **ccauth** | Credit/Debit Card | | **ccweb** | Credit/Debit Card | | **cencosud** | Cencosud | | **cimbclicks** | CIMB Clicks | | **cmr** | CMR | | **davivienda** | Davivienda | | **directpay** | Sofortüberweisung (Direct Pay) | | **dragonpay** | Dragonpay | | **easypay** | EasyPay | | **efecty** | Efecty | | **elo** | Elo | | **empresedeenergia** | Emprese de Energia | | **enets** | eNETS | | **entercash** | Entercash | | **eps** | EPS | | **estonianbanks** | Estonian Banks | | **giropay** | Giropay | | **hipercard** | Hipercard | | **hongleongbank** | Hong Leong Bank | | **ideal** | iDEAL | | **instanttransfer** | Instant Transfer | | **int_payout** | International Pay-Outs | | **itau** | Itau | | **latvianbanks** | Latvian Banks | | **lithuanianbanks** | Lithuanian Banks | | **magna** | Magna | | **maxima** | Maxima | | **maybanktwou** | Maybank2u | | **multibanco** | Multibanco | | **mybank** | MyBank | | **myclearfpx** | MyClear FPX | | **naranja** | Naranja | | **narvesen** | Narvesen | | **nativa** | Nativa | | **oxxo** | OXXO | | **p24** | Przelewy24 | | **p24payout** | Przelewy24 Payout | | **pagofacil** | Pago Facil | | **paypost** | PayPost | | **paysafecard** | Paysafe Card | | **paysbuy** | Paysbuy | | **paysera** | Paysera | | **payu** | PayU | | **perlas** | Perlas Terminals | | **poli** | OLI | | **presto** | Presto | | **pse** | PSE | | **pugglepay** | Pugglepay | | **qiwi** | QIWI | | **qiwipayout** | QIWI Payout | | **rapipago** | Rapipago | | **redpagos** | Redpagos | | **rhbbank** | RHB Bank | | **safetypay** | SafetyPay | | **santander** | Santander | | **sepadirectdebit** | SEPA DirectDebit | | **sepapayout** | SEPA Payout | | **seveneleven** | Seveneleven (7eleven) | | **singpost** | SingPost | | **skrill** | Skrill | | **surtimax** | Surtimax | | **tarjetashopping** | Tarjeta Shopping | | **trustly** | Trustly | | **trustpay** | TrustPay | | **unionpay** | UnionPay | | **verkkopankki** | Verkkopankki – Finish Online Banking | | **webpay** | Webpay | | **yellowpay** | Yellow Pay | ### 15.3.2 Initial Request These fields should be sent in addition to the basic request fields in section [2.1](#2.1) excluding any card details. | Field Name | Mandatory? | Description | | :--------- | :--------- | :---------- | | **paymentMethod** | <center>Yes<center/> | Payment method to be used with PPRO (e.g. **ppro.astropay**, **ppro.alipay**, etc.). | | **checkoutOptions** | <center>No^{<a name="15.3.2-1">[<span title="Whilst we do not see this field as mandatory by our system, PPRO may have payment methods that require additional configuration using checkout options. Please see section 15.4 which explains this in detail.">1</span>](#15.3.2-f1)</a>}<center/> | Pass in an associative array with configuration options as defined in section [15.4](#15.4) below. | | **checkoutRedirectURL** | <center>Yes<center/> | The URL to go back to during the 2-stage checkout process. | *^{<a name="15.3.2-f1">[1](#15.3.2-1)</a>} Whilst the Gateway does not see this field as mandatory, PPRO may have payment methods that require additional configuration using checkout options. Please see section [15.4](#15.4) which explains this in detail.* ### 15.3.3 Checkout Required After the initial request the customer would normally receive a **`responseCode`** of **65826 (CHECKOUT REQUIRED)** which will indicate that the 2-stage checkout needs to be actioned to complete the payment. The developer integrating this payment method must intercept this response (as the customer should never see the response code and response message). The developer should use the **`checkoutURL`** from the response fields to automatically redirect the customer to the checkout page. Ideally this is done creating a new popup browser window with JavaScript or the use of an inline frame or redirect. To keep track of the checkout process, the use of a ‘step’ or ‘stage’ parameter in the **`checkoutRedirectURL`** query string can be very useful. This can help the developer redirect the customer to the original page they were from when using the inline frame or popup window method. <a name="15.4"></a> ## 15.4 Request fields Most of the checkout fields will be handled by the Gateway; however, there might be mandatory fields that will have to be included manually for different payment methods. These fields can also be overridden if necessary. For example, most European services may require the **`nationalid`** and **`consumerref`** fields. Recurring transactions will require the use of **`iban`** (optionally **`sequencetype`**) and in follow-up payments; **`mandatereference`**, **`mandatesignaturedate`**, and **`sequencetype`**. Customer support will be able to help guide you on any missing fields as may you may find the transaction will come up with a **`responseCode`** of **65550 (PROCESSOR_ERROR - Invalid request data)**. ### 15.4.1 checkoutOptions Field The **`checkoutOptions`** field can be added as a set of key/value pairs that allows more information to be given to the payment method during the PPRO checkout process. <br/>**Request Fields for checkoutOptions:** | Checkout Option | Description | | :--------- | :--------- | | **nationalid** | Consumer’s national ID (up to 30 characters). | | **consumerref** | Unique reference identifying the consumer within 1 to 20 characters and a format of A-Za-z0-9.%,&/+*$- | | **siteid** | Unique site identifier. Required for clients serving multiple points of sale and forwarded onwards whilst using the qiwi payment method. | | **iban** | Valid IBAN of consumer/destination account. | | **sequencetype** | Sequence type of the direct debit.<br/><br/>Possible values are:<br/>**oneOff** – The direct debit is executed once (default) <br/>**first** – First direct debit in a series of recurring ones | | **mandatereference** | Mandate reference as returned on the first transaction in the sequence (found from **`mandatereference`** in **`checkoutDetails`**). | | **mandatesignaturedate** | Date of the initial transaction. Format: YYYY-MM-DD | | **bic** | Valid BIC (8 or 11 alphanumeric letters) – optionally supplied to skip the bank selection page (by using the bank referenced by BIC as supplied) | | **clientip** | Optional IP address of the consumer during checkout using Trustly (127.0.0.1 is not allowed!) | | **address** | Customer’s billing address^{<a name="15.4.1-1">[<span title="This information is supplied to PPRO by default using the following fields: customerAddress, customerPostcode, customerTown, customerEmail, customerPhone, customerMobile, receiverDateOfBirth, statementNarrative1.">1</span>](#15.4.1-f1)</a>} | | **city** | Customer’s billing city^{<a name="15.4.1-1">[<span title="This information is supplied to PPRO by default using the following fields: customerAddress, customerPostcode, customerTown, customerEmail, customerPhone, customerMobile, receiverDateOfBirth, statementNarrative1.">1</span>](#15.4.1-f1)</a>} | | **phone** | Customer’s phone^{<a name="15.4.1-1">[<span title="This information is supplied to PPRO by default using the following fields: customerAddress, customerPostcode, customerTown, customerEmail, customerPhone, customerMobile, receiverDateOfBirth, statementNarrative1.">1</span>](#15.4.1-f1)</a>} | | **mobilephone** | Customers mobile phone^{<a name="15.4.1-1">[<span title="This information is supplied to PPRO by default using the following fields: customerAddress, customerPostcode, customerTown, customerEmail, customerPhone, customerMobile, receiverDateOfBirth, statementNarrative1.">1</span>](#15.4.1-f1)</a>} | | **dob** | MCC 6012 Date of Birth^{<a name="15.4.1-1">[<span title="This information is supplied to PPRO by default using the following fields: customerAddress, customerPostcode, customerTown, customerEmail, customerPhone, customerMobile, receiverDateOfBirth, statementNarrative1.">1</span>](#15.4.1-f1)</a>} | | **dynamicdescriptor** | Statement narrative^{<a name="15.4.1-1">[<span title="This information is supplied to PPRO by default using the following fields: customerAddress, customerPostcode, customerTown, customerEmail, customerPhone, customerMobile, receiverDateOfBirth, statementNarrative1.">1</span>](#15.4.1-f1)</a>} | *^{<a name="15.4.1-f1">[1](#15.4.1-1)</a>} This information is supplied to PPRO by default using the following fields: customerAddress, customerPostcode, customerTown, customerEmail, customerPhone, customerMobile, receiverDateOfBirth, statementNarrative1.* ## 15.5 Repsonse Fields ### 15.5.1 Initial Repsonse The fields below will be returned in addition to the basic response fields in section [2.2](#2.2) for the start of a PPRO transaction and the PPRO checkout process. | Field Name | Description | | :--------- | :---------- | | **checkoutName** | The **`paymentMethod`** you used to identify the PPRO payment method. | | **checkoutRedirectURL** | The URL to redirect the customer to, to start the checkout process. | | **checkoutOptions** | The same **`checkoutOptions`** used for the request. | | **checkoutDetails** | Additional information provided from the payment method used during checkout. | | **checkoutRef** | The unique reference required to continue the transaction when PPRO checkout is complete. | | **checkoutRequest** | Containing the redirect secret, checksum and request status. | ### 15.5.2 Continuation Repsonse Fields from the initial response in the previous section may be present^{<a name="15.5.2-1">[<span title="Duplicate fields in the response of a request can help identify that the data given to the Gateway has been correctly formatted and processed.">1</span>](#15.5.2-f1)</a>} as well as the fields below and will not contain any card details. | Field Name | Description | | :--------- | :---------- | | **checkoutResponse** | Containing additional information about the end of the checkout process in key/value pairs. At the very least, this will include the transaction id (txid) and checksum of the transaction. This will also be given during a notification from PPRO to check and update the status of a transaction alongside internal information. Any change in the payments status will be given in responseMessage and responseCode^{<a name="15.5.2-2">[<span title="Not all payment methods give an immediate payment status. This will require a further QUERY to the Gateway to see whether this value has changed and a status of ‘tendered’.">2</span>](#15.5.2-f2)</a>}. | | **checkoutStatus** | A string containing the result of the checkout process. This is not used to identify the transaction’s payment status. | *^{<a name="15.5.2-f1">[1](#15.5.2-1)</a>} Duplicate fields in the response of a request can help identify that the data given to the Gateway has been correctly formatted and processed.* <br/>*^{<a name="15.5.2-f2">[2](#15.5.2-2)</a>} Not all payment methods give an immediate payment status. This will require a further QUERY to the Gateway to see whether this value has changed and a status of ‘tendered’.* ### 15.5.3 Notifications and “Tendered” Payments Whilst some payment methods give an immediate payment status (i.e. direct card payment methods rather than SMS and e-wallet systems), some payments may come back with the status of ‘tendered’. At this time, online shopping modules will not be able to monitor the transaction status. The use of a QUERY request may be of use as seen in section [1.7.8](#1.7.8). Please ask customer support in this matter who will be able to give more information and may be able to provide better advice for your situation. Notifications from PPRO regarding the payment status, seconds, minutes or hours after the checkout will automatically update the transaction status. --- #A-1 Response Codes The Gateway will always issue a **`responseCode`** to report the status of the transaction. These codes should be used rather than the **`responseMessage`** field to determine the outcome of a transaction. A zero response code always indicates a successful outcome. Response codes are grouped as follows, the groupings are for informational purposes only and not all codes in a group are used; **Acquirer (FI) Error codes: 1-99** | Code | Description | | :--- | :---------- | | **0** | Successful / authorised transaction.<br>Any code other than 0 indicates an unsuccessful transaction. | | **1** | Card referred - Refer to card issuer. | | **2** | Card referred - Special condition. | | **4** | Card declined – Keep card. | | **5** | Card declined. | | **30** | An error occurred. Check **`responseMessage`** for more detail.<br> | **General Error Codes: 65536 - 65791** | Code | Description | | :---- | :----------- | | **65536** | Transaction in progress. Contact customer support if this error occurs. | | **65537** | Reserved for future use. Contact customer support if this error occurs. | | **65538** | Reserved for future use. Contact customer support if this error occurs. | | **65539** | Invalid Credentials: **`merchantID`** is unknown. | | **65540** | Permission denied: caused by sending a request from an unauthorised IP address. | | **65541** | Action not allowed: the transaction state or Acquirer doesn’t support this action. | | **65542** | Request Mismatch: fields sent while completing a request do not match initially requested values. Usually due to sending different card details to those used to authorise the transaction when completing a 3-D Secure transaction or performing a REFUND_SALE transaction. | | **65543** | Request Ambiguous: request could be misinterpreted due to inclusion of mutually exclusive fields. | | **65544** | Request Malformed: couldn’t parse the request data. | | **65545** | Suspended Merchant account. | | **65546** | Currency not supported by Merchant. | | **65547** | Request Ambiguous, both **`taxValue`** and **`discountValue`** provided when should be one only. | | **65548** | Database error. | | **65549** | Payment processor communications error. | | **65550** | Payment processor error. | | **65551** | Internal Gateway communications error. | | **65552** | Internal Gateway error. | | **65553** | Encryption error. | | **65554** | Duplicate request. Refer to Section [11](#11).<br> | | **65555** | Settlement error. | | **65556** | AVS/CV2 Checks are not supported for this card (or Acquirer). | | **65557** | IP Blocked: Request is from a banned IP address. | | **65558** | Primary IP blocked: Request is not from one of the primary IP addresses configured for this Merchant Account. | | **65559** | Secondary IP blocked: Request is not from one of the secondary IP addresses configured for this Merchant Account. | | **65560** | Reserved for future use. Contact customer support if this error occurs. | | **65561** | Unsupported Card Type: Request is for a card type that is not supported on this Merchant Account. | | **65562** | Unsupported Authorisation: External authorisation code **`authCode`** has been supplied and this is not supported for the transaction or by the Acquirer. | | **65563** | Request not supported: The Gateway or Acquirer does not support the request. | | **65564** | Request expired: The request cannot be completed as the information is too old. | | **65565** | Request retry: The request can be retried later. | | **65566** | Test Card Used: A test card was used on a live Merchant Account. | | **65567** | Unsupported card issuing country: Request is for a card issuing country that is not supported on this Merchant Account. | | **65568** | Unsupported payment type: Request uses a payment type which is not supported on this Merchant Account.<br> | **3-D Secure Error Codes: 65792-66047** | Code | Description | | :---- | :----------- | | **65792** | 3-D Secure transaction in progress. Contact customer support if this error occurs. | | **65793** | Unknown 3-D Secure Error. | | **65794** | 3-D Secure processing is unavailable. Merchant account doesn’t support 3-D Secure. | | **65795** | 3-D Secure processing is not required for the given card. | | **65796** | 3-D Secure processing is required for the given card. | | **65797** | Error occurred during 3-D Secure enrolment check. | | **65798** | Reserved for future use. Contact customer support if this error occurs. | | **65799** | Reserved for future use. Contact customer support if this error occurs. | | **65800** | Error occurred during 3-D Secure authentication check. | | **65801** | Reserved for future use. Contact customer support if this error occurs. | | **65802** | 3-D Secure authentication is required for this card. | | **65803** | 3-D Secure enrolment or authentication failure and Merchant 3-D Secure preferences are to STOP processing. | **Missing Request Field Error Codes: 66048 - 66303** | Code | Description | | :---- | :----------- | | **66048** | Missing request. No data posted to integration URL. | | **66049** | Missing **`merchantID`** field. | | **66050** | Reserved for future use. Contact customer support if this error occurs. | | **66051** | Reserved for internal use. Contact customer support if this error occurs. | | **66052** | Reserved for internal use. Contact customer support if this error occurs. | | **66053** | Reserved for internal use. Contact customer support if this error occurs. | | **66054** | Reserved for internal use. Contact customer support if this error occurs. | | **66055** | Missing **`action`** field. | | **66056** | Missing **`amount`** field. | | **66057** | Missing **`currencyCode`** field. | | **66058** | Missing **`cardNumber`** field. | | **66059** | Missing **`cardExpiryMonth`** field. | | **66060** | Missing **`cardExpiryYear`** field. | | **66061** | Missing **`cardStartMonth`** field (reserved for future use). | | **66062** | Missing **`cardStartYear`** field (reserved for future use). | | **66063** | Missing **`cardIssueNumber`** field (reserved for future use). | | **66064** | Missing **`cardCVV`** field. | | **66065** | Missing **`customerName`** field. | | **66066** | Missing **`customerAddress`** field. | | **66067** | Missing **`customerPostcode`** field. | | **66068** | Missing **`customerEmail`** field. | | **66069** | Missing **`customerPhone`** field (reserved for future use). | | **66070** | Missing **`countyCode`** field. | | **66071** | Missing **`transactionUnique`** field (reserved for future use). | | **66072** | Missing **`orderRef`** field (reserved for future use). | | **66073** | Missing **`remoteAddress`** field (reserved for future use). | | **66074** | Missing **`redirectURL`** field. | | **66075** | Missing **`callbackURL`** field (reserved for future use). | | **66076** | Missing **`merchantData`** field (reserved for future use). | | **66077** | Missing **`origin`** field (reserved for future use). | | **66078** | Missing **`duplicateDelay`** field (reserved for future use). | | **66079** | Missing **`itemQuantity`** field (reserved for future use). | | **66080** | Missing **`itemDescription`** field (reserved for future use). | | **66081** | Missing **`itemGrossValue`** field (reserved for future use). | | **66082** | Missing **`taxValue`** field (reserved for future use). | | **66083** | Missing **`discountValue`** field (reserved for future use). | | **66084** | Missing **`taxDiscountDescription`** field (reserved for future use). | | **66085** | Missing **`xref`** field (reserved for future use). | | **66086** | Missing **`type`** field (reserved for future use). | | **66087** | Missing **`signature`** field (field is required if message signing is enabled). | | **66088** | Missing **`authorisationCode`** field (reserved for future use). | | **66089** | Missing **`transactionID`** field (reserved for future use). | | **66090** | Missing **`threeDSRequired`** field (reserved for future use). | | **66091** | Missing **`threeDSMD`** field (reserved for future use). | | **66092** | Missing **`threeDSPaRes`** field. | | **66093** | Missing **`threeDSECI`** field. | | **66094** | Missing **`threeDSCAVV`** field. | | **66095** | Missing **`threeDSXID`** field. | | **66096** | Missing **`threeDSEnrolled`** field. | | **66097** | Missing **`threeDSAuthenticated`** field. | | **66098** | Missing **`threeDSCheckPref`** field. | | **66099** | Missing **`cv2CheckPref`** field. | | **66100** | Missing **`addressCheckPref`** field. | | **66101** | Missing **`postcodeCheckPref`** field. | | **66102** | Missing **`captureDelay`** field. | | **66103** | Missing **`orderDate`** field. | | **66104** | Missing **`grossAmount`** field. | | **66105** | Missing **`netAmount`** field. | | **66016** | Missing **`taxRate`** field. | | **66016** | Missing **`taxReason`** field. | | **66160** | Missing **`cardExpiryDate`** field. | | **66161** | Missing **`cardStartDate`** field. | **Invalid Request Field Error Codes: 66304 - 66559** | Code | Description | | :---- | :----------- | | **66304** | Invalid request. | | **66305** | Invalid **`merchantID`** field. | | **66306** | Reserved for future use. Contact customer support if this error occurs. | | **66307** | Reserved for internal use. Contact customer support if this error occurs. | | **66308** | Reserved for internal use. Contact customer support if this error occurs. | | **66309** | Reserved for internal use. Contact customer support if this error occurs. | | **66310** | Reserved for internal use. Contact customer support if this error occurs. | | **66311** | Invalid action field. | | **66312** | Invalid amount field. | | **66313** | Invalid **`currencyCode`** field. | | **66314** | Invalid **`cardNumber`** field. | | **66315** | Invalid **`cardExpiryMonth`** field. | | **66316** | Invalid **`cardExpiryYear`** field. | | **66317** | Invalid **`cardStartMonth`** field. | | **66318** | Invalid **`cardStartYear`** field. | | **66319** | Invalid **`cardIssueNumber`** field. | | **66320** | Invalid **`cardCVV`** field. | | **66321** | Invalid **`customerName`** field. | | **66322** | Invalid **`customerAddress`** field. | | **66323** | Invalid **`customerPostcode`** field. | | **66324** | Invalid **`customerEmail`** field. | | **66325** | Invalid **`customerPhone`** field. | | **66326** | Invalid **`countyCode`** field. | | **66327** | Invalid **`transactionUnique`** field (reserved for future use). | | **66328** | Invalid **`orderRef`** field (reserved for future use). | | **66329** | Invalid **`remoteAddress`** field. | | **66330** | Invalid **`redirectURL`** field. | | **66331** | Invalid **`callbackURL`** field (reserved for future use). | | **66332** | Invalid **`merchantData`** field (reserved for future use). | | **66333** | Invalid **`origin`** field (reserved for future use). | | **66334** | Invalid **`duplicateDelay`** field. Refer to Section [11](#11).<br> | | **66335** | Invalid **`itemQuantity`** field. | | **66336** | Invalid **`itemDescription`** field. | | **66337** | Invalid **`itemGrossValue`** field. | | **66338** | Invalid **`taxValue`** field. | | **66339** | Invalid **`discountValue`** field. | | **66340** | Invalid **`taxDiscountDescription`** field (reserved for future use). | | **66341** | Invalid **`xref`** field. | | **66342** | Invalid **`type`** field. | | **66343** | Invalid **`signature`** field. | | **66344** | Invalid **`authorisationCode`** field. | | **66345** | Invalid **`transactionID`** field. | | **66356** | Invalid **`threeDSRequired`** field. | | **66347** | Invalid **`threeDSMD`** field. | | **66348** | Invalid **`threeDSPaRes`** field. | | **66349** | Invalid **`threeDSECI`** field. | | **66350** | Invalid **`threeDSCAVV`** field. | | **66351** | Invalid **`threeDSXID`** field. | | **66352** | Invalid **`threeDSEnrolled`** field. | | **66353** | Invalid **`threeDSAuthenticated`** field. | | **66354** | Invalid **`threeDSCheckPref`** field. | | **66355** | Invalid **`cv2CheckPref`** field. | | **66356** | Invalid **`addressCheckPref`** field. | | **66357** | Invalid **`postcodeCheckPref`** field. | | **66358** | Invalid **`captureDelay`** field. | | **66359** | Invalid **`orderDate`** field. | | **66360** | Invalid **`grossAmount`** field. | | **66361** | Invalid **`netAmount`** field. | | **66362** | Invalid **`taxRate`** field. | | **66363** | Invalid **`taxReason`** field. | | **66416** | Invalid card expiry date. Must be a date sometime in the next 10 years. | | **66417** | Invalid card start date. Must be a date sometime in the last 10 years. | <a name="A-2"></a> --- # A-2 AVS/CV2 Check Response Codes The AVS/CV2 Check Response Message field avscv2ResponseMessage is sent back in the raw form that is received from the Acquiring bank and can contain the following values; | Response | Description | | :------- | :---------- | | **ALL MATCH** | AVS and CV2 match. | | **SECURITY CODE MATCH ONLY** | CV2 match only. | | **ADDRESS MATCH ONLY** | AVS match only. | | **NO DATA MATCHES** | No matches for AVS and CV2. | | **DATA NOT CHECKED** | Supplied data not checked. | | **SECURITY CHECKS NOT SUPPORTED** | Card scheme does not support checks. | The AVS/CV2 Response Code **`avscv2ResponseCode`** is made up of six characters and is sent back in the raw form that is received from the Acquiring bank. The first 4 characters can be decoded as below, the remaining 2 characters are currently reserved for future use; | Position 1 Value | Description | | :--------------- | :---------- | | **0** | No Additional information available. | | **1** | CV2 not checked. | | **2** | CV2 matched. | | **4** | CV2 not matched. | | **8** | Reserved. | | Position 2 Value | Description | | :--------------- | :---------- | | **0** | No Additional information available. | | **1** | Postcode not checked. | | **2** | Postcode matched. | | **4** | Postcode not matched. | | **8** | Postcode partially matched. | | Position 3 Value | Description | | :--------------- | :---------- | | **0** | No Additional Information. | | **1** | Address numeric not checked. | | **2** | Address numeric matched. | | **4** | Address numeric not matched. | | **8** | Address numeric partially matched. | | Position 4 Value | Description | | :--------------- | :---------- | | **0** | Authorising entity not known. | | **1** | Authorising entity – merchant host. | | **2** | Authorising entity – acquirer host. | | **4** | Authorising entity – card scheme. | | **8** | Authorising entity – issuer. | <a name="A-3"></a> --- # A-3 3-D Secure Enrolment/Authentication Codes The 3-D Secure enrolment check field **`threeDSEnrolled`** can return the following values; + **Y - Enrolled**: The card is enrolled in the 3-D Secure program and the payer is eligible for authentication processing. + **N - Not Enrolled**: The checked card is eligible for the 3-D Secure (it is within the card association’s range of accepted cards) but the card issuing bank does not participate in the 3-D Secure program. If the Cardholder later disputes the purchase, the issuer may not submit a chargeback to you. + **U - Unable To Verify Enrolment**: The card associations were unable to verify if the Cardholder is registered. As the card is ineligible for 3-D Secure, Merchants can choose to accept the card nonetheless and precede the purchase as non-authenticated and submits authorization with ECI 7. The Acquirer/Merchant retains liability if the Cardholder later disputes making the purchase. + **E - Error Verify Enrolment**: The Gateway encountered an error. This card is flagged as 3-D Secure ineligible. The card can be accepted for payment, yet you may not claim a liability shift on this transaction in case of a dispute with the Cardholder. <a name="A-3b"></a> The 3-D Secure authentication check field **`threeDSAuthenticated`** can return the following values; + **Y - Authentication Successful**: The Issuer has authenticated the Cardholder by verifying the identity information or password. A CAVV and an ECI of 5 is returned. The card is accepted for payment. + **N - Not Authenticated**: The Cardholder did not complete authentication and the card should not be accepted for payment. + **U - Unable To Authenticate**: The authentication was not completed due to technical or another problem. A transmission error prevented authentication from completing. The card should be accepted for payment but no authentication data will be passed on to authorization processing and no liability shift will occur. + **A - Attempted Authentication**: A proof of authentication attempt was generated. The Cardholder is not participating, but the attempt to authenticate was recorded. The card should be accepted for payment and authentication information passed to authorization processing. + **E - Error Checking Authentication**: The Gateway encountered an error. The card should be accepted for payment but no authentication information will be passed to authorization processing and no liability shift will occur. <a name="A-4"></a> --- # A-4 3-D Secure Enrolment/Authentication Only Normally the Gateway will perform most of the 3-D Secure processing in the background leaving only the actual contacting of the issuers Access Control Server (ACS) to the Merchant. However, there may be times when you may wish to gain more control over the Enrolment and Authentication process. The following field allows the request processing to stop after the 3-D Secure enrolment check or authentication check and return; | Field Name | Mandatory? | Description | | :--------- | :--------- | :---------- | | **threeDSOnly** | <center>No<center/> | Complete the processing as far as the next 3-D Secure stage and then return with the appropriate response fields for that stage. | As this stop is requested then a **`responseCode`** is returned as **0 (Success)** however it will be recorded in the Merchant Management System (MMS) as **65792 (3DS IN PROGRESS)** indicating that the transaction has been prematurely halted expecting it to be continued to the next 3-D Secure stage when required. In order to continue the process, the **`threeDSMD`** field is returned along with any relevant 3-D Secure response fields suitable for that stage in the processing. If this flag is used when 3-D Secure is not enabled on the account or after the 3-D Secure process has been completed for the request (i.e. once the authentication step has completed), then passing the flag will cause the transaction to abort with a **`responseCode`** of **65795 (3DS PROCESSING NOT REQUIRED)**. This ensures that the transaction doesn’t go on to completion by accident while trying to do 3-D Secure enrolment or authentication only. <a name="A-5"></a> --- # A-5 Request Checking Only Sometimes you may wish to submit a request to the Gateway in order for it to be validated only and not processed or sent to the Acquirer. In these instances, the following flag can be used which will stop the processing after the integrity verification has been performed; | Field Name | Mandatory? | Description | | :--------- | :--------- | :---------- | | **checkOnly** | <center>No<center/> | Check the request for syntax and field value errors only. Do not attempt to submit the transaction for honouring by the Aquirer.| If the request is ok, then a **`responseCode`** is returned as **0 (Success)** otherwise the code that would have prevented the request from completing is returned. <br/><br/>Note: in these situations, the request is not stored by the Gateway and is not available within the Merchants Management System (MMS). <a name="A-6"></a> --- # A-6 Merchant Account Mapping Merchant Accounts can be grouped together so that if a transaction is sent to an account that doesn't support either the requested card type or currency then it can be automatically routed to another account in the same group that does support them. For example; you can group a Merchant Account that only supports American Express cards with a Merchant Account that only supports Visa cards, then if a request using an American Express card is sent to the Visa only Merchant Account the Gateway will automatically route it to the American Express Merchant Account. This prevents you from needing to know the card type in advance in order to send the request to the correct Merchant Account. This is important when using the Hosted integration as you don’t know the card type at the time you send the request. It is usual for you to have one master account to which you direct all requests and then group all your accounts together. Any Gateway routing of the transaction can be seen from the following additional response fields; | Field Name | Returned? | Description | | :--------- | :-------- | :---------- | | **requestMerchantID** | <center>Always<center/> | ID of Merchant Account request was sent to (usually same as **`merchantID`**). | | **processMerchantID** | <center>Always<center/> | ID of Merchant Account request was processed by. | <a name="A-7"></a> --- #A-7 Velocity Control System (VCS) The Gateway allows you to configure velocity controls using the Merchant Management System (MMS). These can be used to automatically email you decline transactions that exceed these controls. For example; you can set up a control that stops a certain card number from being used more than twice in the space of a few minutes. If one or more of these controls are broken by a transaction, then the following response fields will show the problem. If a transaction is declined due to one or more of these rules, then a **`responseCode`** of **5 (VCS DECLINE)** will be returned. | Field Name | Returned? | Description | | :--------- | :-------- | :---------- | | **vcsResponseCode** | <center>Always<center/> | VCS error code. Normally **5**. Refer to appendix [A-1](#A-1) for details. | | **vcsResponseMessage** | <center>Always<center> | Description of above response code or list of controls that are broken by this transaction.<br> | <a name="A-8"></a> --- # A-8 Capture Delay Capture Delay enables you to specify a delay between the authorisation of a payment and its capture. This allows you time to verify the order and choose whether to fulfil it or cancel it. This can be very helpful in preventing chargebacks due to fraud. When NOT using capture delay, payments are authorised and captured immediately - funds are automatically debited from the Customer’s credit or debit card at that time. When using capture delay, the payment is authorised only at the time of payment - funds are reserved against the credit or debit card and will not be debited until the payment is captured or cancelled. The Customer experience with capture delay is exactly the same as when capture delay is not used. The Customer will not know whether you are using capture delay or not. If you choose to use a capture delay, you must specify the number of days that the capture is delayed for - this will be in the range of 0 - 30 days depending on the Acquirer. Payments will automatically be captured after that delay unless you manually cancel the transaction (either using the Hosted Integration or via the Merchant Management System (MMS)). (Note that some cards require capture within 4-5 days - if payment is not automatically captured within that 4-5 day period, the transaction will expire and the reserved funds will be released to the Customer.) **Why Use Capture Delay?** Capture delay allows you to accept online orders normally, but allows you to cancel any transactions that you cannot or will not fulfil, thereby reducing the risks of chargeback. If you receive an order that appears to be fraudulent or that you cannot or do not wish to fulfil, you can simply cancel the transaction. *Note: Cancelling a trsansaction will not reverse the authorisation and will not release the funds back to the Customer. The authorisation will be left to expire and release reserved funds, the time taken for this varies between cards.* >*Some Acquirers do not support delayed capture, in which the Hosted Integration will return a **`responseCode`** of **66358 (INVALID CAPTURE DELAY)**.* <a name="A-9"></a> --- # A-9 Types of card The following is a list of primary card types supported by the Gateway. | Card Code | Card Type | | :-------- | :-------- | | **MC** | MasterCard Credit | | **MD** | MasterCard Debit | | **MA** | MasterCard International Maestro | | **MI** | MasterCard/Diners Club | | **MP** | MasterCard Purchasing | | **MU** | MasterCard Domestic Maestro (UK) | | **VC** | Visa Credit | | **VD** | Visa Debt | | **EL** | Visa Electron | | **VA** | Visa ATM | | **VP** | Visa Purchasing | | **AM** | American Express | | **JC** | JCB | The Gateway primarily supports MasterCard, Visa and American Express branded cards. Some Acquirers may support JCB cards. Not all Acquirers support all types. Where cards are provided by a single card scheme then the primary card code is also used as a code to identify the card scheme (referred to as the **`cardSchemeCode`** in the transaction response). For example, cards issued by VISA will use the code **‘VC’**, cards issued by MasterCard will use the code **‘MC’**, etc. The following is a list of secondary card types recognised by the Gateway. | Card Code | Card Type | | :-------- | :-------- | | **CF** | Clydesdale Financial Services | | **CU** | China UnionPay | | **BC** | BankCard | | **DK** | Dankort | | **DS** | Discover | | **DI** | Diners Club | | **DE** | Diners Club Enroute | | **DC** | Diners Club Carte Blanche | | **FC** | FlexCache | | **LS** | Laser | | **SO** | Solo | | **ST** | Style | | **SW** | Switch | | **TP** | Tempo Payments | | **IP** | InstaPayment | | **XX** | Unknown/unrecognised card type | These cards may be returned in response to a card lookup but they are either deprecated or most likely not supported by any current Acquirer. <a name="A-10"></a> --- # A-10 Integration Testing You can perform test transaction using one of the test Merchant IDs below and using test card details. For non 3-D Secure testing use Merchant ID **100001** <br/>For 3-D Secure Testing use Merchant ID **100856** Test Merchant Accounts are not connected to an Acquirer and so simulate their response depending on the request **`amount`** as follows; | Amount range from | Amount range to | Expected response | | :---------------- | :-------------- | :---------------- | | **101 (£1.01)** | 4999 (£49.99) | AUTH CODE: XXXXXX | | **5000 (£50.00)** | 9999 (£99.99) | CARD REFERRED | | **10000 (£100.00)** | 14999 (£149.99) | CARD DECLINED | | **15000+ (£150.00+)** | | CARD DECLINED – KEEP CARD | ## A-10.1 Test Card Details >**DO NOT USE THESE TEST CARDS ON LIVE MERCHANT ACCOUNT. THEY ARE FOR TEST PURPOSES ONLY.**<br> The expiry date used for each test card should be December of the current year; in two digit format – E.g. 12/15 for December 2015. **Visa Credit** | Card Number | CVV | Address | | :---------- | :--: | :------ | | 4929421234600821 | <center>356<center/> | Flat 6<br>Primrose Rise<br>347 Lavender Road<br>Northampton<br>NN17 8YG | | 4543059999999982 | <center>110<center/> | 76 Roseby Avenue<br>Manchester<br>M63X 7TH | | 4543059999999990 | <center>689<center/> | 23 Rogerham<br>Mansions<br>4578 Ermine Street<br>Borehamwood<br>WD54 8TH | **Visa Debit** | Card Number | CVV | Address | | :---------- | :--: | :------ | | 4539791001730106 | <center>289<center/> | Unit 5<br>Pickwick Walk<br>120 Uxbridge Road<br>Hatch End<br>Middlesex<br>HA6 7HJ | | 4462000000000003 | <center>672<center/> | Mews 57<br>Ladybird Drive<br>Denmark 65890<br> | **MasterCard Credit** | Card Number | CVV | Address | | :---------- | :--: | :------ | | 5301250070000191 | <center>419<center/> | 25 The Larches<br>Narborough<br>Leicester<br>LE10 2RT | | 5413339000001000 | <center>304<center/> | Pear Tree Cottage<br>The Green<br>Milton Keynes<br>MK11 7UY | | 5434849999999951 | <center>470<center/> | 34a Rubbery Close<br>Cloisters Run<br>Rugby<br>CV21 8JT | | 5434849999999993 | <center>557<center/> | 4-7 The Hay Market<br>Grantham<br>NG32 4HG<br> | **MasterCard Debit** | Card Number | CVV | Address | | :---------- | :--: | :------ | | 5573 4712 3456 7898 | <center>159<center/> | Merevale Avenue <br>Leicester <br>LE10 2BU | **UK Maestro** | Card Number | &nbsp;&nbsp;CVV&nbsp;&nbsp; | Address | | :---------- | :--: | :------ | | 6759 0150 5012 3445 002&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; | <center>309<center/> | The Parkway <br>5258 Larches Approach <br>Hull <br>North Humberside <br>HU10 5OP | | 6759 0168 0000 0120 097 | <center>701<center/> | The Manor <br>Wolvey Road <br>Middlesex <br>TW7 9FF | **JCB** | Card Number | &nbsp;CVV&nbsp; | Address | | :---------- | :--: | :------ | | 3540599999991047&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; | <center>&nbsp;&nbsp;209&nbsp;&nbsp;<center/> | 2 Middle Wallop<br>Merideth-in-the-Wolds<br>Lincolnshire<br>LN2 8HG | **Electron** | Card Number | CVV | Address | | :---------- | :--: | :------ | | 4917480000000008 | <center>009<center/> | 5-6 Ross Avenue<br>Birmingham<br>B67 8UJ | **American Express** | Card Number | CVV | Address | | :---------- | :--: | :------ | | 374245455400001 | <center>4887<center/> | The Hunts Way<br>Southampton<br>SO18 1GW | **Diners Club** | Card Number | CVV Number | | :---------- | :--------- | | 36432685260294 | 111 | ## A-10.2 Test 3-D Secure Card Details >**DO NOT USE THESE TEST CARDS ON LIVE MERCHANT ACCOUNT. THEY ARE FOR TEST PURPOSES ONLY.** The expiry date used for each test card should be December of the current year; in two digit format e.g. 12/15 for December 2015. **Visa Test Cards** | Card Number | CVV | Address | Postcode | Amount | Test Scenario | | :---------- | :--: | :------ | :------- | :----- | :------------ | | **4909630000000008** | | | | £12.01 | Card range not participating. | | **4012010000000000009** | | | | £12.02 | Card registered with VbV<br>(automated ACS response – click on Submit button). | | **4012001037141112** | 083 | 16 | 155 | £12.03 | Card registered with Visa<br>(automated ACS response – click on Submit button). | | **4012001037484447** | 450 | 200 | 19 | £12.04 | Failed authentication – issuer database unavailable. | | **4015501150000216** | | | | £12.05 | Attempts processing<br>(automated ACS response – click on Submit button). | **MasterCard Test Cards**<br/> >*Note: These test cards are controlled by MasterCard and won't always act as expected. The 3-D Secure passwords can be changed by anyone during the 3-D Secure testing which means the password won’t then work for the next person. The standard fall-back password is dog33cat. Use Visa's 3-D Secure test cards if these are not behaving as expected.* | Card Number | CVV | Address | Postcode | Amount | Test Scenario | | :---------- | :--: | :------ | :------- | :----- | :------------ | | **503396198900000818** | 332 | 31 | 18 | £11.01 | Enrolled International Maestro account number – valid<br>SecureCode (multiple Cardholder).<br>Select ‘MEGAN SANDERS’<br>with SecureCode password:<br>secmegan1 | | **5453010000070789** | 508 | 20 | 52 | £11.02 | Enrolled account number - valid SecureCode (single).<br>SecureCode password: sechal1 | | **5453010000070151** | 972 | 22 | 08 | £11.03 | Enrolled account number – mixed SecureCode (multi).<br>SecureCode password:<br>Hannah – sechannah1 (bad)<br>Haley – sechaley1 (good) | | **5453010000070284** | 305 | 35 | 232 | £11.04 | Enrolled account number – invalid SecureCode.<br>Invalid SecureCode password: invseccode | | **5453010000084103** | 470 | 73 | 170 | £11.05 | Attempts processing. | | **5453010000070888** | 233 | 1 | 248 | £11.06 | Account number not enrolled. | | **5199992312641465** | 006 | 21 | 14 | £11.07 | Card range not participating. | ##A-10.3 PayPal Sandbox Accounts PayPal testing is available on the standard **100001** test Merchant account however you may wish to contact your support representative to have your own PayPal test Merchant account created which connects to the your own PayPal sandbox account enabling you to view the transactions as they are sent to PayPal. <a name="A-11"></a> --- #A-11 Sample Signature Calculation It is highly recommended that transactions are protected using message signing. The signing process offers a quick and simple way to ensure that the message came from an authorised source and has not been tampered with during transmission.<br/><br/> Signing however must be done on your servers and never left for the Customers browser to do in JavaScript as this would mean revealing your secret signature code to anyone who viewed the JavaScript code in the browser.<br/><br/> Signatures are especially important when a transaction is sent from a browsers payment form via the use of hidden for fields as the Customer can easily use tools built into their browser to modify these hidden fields and maybe change things like the amount they should be charged etc.<br/><br/> The section below gives a step by step example of how to sign a transaction complete with coding examples using the PHP language **Example Signature Key:** ```php $key = 'DontTellAnyone' ``` **Example Transaction:** ```php $tran = array ( 'merchantID' => '100001', 'action' => 'SALE', 'type' => '1', 'currencyCode' => '826', 'countryCode' => '826', 'amount' => '2691', 'transactionUnique' => '55f025addd3c2', 'orderRef' => 'Signature Test', 'cardNumber' => '4929 4212 3460 0821', 'cardExpiryDate' => '1213', ) ``` **The transaction used for signature calculation must not include any 'signature' field as this will be added after signing once its value is known.**<br/><br/> **Step 1 - Sort transaction values by their field name**<br> Transaction fields must be in ascending field name order according to their numeric ASCII value. ```php ksort($tran) ``` ```php array ( 'action' => 'SALE', 'amount' => '2691', 'cardExpiryDate' => '1213', 'cardNumber' => '4929 4212 3460 0821', 'countryCode' => '826', 'currencyCode' => '826', 'merchantID' => '100001', 'orderRef' => 'Signature Test', 'transactionUnique' => '55f025addd3c2', 'type' => '1' ) ``` **Step 2 - Create url encoded string from sorted fields**<br> Use RFC 1738 and the application/x-www-form-urlencoded media type, which implies that spaces are encoded as plus (+) signs. ```php $str = http_build_query($tran, '', '&'); ``` ```php action=SALE&amount=2691&cardExpiryDate=1213&cardNumber=4929+4212+3460+0821&countryCode=826&currencyCode=826&merchantID=100001&orderRef=Signature+Test&transactionUnique=55f025addd3c2&type=1 ``` **Step 3 - Normalise all line endings in the url encoded string**<br> Convert all CR NL, NL CR, CR character sequences to a single NL character. ```php $str = str_replace(array('%0D%0A', '%0A%0D', '%0D'), '%0A', $str); ``` ```php action=SALE&amount=2691&cardExpiryDate=1213&cardNumber=4929+4212+3460+0821&countryCode=826&currencyCode=826&merchantID=100001&orderRef=Signature+Test&transactionUnique=55f025addd3c2&type=1 ``` **Step 4 - Append you signature key to the normalised string**<br> The signature key is appended to the normalised string with no separator characters. ```php $str .= 'DontTellAnyone' ``` ```php action=SALE&amount=2691&cardExpiryDate=1213&cardNumber=4929+4212+3460+0821&countryCode=826&currencyCode=826&merchantID=100001&orderRef=Signature+Test&transactionUnique=55f025addd3c2&type=1DontTellAnyone ``` **Step 5 - Hash the string using the SHA-512 algorithm**<br> The normalised string is hashed to a more compact value using the secure SHA-512 hashing algorithm1. ```php $signature = hash('SHA512', $str); ``` ```php da0acd2c404945365d0e7ae74ad32d57c561e9b942f6bdb7e3dda49a08fcddf74fe6af6b23b8481b8dc8895c12fc21c72c69d60f137fdf574720363e33d94097 ``` **Step 6 - Add the signature to the transaction form or post data**<br> The signature should be sent as part of the transaction in a field called 'signature'. ```php <input type="hidden" name="signature" value="<?=$signature?>"> ``` or ```php $tran['signature'] = $signature; ``` <a name="A-12"></a> --- # A-12 Transaction Life-cycle Each transaction received by the Gateway follows a pre-determined life-cycle from receipt to completion. The stages in the life cycle are determined by the type of transaction and its success or failure at different stages in its life. <a name="A-12.1"></a> ## A-12.1 Authorise, Capture & Settlement The key stages in the transactions life-cycle can be grouped into the Authorisation, Capture and Settlement stages as follows; ### Authorisation An authorisation places a hold on the transaction amount in the Cardholder’s issuing bank. No money actually changes hands yet. For example, let’s say that you are going to ship a physical product from your website. First you authorise the amount of the transaction, then you ship the product. Only after the product is shipped do you capture the transaction. ### Capture A capture essentially marks a transaction as ready for settlement. As soon as the product is shipped, you can capture an amount up to the amount of the authorisation. Usually the full amount is captured. An example of a situation in which the whole amount is not captured might be if the Customer ordered multiple items and one of them is unavailable. The Payment Gateway will normally automatically capture all authorisations as soon as they are approved freeing you up from having to do this. However, it is usually more desirable to either delay the capture for a period of time or indefinitely. The **`captureDelay`** field can be used for this purpose and will allow you to state the number of days to delay any automatic capture or to never automatically capture. For more details on delayed capture refer to appendix [A-8](#A-8). ### Settlement Within 24 hours the Gateway will instruct your Acquirer to settle the transaction. The Acquirer then transfers the funds between the Cardholder’s and your accounts. <a name="A-12.2"></a> ## A-12.2 Transaction States At any time during the transactions life cycle it is in one of a number of states as follows; #### Received The transaction has been received by the Gateway and stored away. This is the very first stage. The Gateway will examine the transaction and pass it on to the next stage as appropriate. #### Approved The transaction has been sent to the Acquirer for authorisation and the Acquirer has approved it and is holding the Cardholder’s funds. This is an intermediate state and follows the **received** state. #### Verified The transaction has been sent to the Acquirer for verification and the Acquirer has confirmed that the account is valid. This is a terminal state and follows the **received** state. The transaction will never be settled and no funds will ever be transferred. #### Declined The transaction has been sent to the Acquirer for authorisation and the Acquirer declined it. The Acquirer will not normally give any reason for a decline and will not have held any funds. The transaction has now completed its life-cycle and no more processing will be done on it. This is a terminal state and follows the **received** state. The transaction will never be settled and no funds will ever be transferred. The transaction **`responseCode`** will be **5 (Declined)**. #### Referred The transaction has been sent to the Acquirer for authorisation and the Acquirer referred it for verbal approval. You can choose not to seek verbal approval and treat these transactions the same as a normal ‘declined’ authorisation. To seek verbal approval, you will need to phone the Acquirer and ask for an authorisation code. You will probably be asked for more information about the transaction and maybe required to gather other forms of identification from the Cardholder. If an authorisation code is provided then a new transaction can be sent to the Gateway specifying the **`xref`** of this transaction and the received **`authorisactionCode`**. This new request will not be sent for authorisation and will be in the ‘approved’ state ready for capture and settlement. This is a terminal state and follows the **received** state. The transaction will never be settled and no funds will ever be transferred. The transaction **`responseCode`** will be **2 (Referred)**. #### Reversed The transaction was sent to the Acquirer for authorisation and the Acquirer approved it however the transaction has been voided and the approval reversed. The Acquirer will have been asked to reverse any approval previously received effectively cancelling the authorisation and returning any held funds back to the Cardholder. The gateway will reverse an authorisation if it declines the transaction post authorisation due to any AVS/CV checking. The PREAUTH action will also automatically reverse an authorisation before return. This is a terminal state and follows the **approved** state. The transaction will never be settled and no funds will ever be transferred. If the transaction was reversed due to AVS/CV2 checking, then the transaction **`responseCode`** will be **5 (AVS/CV2 Declined)**. #### Captured The transaction has been captured and the Acquirer will be asked to capture the approved held funds when the settling process next runs. The settling process normally runs each evening but the Acquirer may take up to 3 days to transfer the funds. The **capture** state can either be entered automatically if the transaction requested an immediate or delayed capture or it can be manually requested by sending a CAPTURE request. You are free to change the amount to be captured to a value less than that initially approved by issuing one or more CAPTURE commands. Once captured there is no way to un-capture a transaction, if not explicitly cancelled, it will be sent for settlement at the next opportunity. This is an intermediate state and follows the **approved** state. #### Tendered The transaction has been sent to the Acquirer for settlement by the settling process and is awaiting confirmation that it has been accepted. At this point the transaction can no longer be cancelled or re-captured. This is an intermediate state and follows the **captured** state. #### Deferred The transaction could not be settled due to some temporary problem such as a communications loss. It will be attempted again the next time the settling process runs – usually first thing the next day. This is an intermediate state and follows the **tendered** state. It will normally be accompanied by a transaction response that indicates why the settlement process could not settle the transaction. #### Accepted The transaction has been accepted for settlement by the Acquirer. The held funds will be transferred between the Merchant and Cardholder in due course. The transaction has now completed its life-cycle and no more processing will be done on it, unless it is subject to a rejection while the Acquirer is settling it. This is a terminal state and follows the **tendered** state. #### Rejected The transaction has been rejected for settlement by the Acquirer. The held funds will not be transferred between the Merchant and Cardholder. Few Acquirers inform the Gateway that they have rejected a transaction; they normally inform you directly. Therefore, a transaction may show as **accepted** even if was ultimately **rejected** or it may change from **accepted** to **rejected** if the Acquirer does inform the Gateway. The transaction has now completed its life-cycle and no more processing will be done on it. This is a terminal state and follows the **tendered** or **accepted** states. The transaction response will normally indicate the reason the transaction was rejected. #### Cancelled The transaction has been cancelled by the Merchant by sending a cancellation request to the Gateway either using the CANCEL action or via the Merchant Management System (MMS). You can cancel any transaction that is not in a terminal state or in the ‘tendered’ state. Once cancelled any further processing that would have normally taken place will be halted. Cancelling a transaction may or may not release any funds held on the Cardholder’s card depending on support from the Acquirer and card scheme. This is a terminal state and follows any non-terminal state that occurs before the transaction reaches the **tendered** state. #### Finished The transaction has finished and reached the end of its lifespan but did not reach one of the other terminal states. Usually this indicates a problem has occurred with the transaction that prevents it continuing with its normal life-cycle. This is a terminal state and can follow any other state. The transaction response will normally indicate the reason the transaction failed. <a name="A-13"></a> --- #A-13 Transaction types The Gateway only supports card not present (CNP) types of transactions, made where the Cardholder does not or cannot physically present the card for a Merchant's visual examination at the time that an order is given and payment effected. The type of transaction required is specified using the type request field when performing a new payment transaction. ##A-13.1 E-commerce (ECOM) E-commerce transactions are supported by the Gateway by using a transaction **`type`** of **1**. They are designed for Merchants who wish to accept payments via a website, such as a shopping cart payment. E-commerce transactions can use advanced fraud detection such as 3-D Secure. <br/><br/>Due to MasterCard stipulations the Gateway will not allow Maestro cards to be for new e-commerce transactions without the use of 3-D Secure. ##A-13.2 Mail Order/Telephone Order (MOTO) Mail Order/Telephone Order transactions are supported by the Gateway by using a transaction **`type`** of **2**. They are designed for Merchants who wish to build their own virtual terminal system to enter remote order details. You will need to ensure when processing such transactions, that their Acquirer understands the transaction is a MOTO transaction. The reason for this is because the Acquirer will have different requirements in order to classify a transaction as secure, e.g. 3-D Secure is often required for internet transactions, but impossible for MOTO transactions. <a name="A-13.3"></a> ##A-13.3 Continuous Authority (CA) Continuous Authority transactions are supported by the Gateway by using a transaction **`type`** of **9**. They are designed for Merchants who wish to take full control of their subscription transactions. For further details on how to use Continuous Authority transactions please refer to appendix [A-15.2](#A-15.2). The Gateway offers a means of automating the taking of regular CA transactions using Recurring Transaction Agreements (RTA) as detailed in section [10](#10). <a name="A-14"></a> --- #A-14 Payment Tokenisation All new transactions stored by the Gateway are assigned a unique reference number which is referred to the cross reference and returned in the **`xref`** response field. This cross reference is displayed on the Merchant Management System (MMS) and used whenever a reference to a previous transaction is required. The cross reference can be sent as part of a transaction request in the **`xref`** request field to tell the Gateway to perform an action on an existing transaction. This is normally for management actions such as **CANCEL** or **CAPTURE**. The cross reference can also be sent with new transactions such as **PREAUTH**, **SALE**, and **REFUND** actions to request that the Gateway uses the values from the existing transactions if they have not been specified in the new request. For more information on how the existing values are used please refer to appendix [A-16](#A-16). This allows an existing transaction to be effectively repeated without you needing to know the original card number. The only exception to this is the card’s security code (CVV) which, due to PCI:DSS restrictions, the Gateway cannot store this so it will have to be supplied in the new request (unless the new request is a Continuous Authority transaction, refer to appendix [A-13.3](#A-13.3)). The use of cross references to perform repeat transactions is referred to as Payment Tokenisation and should not be confused with Card Tokenisation which is a separate service offered by the Gateway. Refer to section [10](#10) for details on how to instruct the Gateway to automatically repeat payment. The way each action handles any supplied **`xref`** is as follows; ## PREAUTH, SALE, REFUND, VERIFY requests These requests will always create a new transaction. The **`xref`** field can be provided to reference an existing transaction, which will be used to complete any missing fields in the current transaction; this previous transaction will not be modified. For more information on how the existing values are used please refer to appendix [A-16](#A-16). If the existing transaction cannot be found, then an error will be returned and recorded against the new transaction. The request is expected to contain any transaction information required. The **`xref`** will only be used to complete any missing card and order details, preventing you from having to store card details. ## REFUND_SALE requests These requests will always create a new transaction. The **`xref`** field can be provided to reference an existing transaction, which is going to be refunded. This existing transaction will be marked as having been fully or partially refunded and the amounts will be tallied to ensure that you cannot refund more than the original amount of this existing transaction. If the existing transaction cannot be found, then an error will be returned and recorded against the new transaction. The request is expected to contain any transaction information required. The **`xref`** will not only be used to find the transaction to be refunded but that transaction will be used to complete any missing card and order details, preventing you from having to store card details. ## CANCEL or CAPTURE requests These requests will always modify an existing transaction. The **`xref`** field must be provided to reference an existing transaction, which will be modified to the desired state. If the existing transaction cannot be found, then an error is returned but no record of the error will be recorded against any transaction. The request should not contain any new transaction information. Any attempt to send any new transaction information will result in an error. The exception to this is that a CAPTURE request can send in a new lesser **`amount`** field when a lesser amount needs to be settled than was originally authorised. ## QUERY requests These requests will not create or modify any transaction. The **`xref`** field must be provided to reference an existing transaction, which will be returned as if it had just been performed. If the existing transaction cannot be found, then an error is returned but no record of the error will be recorded against any transaction. The request should not contain any new transaction information. Any attempt to send any new transaction information will result in an error. ## SALE or REFUND Referred Authorisation requests These will always create a new transaction. The **`xref`** field must be provided to reference an existing transaction, which must be of the same request type and be in the **referred** state. A new transaction will be created based upon this transaction. If the existing transaction cannot be found or is not in the **referred** state, then an error will be returned and recorded against the new transaction. The new transaction will be put in the **approved** state and captured when specified by the existing or new transaction details. It will not be sent for authorisation again first. The request may contain any new transaction but any card details or order amount must be the same as the existing transaction. Any attempt to send different card details or order details will result in an error. Note: This usage is very similar to a normal SALE or REFUND request sent with an **`authorisationCode`** included; the difference being the **`xref`** must refer to an existing ‘referred’ transaction whose full details are used if required and not just an existing transaction whose card details are used if required. This means that it is not possible to create a pre-authorised SALE or REFUND request and use a **`xref`** (to use the card and order details from an existing transaction). As soon as the **`xref`** field is seen, the Gateway assumes it is a **referred** transaction that you wish to authorise. <a name="A-15"></a> --- # A-15 Repeat Transactions The Gateway supports two main types of repeat transactions and the option for the Gateway to automatically take the repeat transactions on your behalf. Repeat transactions take advantage of the Payment Tokenisation feature of the Gateway as described in appendix [A-14](#A-14) where each transaction is assigned a unique cross reference and allowing the details from a previous transaction to be used in a later transaction. Refer to section [10](#10) for information on how the Gateway can be instructed to automatically take repeat payments depending on a pre-determined schedule. ## A-15.1 Card On File Transactions Transactions made using card details that have been previously captured and then stored ‘on file’ are termed ‘Card On File’ or ‘COF’ transactions. This is how most ad-hoc recurring/repeat transactions are performed using the **`xref`** field to refer to the card details stored on file during a previous transaction. ### A-15.1.1 Initial Transaction The initial transaction can be any transaction that has successfully stored away valid credit card details and returned a **`xref`** response field. The transaction need not have resulted in a successful authorisation but would normally be a successful VERIFY, PREAUTH or SALE request. ### A-15.1.2 Repeat Transaction The repeat transaction would send the **`xref`** returned by the initial transaction (or previous repeat transaction) as the **`xref`** request field. This transaction should use a **`type`** of **2** (MOTO) indicating it is a 'Cardholder not present' transaction. The repeat transaction would be a clone of the cross referenced transaction including any payment details with the exception of any new data provided in the repeat transaction. The **`cloneFields`** request field can also be used to control which fields in the cross referenced transaction are used in the repeat transaction (refer to appendix [A-16](#A-16)). As the card CVV number is never stored then repeat transactions will either require the Cardholder to re-enter their CVV or the transaction has to be performed with no CVV. In such cases the Gateway will automatically suppress CVV checking however not all Acquirers will allow transactions to be performed with no CVV. <a name="A-15.2"></a> ##A-15.2 Continuous Payment Agreements A Continuous Payment Authority (CPA), which is sometimes referred to as a recurring payment or a ‘continuous payment transaction’, is where the Cardholder gives a Merchant permission to regularly take money from their debit or credit card whenever they think they’re owed money. Often payday loan companies, online DVD rental subscriptions, magazine subscriptions and gym memberships use this method of payment. ### A-15.2.3 Initial Transaction The initial transaction must be any successful VERIFY, PREAUTH or SALE request. If no payment is required at the same time then a Merchant must use a VERIFY request. The initial transaction must be subject to the highest level of authentication supported. This would therefore mean that **`eCommerce`** transactions must use 3-D Secure when available. To indicate that the initial transaction is the first in a Continuous Payment Authority then the type of agreement between the Merchant and the Cardholder must be specified using the **`rtAgreementType`** field. The **`rtAgreementType`** can be one of the following values: + **recurring** – this is used when each recurring payment may be for a variable or fixed amount and the agreement shall not have a specified end date. + **instalment** – this is used when each recurring payment may be for a variable or fixed amount but the total of all the recurring payments will be for a fixed amount which shall be specified in the agreement with the Cardholder. Therefore the agreement has a specified end date and the total amount to be paid is known. ###A-15.2.4 Repeat Transaction The repeat transaction would send the **`xref`** returned by the initial transaction (or previous repeat transaction) as the **`xref`** request field. This transaction must use a **`type`** of **9** (CA) indicating it is a Continuous Authority transaction. The repeat transaction would be a clone of the cross referenced transaction including any payment details with the exception of any new data provided in the repeat transaction. The **`cloneFields`** request field can also be used to control which fields in the cross referenced transaction are used in the repeat transaction (refer to appendix [A-16](#A-16)). As the card CVV number is never stored then repeat transactions will not require a card CVV to be supplied. Acquirers insist that a separate acquiring account is used for any Continuous Authority payment in which case this would be associated with a different Merchant Account. In such cases the initial transaction would be performed against your normal Merchant Account and the repeat transactions would be performed against your Continuous Authority Merchant Account. It is the responsibility of the Merchant to regulate the transaction values and frequencies. Please be aware as a rule of thumb the banks expect Continuous Authority payments to be a predictable transaction amount on a regular or predictable frequency, any deviation from this can be viewed as an abuse of the Merchant’s Continuous Authority acquiring account. You must also only ever process a Continuous Authority transaction on a card provided you have obtained full authorisation and authentication against that card via your normal Merchant Account. Due to MasterCard stipulations the Gateway will not allow Maestro cards to be used with Continuous Authority transactions. <a name="A-16"></a> --- # A-16 Transaction Cloning If a new transaction request is received with the Cross Reference (**`xref`**) of an existing transaction, then the values of certain fields in the existing transaction will be used to initialise the new transaction where new values have not been provided in the new request. This copying of fields from a base transaction is termed ‘transaction cloning’, the copied over value is termed the ‘cloned value’. Appendix [A-16.1](#A-16.1) shows all the fields whose values can be copied over from the existing transaction. To easily allow for the addition of future fields the fields are grouped into logical groupings and each group is given a name (as show in brackets after the group title). Certain groups of fields, such as address fields, can only be copied as a whole entity and any new value provided in the new request will prevent the whole group from being copied from the existing transaction. Please note line item data (**`items`**) cannot be merged. By default the values of all the fields listed in appendix [A-16.1](#A-16.1) are copied from the existing transaction where appropriate, however you can control exactly which fields are copied using the **`cloneFields`** field in the new request. The value of **`cloneFields`** should be a comma separated list of field names or group names that should be copied over. Alternatively, if you wish to specify a list of fields not to copy, then prefix the list with a single exclamation mark (!). | Field Name | Mandatory? | Description | | :--------- | :--------- | :---------- | | **cloneFields** | <center>N<center/> | Comma separated list of field names or group names whose values should be cloned. | **Examples** To copy over just the value of **`customerName`** and any values for the fields in the **`customerAddressFields`** group; >``` cloneFields=”customerName, customerAddressFields” ``` To copy over the values of all supported fields apart from the value of **`customerName`** and merchantName; >``` cloneFields=”!customerName,merchantName” ``` <a name="A-16.1"></a> ## A-16.1 Cloned Fields Transaction fields currently cloned are as follows: ### A-16.1.5 Order Details Fields (orderFields) + **`type`** + **`countryCode`** + **`currencyCode`** + **`amount`** + **`grossAmount`** + **`netAmount`** + **`taxRate`** + **`taxAmount`** + **`taxReason`** + **`discountAmount`** + **`discountReason`** + **`handlingAmount`** + **`insuranceAmount`** ### A-16.1.6 Order Reference Fields (orderRefFields) + **`transactionUnique`** + **`orderRef`** + **`orderDate`** ### A-16.1.7 Card Fields (cardFields) + **`paymentMethod`** + **`cardToken`** + **`cardNumber`** + **`cardExpiryDate`** + **`cardExpiryMonth`** + **`cardExpiryYear`** + **`cardStartDate`** + **`cardStartMonth`** + **`cardStartYear`** + **`cardIssueNumber`** ### A-16.1.8 Cardholder Fields (cardholderFields) + **`customerName`** + **`customerAddress`** + **`customerPostcode`** + **`customerEmail`** + **`customerPhone`** ### A-16.1.9 Purchase Fields (purchaseFields) + **`items`** ### A-16.1.10 Statement Narrative Fields (narrativeFields) + **`statementNarrative1`** + **`statementNarrative2`** ### A-16.1.11 3-D Secure Fields (threedsFields) + **`threeDSRequired`** + **`threeDSCheckRef`** <br/><br/>Please note: 3-D Secure fields are only cloned if both the existing and new transaction are **`eCommerce`** transactions supporting 3-D Secure. ### A-16.1.12 AVS/CV2 Fields (avscv2Fields) + **`avscv2Required`** + **`cv2CheckPref`** + **`addressCheckPref`** + **`postcodeCheckPref`** + **`customerAddress`** + **`customerPostcode`** ### A-16.1.13 Merchant Email Notification Fields (notifyFields) + **`notifyEmailRequired`** + **`notifyEmail`** ### A-16.1.14 Customer Receipt Fields (cReceiptFields) + **`customerReceiptRequired`** + **`customerEmail`** ### A-16.1.15 Electronic Receipt Fields (eReceiptFields) + **`eReceiptsRequired`** + **`eReceiptsApiKey`** + **`eReceiptsApiSecret`** + **`eReceiptsStoreID`** + **`eReceiptsCustomerRef`** + **`eReceiptsReceiptRef`** + **`eReceiptsReceiptData`** ### A-16.1.16 Merchant Information Fields (merchantFields) + **`merchantName`** + **`merchantCompany`** + **`merchantAddress`*** + **`merchantTown`*** + **`merchantCounty`*** + **`merchantPostcode`*** + **`merchantCountryCode`*** + **`merchantPhone`** + **`merchantMobile`** + **`merchantFax`** + **`merchantEmail`** + **`merchantWebsite`** + **`merchantData`** + **`merchantOrderRef`** + **`merchantCustomerRef`** + **`merchantTaxRef`** + **`merchantOriginalOrderRef`** + **`merchantCategoryCode`** + **`merchantType`** ### A-16.1.17 Customer Information Fields (customerFields) + **`customerName`** + **`customerCompany`** + **`customerAddress`*** + **`customerTown`*** + **`customerCounty`*** + **`customerPostcode`*** + **`customerCountryCode`*** + **`customerPhone`** + **`customerMobile`** + **`customerFax`** + **`customerEmail`** + **`customerOrderRef`** + **`customerMerchantRef`** + **`customerTaxRef`** ### A-16.1.18 Supplier Information Fields (supplierFields) + **`supplierName`** + **`supplierCompany`** + **`supplierAddress`*** + **`supplierTown`*** + **`supplierCounty`*** + **`supplierPostcode`*** + **`supplierCountryCode`*** + **`supplierPhone`** + **`supplierMobile`** + **`supplierFax`** + **`supplierEmail`** ### A-16.1.19 Receiver Information Fields (receiverFields) + **`receiverName`** + **`receiverCompany`** + **`receiverAddress`*** + **`receiverTown`*** + **`receiverCounty`*** + **`receiverPostcode`*** + **`receiverCountryCode`*** + **`receiverPhone`** + **`receiverMobile`** + **`receiverFax`** + **`receiverEmail`** + **`receiverAccountNo`** + **`receiverDateOfBirth`** ### A-16.1.20 Delivery Information Fields (deliveryFields) + **`deliveryName`** + **`deliveryCompany`** + **`deliveryAddress`*** + **`deliveryTown`*** + **`deliveryCounty`*** + **`deliveryPostcode`*** + **`deliveryCountryCode`*** + **`deliveryPhone`** + **`deliveryMobile`** + **`deliveryFax`** + **`deliveryEmail`** ### A-16.1.21 Shipping Information Fields (shippingFields) + **`shippingMethod`** + **`shippingTrackingRef`** + **`shippingAmount`** + **`shippingGrossAmount`** + **`shippingNetAmount`** + **`shippingTaxRate`** + **`shippingTaxAmount`** + **`shippingTaxReason`** + **`shippingDiscountAmount`** + **`shippingDiscountReason`** ### A-16.1.22 MCC 6012 Additional Authorisation Data (mcc6012Fields) + **`receiverName`** + **`receiverPostcode`** + **`receiverAccountNo`** + **`receiverDateOfBirth`** ### A-16.1.23 Payment Facilitator Data (facilitatorFields) + **`subMerchantID`** + **`facilitatorID`** + **`facilitatorName`** <br/><br/>Please note: Payment facilitator fields are only cloned if the existing transaction uses the same ‘merchantID’ as the new transaction. ## A-16.2 Cloned Groups To easily allow for the future addition of new fields, the existing fields are grouped into logic groupings. Each group is given a name (as show in brackets after the group title). It is recommended that this group name be used in any **`cloneFields`** value instead of listing all the fields separately. ### A-16.2.1 Compound Groups To help maintain transaction integrity certain groups of fields, such as address fields, can only be copied as a whole entity and any new value provided in the new request will prevent the whole group from being copied from the existing transaction. These compound fields are marked with an asterisk in appendix [A-16.1](#A-16.1) and can be referred to in **`cloneFields`** as logical groups using the following group names; merchantAddressFields, customerAddressFields, deliveryAddressFields, supplierAddressFields and receiverAddressFields. ### A-16.2.2 Line Item Data Any line item data (**`items`**) is copied over in its entirety and there is no way to merge the line item from an existing transaction with any sent in a new transaction. ### A-16.2.3 Amount Consistency At present the Gateway does not validate that the various sub-amount fields such as **`netAmount`**, **`grossAmount`** etc. all add up to the actual requested amount. Therefore, these fields are currently not treated as a compound group. If a new amount value is passed which is different to that in the existing transaction, then the following fields should also be passed so they tally with the new amount. + **`grossAmount`** + **`netAmount`** + **`taxRate`** + **`discountAmount`** <a name="A-17"></a> --- # A-17 Example Code ## A-17.1 Direct Integration Example: 3-D Secure SALE Transaction The following PHP code example shows how to send a SALE transaction with support for 3-D Secure for a Direct Integration: ```php <?PHP // Signature key entered on MMS. The demo account is fixed to this value, $key = 'Circle4Take40Idea'; // Gateway URL $url = 'https://gateway.purepay.eu/direct/'; // Request $req = array( 'merchantID' => '100856', 'action' => 'SALE', 'type' => 1, 'countryCode' => 826, 'currencyCode' => 826, 'amount' => 1001, 'cardNumber' => '4012001037141112', 'cardExpiryMonth' => 12, 'cardExpiryYear' => 15, 'cardCVV' => '083', 'customerName' => 'Test Customer', 'customerEmail' => 'test@testcustomer.com', 'customerAddress' => '16 Test Street', 'customerPostcode' => 'TE15 5ST', 'orderRef' => 'Test purchase', 'transactionUnique' => (isset($_REQUEST['transactionUnique']) ? $_REQUEST['transactionUnique'] : uniqid()), 'threeDSMD' => (isset($_REQUEST['MD']) ? $_REQUEST['MD'] : null), 'threeDSPaRes' => (isset($_REQUEST['PaRes']) ? $_REQUEST['PaRes'] : null), 'threeDSPaReq' => (isset($_REQUEST['PaReq']) ? $_REQUEST['PaReq'] : null) ); // Create the signature using the function called below. $req['signature'] = createSignature($req, $key); // Initiate and set curl options to post to the gateway $ch = curl_init($url); curl_setopt($ch, CURLOPT_POST, true); curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($req)); curl_setopt($ch, CURLOPT_HEADER, false); curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); // Send the request and parse the response parse_str(curl_exec($ch), $res); // Close the connection to the gateway curl_close($ch); // Extract the return signature as this isn't hashed $signature = null; if (isset($res['signature'])) { $signature = $res['signature']; unset($res['signature']); } // Check the return signature if (!$signature || $signature !== createSignature($res, $key)) { // You should exit gracefully die('Sorry, the signature check failed'); } // Check the response code if ($res['responseCode'] == 65802) { // Send details to 3D Secure ACS and the return here to repeat request $pageUrl = (@$_SERVER['HTTPS'] == 'on') ? 'https://' : 'http://'; if ($_SERVER['SERVER_PORT'] != '80') { $pageUrl .= $_SERVER['SERVER_NAME'] . ':' . $_SERVER['SERVER_PORT'] . $_SERVER['REQUEST_URI']; } else { $pageUrl .= $_SERVER['SERVER_NAME'] . $_SERVER['REQUEST_URI']; } echo " <p>Your transaction requires 3D Secure Authentication</p> <form action=\"" . htmlentities($res['threeDSACSURL']) . "\"method=\"post\"> <input type=\"hidden\" name=\"MD\" value=\"" . htmlentities($res['threeDSMD']) . "\"> <input type=\"hidden\" name=\"PaReq\" value=\"" . htmlentities($res['threeDSPaReq']) . "\"> <input type=\"hidden\" name=\"TermUrl\" value=\"" . htmlentities($pageUrl) . "\"> <input type=\"submit\" value=\"Continue\"> </form> "; } else if ($res['responseCode'] === "0") { echo "<p>Thank you for your payment.</p>"; } else { echo "<p>Failed to take payment: " . htmlentities($res['responseMessage']) . "</p>"; } // Function to create a message signature function createSignature(array $data, $key) { // Sort by field name ksort($data); // Create the URL encoded signature string $ret = http_build_query($data, '', '&'); // Normalise all line endings (CRNL|NLCR|NL|CR) to just NL (%0A) $ret = str_replace(array('%0D%0A', '%0A%0D', '%0D'), '%0A', $ret); // Hash the signature string and the key together return hash('SHA512', $ret . $key); } ?> ``` ## A-17.2 Direct Integration Example: Non 3-D Secure Sale Transaction The following sample PHP code shows how to send a SALE transaction without support for 3-D Secure for a Direct Integration: ```php <?PHP // Signature key entered on MMS. The demo accounts is fixed to this value, $key = 'Circle4Take40Idea'; // Gateway URL $url = 'https://gateway.purepay.eu/direct/'; // Request $req = array( 'merchantID' => '100001', 'action' => 'SALE', 'type' => 1, 'countryCode' => 826, 'currencyCode' => 826, 'amount' => 1001, 'cardNumber' => '4012001037141112', 'cardExpiryMonth' => 12, 'cardExpiryYear' => 15, 'cardCVV' => '083', 'customerName' => 'Test Customer', 'customerEmail' => 'test@testcustomer.com', 'customerPhone' => '+44 (0) 123 45 67 890', 'customerAddress' => '16 Test Street', 'customerPostcode' => 'TE15 5ST', 'orderRef' => 'Test purchase', 'transactionUnique' => uniqid(), ); // Create the signature using the function called below. $req['signature'] = createSignature($req, $key); // Initiate and set curl options to post to the gateway $ch = curl_init($url); curl_setopt($ch, CURLOPT_POST, true); curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($req)); curl_setopt($ch, CURLOPT_HEADER, false); curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); // Send the request and parse the response parse_str(curl_exec($ch), $res); // Close the connection to the gateway curl_close($ch); // Extract the return signature as this isn't hashed $signature = null; if (isset($res['signature'])) { $signature = $res['signature']; unset($res['signature']); } // Check the return signature if (!$signature || $signature !== createSignature($res, $key)) { // You should exit gracefully die('Sorry, the signature check failed'); } // Check the response code if ($res['responseCode'] === "0") { echo "<p>Thank you for your payment.</p>"; } else { echo "<p>Failed to take payment: " . htmlentities($res['responseMessage']) . "</p>"; } // Function to create a message signature function createSignature(array $data, $key) { // Sort by field name ksort($data); // Create the URL encoded signature string $ret = http_build_query($data, '', '&'); // Normalise all line endings (CRNL|NLCR|NL|CR) to just NL (%0A) $ret = str_replace(array('%0D%0A', '%0A%0D', '%0D'), '%0A', $ret); // Hash the signature string and the key together return hash('SHA512', $ret . $key); } ?> ``` ## A-17.3 Hosted Integration Example: 3-D Secure SALE Transaction The following PHP code example shows how to send a SALE transaction with support for 3-D Secure for a Hosted Integration (The 3-D Secure scheme is controlled within the Merchant Management System (MMS)): ```php <?PHP // Signature key entered on MMS. The demo accounts is fixed to this value, $key = 'PurePayRocks'; // Gateway URL $url = 'https://gateway.purepay.eu/paymentform/'; if (!isset($_POST['responseCode'])) { // Send request to gateway // Request $req = array( 'merchantID' => '100001', 'action' => 'SALE', 'type' => 1, 'countryCode' => 826, 'currencyCode' => 826, 'amount' => 1001, 'orderRef' => 'Test purchase', 'transactionUnique' => uniqid(), 'redirectURL' => ($_SERVER['HTTPS'] == 'on' ? 'https' : 'http') . '://' . $_SERVER['HTTP_HOST'] . $_SERVER['REQUEST_URI'], ); // Create the signature using the function called below. $req['signature'] = createSignature($req, $key); echo '<form action="' . htmlentities($url) . '" method="post">' . PHP_EOL; foreach ($req as $field => $value) { echo ' <input type="hidden" name="' . $field . '" value="' . htmlentities($value) . '">' . PHP_EOL; } echo ' <input type="submit" value="Pay Now">' . PHP_EOL; echo '</form>' . PHP_EOL; } else { // Handle the response posted back $res = $_POST; // Extract the return signature as this isn't hashed $signature = null; if (isset($res['signature'])) { $signature = $res['signature']; unset($res['signature']); } // Check the return signature if (!$signature || $signature !== createSignature($res, $key)) { // You should exit gracefully die('Sorry, the signature check failed'); } // Check the response code if ($res['responseCode'] === "0") { echo "<p>Thank you for your payment.</p>"; } else { echo "<p>Failed to take payment: " . htmlentities($res['responseMessage']) . "</p>"; } } // Function to create a message signature function createSignature(array $data, $key) { // Sort by field name ksort($data); // Create the URL encoded signature string $ret = http_build_query($data, '', '&'); // Normalise all line endings (CRNL|NLCR|NL|CR) to just NL (%0A) $ret = str_replace(array('%0D%0A', '%0A%0D', '%0D'), '%0A', $ret); // Hash the signature string and the key together return hash('SHA512', $ret . $key); } ?> ``` --- # A-18 Frequently Asked Questions **1. I'm getting Invalid Credentials. What do I do?** + Check your Merchant ID in your integration is correct. Our Gateway Merchant IDs typically begin with 1 and are currently 6 digits long, e.g. 100001. **2. I'm getting an invalid signature error message. How do I fix it?** + Check you are using the correct method for calculating the signature and the correct secret signature key for the Merchant Account used. + Make sure you are not using an image form submit button as that will add fields to the post which cannot be removed and will render the signature useless. Refer to appendix [A-11](#A-11) for a step by step guide to creating a signature with the same values which you can test using your own signature generation routine to see if it produced the same value as ours. This test step by step generator is available on our website, just click on the link below and follow the instructions. https://gateway.purepay.eu/devtools/sigtest.php <br/>**3. I have more than one Merchant ID - how do I use more than one?** + You have a couple options here. You can setup separate integrations for each MID, which can be a bit inconvenient. Your other option is to request they are connected together. Please contact our support team to get your MIDs connected and you will then only need to use one. **4. I receive a 'Bad Testcard Usage' error message. Why?** + If you receive this error message you are using test cards on a live Merchant ID. Please only use live cards on live Merchant IDs. Our test cards will only work on the test Merchant ID provided when you sign up with us. --- ## Hosted Form [/hosted/] Posting to the hosted form redirects the user to the Gateway hosted payment form. Here the Customer can enter their details, carry out any additional 3-D secure authentication, before being redirected back to your site. All response fields are posted back to the **`redirectURL`** and the **`callbackURL`**. ### Get the hosted form for a simple SALE transaction [POST] + Request (application/x-www-form-urlencoded) + Attributes - Include Transaction + Body merchantID=100001&action=SALE&type=1&amount=1099&currencyCode=826&countryCode=826&transactionUnique=55e6db3c81d75&orderRef=Test+hosted+purchase&redirectURL=http://www.example.com&signature=b1b7fbfe0c08dabaaafa75aab3ae369f36d6b9788805e75a5b8f6f90c56d89bc62ffb6b5300a801ec3e28fedb78bf96aec4f97b092d2c4bef2cb99e8f8c51eb5 + Response 200 (text/plain) Responds with a form that a customer can use to enter their details ### Get a hosted form with Customer details prefilled [POST] + Request (application/x-www-form-urlencoded) + Attributes - Include Transaction + customerName: Mr John Smith - Default value to display in the Cardholder’s name field. + customerAddress: Flat 6, Primrose Rise, 347 Lavender Road, Northampton - Default value to display in the Cardholder’s postal address field. + customerPostcode: NN17 8YG - Default value to display in the Cardholder’s postcode field. + customerEmail: test@example.com - Default value to display in the Cardholder’s email address field. + customerPhone: 01234567890 - Default value to display in the Cardholder's phone number field. + Body merchantID=100001&action=SALE&type=1&amount=1099&currencyCode=826&countryCode=826&transactionUnique=45f2dq1c81d25&orderRef=Test+hosted+purchase&customerName=Test+Customer&customerAddress=6347&customerPostCode=NN17+8YG&customerEmail=test@example.com&customerPhone=01234567890&redirectURL=http://www.example.com&signature=18bd2b91b78f0262c5a05849a81077cde3d09ea321c6765d0922f424cab6111c7c808fe8583b99ab120dc505eabc8005b2ba9655735949c57beb9a4d7f26895f + Response 200 (text/html) Responds with a form that a customer can use to enter their card details. Their personal details will already be filled in ## Direct Integration [/direct/] The process for VERIFY, PREAUTH and REFUND are similar to that for a SALE request. The CAPTURE, CANCEL and QUERY request are similar to REFUND_SALE in that they must reference the original SALE using the **`xref`** field. ### Process a simple SALE request [POST] + Request (application/x-www-form-urlencoded) + Attributes - Include Transaction + cardNumber: 4929421234600821 (required) + cardCVV: 356 (required) + cardExpiryDate: 1215 - In the format MMYY + customerName: Test Customer + customerAddress: 6347 - Full address or just the numeric values + customerPostcode: NN17 8YG - Full postcode or just the numeric values + Body merchantID=100001&action=SALE&type=1&amount=1099&currencyCode=826&countryCode=826&transactionUnique=55f6db1c81d95&orderRef=Test+purchase&customerName=Test+Customer&customerAddress=6347&customerPostCode=NN17+8YG&cardNumber=4929+4212+3460+0821&cardExpiryDate=1215&cardCVV=356&duplicateDelay=5&signature=f25823af5ba117e3af146c8728cb5260724c34dc4d7d4fd3b98b0cab99b7723e018275d55d9919ff1e2386d82cb2feaa6f5a82034e571dc809124bf8be291c64 + Response 200 (application/x-www-form-urlencoded) + Attributes - Include TransactionResponse + Body merchantID=100001&threeDSEnabled=N&avscv2CheckEnabled=Y &riskCheckEnabled=N&caEnabled=N&rtsEnabled=Y&cftEnabled=N &threeDSCheckPref=authenticated%2Cnot+authenticated%2Cattempted+authentication &cv2CheckPref=matched&addressCheckPref=matched &postcodeCheckPref=matched&cardCVVMandatory=N &customerReceiptsRequired=N&eReceiptsEnabled=N &eReceiptsStoreID=1&surchargeEnabled=Y&surchargeRequired=Y &action=SALE&type=1&amount=1099&currencyCode=826 &countryCode=826&transactionUnique=55f6db1c81d95 &orderRef=Test+purchase&customerName=Test+Customer &customerAddress=6347&customerPostCode=NN17+8YG &cardExpiryDate=1215&duplicateDelay=5&customerPostcode=NN17+8YG &requestID=5ac4a4e64692c&merchantAlias=100001 &responseCode=0&responseMessage=AUTHCODE%3A386393 &state=captured&requestMerchantID=100001&processMerchantID=100001 &xref=18040411QH11FL51GD38SZR&paymentMethod=card &cardExpiryMonth=12&cardExpiryYear=15 &authorisationCode=386393&transactionID=26004960 &responseStatus=0&timestamp=2018-04-04+11%3A11%3A51 &amountApproved=1099&amountReceived=1099 &amountRetained=1099&avscv2ResponseCode=222100 &avscv2ResponseMessage=ALL+MATCH&avscv2AuthEntity=merchant+host &cv2Check=matched&addressCheck=matched&postcodeCheck=matched &cardNumberMask=492942%2A%2A%2A%2A%2A%2A0821 &cardType=Visa+Credit&cardTypeCode=VC&cardScheme=Visa+ &cardSchemeCode=VC&cardIssuer=BARCLAYS+BANK+PLC &cardIssuerCountry=United+Kingdom&cardIssuerCountryCode=GBR &vcsResponseCode=0&vcsResponseMessage=Success+-+no+velocity+check+rules+applied &cardFlags=8323072&currencyExponent=2&merchantID2=100001 &signature=3efa8638430dad5be9aec44390cc0fd2624c979601da5167b5a4ec546485a4a420e0aba8c9a1c568f4390431a09286469b9a7f7a880c4a7902e8420a5bc66988 ### Process a simple REFUND_SALE request [POST] + Request (application/x-www-form-urlencoded) + Attributes - Include Transaction + cardNumber + cardCVV + cardExpiryMonth + cardExpiryYear + customerName + customerAddress + customerPostcode + Body merchantID=100001&action=REFUND_SALE&xref=18040415WZ12GK27MH33DPC&orderRef=Test+Refund+Sale&duplicateDelay=5&signature=63e2b7fa74125c0fe4747e9e92d39bdf3ad493e917740b8b591dd266770b34f8201c5a1cec80fea3ce65a55a7816a826a217d9f984fbdc27e897ea21c5f68dec + Response 200 (application/x-www-form-urlencoded) + Attributes - Include TransactionResponse ### Process a simple QUERY request [POST] + Request (application/x-www-form-urlencoded) + Attributes - Include Transaction + Body merchantID=100001&action=QUERY&xref=18040415WZ12GK27MH33DPC&signature=3f30d70d91ce87a5571dc66420f61615f2e8bd8b03097f96acaaba091a6648b4378d9816209198e28d37695d7bb63c7d78a22c37a26d6df37dab93186bd88cba + Response 200 (application/x-www-form-urlencoded) + Attributes - Include TransactionResponse ## Direct Integration with 3-D Secure [/direct/ ] The 3-D Secure process requires two steps. <br/>Step one: Process an initial 3-D Secure SALE request. <br/>Step two: On completion of the 3-D Secure authentication the ACS will post the original MD along with a PaRes value to the TermUrl provided. These values should then be sent to the Gateway in the threeDSMD and threeDSPaRes fields of a new request. See section [5.3.2](#5.3.2) for more details. ### Process an initial 3-D Secure SALE request [POST] + Request (application/x-www-form-urlencoded) + Attributes - Include Transaction + cardNumber: 4929421234600821 + cardCVV: 356 + cardExpiryDate: 1215 - In the format MMYY + customerName: Test Customer + customerAddress: 6347 - Full address or just the numeric values + customerPostcode: NN17 8YG - Full postcode or just the numeric values + threeDSRequired: Y - Use 3-D Secure + merchantID: 100856 (number, required) - Your Gateway Merchant ID + Body merchantID=100856&action=SALE&type=1&amount=1099&currencyCode=826&countryCode=826&transactionUnique=55f6db1c81d95&orderRef=Test+purchase&customerName=Test+Customer&customerAddress=6347&customerPostCode=NN17+8YG&cardNumber=4929+4212+3460+0821&cardExpiryDate=1215&cardCVV=356&duplicateDelay=5&threeDSRequired=Y&signature=253bc39c2a5b1bdbe2951c9efeb54554d9064bcc839f124da30d97d1cbff7d9d2e022cc5fc6d9d886335e9c0aecd894ba3b9cf724587d2e08cc668e0b22a090a + Response 200 (application/x-www-form-urlencoded) + Attributes - Include TransactionResponse + threeDSACSURL - The field containing the URL required to contact the ACS on. + threeDSMD - The MD field for sending to the ACS URL. + threeDSPaReq - The PaReq field for sending to the ACS URL. ### Process a 3-D Secure continuation SALE request [POST] + Request (application/x-www-form-urlencoded) + Attributes - Include Transaction + cardNumber: 4929421234600821 + cardCVV: 356 + cardExpiryDate: 1219 - In the format MMYY + customerName: Test Customer + customerAddress: 6347 - Full address or just the numeric values + customerPostcode: NN17 8YG - Full postcode or just the numeric values + threeDSMD - The MD field that you sent to the ACS URL in the inital request + threeDSPaReq - The PaReq field that you sent to the ACS URL in the inital request + threeDSPaRes - The PaRes field that was received from the ACS server in the inital request + merchantID: 100856 (number, required) - Your Gateway Merchant ID + Body merchantID=100856&action=SALE&type=1&amount=1099&currencyCode=826&countryCode=826&transactionUnique=55f6db1c81d95&orderRef=Test+purchase&customerName=Test+Customer&customerAddress=6347&customerPostCode=NN17+8YG&cardNumber=4929+4212+3460+0821&cardExpiryDate=1215&cardCVV=356&duplicateDelay=5&threeDSMD=UDNLRVk6dHJhbnNhY3Rpb25JRD0yNjAwNTc3MiZtZXJjaGFudElEPTEwMDg1NiZfX2xpZmVfXz0xNTIyODM5NjM5&threeDSPaReq=eJxVUltuwjAQvErEAWI7D5qgxRIQqeUDhAr96KflrEqq5oGdNLSn7xoSKJYt78w%2B%0D%0AvB4bDkeDmO1RdwYlbNBa9YFekc8nsdKRSiN8Usk0nkjYLV7xJOEbjS3qSgqf%2BwGw%0D%0AEVKq0UdVtRKUPi3XWymCMIqnwAYIJZp1JjmNNKXEK4RKlShXyuS2NahKL8z23gFt%0D%0AC%2BziAV13VWt%2BZBJQqRFAZ77ksW0bO2Os73tf3wr4ui4ZMBcA7N7TrnOWpYLnIpeb%0D%0AbNE%2FrM932t%2FC7e96DsxFQK5alAEXCY945Ak%2BC2mmwC48qNJ1Ip%2BXO3L5KfEDA407%0D%0AaHEFgjvPfwZIZoOVHu8zIsBzU1dIEaTMzYYcrZZODa8Z%2BqcGHAfsfqHVi5Nct6Rm%0D%0AlAZpFDjhp5wngXDiXxyufkHCiVhcD3AAmEtlw7uy4e3JevgTf%2FGMs7Q%3D&threeDSPaRes=eJylVmmTokgT/isdvR+NHg7BY4J2o7gEFJBT4BtHgSiHAsrx6xe1p6ff2Yk3NnaJIMjKynzyrKSoP7s8e7nBqk7L4v0V+4a+vvy5osxDBSFrwPBawRUlw7r2E/iSRu+vpB8Svg/jIIqI4HVF7YAO68fOOe6I5SLAfZ94w1HSfwtnPnzDien8DY1IEoPoMg5ni1Hnw9xqtPYNp5Afy9FOFR78ollRfnihRWWF4VOCnFHIx5LKYSWyK3R8lstR8bmkkJ96u+udqkefuzRaySxo//5yhGxq7xRyl6Aiv4ErHMUWKIESLxj6fTr/Ph0tPvjU+Q4H8vI6YmMYilHIVw41ZqeCRdivFvio8rmiYHcuCzhKjD5+0hTy07mzXzyi+Hzmi+WIPXIp01lRTZr/zSmCoJAHn6obv7nWK5dCPigq9G+3lYzqpsVl1tbiWQ21TQtVdmamGybajsE+RCgYpiv07tT4fWiBLCmrtDnkd1f/l0Ehd1eQR31XlJEmxWisgi9jvxT1++uhac7fEaRt22/t9FtZJQg+xoGgS2QUiOo0+eP1qQUjsYjLFcX4RVmkoZ+lg9+M5ZZhcyijl0+Dv4M09Tsqhugc8zbCvoUYUbzdOegUI0d85PegX9z9J1Z+dbyq/bf64GN3A78ArSgdxvBeZvhi6eL76x//vOvNyi/quKzy+gv9H+P/xPlKj/hsmsC6+TfB/wj8K8IPPNvPrnCVtbsST87ntCC9YIfHmtPQ2zXZhTv0/YfeU5JCPrP1kcofzfCZ1qdgfmbkXhxTCEy8tefp7lLtLrJlZu0SF0RsPaQna2pdHK4Iitzm/HNR1Libzl0Vu+bSulK7+fUSsLHTbPYNh50Fh5uoG59WRGw3bNXNbIQlUHrjDvkglttWPEhuOONYXSZQ9bong7O5dfok3ZonUdzzOUi2GnRtATF2IFcWPhxUoTWz7qQZThwzwh4zguy4v9o5WjWNbtnYaRdnQMl0ZkfkJ84rZ2yaMlx98WPjcLUvRbfr6zgpqjKouj3RLVWl8TBcn9baJmSErtsP/B5oiaeYsxtCzIqiOR/Xxlqivbk+qJaHXdeIJzYYZ2TLgNQBsm95bno1wWaDgIPk34pUHZQNfRbx3oTIxVzY4P39S/9+VGQD+2cFHBJdsn7jPykGVk0ajwdpnHqyKLLXI8OAyyYBrUiDROT2mQq1ASh0crocTul62aI00GoesDQua3XLaC5ra9qaayXbGLi9TGtrgFkck7SKjGqJhdvHyJEykaclm+WgTLfP/ba1tb1y9BxlEDnlFhR6H+DtXb6PcruX9aTlkwc2y4LlwZ3KVxnXh61DnyOGPAY42vEmMOlEsWkQjsNdz7ycxwJBSzQ8Q6EJIN+incqCTmaTTjnKU/mo+COvf/LcT54suB0zAOmJ5Zogs7ey7rY8eNjfsAAddIY2vb2ChbmV3IetrBOt8NzfsrRNu7iShVN5tL28RoJ0C+7yjoR7jtitWbB/Yssyi/PHsCcGT5CbcJ2h23yM3eRsmZYfeaHbVtbXdu46dh0xNOs7OjnWhRaPv9aA4wFQGaAtwH2fSTYjzYGOOXOKU+8molhWJZnB8jJwNH1EeJ3XsoVRFIXE3hKxTY1NqAobO7jS3s1KF7tE1C4aMbFiuKxPS0se1k3O6fu9AdfMvAn7y1ZSZWUB9SQ+dzWG9OpGAtLClklpMHxY7Mt2wg42SC6MgSbX3M0cb5Tukm4XH3m6s9nN5hgr6Ck+0IBYaEq4oG00BVE5lTL6PBlPUc8GKVLMyfQknM4Y71RBlBIoMrkqiQ8JUgHtVbG0C9d7rFvagejP3IonB8GCuKVztcmfcNbNaTKpNvOiWxeC4K55myAaY6YvND0k3CwTbS9DYgkLcr7PjzoArLi51YwhFZIm34wyFk32dj0gV98d3WEntXAYNJEFGqBLDLTmEUT3WgoawfGJZs0aPRoCRIgYrIFNz2hJtT3LhSauT63Qjv2ho0eaHnu5BP9XlgUPWZMGVgtajkZ+d+Ye9eYA7ZCcNVsixrxNiqlIsruF2qcczES1V+KD7okDh+oCv8xJJ1qjB883WHnWgXh+qbko2NqZmeokS67rjZ4YB2/iivXcP8QktmdJFjMsnXRFdDb2HyZwgxpfthezPmPb3SGdsujav9XiRLcKMQh0Y7nUbV9jXJpR1ZLhB5zR7X160/wqHH8iy7zmqgswoFSG6tkJeSawZNz1q9y02rp0a0tLOS0Tem4+qUkUW++95CRyqJNVypwsGWmSTYXDgSkRBqsIq04ybJL3fKyPlSGGec9XbNgyY1SlepKK2AcKkUx26NGrUWc21YK022jdNDstBV8AcOgjfxLM19lJ2bKXfUTwKehZxvaUizt/DM1fJ+KT85yWyOcE/TlbH1fQxxX5/hv+enX+Cxw0vxk=&signature=21b975f6e875047e5e8cf7e70206a828b8482f0cd651e9d33fc1ce6299116d0dd5f7b0863353eb46a8a22033649fbc9c7f510cb528d470cf8695517bf51f44bf + Response 200 (application/x-www-form-urlencoded) + Attributes - Include TransactionResponse ## Data Structures ### Transaction + merchantID: 100001 (number, required) - Your Gateway Merchant ID + action (enum, required) - Specifies the type of transaction taking place + SALE - A basic sale transaction + VERIFY - Checks the card details exist + PREAUTH - To check whether the transaction will be authorised e.g. account is valid and funds are available + REFUND_SALE - Refunds the transaction amount + REFUND - Refunds an amount to a card + CAPTURE - Capture an existing transaction + CANCEL - Cancels the given transaction + QUERY - Query an existing transaction + type: 1 - The type of transaction e.g. E-commerce + amount: 1099 (number,required) - The amount of the transaction in minor currency. For the UK, this is pence, so £10.99 should be sent as 1099. **Numeric values only – no decimal points or currency symbols. ** + countryCode: 826 (required) - Merchant’s location **Valid ISO-3166 alpha or numeric code.** + currencyCode: 826 (required) - Transaction currency **Valid ISO-4217 alpha or numeric code.** + transactionUnique (string, optional) - You can supply a unique identifier for this transaction. This is an added security feature to combat transaction spoofing. + orderRef (string, optional) - Free format test field to store order details, reference numbers, etc. for the Merchant’s records. + signature: A string (string, required) - Any hash used to sign this request ### Full Transaction + captureDelay: 1 (number, optional) - Number of days to wait between authorisation of a payment and subsequent settlement. + callbackURL: https://example.com/callback - An additional location in which to post the response of the transaction to. Useful in shopping carts where customers may exit the custom form before being redirected. ### TransactionResponse + responseCode (enum) - A numeric code providing the outcome of the transaction. Check responseMessage for more details of any error that occurred. + 0 - Successful/authorised transaction + 1 - Card referred - Refer to card issuer + 2 - Card referred - Special condition + 4 - Card declined - keep card + 5 - Card declined + 30 - An error occured - check responseMessage for more detail + responseMessage: AUTHCODE:120394 - The message received from the Acquiring bank, or any error message + authorisationCode: 120394 - Authorisation code received from Acquirer + transactionID: 1245789461 - A unique ID assigned by the Gateway. + xref: 16030805SG41VG18FT00KLX - You may store the cross reference for repeat transactions. Refer to appendix [A-14](#A-14) for details. + state: accepted - Transaction state. Refer to appendix [A-12.2](#A-12.2) for details. + timestamp: 2016-03-08 05:41:18 - Time the transaction was created or last modified. + cardNumberMask: \*\*\*\*\*\*\*\*\*\*\*\*0821 - Card number masked so only the last 4 digits are visible. + cardTypeCode: VC - The code of the card used. Refer to appendix [A-9](#A-9) for details. + cardType: Visa Credit - The description of the card used. Refer to appendix [A-9](#A-9) for details. + cardSchemeCode - The code of the card scheme used. Refer to appendix [A-9](#A-9) for details. + cardScheme - The description of the card scheme used. Refer to appendix [A-9](#A-9) for details. + cardIssuer - The card issuer + cardIssuerCountry : Name of card issuing country + cardIssuerCountryCode - ISO-3166 Alpha 2 code of the card issuing country