MobilePay for Webservices API

MobilePay is a mobile payment application developed by Danske Bank. They merged with Vipps in 2022 to become Vipps MobilePay. When selecting MobilePay, customers will be prompted to enter their mobile phone number. While customers new to MobilePay will be guided through a registration process, returning customers will be prompted to open the MobilePay app on their smartphone and approve the transaction. As a digital wallet, MobilePay is responsible for securely storing the customer's card details, enabling them to easily select their preferred card at checkout. The transaction is ultimately processed and authorised by acquiring banks, as with standard card transactions.

Supported customer countries	DK, FI
Supported currencies	DKK, EUR, NOK, SEK
Refunds	Full and partial refunds permitted for up to 365 days.
Chargebacks	Payments may be subject to chargebacks.
Zero-authorisation	Zero-authorisations can performed by submitting an ACCOUNTCHECK request, if supported by your acquiring bank.
Recurring payments	Not supported.

Configuration

To enable MobilePay on your account, please get in touch with your account manager. You will need to provide an image of your company logo that will be displayed to the customer in the MobilePay app when they are prompted to authorise the payment. In turn, we will provide a test sandbox account that you will need when testing your implementation.

Requirements

MobilePay can only be offered by merchants operating in countries within the European Union (EU) and/or European Economic Area (EEA), and the UK. MobilePay is particularly popular in Denmark and Finland.
To integrate MobilePay into your checkout, you are required to have a Merchant Id (MID) that will allow you to process e-commerce (ECOM) transactions. This is because, despite the customer approving the payment using MobilePay, ultimately a card transaction is processed and this necessitates you having a relationship with an acquiring bank.

Trust Payments only supports MobilePay transactions processed using Mastercard and Visa-branded payment cards.

Process overview

Initiate the customer
- Customer agrees to a payment using MobilePay on the merchant’s website.
- Merchant submits a combined ORDER, THREEDQUERY, AUTH request to initiate the session. This request includes fields returnurl and cancelurl.
- Merchant receives the response, including redirecturl.
- If configured, Trust Payments will submit a URL notification to the merchant’s system to notify of the above.
Redirect to MobilePay
- Merchant redirects the customer’s browser to the redirecturl.
- Customer follows instructions on MobilePay's hosted pages to authorise the payment.
- If successful, the browser is redirected to the returnurl, a holding page hosted by the merchant that displays a "Please wait" message. This redirect includes the fields transactionreference, ordertransactionreference and signature.
- If there has been a problem with the payment, the browser is redirected to the cancelurl, a page hosted by the merchant that displays an error to the customer.
Verify Auth Response
- Once the merchant receives a URL notification informing of successful authorisation (this must first be configured on your site reference), they process a VERIFYAUTHRESPONSE request including verifystring, an object containing the values of the transactionreference, ordertransactionreference and signature fields returned in the redirect from MobilePay.
Payment completion
- If the VERIFYAUTHRESPONSE returns a success response, the merchant displays a success message in the browser.
- If there has been a problem, the merchant displays an error message in the browser.
- Following authorisation, funds will be settled into your bank account following the same process used for standard card transactions.
- Following the standard payment flow for card transactions, funds will typically be settled into your bank account within 24 hours of authorisation.

Trust Payments does not support the processing of re-authorisations or new Account Checks that inherit payment credentials from a previously-processed MobilePay transaction. Attempting such actions will result in errorcode "60018" with errormessage "Invalid requesttype" being returned.

1. Initiate the customer

When the customer chooses to pay with MobilePay, your system will need to submit a combined ORDER, THREEDQUERY, AUTH request and, if successful, redirect the customer’s browser to the redirecturl returned in the response.

Before you begin testing, you must contact our Support Team and request that a rule is enabled on your account, which submits a URL notification to your system following authorisation.

We recommend including at least the following fields in your authorisation notification:

Click here to view full list

Acquirer Response Message (acquirerresponsemessage)
Base Amount (baseamount) (e.g. £10.50 is “1050”)*
Main Amount (mainamount) (e.g. £10.50 is “10.50”)*
Billing Country (billingcountryiso2a)
Currency (currencyiso3a)
Error Code (errorcode)
Live Status (livestatus)
Order Reference (orderreference)
Payment Type (paymenttypedescription)
Request Type (requesttypedescription)
Settle Status (settlestatus)
Site Reference (sitereference)
Transaction Reference (transactionreference)
Transaction Started Timestamp (transactionstartedtimestamp)

