MobilePay
Overview
Checkout can be used to accept MobilePay payments.
Integration options supported: Hosted payment page (HPP) or IFRAME.
This guide requires familiarity with Accepting payments.
Integrate MobilePay via Checkout
| Parameters | Type | Required | Description |
|---|---|---|---|
| currency_code | String | Yes | Supported currencies: EUR, NOK, SEK, DKK |
| amount | Integer | Yes | Transaction amount |
| payment_contract_id | String | Yes | Payment Provider Contract ID obtained from Verifone Central interface |
| customer | String | Yes | Required only if threed_secure contract is applied and the transaction needs 3DS validation |
| app_phone_number | String | No | Phone number of the shopper. Max 18 characters. |
| dynamic_descriptor | String | No |
Short text to be displayed on the bank statement of the cardholder. Support varies per Payment Contract (<= 25 characters) |
| capture_now | Boolean | No | Used for separate authorization and capture |
| card | Object | No | Payment configuration needed in case of 3DS or Authorization type |
Authorization and capture
MobilePay transactions through the Checkout can be used to do a sale (capture_now = true) or to authorize without capturing immediately (capture_now = false). An authorized payment reserves the money and allows you to capture the funds at a later stage.
Sending a checkout request using MobilePay payment method:
{
"currency_code": "EUR",
"entity_id": "87db5a22-9e9e-4b71-9c61-6fb4f6628833",
"customer": "4b32a5ef-dd84-45ba-81ae-f676ef032580",
"configurations": {
"mobile_pay": {
"dynamic_descriptor": "Demo Description",
"capture_now": false,
"payment_contract_id": "e0a66743-fae4-4e59-a052-81f4729be299",
"card": {
"sca_compliance_level": "WALLET",
"authorization_type": "FINAL_AUTH",
"threed_secure": {
"enabled": true,
"threeds_contract_id": "86611b72-a870-428a-b436-8bee474e7132",
"total_items": "01",
"transaction_mode": "S"
}
}
}
},
"amount": 850,
"merchant_reference": "TEST 123",
"return_url": "https://test.url.com",
"interaction_type": "HPP"
}Special conditions during purchase experience
1. The user initiates the purchase in a browser that is not the default one on their phone.
If a user initiates the purchase in a browser that is not the default one on their phone, and then they switch to MobilePay and accept the payment, the app will redirect to the merchant's URL which will always open in the default browser, even if it is not the same browser where the payment was initiated.
The MobilePay app cannot decide which browser is used, or redirect back to the first browser if that is not the default one.
In this case, as a merchant, you cannot rely on session objects and only rely on the data in the Redirect to show a confirmation page.
2. The user breaks the flow and does not return at all by closing the browser.
The user initiates the purchase and switches to MobilePay to accept the payment. Before the switch to merchant URL, the user closes MobilePay and/or browser.
The payment is successful and as a merchant you should complete the order based on the information from callbacks.
Handling responses
Whenever a card payment is processed via the Checkout, the responses events would contain additional fields specific to card payments in the details object.
Example of successful checkout via the Checkout:
[
{
"type": "TRANSACTION_INITIATED",
"id": "e66df672-385a-43fe-812a-f4866135f977",
"timestamp": "2021-10-14T11:37:17.533Z",
"details": {
"amount": 850,
"blocked": false,
"created_at": "2021-10-14T11:37:16.509608Z",
"customer": "4b32a5ef-dd84-45ba-81ae-f676ef032580",
"details": {
"auto_capture": false
},
"merchant_reference": "80dc4e7b-e90e-4f8d-bdfe-9c51d2ccdbcb",
"status": "INITIATED",
"created_by": "b2ee94dd-cfbd-4cea-8c4b-d026ad79eac8",
"geo_location": [
20.0063,
77.006
],
"country_code": "NL",
"id": "c0ac5d4d-c958-41d4-9b8f-0edf91e08d78",
"redirect_url": "https://sandprod-products.mobilepay.dk/remote-website/index.html?page=request&id=9bd2daa5-b4f4-4978-9e1f-6209c6bacb8e",
"processor": "NETS",
"payment_product": "CARD",
"payment_product_type": "Unknown"
}
},
{
"type": "TRANSACTION_SUCCESS",
"id": "a545e11f-1fa5-4a33-bdb0-acfa1ec4334d",
"timestamp": "2021-10-14T11:38:42.721Z",
"details": {
"id": "c0ac5d4d-c958-41d4-9b8f-0edf91e08d78",
"processor_reference": "141138001504",
"status": "AUTHORISED",
"authorization_code": "061984",
"cvv_result": null,
"details": {
"mid": "746025"
},
"reason_code": "0000",
"rrn": "141138001504",
"stan": "1504",
"additional_data": {
"acquirer_response_code": "00",
"initiator_trace_id": "1504"
}
}
}
]
{
"id": "14f073a3-a45e-4991-ba56-9eeff1ea601c",
"events": [
{
"type": "VISITED",
"id": "32caff1f-370b-4ed0-bbc5-a31600f1ad74",
"timestamp": "2022-11-18T10:37:30.353Z"
},
{
"type": "SUBMITTED",
"id": "25d7f75f-65df-4d09-8a6b-1a04ef7b2249",
"timestamp": "2022-11-18T10:37:38.913Z"
},
{
"type": "TRANSACTION_INITIATED",
"id": "8bac9557-2e9e-4d4d-9c2b-c9be10789329",
"timestamp": "2022-11-18T10:37:40.529Z",
"details": {
"amount": 5000,
"blocked": false,
"created_at": "2022-11-18T10:37:39.819682Z",
"customer": "deebacec-cd75-4ce5-9641-bfc40de5710d",
"details": {
"auto_capture": false
},
"merchant_reference": "20021165432",
"status": "INITIATED",
"created_by": "0bc5a545-6bbf-49b1-a1b8-ef533f47cf71",
"geo_location": [
12.9719,
77.5937
],
"city": "Bengaluru",
"country_code": "FI",
"id": "3533b6de-8bdb-4e03-a7ce-4851218af114",
"redirect_url": "https://sandprod-products.mobilepay.dk/remote-website/index.html?page=request&id=fe1eecc2-9dde-42a7-b368-6c3122064370",
"processor": "INTERCARD",
"payment_product": "CARD",
"payment_product_type": "Unknown"
}
}- Note: To ensure that the redirection request was not tampered with, always check that the
transaction_idreceived as query parameter in the redirection matches thetransaction_idproperty of the retrieved Checkout. If those are not matching, this is indication of either an incorrect integration, that the redirection to yourreturn_urldid not originate from Verifone, ortransaction_idwas tampered with. - You can now store the
transaction_idvalue together with the order1234in your system to link the two together.
Scenarios
The table below describes the different outcomes of a Checkout. A full list error codes are available.
| Description | Result | Merchant action |
|---|---|---|
| Failed transaction* | Redirect: checkout_id={checkout_id} & transaction_id={transaction_id} & errorCode=123 |
Unsuccessful payment (technical reason), do not display order confirmation |
| Successful transaction | Redirect: checkout_id={checkout_id} & transaction_id={transaction_id} |
Display order confirmation |
| Customer visits the URL of an already completed Checkout | Redirect: checkout_id={checkout_id} & errorCode=168 |
Display corresponding message to the customer. Checkout is completed whenever there was a single successful payment processed through it. |
| Customer visits the URL of an expired Checkout | Redirect: checkout_id={checkout_id} & errorCode=169 |
Display corresponding message to the customer. Checkout is expired whenever the expiry_time is reached. |
| Customer visits the URL of a Checkout which has reached the maximum of failed payment attempts | Redirect: checkout_id={checkout_id} & errorCode=165 |
Display corresponding message to the customer. Payments through a single Checkout can be attempted up to three times unsuccessfully. |
| Form validation errors / Other service failures on the Checkout page | Displays error alert to Customer on the page | Customer is prompted to correct their form input and retry the payment or try using an alternate card or payment method |
*Failed transaction - Depending on which step in the payment process failed, the transaction_id might not always be present as the query parameter.
