General

When setting up Apple Pay you will need to complete the device setup and domain registration steps below.

1. Set up a device

You have 2 options for testing Apple Pay:

  • Sandbox account. When testing, you will need to be logged in to an iCloud account that corresponds to your environment. Testing in sandbox requires you to be logged in to an iTunes Connect sandbox tester account, which you can create with an Apple Developer account.
  • Production account. You won’t need a developer account for this option. You’ll need an iOS device and a debit/credit card which is supported by Apple Pay. You can safely create test transactions with a real card. As long as you are creating test transactions your debit/credit card will not be charged.

2. Register your domain

  • You will need to register every domain name that will be used to perform Apple Pay payments with. Before registering your domain names you will need to download the domain association file and host it on your site at /.well-known/apple-developer-merchantid-domain-association. NOTE: Apple does not support HTTP URL redirects for the domain association file. Be sure that the file is not served with a 3xx status code.
  • When you have successfully placed this file for each domain name, you can log in to the Buckaroo Plaza and visit the Apple Pay page in the Configuration menu. On this page, you will be able to register your domains with Apple by simply entering your domains in the Sandbox and Production account tabs. We will take care of the rest.

3. Client-Side integration

Our ClientSide SDK works as a wrapper for Safari's Apple Pay API Reference. It will take care of a few parts for you, namely:

  • Easier API integration
  • Setting up the Apple Pay Button
  • Callback management
  • Creating a Session with Apple Pay

 

3.1 Get the SDK

Include the following script in your page.

<script src="https://checkout.buckaroo.nl/api/buckaroosdk/script"></script>

3.2 Check for Apple Pay support in browser

First we need to determine if Apple Pay is supported on the customer’s device. Change the 'YOUR_MERCHANT_GUID' value to your merchant GUID.

You can find this ID in the Buckaroo Plaza: Click on “Your merchant name” and then open the General page.

var merchantIdentifier = 'YOUR_MERCHANT_GUID';
BuckarooSdk.ApplePay.checkApplePaySupport(merchantIdentifier)
  .then(function (applePaySupported) {
    if (applePaySupported) {
      init(merchantIdentifier);
    }
  });

3.3 Initialize Apple Pay

This code sample demonstrates the initialization of a new Apple Pay payment. As described in the code comments the available fields are:

StoreName 			(REQUIRED) Display name of your store
CountryCode 			(REQUIRED) Format: ISO 3166 
Currency			(REQUIRED) ISO 4217
Language			(REQUIRED) ISO 639-1
MerchantIdentifier	 	(REQUIRED) Your merchant GUID
LineItemsForDelivery 	        (REQUIRED) Shows the product lines in a shopping cart view. See sample for the format
TotalForDelivery		(REQUIRED) Is used to display a total price for the order. See sample code for the format.
ShippingOption 		        (REQUIRED) See Apple Docs.
ShippingMethods 		(REQUIRED) See sample code for the format.
CaptureFunds	 		(REQUIRED) Callback: for capturing funds. This callback is executed when the user successfully authenticates the payment intent with Apple. The encrypted token needs to be sent to Buckaroo via a server-to-server API request.
ShippingMethodSelected 	        (OPTIONAL) Callback: This callback is called when the user selects a different shipping method. It can be used to recalculate shipping costs and alter the line items.
ShippingContactSelected	        (OPTIONAL) Callback: This callback is called when the user selects a different shipping address. It can be used to recalculate shipping costs and alter the line items.
RequiredBillingFields	        (OPTIONAL) Required fields for billing. See Apple Docs.
RequiredShippingFields 	        (OPTIONAL) Required fields for shipping. See Apple Docs.
Cancel		 		(OPTIONAL) Callback: This callback is called then the user dismisses the ApplePay UI.

function init(merchantIdentifier) {
   var totalForDelivery = {
      label: "Total price",
      amount: "5.99",
      type: "final"
   };
   var subtotal = "4.99";
   var lineItemsForDelivery = [
      { label: "Subtotal", amount: subtotal, type: "final" },
      { label: "Delivery", amount: "1.00", type: "final" }
   ];
   var shippingMethods = [
      { label: "Delivery", amount: "1.00", identifier: "delivery", detail: "Deliver   y to you" },
      { label: "Collection", amount: "0.00", identifier: "collection", detail: "Collect from the store" }
   ];
   var requiredContactFields = ["email", "name", "postalAddress"];
   var captureFunds = function (payment) {
      var result = {}; // https://developer.apple.com/documentation/apple_pay_on_the_web/applepaypaymentauthorizationresult

      var captureInfo = {
         customerCardName: payment.billingContact.givenName + " " + payment.billingContact.familyName,
         paymentData: btoa(JSON.stringify(payment.token))
      }

      // TODO: send captureInfo to Buckaroo

      return Promise.resolve(result);
   }
   var shippingMethodSelected = function (shippingMethod) {
      var result = {}; // https://developer.apple.com/documentation/apple_pay_on_the_web/applepayshippingmethodupdate
      return Promise.resolve(result);
   }
   var shippingContactSelected = function (shippingContact) {
      var result = {}; // https://developer.apple.com/documentation/apple_pay_on_the_web/applepayshippingcontactupdate
      return Promise.resolve(result);
   }
   var cancel = function(event) {
      console.log("Payment UI is dismissed.");
   }
   var shippingOption = "shipping"; // https://developer.apple.com/documentation/apple_pay_on_the_web/applepayshippingtype
   var options = new BuckarooSdk.ApplePay.ApplePayOptions(
      'STORE_NAME',    		 // store name
      'NL', 			 // country code
      'EUR',			 // currency code
      'NL',			 // language
      merchantIdentifier, 	 // your merchant guid
      lineItemsForDelivery, 	 // default line items
      totalForDelivery, 	 // default total line
      shippingOption, 		 // default shipping option
      shippingMethods, 		 // available shipping methods
      this.captureFunds, 	 // callback method for capturing funds
      this.shippingMethodSelected, // (OPTIONAL) after shipping method is altered
      this.shippingContactSelected,// (OPTIONAL) after shipping contact is altered
      requiredContactFields,	 // (OPTIONAL) fields for billing contact
      requiredContactFields, 	 // (OPTIONAL) required fields for shipping    
      this.cancel		 // (OPTIONAL) after payment UI is dismissed
   );

   showButton(options);
}

3.4 Show button

This sample code creates the payment and shows the Apple Pay button with a white-on-black design and the check-out text.

function showButton(options) {
   var payment = new BuckarooSdk.ApplePay.ApplePayPayment(
      "#button",  // selector for the element to use as the button
      options	 // the ApplePay payment options object
   );

   payment.showPayButton(
      "black",    // black, white or white-outline
      "check-out" // plain, book, buy, check-out, donate, set-up or subscribe
   );
}

Pay

The Pay action is the default action. The action is used to perform a single payment with Apple Pay.

View in playground

Request


JSON gateway request

PaymentData
Required

This can be retrieved from the "captureInfo"-variables of our Client Side Encryption SDK.

CustomerCardName

This can be retrieved from the "captureInfo"-variables of our Client Side Encryption SDK.

JSON

copy
{
   "Currency": "EUR",
   "AmountDebit": 1.00,
   "Invoice": "10000480",
   "Services": {
      "ServiceList": [
         {
            "Name": "applepay",
            "Action": "Pay",
            "Parameters": [
               {
                  "Name": "PaymentData",
                  "Value": "XXXXXXXXXXXXX"
               },
               {
                  "Name": "CustomerCardName",
                  "Value": "XXXXXXXXXXXXX"
               }
            ]
         }
      ]
   }
}

Response


JSON gateway response

CardNumberEnding

Last 4 digits of the creditcard number.

CardExpirationDate

Credit card expiration date.

MaskedCreditcardNumber

Masked card number.

JSON

copy
{
   "Key": "9AA4C81A08A84FA7B68E6A6A6291XXXX",
   "Status": {
      "Code": {
         "Code": 190,
         "Description": "Success"
      },
      "SubCode": {
         "Code": "S001",
         "Description": "Transaction successfully processed"
      },
      "DateTime": "2019-06-13T09:19:52"
   },
   "RequiredAction": null,
   "Services": [
      {
         "Name": "applepay",
         "Action": null,
         "Parameters": [
            {
               "Name": "CardNumberEnding",
               "Value": "00XX"
            },
            {
               "Name": "CardExpirationDate",
               "Value": "0019-07"
            },
            {
               "Name": "MaskedCreditcardNumber",
               "Value": "XXXXXX******XXXX"
            }
         ]
      }
   ],
   "CustomParameters": null,
   "RequestErrors": null,
   "Invoice": "10000480",
   "ServiceCode": "applepay",
   "IsTest": true,
   "Currency": "EUR",
   "AmountDebit": 1.00,
   "TransactionType": "V187",
   "MutationType": 2,
   "RelatedTransactions": null,
   "ConsumerMessage": null,
   "Order": "10000480",
   "IssuingCountry": null,
   "StartRecurrent": false,
   "Recurring": false,
   "CustomerName": "XXXXXXXXXXXX",
   "PayerHash": "XXXXXXXXXXXXXXXXXXX",
   "PaymentKey": "XXXXXXXXXXXXXXXXXXXXXX"
}