*Please choose your preferred format.

Combined ORDER, THREEDQUERY, AUTH request

The example request below is for the request submitted to initialise the MobilePay payment session:

You can exclude request type THREEDQUERY from the request to exempt the transaction from 3-D Secure authentication checks. Transactions exempt in this manner are automatically flagged with the relevant SCA exemption flag (in this case "5", denoting a delegated authentication). If the issuer returns a soft decline, we will automatically retry the transaction with necessary 3-D Secure authentication.

#!/usr/bin/python
import securetrading

stconfig = securetrading.Config()
stconfig.username = "webservices@example.com"
stconfig.password = "Password1^"
st = securetrading.Api(stconfig)

order = {
  "accounttypedescription": "ECOM",
  "baseamount": "1050",
  "billingcontactdetailsoverride": "1",
  "cancelurl": "https://example.com/cancelpayment",
  "currencyiso3a": "DKK",
  "customercontactdetailsoverride": "1",
  "orderreference": "MyOrder123",
  "paymenttypedescription": "MOBILEPAY",
  "requesttypedescriptions": ["ORDER","THREEDQUERY","AUTH"],
  "returnurl":" https://example.com/successpayment",
  "sitereference":"test_site12345"
}

strequest = securetrading.Request()
strequest.update(order)
stresponse = st.process(strequest) #stresponse contains the transaction response

<?php

if (!($autoload = realpath(__DIR__ . '/../../../autoload.php')) && !($autoload = realpath(__DIR__ . '/../vendor/autoload.php'))) {
throw new Exception('Composer autoloader file could not be found.');
}
require_once($autoload);

$configData = array(
  'username' => 'webservices@example.com',
  'password' => 'Password1^'
);

$requestData = array(
  'accounttypedescription' => 'ECOM',
  'baseamount' => '1050',
  'billingcontactdetailsoverride' => '1',
  'cancelurl' => 'https://example.com/cancelpayment',
  'currencyiso3a' => 'DKK',
  'customercontactdetailsoverride' => '1',
  'orderreference' => 'MyOrder123',
  'paymenttypedescription' => 'MOBILEPAY',
  'requesttypedescriptions' => array('ORDER','THREEDQUERY','AUTH'),
  'returnurl' => 'https://example.com/successpayment',
  'sitereference' => 'test_site12345',
);

$api = \Securetrading\api($configData);
$response = $api->process($requestData);
var_dump($response->toArray());

?>

curl --user webservices@example.com:Password1^ <DOMAIN>/json/ -H "Content-type: application/json" -H "Accept: application/json" -X POST -d '{
  "alias": "webservices@example.com",
  "version": "1.00",
  "request": [{
    "accounttypedescription": "ECOM",
    "baseamount": "1050",
    "billingcontactdetailsoverride": "1",
    "cancelurl": "https://example.com/cancelpayment",
    "currencyiso3a": "DKK",
    "customercontactdetailsoverride": "1",
    "orderreference": "MyOrder123",
    "paymenttypedescription": "MOBILEPAY",
    "requesttypedescriptions": ["ORDER","THREEDQUERY","AUTH"],
    "returnurl": "https://example.com/successpayment",
    "sitereference": "test_site12345"
  }]
}'

{
  "alias": "webservices@example.com",
  "request": [{
    "accounttypedescription":"ECOM",
    "baseamount":"1050",
    "billingcontactdetailsoverride":"1",
    "cancelurl":"https://example.com/cancelpayment",
    "currencyiso3a":"DKK",
    "customercontactdetailsoverride":"1",
    "orderreference":"MyOrder123",
    "paymenttypedescription":"MOBILEPAY",
    "requesttypedescriptions":["ORDER","THREEDQUERY","AUTH"],
    "returnurl":"https://example.com/successpayment",
    "sitereference":"test_site12345"
  }],
  "version": "1.00"
}

<requestblock version="3.67">
  <alias>webservices@example.com</alias>
  <request type="ORDER">
    <billing>
      <amount currencycode="DKK">1050</amount>
      <contactdetailsoverride>1</contactdetailsoverride>
      <payment type="MOBILEPAY"/>
    </billing>
    <customer>
      <contactdetailsoverride>1</contactdetailsoverride>
    </customer>
    <merchant>
      <cancelurl>https://example.com/cancelpayment</cancelurl>
      <returnurl>https://example.com/successpayment</returnurl>
    </merchant>
    <operation>
      <accounttypedescription>ECOM</accounttypedescription>
      <sitereference>test_site12345</sitereference>
    </operation>
  </request>
  <request type="THREEDQUERY"/>
  <request type="AUTH"/>
