Apple Pay Browser Payments

Google Pay enables fast, simple and convenient payment experiences for millions of customers globally using a compatible registered device or browser. By calling on Google Pay APIs, you can reduce payment frictions for your customers by allowing them to check out without having to enter any payment information themselves.

To get browser-based Apple Pay running with Tyro eCommerce functionality please follow these Tyro-specific instructions.

How to use this guide

This guide walks you through the steps required to implement the Apple Pay browser payment experience and includes:

The end-to-end workflow to successfully process a Apple Pay browser payment transaction, Tyro eCommerce payment gateway specific code and instructions, Guidance on when and how to refer to the Apple Pay developer documentation. Apple Pay’s own developer documentation complements this guide and must be used in conjunction with these implementation instructions and whenever you are prompted with a link.

Apple’s own term for their browser-based functionality is “Apple Pay on the Web”. You can find full information about it here.

Workflow

Apple Pay implementation

  • The Apple Pay library is needed to create an Apple Pay button.
  • The transaction amount, merchant details and token options are configured.
  • The user will select their stored card or enter new details.
  • The payment token (DPAN) is then returned by Apple Pay

Tyro Gateway implemenation

  • The payment token is sent from the browser to your merchant server.
  • Transaction request is sent to Tyro with payment token included.
  • Transaction result is sent back eg. APPROVED or DECLINED.

Prerequisites

Before you implement Apple Pay digital wallet and start sending requests, you will have to perform some initial integration steps: creating a merchant ID, configuring your profile correctly, etc.

In order to use Apple Pay JS you will need the following accounts:

  • You must sign up with Apple and create your merchant ID here.

  • Your merchant profile on the gateway must be enabled for Device Payments by Tyro.

  • All webstore pages served to the customer must use HTTPS

  • The domain and all subdomains must have valid SSL certificates and be registered with Apple.

  • The merchant server must support the Transport Layer Security (TLS) 1.2 protocol and one of the cipher suites listed by Apple.

  • Create a Payment Processing Certificate.

  • Upload your Payment Process Certificate to the Tyro eCommerce portal (Merchant Administrator)

  • Create a Merchant identity certificate

For a video showing the configuration steps, see: Configuring Your Developer Account for Apple Pay.

Implementing Apple Pay button and retrieving token

Use the Apple Pay tutorial (available here) with Apple Pay JS to complete your integration.

The following steps are necessary for integrating with Apple Pay JS API:

  1. Show Apple Pay Web button

  2. Merchant Validation

  3. Display Payment Sheet

  4. Capturing the encrypted PaymentToken

Merchant Validation

After the user clicks the Buy with Apple Pay button, you must create an Apple Pay session with the necessary order data.

After the session is initiated, define the session.onvalidatemerchant method from Apple JS API. In this method, do a server-to-server call on a validationURL (this will be generated from Safari browser) with a payload (an example is below).

{
        "merchantIdentifier": "B7...D8",
        "domainName:"www.xxx",
        "displayName":"merchant.com.xxxxxxxxx"
}

After the success message comes back, use this response on session.completeMerchantValidation(response).

Display Apple Pay Payment Sheet on Browser

After the merchant validation is completed, the Apple payment sheet will be shown to the customer. Below are screenshots and a code example.

Apple Pay Payment Sheet (Web) Code Example

<script type="text/javascript">

  function showApplePayButton()

  {
  document.getElementsByClassName("apple-pay-button").style.visibility = "visible";

  }

  document.addEventListener('DOMContentLoaded', () => {
      if (window.ApplePaySession) {
          if (ApplePaySession.canMakePayments) {
          alert("going to show button")

              showApplePayButton();

          }

      }

  });

  function applePayButtonClicked()

  {
  alert("apple pay begins")

  var request = {
   countryCode: 'AU',

   currencyCode: 'AUD',

   supportedNetworks: ['visa', 'masterCard'],

   merchantCapabilities: ['supports3DS'],

   total: { label: 'Tyro Test', amount: '1.00' },

  }

  debugger

  var session = new ApplePaySession(2, request);

  debugger

   session.begin();

  }

  </script>

Capturing the encrypted PaymentToken

After the (Apple) merchant is validated and touchID is validated, the next step is to capture the payment object (the encrypted token, as in the example below) from the Apple Pay event and pass it to the Tyro Payment Gateway to process the Payment.

Apple sends a lot of transaction data, but for payment processing purposes, only the paymentData information is relevant.

Extract the data and send it to Tyro.

Tyro will use it to do an Authorization or Pay call within the Payment Gateway - example below:

  "paymentData": {
        "version": "EC_v1",
        "data": "cVSiVUsQHFWiJ5jUBKOozrSRw1s1jRnKhjfC5/Lq7zsr7nXCVqYRIdi3RJoOBGz4kNCOoCXs8xWXrLpCppFxw1HOZBdIxlWoJ0BJLlj+jgs775f6MFs6AE7i64R0oRuw03PJxTJ9wOqux39a/JCywvjFiDsRaOK+lY9L76KXUeZ0f7wrTIVJZTrFhz6Iob4vYMFXk+o4ynfLnZyHqO5TRhjGP06DNPVRmRZOGWkSnVRGWYEqqteY2SL3PEqfEkguy4pClTHmqq367qBhhescFHpiDqtFjxeUV3h4WLIKNwWzSmjSoyFAyWR5LLo9cKaaAExABJF+quO9GWqwiyvqPtmrFTYamEtnS/dZPHxeRWC97v2ktIy2jIEGhu4vDy13wYvz/VgKU8pAkHNbtWsattMDG+XGG3EeeZRvFWl1",
        "signature": "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",
        "header": {
        "ephemeralPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEKHACe0d4cHonHQJwjrZB6q/GDpv574RoKkc/xYbgpSP5p/4GqT8k4/y6rHUy75e+qW9yUVPo7kOWr9YZ6wB2sw==",
        "publicKeyHash": "sNALPkRCH7b7dM63odMKQhMx8oCriXbTNxkOdvuqnAA=",
        "transactionId": "d280ae5d54a9c13ab73abcf55a12c24aac32ea240e3e74cc7a15a5d9cc82fda6"
        }
        },
        "paymentMethod": {
        "displayName": "Visa 1111",
        "network": "Visa",
        "type": "debit"
        },
        "transactionIdentifier": "D280AE5D54A9C13AB73ABCF55A12C24AAC32EA240E3E74CC7A15A5D9CC82FDA6"
        } 

