Apple Pay

You can initiate commercial payments on behalf of your merchants using Apple Pay in your frontend. Currently, this flow is for web-based platforms only. If you plan to build a mobile app, please mention it to your account manager.

If you plan to integrate top up by Apple Pay, please refer to this page (set up is different).

Prerequisites (initial set up):

Tip! For faster set up, we strongly recommend scheduling a call with our engineers, together all set up can be done during one call.

1. If you don’t have it yet, first thing would be to create Apple developer account based on instructions from Apple: Before You Enroll – Apple Developer Program
2. Then sign in to Your Apple Developer account
3. Create new merchant identifier by opening Identifiers section

4. Select “+” sign and Merchant IDs under it

5. Fill in required data and register it
6. Write email to [email protected] including merchant Identifier, brand Id and asking to create .csr file for Apple pay integration
7. After receiving .csr file from us, payment processing certificate can be created in Apple Developer account. Open created merchant identifier and click “Create Certificate”

8. Then upload .csr file received from us

9. You will receive payment processing certificate from Apple. Send certificate to [email protected] in zip file. Certificate needs to be send in zip file because of security reasons we block all certificate files send to ConnectPay server. We will send you back merchant identity .csr file
10. Then add your domain in Apple Developer portal. Open your merchant identifier, click “Add Domain” at the bottom of the page, enter it and save

11. Download .txt file from Apple after saving your domain. You must place the domain validation file on your server at: https://yourdomain/.well-known/apple-developer-merchantid-domain-association. Without this file, it will not be possible to use Apple Pay on your domain. Upload this file to server so it’s accessible at the following location (replacing yourdomain.com with the URL of the domain): https://domain.com/.well-known/apple-developer-merchantid-domain-association.txt . To do this, create a folder called .well-known in the root directory of the website and put the .txt file in that folder

12. Once .txt file have been uploaded, select Verify. Apple will check your domain ownership

13. Then you will need to create merchant identity certificate. Open your merchant identifier in Apple Developer Portal, click “Create certificate” under Apple Pay Merchant Identity Certificate sections (make sure you’re not in the Apple Pay Payment Processing Certificate section). Upload .csr file received from #9 step and press “Continue”

14. Download new .crt files and send it to [email protected] in a zip file. Certificate needs to be send in zip file because of security reason we block all certificate files send to ConnectPay server
15. Please wait our confirmation that set up is finished
16. Also, you’ll need to white-list Apple IP’s and domain names for merchant validation in production and testing. You can find the list here. Do not allow your server to access any other URLs for merchant validation

As BaaS partner, you can use same Apple merchant identifier for all sub-merchants.

Apple Pay commercial payments are settled after 3 days of payment initiation.

Flow:

Integration can be split in two parts – merchant validation together with session creation and payment initiation.

1. When your end-user selects to pay by Apple Pay, you need to check if they are using Safari browser by checking if window.ApplePaySession class exist.
2. After that, you’ll need to check if device supports it. This can be done by calling Apple canMakePayments method. If you receive true value, then device supports making payments with Apple Pay and you can show Apple button on your frontend. It doesn’t verify whether or not the user has any provisioned cards in Wallet. If you want to show Apple button only for those users who have active cards added to the Wallet, you can use canMakePaymentsWithActiveCard method. If returned true, then device supports Apple Pay and there is at least one active card in Wallet that is qualified for payments on the web.

if(window['ApplePaySession'] u0026amp;u0026amp; ApplePaySession.canMakePayments(u0022pass merchant id hereu0022))

3. You’ll need to style Apple Pay button based on Apple’s requirements. Styling done against requirements might bring blocking from Apple after some time.
4. After you decide to show Apple Pay button and user selects to Pay, you’ll need to create a session with Apple by initiating Apple Pay session. For version parameter follow Apple’s guidelines, for payment request parameters, use:

• countryCode – LT;
• currencyCode – selected currency, for now EUR only;
• supportedNetworks – visa, mastercard
• merchantCapabilities – supports3DS
• label – your Platform name or what you want to show on Apple pop-up;
• amount – amount from user’s selection.

nvar request = { countryCode: 'LT', currencyCode: 'EUR', supportedNetworks: ['visa', 'masterCard'], merchantCapabilities: ['supports3DS'], total: { label: 'Your Merchant Name', amount: '10.00' }, } var session = new ApplePaySession(3, request);n

5. After the session is created, call its begin method to show the payment sheet. When this method is called, the payment sheet is presented and the merchant validation process is initiated. Then use onvalidatemerchant function to start validation process.

const request = {n        countryCode: 'LT',n        currencyCode: 'EUR',n        supportedNetworks: ['visa', 'masterCard'],n        merchantCapabilities: ['supports3DS'],n        total: { label: 'ConnectPay', amount },n      }n  const session = new ApplePaySession(3, request);n  session.begin();n  session.onvalidatemerchant = (event) =u003e {n        const { validationURL } = event;n         // do the validation here         // after receiving the session object from back end call in         session.completeMerchantValidation(by passing the object here);n  };

6. After Apple validates the session and provides session URL, send this URL together with your brand ID from your backend to us using Create Apple Pay Session API .
7. We will complete merchant validation with Apple, create a session and return you merchant session object. Don’t modify this object, you’ll need to use it for payment authorization flow.
8. Pass merchant session object received from us to Apple using completeMerchantValidation method to enable the user to authorize a transaction. The merchant session object expires 5 minutes after it is created.

9. When your session is validated and created at Apple side, user can now authorize a payment. When user authorizes a payment, onpaymentauthorized function is called. The event parameter contains the payment attribute. The onpaymentauthorized function must complete the payment and respond by calling completePayment before the 30 second timeout, after which a message appears stating that the payment couldn’t be completed.

session.onpaymentauthorized =  (event)=u003e {n        const token = event.payment.token;n        // handling the payment authorization n}

10. Take Apple token from onpaymentauthorized function and send it to us using Initiate Apple Pay API. We will create a payment and send it to your customer’s issuer.
11. For receiving payment status you have 2 options: calling our Get payment details API using paymentId provided in Initiate Apple Pay API response or receiving payment status from Notifications (you need to subscribe notifications to do that).
12. After you receive terminal payment status from us – Failed or Approved, you need to complete payment on Apple side using completePayment method. Until this method is called Apple will load spinner on UI blocking user from further actions or time out it after 30 seconds claiming payment couldn’t be completed. If payment status is PendingProvider or Processing, retry calling Get payment details API until you receive terminal status.
13. After payment is completed on Apple, you can decide what to do with user journey – show success/failure message or redirect to other page.

Tip! Before payment authorization flow, Apple session time out is 1 hour (time frame when user can select their card), if your session is shorter, you can handle it by calling abort function on your session time-out event. If you don’t align Apple session with your session time, after your session is expired, your user will be blocked by Apple pop-up.

Splitting one payment for multiple
sub-merchants

For BaaS partners it is possible to send 1 Apple Pay payment request on behalf of multiple merchants. This feature is used for marketplaces where end user can add multiple goods from different merchants through one platform’s website. One payment can have max 10 different merchants in payment request. Configuration at Apple side remains same as you’ve created, website where end-user is making a payment should be registered at Apple. When sending Initiate Apple Pay API request, add optional object splittingInstructions with brand Ids representing merchants user is paying for. You can add your own commission fee for each merchant.