</requestblock>

Replace <DOMAIN> with a supported domain. Click here for a full list.

Field specification

Field	Format	Description
accounttypedescription XPath: /operation/accounttypedescription	Alpha (20)	Only “ECOM” (e-commerce) is supported.
baseamount XPath: /billing/amount	Numeric (13)	The amount of the transaction in base units, with no commas or decimal points, so €10 is submitted as 1000. This value must be greater than zero. (Max length may vary depending on your acquiring bank – Contact your bank for further info)
cancelurl XPath: /merchant/cancelurl	URL (2048)	The URL that the customer will be returned to, if the customer cancels the transaction after they have been redirected to the redirecturl.
currencyiso3a XPath: /billing/amount/@currencycode	Alpha (3)	The currency that the transaction will be processed in (in ISO3A format). For a list of currency codes supported by MobilePay, refer to the list found at the top of this page.
paymenttypedescription XPath: /billing/payment/@type	Alpha (20)	The value submitted must be “MOBILEPAY”.
requesttypedescriptions XPath: /@type	Alpha (20)	You must submit the array: ["ORDER","THREEDQUERY","AUTH"] (The format required differs for XML requests. Please refer to the example above)
returnurl XPath: /merchant/returnurl	URL (2048)	The URL that the customer will be returned to following a successful authorisation.
sitereference XPath: /operation/sitereference	Alphanumeric & underscore (50)	The site reference relates to your individual account which you received on setup. If you do not know your site reference, please contact our Support Team.
billingcontactdetailsoverride XPath: /billing/contactdetailsoverride	Numeric (1)	"0" – Uses billing details submitted in the ORDER request (this is the default behaviour if billingcontactdetailsoverride not submitted). "1" – Uses billing details from the customer’s wallet. Value 1 cannot be submitted if no physical goods are being delivered.
billingcounty XPath: /billing/county	Alphanumeric including symbols (127)	The county entered for the customer’s billing address. If billingcontactdetailsoverride=1, this value will be overridden by value in customer's wallet.
billingcountryiso2a XPath: /billing/country	Alpha (2)	The country for the customer’s billing address. This will need to be in ISO2A format. For a list of country codes supported by MobilePay, refer to the list found at the top of this page. If billingcontactdetailsoverride=1, this value will be overridden by value in customer's wallet.
billingemail XPath: /billing/email	Email (255)	The customer’s billing email address. Maximum length of 255 (maximum of 64 characters before the ”@” symbol). If billingcontactdetailsoverride=1, this value will be overridden by value in customer's wallet.
billingfirstname XPath: /billing/name/first	Alphanumeric including symbols (127)	The customer’s billing first name. If billingcontactdetailsoverride=1, this value will be overridden by value in customer's wallet.
billinglastname XPath: /billing/name/last	Alphanumeric including symbols (127)	The customer’s billing last name. If billingcontactdetailsoverride=1, this value will be overridden by value in customer's wallet.
billingmiddlename XPath: /billing/name/middle	Alphanumeric including symbols (127)	The customer’s billing middle name(s). If billingcontactdetailsoverride=1, this value will be overridden by value in customer's wallet.
billingpostcode XPath: /billing/postcode	Alphanumeric (25)	The billing postcode or ZIP code. This must be a valid postcode/ZIP code for the billingcountryiso2a submitted. If billingcontactdetailsoverride=1, this value will be overridden by value in customer's wallet.
billingprefixname XPath: /billing/name/prefix	Alphanumeric including symbols (25)	The prefix of the customer’s billing name (e.g. Mr, Miss, Dr). If billingcontactdetailsoverride=1, this value will be overridden by value in customer's wallet.
billingpremise XPath: /billing/premise	Alphanumeric including symbols (25)	The house number or first line of the customer’s billing address. If billingcontactdetailsoverride=1, this value will be overridden by value in customer's wallet.
billingstreet XPath: /billing/street	Alphanumeric including symbols (127)	The street entered for the customer’s billing address. If billingcontactdetailsoverride=1, this value will be overridden by value in customer's wallet.
billingsuffixname XPath: /billing/name/suffix	Alphanumeric including symbols (25)	The suffix of the customer’s billing name (e.g. Bsc). If billingcontactdetailsoverride=1, this value will be overridden by value in customer's wallet.
billingtelephone XPath: /billing/telephone	Alphanumeric including symbols (20)	The customer’s telephone number. Valid characters: Numbers 0-9 Spaces Special characters: + – ( ) If billingcontactdetailsoverride=1, this value will be overridden by value in customer's wallet.
billingtelephonetype XPath: /billing/telephone/@type	Char (1)	The type of telephone number. The options available are: H = Home M = Mobile W = Work If billingcontactdetailsoverride=1, this value will be overridden by value in customer's wallet.
billingtown XPath: /billing/town	Alphanumeric including symbols (127)	The town entered for the customer’s billing address. If billingcontactdetailsoverride=1, this value will be overridden by value in customer's wallet.
customercontactdetailsoverride XPath: /customer/contactdetailsoverride	Numeric (1)	"0" – Uses delivery details submitted in the ORDER request (this is the default behaviour if customercontactdetailsoverride not submitted). "1" – Uses delivery details from the customer’s wallet. Value 1 cannot be submitted if no physical goods are being delivered.
customercounty XPath: /customer/county	Alphanumeric including symbols (127)	The county entered for the delivery address. If customercontactdetailsoverride=1, this value will be overridden by value in customer's wallet.
customercountryiso2a XPath: /customer/country	Alpha (2)	The country for the delivery address. This will need to be in ISO2A format. If customercontactdetailsoverride=1, this value will be overridden by value in customer's wallet.
customeremail XPath: /customer/email	Email (255)	The delivery email address. Maximum length of 255 (maximum of 64 characters before the ”@” symbol). If customercontactdetailsoverride=1, this value will be overridden by value in customer's wallet.
customerfirstname XPath: /customer/name/first	Alphanumeric including symbols (127)	The delivery first name. If customercontactdetailsoverride=1, this value will be overridden by value in customer's wallet.
customerlastname XPath: /customer/name/last	Alphanumeric including symbols (127)	The delivery last name. If customercontactdetailsoverride=1, this value will be overridden by value in customer's wallet.
customermiddlename XPath: /customer/name/middle	Alphanumeric including symbols (127)	The delivery middle name(s). If customercontactdetailsoverride=1, this value will be overridden by value in customer's wallet.
customerpostcode XPath: /customer/postcode	Alphanumeric (25)	The delivery postcode or ZIP code. This must be a valid postcode/ZIP code for the customercountryiso2a submitted. If customercontactdetailsoverride=1, this value will be overridden by value in customer's wallet.
customerprefixname XPath: /customer/name/prefix	Alphanumeric including symbols (25)	The prefix of the delivery name (e.g. Mr, Miss, Dr). If customercontactdetailsoverride=1, this value will be overridden by value in customer's wallet.
customerpremise XPath: /customer/premise	Alphanumeric including symbols (25)	The house number or first line of the delivery address. If customercontactdetailsoverride=1, this value will be overridden by value in customer's wallet.
customerstreet XPath: /customer/street	Alphanumeric including symbols (127)	The street entered for the delivery address. If customercontactdetailsoverride=1, this value will be overridden by value in customer's wallet.
customersuffixname XPath: /customer/name/suffix	Alphanumeric including symbols (25)	The suffix of the delivery name (e.g. Bsc). If customercontactdetailsoverride=1, this value will be overridden by value in customer's wallet.
customertelephone XPath: /customer/telephone	Alphanumeric including symbols (20)	The delivery telephone number. Valid characters: Numbers 0-9 Spaces Special characters: + – ( ) If customercontactdetailsoverride=1, this value will be overridden by value in customer's wallet.
customertelephonetype XPath: /customer/telephone/@type	Char (1)	The type of telephone number. The options available are: H = Home M = Mobile W = Work If customercontactdetailsoverride=1, this value will be overridden by value in customer's wallet.
customertown XPath: /customer/town	Alphanumeric including symbols (127)	The town entered for the delivery address. If customercontactdetailsoverride=1, this value will be overridden by value in customer's wallet.
orderreference XPath: /merchant/orderreference	Alphanumeric including symbols (25) Recommended length 25 characters or less (exact length dependent on acquiring bank). Failure to adhere to this requirement may result in the text being truncated in the transaction.	Your unique order reference that can be stored on the Trust Payments system.