Sending Payment Request to Tyro

Now that your implementation is finished you can begin sending Payment Requests

Provide the following fields in your Pay API request:

  • order.walletProvider = APPLE_PAY

  • order.amount (Final value of the transaction including any additional charges)

  • order.currency

  • sourceOfFunds.provided.card.devicePayment.paymentToken

    (The encrypted payment token obtained from the Apple Pay API, this sentfrom PKPaymentToken.paymentData from Apple’s API)

  • device.mobilePhoneModel

  • transaction.source = INTERNET

A sample Purchase request and response follow.

URL: https://test tyro.mtf.gateway.mastercard.com/api/rest/version/57/merchant/{merchantId}/order/{orderid}/transaction/{transactionid}

HTTP Method: PUT

Request
{
    "apiOperation":"AUTHORIZE",
    "device":{
        "mobilePhoneModel":"Apple iPhone 6S Plus"
    },
    "order":{
        "amount":1.00,
        "currency":"AUD",
        "walletProvider":"APPLE_PAY"
    },
    "sourceOfFunds":{
        "provided":{
            "card":{
                "devicePayment":{
                    "paymentToken":"{\r\n\t\"version\": \"EC_v1\",\r\n\t\"data\": \"WO\/fTbdARsB1Rg3tS4ISwNG4cWDRk3JZDSbP32iDdeMP7UFouS...\",\r\n\t\"signature\": \"MIAGCSqGSIb3DQEHAqCAMIACAQExDzANBglghkg...\",\r\n\t\"header\": {\r\n\t\t\"transactionId\": \"c162557e7ae1c69a47583bc2364d1a3e531428d13fb664032f9e09fa37381fc1\",\r\n\t\t\"ephemeralPublicKey\": \"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEMeuRqVEOZAQ...\",\r\n\t\t\"publicKeyHash\": \"tBGp1mEoHLiHwfOkazpKVbf3cMKmVS98PGufUJ2Q3ys=\"\r\n\t}\r\n}"

//This is only a sample token and will not pass validation. You should substitute this with an actual payment token returned from Apple Pay (PKPaymentToken.paymentData).   
//The gateway considers this value to be a string, NOT JSON itself. The parenthesis are a part of the string. 
                }
            }
        },
        "type":"CARD"
    },
    "transaction":{
        "frequency:" "SINGLE",
        "source":"INTERNET"
    }
}
 
Response
{
  "authorizationResponse": {
    "transactionIdentifier": "000000285377253"
  },
  "device": {
    "mobilePhoneModel": "Apple iPhone 6S Plus"
  },
  "gatewayEntryPoint": "WEB_SERVICES_API",
  "merchant": "TEST_MERCHANT",
  "order": {
    "amount": 1,
    "creationTime": "2016-11-09T23:20:58.675Z",
    "currency": "AUD",
    "id": "01",
    "status": "AUTHORIZED",
    "totalAuthorizedAmount": 1,
    "totalCapturedAmount": 0,
    "totalRefundedAmount": 0,
    "walletProvider": "APPLE_PAY"
  },
  "response": {
    "acquirerCode": "000",
    "cardholderVerification": {
      "avs": {
        "acquirerCode": "N",
        "gatewayCode": "NO_MATCH"
      }
    },
    "gatewayCode": "APPROVED"
  },
  "result": "SUCCESS",
  "sourceOfFunds": {
    "provided": {
      "card": {
        "brand": "MASTERCARD",
        "deviceSpecificExpiry": {
          "month": "05",
          "year": "21"
        },
        "deviceSpecificNumber": "512345xxxxxx0008",
        "encryption": "DEVICE",
        "expiry": {
          "month": "05",
          "year": "28"
        },
        "fundingMethod": "UNKNOWN",
        "devicePayment": {
          "cryptogramFormat": "3DSECURE"
        },
        "number": "xxxxxxxxxxxx0023",
        "scheme": "MASTERCARD"
      }
    },
    "type": "CARD"
  },
  "timeOfRecord": "2016-11-09T23:20:58.675Z",
  "transaction": {
    "acquirer": {
      "batch": 3,
      "id": "TESTACQUIRER",
      "merchantId": "6465720084"
    },
    "amount": 30.1,
    "authorizationCode": "377253",
    "currency": "AUD",
    "frequency": "SINGLE",
    "id": "1",
    "receipt": "001611092532",
    "source": "INTERNET",
    "terminal": "12333",
    "type": "AUTHORIZATION"
  },
  "version": "57"
}

Testing and Go Live

You can test your integration with the gateway in production using your test merchant profile.

Please note, you must configure your application to use the Apple Pay Sandbox enviroment. A signed certificate from Apple will need uploaded to the gateway via Merchant Administration.

The gateway uses the certificate to process the payment token provided by Apple.

If the transactions are either APPROVED or DECLINED then the gateway was able to process your test transactions successfully.

A list of supported ‘sandbox / development’ cards can be found here on Apple’s website.

An example of Apple Pay Sandbox can be found below: