A2A


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.

Download A2A integration guide

There are two ways of how A2A can be integrated:

  • A2A Standalone
  • A2A via PxPay 2.0

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

A2A standalone

A2A Standalone Process Flow

A2A via PxPay 2.0

PxPay 2.0 Standalone Process Flow

Supported Banks New Zealand

Supported Banks Australia

Technical Specification/Features

  • No Payment Express software required
  • No SSL certificate requried
  • Fail-proof result notification
  • View of demo of how Account2Account works

Test Accounts

Live bank accounts are required for testing. If you wish to test A2A please send request to sales@paymentexpress.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.

Generate Request

GenerateRequest XML Document - To initiate a transaction the merchant posts the GenerateRequest to:

https://sec.paymentexpress.com/pxaccess/pxa2a.aspx (Live)

Note, if you are using A2A via PxPay 2.0, you should be posting the GenerateRequest to:

https://sec.paymentexpress.com/pxaccess/pxpay.aspx (Live)

Transaction Request

The following is a list of the inputs elements applicable for a GenerateRequest.

Input Element Required Datatype Notes
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

Transaction Response

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.

The following is a list of the output elements applicable for a Request.

Output Element Datatype
valid [Attribute] BSTR 1 character
URI Datatype: BSTR

Example

ProcessResponse

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
https://demo.paymentexpress.com/a2a/pxpaysetup.aspx?result=0000840000100582bdc5b5e430bc5854&userid=SampleA2AUser

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).

Process Response

The following is a list of the inputs elements applicable to the ProcessResponse.

Input Element Required Datatype
PxPayUserId Yes Max 32 characters
PxPayKey Yes Max 64 characters
Response Yes String

Example:

Response

The following is a list of the output elements applicable to the Response

Output Element Datatype
valid [Attribute] 1 character
AmountSettlement BSTR Max 13 characters
AuthCode BSTR Max 22 characters
DpsTxnRef BSTR Max 16 bytes
Success Long
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
A2aTxnStan Long
TxnId BSTR Max 16 bytes
EmailAddress BSTR Max 255 bytes

A full description of all available elements can be found on the integration guide.

Well Formed XML

Character data sent via PX Pay must be well formed XML. For example, the following is invalid XML:

Well Formed XML

The above example should be formatted as follows:

Fail-proof Result Notification

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.

Statement fields and reconciliation

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:

Particulars: "000001DPSA2A"

Code: "TheShop"

Reference: "Order1234567"

Please note the above is only applicable for transactions in NZD via New Zealand banks.

PxPay 2.0 Comparison

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.

Other notable difference is:

A2A does not support tokenisation.

Response Code (ReCo)

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