ORDER response

{
u'requestreference': u'An3ug1kap',
u'version': u'1.00',
u'responses': [{
u'accounttypedescription': u'ECOM',
u'errorcode': u'0',
u'errormessage': u'Ok',
u'livestatus': u'0',
u'operatorname': u'webservices@example.com',
u'orderreference': u'MyOrder123',
u'paymenttypedescription': u'MOBILEPAY',
u'redirecturl': u'https://example.com',
u'requesttypedescription': u'ORDER',
u'settleduedate': u'2022-08-24',
u'settlestatus': u'0',
u'transactionreference': u'30-101-155',
u'transactionstartedtimestamp': u'2022-08-24 15:20:47'
}]
}

array(3) {
  ["requestreference"] => string(9) "A0345jmuw"
  ["version"] => string(4) "1.00"
  ["responses"] => array(1) {
    [0]=> array(13) {
      ["accounttypedescription"] => string(4) "ECOM"
      ["errorcode"] => string(1) "0"
      ["errormessage"] => string(2) "Ok"
      ["livestatus"] => string(1) "0"
      ["operatorname"] => string(23) "webservices@example.com"
      ["orderreference"] => string(10) "MyOrder123"
      ["paymenttypedescription"] => string(9) "MOBILEPAY"
      ["redirecturl"] => string(19) "https://example.com"
      ["requesttypedescription"] => string(5) "ORDER"
      ["settleduedate"] => string(10) "2022-08-24"
      ["settlestatus"] => string(1) "0"
      ["transactionreference"] => string(10) "30-101-155"
      ["transactionstartedtimestamp"] => string(19) "2022-08-24 15:20:47"
    }
  }
}