Push


JSON push response

CardNumberEnding

Last 4 digits of the creditcard number.

CardExpirationDate

Credit card expiration date.

MaskedCreditcardNumber

Masked card number.

JSON

copy
{
   "Transaction": {
      "Key": "9AA4C81A08A84FA7B68E6A6A6291XXXX",
      "Invoice": "10000480",
      "ServiceCode": "applepay",
      "Status": {
         "Code": {
            "Code": 190,
            "Description": "Success"
         },
         "SubCode": {
            "Code": "S001",
            "Description": "Transaction successfully processed"
         },
         "DateTime": "2019-06-13T09:19:52"
      },
      "IsTest": true,
      "Order": "10000480",
      "Currency": "EUR",
      "AmountDebit": 1,
      "TransactionType": "V187",
      "Services": [
         {
            "Name": "applepay",
            "Action": null,
            "Parameters": [
               {
                  "Name": "CardNumberEnding",
                  "Value": "00XX"
               },
               {
                  "Name": "CardExpirationDate",
                  "Value": "0019-07"
               },
               {
                  "Name": "MaskedCreditcardNumber",
                  "Value": "XXXXXX******XXXX"
               }
            ],
            "VersionAsProperty": 1
         }
      ],
      "CustomParameters": null,
      "MutationType": 2,
      "RelatedTransactions": null,
      "IsCancelable": false,
      "IssuingCountry": null,
      "StartRecurrent": false,
      "Recurring": false,
      "CustomerName": "XXXXXXXXXXXX",
      "PayerHash": "XXXXXXXXXXXXXXXXXXX",
      "PaymentKey": "XXXXXXXXXXXXXXXXXXXXXX"
   }
}

Refund

The Refund action can be used to perform a refund on an earlier Apple Pay transaction. There is no customer interaction needed to do this.

View in playground

Request


JSON gateway request

OriginalTransactionKey
Required

Transaction key of the payment that needs to be refunded.Please note: This is a basic parameter, not a service specific parameter.

JSON

copy
{
   "Currency": "EUR",
   "AmountCredit": 1.00,
   "Invoice": "10000480",
   "OriginalTransactionKey": "XXXXXXXXXXXXXXX",
   "Services": {
      "ServiceList": [
         {
            "Name": "applepay",
            "Action": "refund"
         }
      ]
   }
}

Response


JSON gateway response

JSON

copy
{
   "Key": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
   "Status": {
      "Code": {
         "Code": 190,
         "Description": "Success"
      },
      "SubCode": {
         "Code": "S001",
         "Description": "Transaction successfully processed"
      },
      "DateTime": "2019-06-13T09:20:24"
   },
   "RequiredAction": null,
   "Services": null,
   "CustomParameters": null,
   "RequestErrors": null,
   "Invoice": "10000480",
   "ServiceCode": "applepay",
   "IsTest": true,
   "Currency": "EUR",
   "AmountCredit": 1.00,
   "TransactionType": "V188",
   "MutationType": 2,
   "RelatedTransactions": [
      {
         "RelationType": "refund",
         "RelatedTransactionKey": "XXXXXXXXXXXXXXXXXXXXX"
      }
   ],
   "ConsumerMessage": null,
   "Order": null,
   "IssuingCountry": null,
   "StartRecurrent": false,
   "Recurring": false,
   "CustomerName": "XXXXXXXXXXXX",
   "PayerHash": null,
   "PaymentKey": "XXXXXXXXXXXXXXXX"
}

Push


JSON push response

JSON

copy
{
   "Transaction": {
      "Key": "XXXXXXXXXXXXXXXXXXXXXXXXXX",
      "Invoice": "10000480",
      "ServiceCode": "applepay",
      "Status": {
         "Code": {
            "Code": 190,
            "Description": "Success"
         },
         "SubCode": {
            "Code": "S001",
            "Description": "Transaction successfully processed"
         },
         "DateTime": "2019-06-13T09:20:24"
      },
      "IsTest": true,
      "Order": null,
      "Currency": "EUR",
      "AmountCredit": 475.85,
      "TransactionType": "V188",
      "Services": null,
      "CustomParameters": null,
      "MutationType": 2,
      "RelatedTransactions": [
         {
            "RelationType": "refund",
            "RelatedTransactionKey": "XXXXXXXXXXXXXXXXXXX"
         }
      ],
      "IsCancelable": false,
      "IssuingCountry": null,
      "StartRecurrent": false,
      "Recurring": false,
      "CustomerName": "XXXXXXXXXXXXX",
      "PayerHash": null,
      "PaymentKey": "XXXXXXXXXXXXXXXXXXXXXX"
   }
}