How to accept Apple Pay from customers

Accept Apple Pay payments in your Kushki integration. Depending on the type of solution you use (Smartlink/Button or Custom Integration), the configuration process varies.

🚧 BETA: Limited Availability 🇵🇪 🇨🇱
Please note that Apple Pay is currently in Beta phase. This feature is available only for merchants in Chile and Peru, and processes transactions exclusively with Visa and Mastercard cards.

There are 3 types of integrations available:

1. No-code Integrations (Payment Button and Smartlinks)

If you use Payment Button (Webcheckout) or Smartlinks, the technical integration is already handled. However, it is necessary to manually activate this option in your Kushki Console.

When creating or editing your Smartlink or Payment Button in the Console, make sure to enable the Apple Pay toggle in the "Payment Methods" section.

• Smartlinks: Review the step-by-step guide for activating Apple Pay in Smartlinks.
• Payment Button: Consult the guide for activating Apple Pay in Payment Buttons.

Do I need an Apple Developer account?
No. For No-Code Integrations (Smartlinks, Payment Button) and Custom Integrations (libraries and Kajita), you do not need an Apple Developer account.
 

By using Kushki as your payment processor, we manage the complexity of certificates with Apple. You only need to host the file we provide to prove domain ownership.

2. Custom Integrations (Libraries and Kajita)

If you use Kushki.js (v1 or v2 - hosted fields) or Kajita, domain verification is required to ensure your website is authorized to process Apple Pay payments.

ℹ️ Prerequisites: Before starting, ensure you have access to the Kushki Console, specifically the Configuration module.

Step 1: Request the verification file

To validate your domain, you need the Apple merchant association file (apple-developer-merchantid-domain-association).

1. Contact the Kushki Support team.
2. Request the Apple Pay Configuration Certificate.
3. Specify the environment you require the file for: Testing (UAT) or Production.

❗ Important: Verification files are unique to each environment. Ensure you request and use the correct file for UAT or Production accordingly.

Step 2: Host the file on your server

Once Kushki provides the file, you must host it on your web server. Apple requires this file to be publicly accessible via HTTPS at a specific path.

Create a folder named .well-known at the root of your domain and place the downloaded file there. The final URL should look like this:

https://your-domain.com/.well-known/apple-developer-merchantid-domain-association

You can verify that the file is correctly hosted by running the following command in your terminal or simply pasting the URL in your browser:

curl -I https://your-domain.com/.well-known/apple-developer-merchantid-domain-association

You should receive a 200 OK response and the file must be downloadable or visible.

Step 3: Domain registration in Kushki Console

With the file correctly hosted, the final step is to register your domain in our platform to complete the association.

1. Log in to the Kushki Console.
2. Go to Settings > Integrations.
3. Look for the Apple Pay section.
4. Enter your domain URL (example: your-domain.com) in the corresponding field.
5. Click Register or Verify.

Kushki will then communicate with Apple to verify the file's existence on your server. If successful, the domain will be verified.

Step 4: Technical implementation

Once the domain is verified, proceed with the technical implementation according to your integration method:

• Kajita: Follow the guide to activate Apple Pay in your Kajita form.
• Kushki.js v2 (Hosted Fields): Review the Apple Pay integration in v2 documentation.
• Kushki.js v1: Consult the one-time payment examples to see the implementation.

3. Direct Integration with Apple Pay

This guide details the process of obtaining the necessary credentials directly from Apple.

Prerequisites:

• You must have an active Apple Developer account.
• This account has an annual cost. Consult details in the Apple Developer Program ›

Phase 1: Obtain your Merchant ID

The Merchant ID identifies your business to accept payments.

1. Log in to your Apple Developer account.
2. Enter the Certificates, Identifiers & Profiles section.
3. Select Identifiers from the sidebar and then Merchant IDs from the list.
4. Click the blue (+) button to add a new one.
5. Select Merchant IDs and click Continue.
6. Provide a Description and a unique Identifier.
7. Review the data and click Register.

Phase 2: Obtain the Merchant Identity Certificate

This certificate validates that your website is legitimate to display the Apple Pay button. Apple requires 2048-bit RSA encryption for this step.

1. Generate the RSA Private Key: Open your terminal and run the following command to create your key:

openssl genrsa -out merchant.key 2048

2. Create the Certificate Signing Request (CSR): Generate the .csr file using your Merchant ID as the common name.

openssl req -new -key merchant.key -out merchant.csr \
 -subj "/CN={merchant_ID}"

3. Create in Apple:

• Return to the Apple console (Merchant IDs section), select your ID and click Create Certificate under Apple Pay Merchant Identity Certificate.
• Upload the generated merchant.csr file and click Continue.
• Download the certificate (merchant_id.cer).

Phase 3: Generate the Apple Pay Payment Processing Certificate

Once the Merchant ID and Merchant Identity Certificate are generated, you need to obtain a Payment Processing Certificate.

Follow these steps to obtain the certificate:

1. Create the EC Private Key (P-256): Run the following command to generate the processing key:

openssl ecparam -name prime256v1 -genkey -noout -out payment.key

2. Create the Certificate Signing Request (CSR): Generate the file to provide to Apple using your Merchant ID.

openssl req -new -key payment.key -out payment.csr \
 -subj "/CN={merchant_ID}"

3. Activate your certificate in Apple:

• Return to the console and select Certificates, Identifiers & Profile.
• Under Identifiers, select Merchant IDs.
• Select the Merchant ID previously created.
• In the Apple Pay Payment Processing Certificate section, click Create Certificate.
• Follow the instructions, then upload the generated file.
• Download the final certificate to complete the process.

Phase 4: Web Domain Validation

Apple needs to confirm that you are the owner of the website.

1. In your Merchant ID, go to the Merchant Domains section.
2. Click Add Domain, enter your website (e.g., www.example.com or example.com) and save.
3. Download the verification file.
4. Host the file at the .well-known path of your server.
5. Go back to the Apple console and click Verify.

4.1. Verification Confirmation:

• Success: If the file is accessible, Apple will verify the domain immediately, and the status will show as "Verified".
• Error: If verification fails, check these critical points:
  • Exact path: ensure the folder is named .well-known (with the leading dot) and the filename has no extra extensions.
  • Accessibility: try opening the file URL from an incognito window. If you cannot see it, Apple cannot either.
  • Redirects: ensure your server is not forcing redirects or using firewalls that block direct access to the text file.

Phase 5: Web Implementation and Tokenization

Once you have your certificates and the domain is verified, proceed with programming the payment button on your website.

Follow these steps:

1. Create the Apple Pay Session: Use your Merchant Identity Certificate (generated in Phase 2) to communicate with Apple servers. This is mandatory to validate your identity and allow the payment sheet (Wallet) to appear on the client's device.
2. Decrypt data: Once the client authorizes the purchase, Apple will return an encrypted payment object. Use the private key from your Payment Processing Certificate (Phase 3) to decrypt this package and obtain card details.
3. Tokenize with Kushki: Finally, with the decrypted card information, send it to Kushki to generate a secure transport token.
   • You must consume the endpoint to create a Network Token.
   • Check the required parameters in our API Reference: Create a Card Token ›