{
  "requestreference":"W30-jc1pdcm4",
  "response":[{
    "accounttypedescription":"ECOM",
    "errorcode":"0",
    "errormessage":"Ok",
    "livestatus":"0",
    "operatorname":"webservices@example.com",
    "orderreference":"MyOrder123",
    "paymenttypedescription":"MOBILEPAY",
    "redirecturl":"https://example.com",
    "requesttypedescription":"ORDER",
    "settleduedate":"2022-08-24",
    "settlestatus":"0",
    "transactionreference":"30-101-155",
    "transactionstartedtimestamp":"2022-08-24 15:20:47"
  }],
  "secrand": "SjBuz3MmMGu",
  "version": "1.00"
}

<responseblock version="3.67">
  <requestreference>Xd4nk260v</requestreference>
  <response type="ORDER">
    <billing>
      <payment type="MOBILEPAY"/>
    </billing>
    <error>
      <message>Ok</message>
      <code>0</code>
    </error>
    <live>0</live>
    <merchant>
      <orderreference>MyOrder123</orderreference>
      <operatorname>webservices@example.com</operatorname>
    </merchant>
    <operation>
      <accounttypedescription>ECOM</accounttypedescription>
    </operation>
    <other>
      <redirecturl>https://example.com</redirecturl>
    </other>
    <settlement>
      <settleduedate>2022-08-24</settleduedate>
      <settlestatus>0</settlestatus>
    </settlement>
    <transactionreference>30-101-155</transactionreference>
    <timestamp>2022-08-24 15:20:47</timestamp>
  </response>
  <secrand>Z1W</secrand>
</responseblock>

Field specification

Field	Format	Description
accounttypedescription XPath: /operation/accounttypedescription	Alpha (20)	The value returned is “ECOM”.
errorcode XPath: /error/code	Numeric (1-5)	The error code should be used to determine if the request was successful or not. If the error code is “0” then the transaction was successful. If the error code is not “0” then the transaction was not successful. Click here for a full list of errorcode and message values.
errormessage XPath: /error/message	Alphanumeric (255)	This is the corresponding message to the above code. Click here for a full list of errorcode and message values.
livestatus XPath: /live	Numeric (1)	0 – Transaction processed using a test account. 1 – Transaction processed using a live account.
operatorname XPath: /merchant/operatorname	Alphanumeric (255)	The value of this field contains the name of the user that processed the request.
orderreference XPath: /merchant/orderreference	Alphanumeric including symbols (25)	The unique order reference stored on the Trust Payments system.
paymenttypedescription XPath: /billing/payment/@type	Alpha (20)	This value returned is “MOBILEPAY”.
redirecturl XPath: /other/redirecturl	URL (255)	Redirect the customer’s browser to this URL to allow them to complete the payment on MobilePay's hosted pages. You will need to remove any URL encoding before redirecting the customer's browser to ensure special characters are formatted correctly.
requesttypedescription XPath: /@type	Alpha (20)	The value returned is “ORDER”.
settleduedate XPath: /settlement/settleduedate	Date YYYY-MM-DD	The date on which the transaction will be settled.
settlestatus XPath: /settlement/settlestatus	Numeric (3)	This allows you to determine the status of the payment. Refer to the Handling the response section below for information on how to best interpret this field.
transactionreference XPath: /transactionreference	Alphanumeric including hyphens (25)	A unique reference for the transaction assigned by Trust Payments.
transactionstartedtimestamp XPath: /timestamp	The time the transaction was processed.	The time the request was processed.
errordata XPath: /error/data	Alphanumeric (255)	Additional information to help troubleshoot the error. Only returned if there has been an error.

