Apple Pay - Integration

Steps for Integration

1. Set up a device for testing

• Sandbox account: Requires an iCloud account corresponding to your environment. Testing in the 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: Requires an iOS device and a supported debit/credit card.

2. Register your domain

• Host the domain association file and register your domain in the Buckaroo Plaza.

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 Apple Pay support in the 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 if you go to the Buckaroo Plaza: Click on “Your merchant name” and then open the General page. The ID is then visible in the URL: https://plaza.buckaroo.nl/Merchant/[your merchant GUID]

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:

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
   );
}

3.5 Reserving funds instead of collecting them

By default the SDK flow collects the money immediately: your server posts a Pay request and the funds move as soon as the buyer approves the Apple Pay sheet. To reserve the funds at checkout and collect them later — once stock is confirmed, or the order ships — post a reservation action instead of Pay:

• Authorize — when the amount is already final.
• PreAuthorize — when the amount finally captured may differ from the amount reserved, for example when you reserve a maximum up front and settle the actual amount later.
  The client-side integration in steps 3.1 to 3.4 does not change in either case. The Apple Pay sheet is presented and approved exactly as before, the buyer authenticates with Face ID, Touch ID or their device passcode, and the CaptureFunds callback hands you the encrypted Apple Pay token. Only the action name on the server-to-server request differs.

Server-side request

Forward the token from the CaptureFunds callback to your own server, then post it to the gateway with the action you need — PreAuthorize shown here:

{
   "Currency": "EUR",
   "AmountDebit": 10.00,
   "Invoice": "testinvoice 123",
   "Services": {
      "ServiceList": [
         {
            "Name": "applepay",
            "Action": "PreAuthorize",
            "Parameters": [
               {
                  "Name": "PaymentData",
                  "Value": "eyJkYXRhIjoiU2FtcGxl...base64-encoded-Apple-Pay-token...XXXX"
               }
            ]
         }
      ]
   }
}

Buckaroo reserves the funds on the card behind the wallet without moving them. There is no 3-D Secure step and no redirect, so the result is returned synchronously. See PreAuthorize and Authorize on the Apple Pay - Requests page for the complete response and push payloads, and for the difference between the two actions.

Capturing or releasing the funds later

Capture and CancelAuthorize do not involve the SDK or the buyer's device — they are plain server-to-server gateway requests, sent whenever your own process decides the outcome (order shipped, stock confirmed, fraud check failed, buyer cancelled). Both are identified by the OriginalTransactionKey, which is the Key of the Authorize or PreAuthorize transaction:

• Capture — collects the funds. A full capture or a single partial capture; a second capture against the same reservation is rejected.
• CancelAuthorize — releases the reserved funds back to the buyer.

  📘 ### Nothing to change in an existing integration

Keeping the Pay action leaves the current immediate-capture behaviour exactly as it is. Existing Apple Pay integrations need no changes on either the client side or the server side.