Account2Account (A2A) provides a solution for merchants to accept payments directly into their bank account by creating a one-off online payment using the customer's online banking portal. This sort of facility is already widely used where a merchant provides their bank account details and customers pay by creating a one-off payment via their online banking portal.
The key difference is that with A2A, the one-off payment is created on a secure page hosted by Payment Express. Payment Express can authoritatively inform the merchant when a payment is created and the customer is redirected back to the merchant's website once payment is created. This means that the merchant website receives the transaction outcome in real-time. Goods can then be shipped on the receipt of funds to the merchant's bank account (or at the merchant's discretion).
The Account2Account page is securely hosted by DPS (a Level 1 service provider) and is compliant to the latest PCI DSS standards. Abiding by the comprehensive set of requirements of PCI DSS means that we use the latest security technologies to ensure the safe handling of all sensitive data. During the course of the Account2Account payment process, we do not store any of the customer's bank account information. The same security features setup on the customer's bank account such as additional authentication methods are prompted during the course of the Account2Account payment process. More information on Account2Account security can be found here
As with any transaction processed via the Payment Express gateway, all transaction details are logged and are made available on Payline for reporting and reconciliation purposes.
A2A is also an extension of Payment Express' PxPay 2.0 API which provides merchants with an alternative payment option to card oriented payments and using the same hosted payments page architecture.
There are two ways of how A2A can be integrated:
We will be focusing on the A2A standalone integration here.
Note: The integration process is very similar to the PxPay 2.0 integration. For the merchants already integrated and familiar with PxPay 2.0 please refer to PxPay 2.0 Comparison section for PxPay 2.0 & A2A differences.
NOTE: Please ensure that your integration support LAX versioning
|Bank of Melbourne||www.bankofmelbourne.com.au|
Live bank accounts are required for testing. If you wish to test A2A please send request to email@example.com.
Payment Expres Support will require a live merchant bank account number (e.g. 01-1234-5678910-00). This is the bank account number that the funds will be transferred into.
Note that you will only be able to receive payments in your bank accounts local currency, i.e. A BNZ merchant account (even a multi-currency account) will only be able to process A2A payments using NZD.
Merchant can setup A2A with multiple bank account details each with different local currencies to have the ability to accept a wider range of currencies, and A2A will automatically select the correct account based on the transactions currency (As specified in the GenerateRequest message).
Account and currency mismatches will simply result in GenerateRequest failure.
GenerateRequest XML Document - To initiate a transaction the merchant posts the GenerateRequest to:
Note, if you are using A2A via PxPay 2.0, you should be posting the GenerateRequest to:
|PxPayUserId||Yes||BSTR Max 32 bytes||Use your A2A PX Pay username here|
|PxPayKey||Yes||BSTR Max 64 bytes||Use your A2A PX Pay key here|
|AmountInput||Yes||BSTR Max 13 characters||Transaction amount|
|CurrencyInput||Yes||BSTR Max 4 characters||Currently supports "NZD" only|
|EmailAddress||No||BSTR Max 255 bytes||Optional Email field|
|MerchantReference||Yes||BSTR Max 64 bytes||Reference value to appear on merchant bank statement. Note: Certain special characters may not be permitted by the banks and will be excluded by A2A.|
|TxnData1||No||BSTR Max 255 bytes||Optional free text fields|
|TxnData2||No||BSTR Max 255 bytes||Optional free text fields|
|TxnData3||No||BSTR Max 255 bytes||Optional free text fields|
|TxnType||Yes||BSTR Max 8 characters||Must be set to "Purchase"|
|TxnId||No||BSTR Max 16 bytes||Contains a unique merchant application generated value that uniquely identifies the transaction.|
|UrlFail||Yes||BSTR Max 255 bytes||URL of page to redirect to if transaction failed. Please ensure the URL starts with the protocol for example: "https:..." or "http:...". Query string characters are permitted. However percent-encoding the URL is not permitted.|
|UrlSuccess||Yes||BSTR Max 255 bytes||URL of page to redirect to if transaction successful. Please ensure the URL starts with the protocol for example: "https:..." or "http:...". Query string characters are permitted. However percent-encoding the URL is not permitted.|
Request XML Document - Once the GenerateRequest has been processed a Request will be returned.
The URI returned can then be used to redirect the customer to the Payment Express Hosted Payments Page.
|valid [Attribute]||BSTR 1 character|
ProcessResponse XML Document - Once the user has submitted the payment and the transaction has been processed, the merchant now needs to obtain the transaction outcome and details. When a user finishes the payment process the user is redirected to the merchant website. This URL has the result and userid appended to it e.g
To obtain the transaction details, the merchant sends the result string with their A2A PX Pay username and A2A PX Pay key in the ProcessResponse (Input XML Document).
|PxPayUserId||Yes||Max 32 characters|
|PxPayKey||Yes||Max 64 characters|
|valid [Attribute]||1 character|
|AmountSettlement||BSTR Max 13 characters|
|AuthCode||BSTR Max 22 characters|
|DpsTxnRef||BSTR Max 16 bytes|
|ResponseText||BSTR Max 32 bytes|
|ReCo||Max 2 characters|
|CurrencySettlement||max 4 characters|
|TxnData1||BSTR Max 255 bytes|
|TxnData2||BSTR Max 255 bytes|
|TxnData3||BSTR Max 255 bytes|
|TxnType||BSTR Max 8 characters|
|CurrencyInput||BSTR Max 4 characters|
|MerchantReference||BSTR Max 64 bytes|
|ClientInfo||Max 15 characters|
|TxnId||BSTR Max 16 bytes|
|EmailAddress||BSTR Max 255 bytes|
A full description of all available elements can be found on the integration guide.
Character data sent via PX Pay must be well formed XML. For example, the following is invalid XML:
Fail-proof result notification (FPRN) is a service that provides additional assurance that the merchant website will receive notification regarding the outcome of transactions completed via the Payment Express hosted payment page.
FPRN helps cater for the possibility that a user may not successfully navigate to the nominated success or failure URL enabling the merchant web application to acknowledge the outcome of the transaction. The user could close their browser or otherwise navigate away from the Payment Express hosted payment page once they have been informed of the transaction outcome. The merchant's web server may be temporarily unavailable as the transaction is completed and therefore unable to recognise that a transaction has taken place. Using the FPRN service the merchant website is virtually guaranteed to receive notification of the each and every transaction.
FPRN is highly recommended by Payment Express and is enabled on all new accounts by default. The service ensures that the following processes occur for every transaction performed via hosted payment page: As soon as the transaction is completed, a background process at Payment Express makes an HTTP GET request to the merchant-nominated success or failure URL. If the merchant web site is unreachable or returns any HTTP status code other than 200 or 404 the HTTP GET is retried up to a maximum of six times. It will give up immediately on receiving a 404 HTTP status code (page not found). A 500 HTTP status code, indicating a temporary problem at the client site, will cause a retry.
In order to ensure that the web application is in the best position to acknowledge the outcome of each and every transaction certain guidelines should be followed.
The merchant web application should not:
Filter or base any conditional logic upon the originating IP address (this can vary) Depend upon receiving one and only one request for the success/fail URL from the Payment Express FPRN system (multiple requests may be sent)
The merchant web application should:
Decrypt the query string for all requests for a success/fail page requests where the requested URL contains a 'result' parameter containing the encrypted transaction outcome details Determine if a database operation or some form of communication such as generating an order record or sending an email is required. Generally this will mean that the application needs to be aware if these actions have been taken previously for the particular transaction or not (TxnId should be used for this purpose).
N.B. The URL at which the merchant website will process FPRN requests must be exposed via standard internet ports i.e. port 80 or port 443 for SSL/TLS traffic. When specifying UrlSuccess and UrlFail values do not specify a non-standard port number within the URL.
For Account2Account statement reconciliation process please note the following:
Particulars field contains 6 digits rolling number (Stan) and string "DPSA2A". The Stan also appears in your payline transaction records.
Code field contains the first 12 characters of your merchant statement name.
Reference field contains the first 12 characters of Merchant Reference.
Please note certain banks do not allow entering special characters such as _, &, ?, @ in the reference field. Hence we strongly suggest to avoid adding these characters in the merchant reference field. The alphanumeric and space characters will be accepted by all banks. Any other characters may be omitted by Account2Account for certain banks.
The following is an example of the Merchant Bank's Particular, Code and Reference fields:
Merchant Reference: "Order1234567"
Merchant statement name: "TheShop"
Your fields will be for example:
Please note the above is only applicable for transactions in NZD via New Zealand banks.
A2A and PxPay 2.0 integrations are very similar. The key factor is that the A2A user is setup and configured differently at Payment Express.
Merchants who are already using PxPay 2.0 should be able to re-use existing PxPay 2.0 implementation with a few minor changes.
Change Payment Express endpoint address to https://sec.paymentexpress.com/pxaccess/pxa2a.aspx (for A2A standalone).
- Change PxPayUserId (if different).
- Change PxPayKey (if different).
- Set TxnType to 'Purchase' only.
- Set CurrencyInput to 'NZD' or 'AUD' depending on the account setup.
A2A does not support tokenisation.
The ReCo listed below describe the general outcome of an Account2Account transaction for a merchant’s reference.
These ReCo values are subject to change, hence the decision should not be automatically made by the merchant application or website. Use the Success property (from Response data) to determine the result of a transaction.
|ReCo (Response Code)||Reason|
|RC||User Cancelled (customer may have explicitly cancelled the transaction from the Account2Account hosted payment page)|
|51||Possibly Insufficient Funds in the customer’s (payer’s) bank account (or the payment failed due to a bank account issue)|
|U9||Uplink Timeout. NOTE: Possible payment may have occurred if the customer attempted to submit at the payment confirmation stage. Please contact the Support team.|
|NY||Uplink Connection Error or Uplink may be offline. NOTE: Possible payment may have occurred if the customer attempted to submit at the payment confirmation stage. Please contact the Support team.|
|EN||User Timeout (payer may have abandoned during bank account logon or the bank account selection stage) NOTE: However no payment has occurred|
|G3||User Cancellation during authentication of account|
|GN||Timeout of the payment|