2. Redirect to MobilePay

After successfully submitting the first initialisation request as documented above, your system will be returned a redirecturl in the response. Your system will need to remove any URL encoding from the URL (to ensure special characters are formatted correctly), and then redirect the customer’s browser to this modified URL. The browser will display a page hosted by MobilePay where the customer will be prompted for their phone number to continue.

Testing notes

Before you get started, you will need to install the MobilePay testing app to a smartphone in your possession and sign in using one of the test mobile phone numbers provided by MobilePay. Click here for further details (link to external site). Using these test credentials and the app provided, you can perform test MobilePay transactions using your test site reference. When testing with MobilePay, your browser will display the test environment hosted by MobilePay (as shown below).

After signing in, a 5 minute countdown is displayed in the browser. The customer will have 5 minutes to open the MobilePay app on their smartphone to approve the pending payment. They will be presented with the full transaction amount, the name of your shop and an option to choose their preferred card for payment.

When testing, these card numbers will be test cards provided by MobilePay for testing purposes.

The customer swipes right on the "Authorise" slider to approve the transaction.

EMV 3-D Secure

It is at this point in the checkout process that EMV 3-D Secure is performed to authenticate the transaction.

About 3-D Secure

3-D Secure is a form of Strong Customer Authentication (SCA) designed to reduce fraud and chargebacks during e-commerce transactions. It allows card issuers to provide an extra level of protection, by authenticating cardholders at the point of sale. Click here to learn more.

For enhanced security, the card issuer may force step-up authentication, where the customer is required to take additional steps to verify their identity (e.g. reviewing and approving the order in their banking app). If this occurs, the amount of time the customer is allowed to complete the transaction is increased to 20 minutes.

Otherwise, the transaction will be treated as "frictionless" and the customer will not be interrupted.

If the transaction is ultimately successful, the app will display an "Authorised" response. Meanwhile in the browser, the customer will be redirected to the returnurl, a holding page hosted by the merchant that displays a "Please wait" message. This redirect includes the fields transactionreference, ordertransactionreference and signature.

If there has been a problem with the payment, the browser is redirected to the cancelurl, a page hosted by the merchant that displays an error to the customer.

3. Verify Auth Response

Handling the authorisation notification

Your system will need to listen for URL notifications that were configured to be sent following authorisation of MobilePay transactions. You will need to check the contents of each notification received and respond accordingly by following the processes outlined in our URL notifications documentation. In particular, you will need to look at the updated settlestatus value:

If the settlestatus is “0”, “1” or “10”, the payment has been authorised and you are not required to take further action at this time. However, values of “2” or “3” indicate funds are not scheduled for settlement (suspended and cancelled, respectively).

VERIFYAUTHRESPONSE request

To verify that the payment was processed successfully while the customer was using the MobilePay app, you will need to submit a VERIFYAUTHRESPONSE request to Trust Payments. This must include:

The parenttransactionreference, which is the transactionreference returned in the ORDER response;
And the verifystring, which is an object constructed from the transactionreference, ordertransactionreference and signature field values returned in the redirect, like so:
```
"verifystring":"{\"transactionreference\":\"30-17-111\",\"ordertransactionreference\":\"30-101-155\",\"signature\":\"3b48b7777\"}"
```

#!/usr/bin/python
import securetrading

stconfig = securetrading.Config()
stconfig.username = "webservices@example.com"
stconfig.password = "Password1^"
st = securetrading.Api(stconfig)

verifyAuthResponse = {
  "parenttransactionreference": "30-101-155",
  "requesttypedescriptions": ["VERIFYAUTHRESPONSE"],
  "sitereference": "test_site12345",
  "verifystring": "{\"transactionreference\":\"30-17-111\",\"ordertransactionreference\":\"30-101-155\",\"signature\":\"3b48b7777\"}"
}

