Integration Guides

Overview Hosted Fields 3D Secure Customers Recurring Payments Marketplaces Apple Pay Google Pay Webhooks Payment Forms Pin.js

Apple Pay

Add Apple Pay to your website or iOS application so customers can seamlessly and securely pay you using a card connected to their Apple Pay wallet.

Supported card brands

Integration Options

Pin Payments offers the following options for Apple Pay integration:

Hosted Payment Page
Hosted Payment Button
Integrate with your website
Integrate with your iOS application

Hosted Payment Page

Apple Pay is supported on the Payment Page by default for eligible merchants, no configuration is required.

Hosted Payment Button

You must first register your domain for Apple Pay enablement via the Apple Pay dashboard interface and follow our Payment Buttons guide.

Integrate with your website

You must first register your domain for Apple Pay enablement via the Apple Pay dashboard interface and follow the Apple Pay on the web documentation.

In order to provide merchant validation, you will need to:

Create an API endpoint on your server, taking the validationURL parameter from the onvalidatemerchant event and passing it to our Apple Pay create session API endpoint along with your secret API key, setting the initiative_context to the domain name from which the Apple Pay session is initiated
Pass the response to the completeMerchantValidation method on the Apple Pay session.
Create an additional endpoint to tokenise the Apple Pay payment data and create a charge with the payment token. Call this endpoint via an XMLHttpRequest as the Apple Pay Javascript API requires reporting the payment status before the payment sheet closes.

Tokenise the Apple Pay payment data

Once you have received the payment data from Apple, you then need to call the Pin Payments create payment source endpoint to tokenise the encrypted payment data.

Use the details below to set up your request.

Read our payment sources API reference for a list of all endpoints, as well as complete request and response examples.

Request Example

  {
    "type": "applepay",
    "source": {
      "data": "CpNwka2Dx7Ld/5EeIKxk+8Ze5lfjslhe91BGL3xvvHu5LT3hUp…2sdwSw0Sqc7KtmES+rNQFHGbQew6GzFXRHRJbkM3Hylhft22Z",
      "signature": "MIAGCSqGSIb3DQEHAqCAMIACAQExDzANBglghkgBZQMEAgEFAD…Q/i5g+297xl1lS7V3n0FPVG8Fp3E7luPHYEn1nQAAAAAAAA==",
      "header": {
        "publicKeyHash": "T0Dxmof9nRRQ+LIix3IGkVr6KubE5DtsVVx78oGG/Uc=",
        "ephemeralPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEnaHHInIS9BN7S1…fAW+7gFJvVvSnZibtAb8/AdtZ0HRZVY6+0uHs8z5HYFEPBw==",
        "transactionId": "df812fad8a217e5eafad1cdcdf04e5217214172254c0fb00a40d78f9d4ab64d8"
      },
      "version": "EC_v1"
    }

Response Example

  {
    "response": {
      "token": "ps_9hXlCIqqClQAElKT_dw2Pw",
      "type": "applepay",
      "source": {
        "token": "card_2wBUaxkiwRXT7ElyynUrOQ",
        "scheme": "master",
        "display_number": "XXXX-XXXX-XXXX-0000",
        "issuing_country": "US",
        "expiry_month": 5,
        "expiry_year": 2022,
        "name": null,
        "address_line1": null,
        "address_line2": null,
        "address_city": null,
        "address_postcode": null,
        "address_state": null,
        "address_country": null,
        "customer_token": null,
        "primary": null,
        "network_type": "applepay",
        "network_format": null
      }
    },
    "ip_address": "192.0.2.42"
  }

Create the charge

Now you have the payment source token, you can create the charge. Take the payment source token, and use it in the body of a charge request from your application.

See below for a simple example implementation of Apple Pay.

  if (window.hasOwnProperty('ApplePaySession') && ApplePaySession.canMakePayments()) {
    var applePayButton = document.getElementById('apple-pay-btn');
    // display your Apple Pay button
    applePayButton.style.display = 'block';

    applePayButton.addEventListener('click', function(e) {
      e.preventDefault()

      // initiate an Apple Pay session
      var session = new ApplePaySession(10, {
        currencyCode: 'AUD',
        countryCode: 'AU',
        total: {
          label: 'Test Payment',
          amount: 1 // dollar amount, not cents
        },
        supportedNetworks: ['masterCard', 'visa'],
        merchantCapabilities: ['supports3DS', 'supportsCredit', 'supportsDebit']
      })

      session.onvalidatemerchant = function(event) {
        var merchantSessionUrl = 'https://yourdomain.com/apple_pay_session'

        fetch(merchantSessionUrl, {
          method: 'POST',
          headers: {
            'Content-Type': 'application/json'
          },
          body: JSON.stringify({
            initiative_context: window.location.hostname,
            validation_url: event.validationURL
          })
        }).then(function(response) {
          return response.json()
        }).then(function(json) {
          session.completeMerchantValidation(json.response)
        })
      }

      session.onpaymentauthorized = function(event) {
        var paymentToken = event.payment.token.paymentData
        var paymentEndpoint = 'https://yourdomain.com/payments'

        fetch(paymentEndpoint, {
          method: 'POST',
          headers: {
            'Content-Type': 'application/json'
          },
          body: JSON.stringify({
            type: 'applepay',
            source: paymentToken,
            amount: 100, // cents
            currency: 'AUD'
          })
        }).then(function(response) {
          return response.json()
        }).then(function(json) {
          var payment = json.response

          if (payment.success) {
            // Notify Apple that the payment was successful
            session.completePayment(ApplePaySession.STATUS_SUCCESS)
            // You should redirect to a thank you page or similar here
          } else {
            // Notify Apple that the payment failed
            session.completePayment(ApplePaySession.STATUS_FAILURE)
            // You should handle your error case here, for example,
            // display the form with a prompt to try again
          }
        })
      }

      // Show the Apple Pay payment sheet and perform merchant validation
      session.begin()
    })
  }

Integrate with your iOS application

Follow the Setting up Apple Pay developer documentation to create a merchant identifier. Once you get to the Create a payment processing certificate step, head over to the Apple Pay dashboard interface and click the Add Certificate button. Download the certificate signing request from the newly generated certificate–you will need to use the certificate signing request when creating your payment processing certificate in the Apple Developer dashboard.

Once you have generated your payment processing certificate, head back over to the Apple Pay dashboard interface and upload the certificate file–you will see the certificate state in the dashboard update from Incomplete to Active.

Now you can Enable Apple Pay Capability in Xcode, making sure you select the merchant identifier associated with the payment processing certificate you uploaded.