strequest = securetrading.Request()
strequest.update(verifyAuthResponse)
stresponse = st.process(strequest) #stresponse contains the transaction response

<?php

if (!($autoload = realpath(__DIR__ . '/../../../autoload.php')) && !($autoload = realpath(__DIR__ . '/../vendor/autoload.php'))) {
throw new Exception('Composer autoloader file could not be found.');
}
require_once($autoload);

$configData = array(
  'username' => 'webservices@example.com',
  'password' => 'Password1^'
);

$requestData = array(
  'parenttransactionreference' => '30-101-155',
  'requesttypedescriptions' => array('VERIFYAUTHRESPONSE'),
  'sitereference' => 'test_site12345',
  'verifystring' => '{\"transactionreference\":\"30-17-111\",\"ordertransactionreference\":\"30-101-155\",\"signature\":\"3b48b7777\"}'
);

$api = \Securetrading\api($configData);
$response = $api->process($requestData);
var_dump($response->toArray());

?>

curl --user webservices@example.com:Password1^ <DOMAIN>/json/ -H "Content-type: application/json" -H "Accept: application/json" -X POST -d '{
  "alias": "webservices@example.com",
  "version": "1.00",
  "request": [{
    "parenttransactionreference": "30-101-155",
    "requesttypedescriptions": ["VERIFYAUTHRESPONSE"],
    "sitereference": "test_site12345",
    "verifystring": "{\"transactionreference\":\"30-17-111\",\"ordertransactionreference\":\"30-101-155\",\"signature\":\"3b48b7777\"}"
  }]
}'

{
  "alias":"webservices@example.com",
  "version":"1.00",
  "request":[{
    "parenttransactionreference":"30-101-155",
    "requesttypedescriptions":["VERIFYAUTHRESPONSE"],
    "sitereference":"test_site12345",
    "verifystring":"{\"transactionreference\":\"30-17-111\",\"ordertransactionreference\":\"30-101-155\",\"signature\":\"3b48b7777\"}"
  }]
}

<requestblock version="3.67">
  <alias>webservices@example.com</alias>
  <request type="VERIFYAUTHRESPONSE">
    <operation>
      <parenttransactionreference>30-101-155</parenttransactionreference>
      <sitereference>test_site12345</sitereference>
      <verifystring>{\"transactionreference\":\"30-17-111\",\"ordertransactionreference\":\"30-101-155\",\"signature\":\"3b48b7777\"}</verifystring>
    </operation>
  </request>
</requestblock>

Replace <DOMAIN> with a supported domain. Click here for a full list.

VERIFYAUTHRESPONSE request field specification

Field	Format	Description
parenttransactionreference XPath: /operation/parenttransactionreference	Alphanumeric & hyphens (25)	The transactionreference returned in the ORDER response.
requesttypedescriptions XPath: /@type	Alpha (20)	The value submitted must be “VERIFYAUTHRESPONSE”.
sitereference XPath: /operation/sitereference	Alphanumeric & underscore (50)	Identifies your site on the Trust Payments system. If you do not know your site reference, please contact our Support Team.
verifystring XPath: /operation/verifystring	Object	An object constructed from the transactionreference, ordertransactionreference and signature field values returned in the redirect. The value of the ordertransactionreference field should match the transactionreference returned in the ORDER response.

VERIFYAUTHRESPONSE response

The information returned in the VERIFYAUTHRESPONSE response should be used to determine the message displayed to the customer following their payment attempt:

{
u'requestreference': u'An3ug1kap',
u'version': u'1.00',
u'response': [{
u'errorcode': u'0',
u'errormessage': u'Ok',
u'requesttypedescription': u'VERIFYAUTHRESPONSE',
u'transactionstartedtimestamp': u'2022-08-24 15:20:47',
}]
}

array(3) {
  ["requestreference"] => string(9) "A0345jmuw"
  ["version"] => string(4) "1.00"
  ["response"] => array(1) {
    [0]=> array(4) {
      ["errorcode"] => string(1) "0"
      ["errormessage"] => string(2) "Ok"
      ["requesttypedescription"] => string(18) "VERIFYAUTHRESPONSE"
      ["transactionstartedtimestamp"] => string(19) "2022-08-24 15:20:47"
    }
  }
}

{
  "requestreference":"W23-fjgvn3d8",
  "version":"1.00",
  "response":[{
    "errorcode":"0",
    "errormessage":"Ok",
    "requesttypedescription":"VERIFYAUTHRESPONSE",
    "transactionstartedtimestamp":"2022-08-24 15:20:47"
  }],
  "secrand":"zO9"
}

<responseblock version="3.67">
  <requestreference>Xd4nk260v</requestreference>
  <response type="VERIFYAUTHRESPONSE">
    <error>
      <code>0</code>
      <message>Ok</message>
    </error>
    <timestamp>2022-08-24 15:20:47</timestamp>
  </response>
  <secrand>Z1W</secrand>
</responseblock>

VERIFYAUTHRESPONSE response field specification

Field	Format	Description
errorcode XPath: /error/code	Numeric (1-5)	The error code should be used to determine if the request was successful or not. If the error code is “0” then the transaction was successful. If the error code is not “0” then the transaction was not successful. Click here for a full list of errorcode and message values.
errormessage XPath: /error/message	Alphanumeric (255)	This is the corresponding message to the above code. Click here for a full list of errorcode and message values.
requesttypedescription XPath: /@type	Alpha (20)	The value returned is “VERIFYAUTHRESPONSE”.
transactionstartedtimestamp XPath: /timestamp	Date time YYYY-MM-DD hh:mm:ss	The time the request was processed.

4. Payment completion

You will need to use the value of the errorcode returned in the VERIFYAUTHRESPONSE response to help determine the appropriate response message to be displayed in the customer's browser, which states the outcome of the payment (e.g. success / error).

If you receive the authorisation URL notification with errorcode=0 and the VERIFYAUTHRESPONSE response also includes errorcode=0, display a success message.
If you receive the authorisation URL notification where errorcode returned is NOT 0 or the VERIFYAUTHRESPONSE response includes errorcode that is NOT 0, display an error message and allow the customer to retry, or provide the customer with alternative methods of payment.

Once a payment has been authorised, funds will be settled into your bank account following the same process as that used for standard card transactions. Click here for further information.

Settlement notification

Before you begin testing, we recommend that you also configure URL notifications that are processed on settlement. You will need to contact our Support Team and request a new rule is configured to be processed on settlement of MobilePay transactions.

We recommend including the following fields in your settlement notification:

Settle Status (settlestatus)
Settled Timestamp (settledtimestamp)
Site Reference (sitereference)
Transaction Reference (transactionreference)

You will need to check the contents of each notification received and respond accordingly by following the processes outlined in our URL notifications documentation. In particular, you will need to look at the updated settlestatus value:

If the settlestatus has been updated to “100”, this indicates that the funds have been settled. Alternatively, if this has been updated to “3”, this indicates there has been a problem and the payment was subsequently cancelled.

Testing

You will need to test your solution before you can begin processing live payments. Test transactions are processed through your test Site Reference. When performing test transactions, the redirect URL returned in the ORDER response will redirect your browser to the MobilePay testing environment to simulate a payment. During a test payment session, you will need to approve the transaction using the MobilePay testing app installed on your smartphone (click here to scroll up to where we explain this in greater detail). This simulates the steps the customer would perform in the production environment to complete a MobilePay transaction.

Cancelling/refunding MobilePay transactions

Prior to settlement, you can cancel a pending MobilePay transaction.

The ability to cancel MobilePay transactions is supported for merchants with a Trust Payments acquiring account. If you are using a different acquiring bank, you will need to contact our Support Team to check this feature is supported before proceeding.

Following settlement, you can instead refund a MobilePay transaction. Refunds for MobilePay follow the standard settlement flow for card transactions, with funds typically returning to the customer within 24 hours.

To perform a cancellation or refund, you will need the unique transactionreference that Trust Payments assigns to identify the AUTH request. You can find this value included on the GET request as the customer is redirected back from MobilePay's servers, but it can also be retrieved from the authorisation URL notification described earlier (if configured).

The transactionreference needed is the value returned on the AUTH response, NOT the ORDER response.
- To cancel a MobilePay transaction, you will need to submit a TRANSACTIONUPDATE request, including the transactionreference and an update of settlestatus=3, and handle the response accordingly. Click here to learn more.
- To refund a MobilePay transaction, you will instead need to submit a REFUND response, including the transactionreference, and handle the response accordingly. Click here to learn more.

Requirements

You cannot refund a payment until the AUTH has been settled (settlestatus is “100”).
You cannot refund a greater amount than was originally settled.

Further reading on this topic