Apple Pay via Widget

Ce guide vous guide dans l'intégration Apple Payer en utilisant les SDK DEUNA

1. Conditions préalables#

Avant de commencer, assurez-vous que les éléments suivants sont en place :

1.1. Vérification de domaine (obligatoire pour les deux chemins)

Chaque domaine qui affiche un bouton Apple Pay, que ce soit via le widget de paiement ou le coffre-fort, doit être enregistré auprès d'Apple via DEUNA. Cela s’applique aux domaines de production et à tous les environnements de test ou de prévisualisation.

Étape par étape

1. Obtenir le fichier d'association de domaine depuis le tableau de bord DEUNA (ou depuis Apple Pay si vous utilisez votre propre identifiant de marchand). Le fichier est généralement nommé apple-developer-merchantid-domain-association (pas de prolongation) ou .txt.
2. Héberger le fichier inchangé à :
   Plain textCopier

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

   Assurez-vous :
   • La réponse est servie plus HTTPS.
   • Content-Type est text/plain; charset=utf-8.
   • Pas de redirection, pas de mur d'authentification, pas de 404. La réponse doit être 200 OK.
3. Vérifier le domaine dans le tableau de bord DEUNA (ou le portail des développeurs Apple Pay). Apple récupérera le fichier sur votre serveur ; si cela correspond, le domaine est enregistré.
4. Répéter par domaine. Chaque nom d'hôte qui charge le widget (par ex. checkout.mystore.com, staging.mystore.com) doit signifier le dossier et être enregistré séparément.

Implémentation de référence (Next.js - Exemple)

Ce référentiel implémente déjà le point de terminaison de vérification. Deux choses sont câblées :

next.config.js — réécrit à la fois le canonique et .txt chemins vers une route API :

async rewrites() {
  return [
    {
      source: '/.well-known/apple-developer-merchantid-domain-association',
      destination: '/api/apple-verification',
    },
    {
      source: '/.well-known/apple-developer-merchantid-domain-association.txt',
      destination: '/api/apple-verification',
    },
  ];
}

src/pages/api/apple-verification.ts — renvoie le contenu du fichier sous la forme text/plain:

import { NextApiRequest, NextApiResponse } from 'next';

export default function domainVerification(
  _req: NextApiRequest,
  res: NextApiResponse,
) {
  const fileContents = process.env.NEXT_PUBLIC_APPLE_VALIDATION_CONTENT_FILE;

  res.setHeader('Content-Type', 'text/plain; charset=utf-8');
  res.status(200).send(fileContents);
}

Le contenu du fichier est stocké dans une variable d'environnement (NEXT_PUBLIC_APPLE_VALIDATION_CONTENT_FILE) afin qu'ils puissent être alternés par environnement sans changement de code.

Comment vérifier que cela fonctionne

curl -i https://<your-domain>/.well-known/apple-developer-merchantid-domain-association

const response = await fetch("https://<your-domain>/.well-known/apple-developer-merchantid-domain-association", {
  method: "GET"
});

if (!response.ok) throw new Error(`Request failed: ${response.status}`);
const data = await response.json();

import requests

response = requests.request(
    "GET",
    "https://<your-domain>/.well-known/apple-developer-merchantid-domain-association",
)
response.raise_for_status()
data = response.json()

<?php
$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://<your-domain>/.well-known/apple-developer-merchantid-domain-association",
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_RETURNTRANSFER => true
]);

$response = curl_exec($curl);
curl_close($curl);

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Example {
  public static void main(String[] args) throws Exception {
    HttpRequest request = HttpRequest.newBuilder()
      .uri(URI.create("https://<your-domain>/.well-known/apple-developer-merchantid-domain-association"))
      .method("GET", HttpRequest.BodyPublishers.noBody())
      .build();

    HttpResponse<String> response = HttpClient.newHttpClient().send(
      request, HttpResponse.BodyHandlers.ofString()
    );
    System.out.println(response.body());
  }
}

package main

import (
  "fmt"
  "io"
  "net/http"
)

func main() {
  request, err := http.NewRequest("GET", "https://<your-domain>/.well-known/apple-developer-merchantid-domain-association", nil)
  if err != nil { panic(err) }

  response, err := http.DefaultClient.Do(request)
  if err != nil { panic(err) }
  defer response.Body.Close()

  body, _ := io.ReadAll(response.Body)
  fmt.Println(string(body))
}

Attendez-vous à :

• HTTP 200 OK
• Content-Type: text/plain; charset=utf-8
• Un corps commençant par 7B22... (la goutte Apple)

2. Intégrations#

Assurez-vous de suivre le guide de démarrage pour nos SDK en fonction de votre intégration spécifique :

• SDK Web >= v1.6
• SDK Android >= 2.11.0
• SDK iOS >= 2.11.0
• SDK natif React >= 2.1.0

2.1. Widget de paiement

Particularités d'Apple Pay

• Aucune configuration supplémentaire nécessaire dans le code. Apple Pay est activé ou désactivé à partir du tableau de bord DEUNA. Si le commerçant l'a actif et que l'appareil de l'utilisateur le prend en charge, le bouton apparaît automatiquement.
• userToken est facultatif — nécessaire uniquement lorsque vous souhaitez associer le paiement à un compte utilisateur DEUNA connu.
• Les rappels de widgets standard (onSuccess, onError, onClosed, onPaymentProcessing) fonctionnent de la même manière que pour les autres modes de paiement.

Quand avez-vous besoin de getWalletsAvailable dans le widget de paiement ?

Si vous ouvrez le widget avec tous les modes de paiement activés, vous n'avez pas besoin d'appeler cette méthode : DEUNA affiche le sélecteur de mode de paiement (y compris les boutons du portefeuille) et résout la disponibilité en interne.

Vous avez seulement besoin getWalletsAvailable lorsque vous affichez votre propre bouton Apple Pay en dehors du sélecteur et que vous utilisez le widget de paiement en mode autonome pour accéder directement à ce mode de paiement. Dans ce cas, appelez-le au préalable pour décider d'afficher ou non votre bouton.

const { DeunaSDK } = window; // from https://cdn.deuna.io/web-sdk/v1.6/index.js

await DeunaSDK.initialize({
  env: 'sandbox',
  publicApiKey: '<YOUR_PUBLIC_API_KEY>',
});

// If Apple Pay is available, it should return it within an array, such as: ["APPLE_PAY"]
const available = await DeunaSDK.getWalletsAvailable();

if (available.includes('APPLE_PAY')) {
  // Render button for Apple Pay and append a listener (EXAMPLE)
  btn.addEventListener('click', () => {
    DeunaSDK.initPaymentWidget({
      orderToken: '<order-token>', // REQUIRED
      paymentMethods: [
        {
          paymentMethod: 'wallet',
          processors: ['apple_pay'],
        },
      ], // In case only the specific payment method is to be used
      callbacks: {
        onSuccess: (order) => {
          console.log('Payment completed:', order);
        },
        onError: (error) => {
          console.error('Payment failed:', error.metadata.message);
        },
        onClosed: (action) => {
          console.log('Widget closed:', action);
        },
      },
    });
  });
} else {
  console.error('Apple Pay is not available on this device.');
}

2.2. Coffre-fort de paiement

SDK Web

Laissez le SDK Web résoudre les informations d'identification Apple Pay à partir du backend DEUNA à l'aide de votre publicApiKey et (éventuellement) un orderToken.

Pour plus d'informations, consultez le getWalletsAvailable documentation.

const { DeunaSDK } = window; // from https://cdn.deuna.io/web-sdk/v1.6/index.js

await DeunaSDK.initialize({
  env: 'sandbox',
  publicApiKey: '<YOUR_PUBLIC_API_KEY>',
});

// If Apple Pay is available, it should return it within an array, such as: ["APPLE_PAY"]
const available = await DeunaSDK.getWalletsAvailable();

if (available.includes('APPLE_PAY')) {
  // Render button for Apple Pay and append a listener (EXAMPLE)
  btn.addEventListener('click', () => {
    deuna.initElements({
      types: [{ name: 'APPLE_PAY' }],
      orderToken: '<order-token>', // REQUIRED FOR MERCHANTS
      userInfo: {
        email: '<email>',
        firstName: '<firstName>',
        lastName: '<lastName>',
      },
      callbacks: {
        // Called after user approves the Google Pay sheet.
        // Send the token to your backend, return the result.
        onSuccess: async (payload) => {
          const cardId = payload.data.id;
          // use the cardId to process payment
        },
        onError: (error) => {
          console.error('Payment failed:', error.metadata.message);
        },
      },
    });
  });
} else {
  console.error('Apple Pay is not available on this device.');
}

SDK iOS

Conditions préalables au portefeuille Apple Pay (iOS)

Pour utiliser Apple Pay Wallet avec le SDK sur iOS, assurez-vous que tous les éléments suivants sont correctement configurés.

1. Configuration de l'application et de l'équipe

   • Votre application doit être signée avec un Équipe de développeurs Apple ça a Apple Pay activé.
   • La cible PRODUCT_BUNDLE_IDENTIFIER doit correspondre à App ID configuré dans Apple Developer.
   • L'application doit être installée sur un véritable appareil iOS (Apple Pay ne fonctionne pas entièrement dans le simulateur).

2. Configuration de l'ID marchand

   • Créez ou utilisez un identifiant marchand dans Apple Developer (exemple : marchand.test.deuna.dev.pay).
   • Attribuez cet identifiant de marchand à l'identifiant d'application de l'application sous Identifiants > ID d'application > Apple Pay.
   • Dans Xcode, activez Signature et fonctionnalités > Apple Pay et sélectionnez le même identifiant marchand.

3. Certificats requis
   Pour l'ID marchand utilisé par le SDK, vous devez avoir :

   • Certificat de traitement des paiements Apple Pay (obligatoire pour le traitement des jetons Apple Pay dans l'application).

4. Profils de provisionnement

   • Régénérez les profils d’approvisionnement après avoir modifié les fonctionnalités Apple Pay ou les attributions d’ID marchand.
   • Réinstallez l'application après les modifications de profil/capacité (Nettoyer le dossier de construction + supprimer l'application de l'appareil + réinstaller).

5. Exigences de cohérence SDK/backend

   • L'ID marchand renvoyé par les informations d'identification backend (external_merchant_id) doit correspondre exactement à l'ID marchand activé dans le droit de l'application.

   • Le flux du portefeuille SDK doit inclure le contexte utilisateur (userInfo) lorsque votre backend l'exige pour renvoyer userToken et userId.

   • Si userToken/userId sont manquants, la tokenisation peut échouer même si l'interface utilisateur Apple Pay s'ouvre.

Étape 1 — Vérifier la disponibilité Appelez getWalletsAvailable() une fois avant l’étape de paiement. Le SDK valide à la fois la configuration du marchand DEUNA et la disponibilité d'Apple Pay sur l'appareil.

import DeunaSDK

let deunaSDK = DeunaSDK(
    environment: .sandbox,
    publicApiKey: "YOUR_PUBLIC_API_KEY"
)

deunaSDK.getWalletsAvailable(
    params: GetWalletsAvailableParams(
        orderToken: "<order-token>", // optional at this stage
        userInfo: DeunaSDK.UserInfo(
            email: "user@example.com",
            firstName: "Jane",
            lastName: "Doe"
        ) // recommended for wallet auth flows
    )
) { wallets, error in
    if let error = error {
        // handle fetch error
        return
    }

    let applePayAvailable = wallets.contains(.applePay)
    // show or hide your Apple Pay button based on applePayAvailable
}

getWalletsAvailable() met en cache le résultat. Les appels suivants renvoient immédiatement les portefeuilles mis en cache, vous pouvez donc appeler en toute sécurité à chaque chargement d'écran.

Étape 2 – Lancez Apple Pay Lorsque l'utilisateur appuie sur votre bouton Apple Pay, appelez initElements avec APPLE_PAY comme type. Le SDK récupère les informations d’identification de la commande et lance la feuille Apple Pay native.

deunaSDK.initElements(
    userToken: "YOUR_ORDER_TOKEN", // required for apple pay wallet
    callbacks: ElementsCallbacks(
        onSuccess: { payload in
            // payload contains tokenized card data
        },
        onError: { error in
            // error.metadata?.code / message
        },
        onClosed: { _ in
            // user dismissed the sheet
        },
        onEventDispatch: nil
    ),
    closeEvents: [],
    userInfo: DeunaSDK.UserInfo(
        email: "user@example.com",
        firstName: "Jane",
        lastName: "Doe"
    ),
    styleFile: nil,
    types: [["name": "APPLE_PAY"]],
    language: nil,
    orderToken: "<order-token>",
    widgetExperience: nil,
    behavior: nil,
    fraudCredentials: nil,
    customUserAgent: nil,
    domain: nil
)

SDK React Native

Utilisez ce chemin lorsque vous souhaitez afficher directement une feuille Apple Pay native, sans WebView. Le SDK vérifie la disponibilité de l'appareil, récupère les informations d'identification Apple Pay à partir du backend DEUNA et lance la feuille de paiement. Le résultat est une charge utile de carte tokenisée envoyée à votre rappel onSuccess.

Prérequis :

• Activez la fonctionnalité Apple Pay dans la cible de votre application (Xcode → cible → Signature et capacités → + Capacité → Apple Pay).
• Ajoutez votre identifiant marchand sous cette fonctionnalité (par exemple marchand.io.votre-domaine.com).
• Le même identifiant de marchand doit être renvoyé par les informations d'identification DEUNA (external_merchant_id). Confirmez-le auprès de votre équipe de compte DEUNA.
• Dans Portail des développeurs Apple, cet identifiant de marchand doit avoir un certificat de traitement de paiement Apple Pay actif.
• Après tout changement de fonctionnalité ou de commerçant, régénérez vos profils d'approvisionnement et réinstallez l'application sur un appareil réel.

Exposition — déclarez le droit dans app.json et exécutez npx expo prebuild pour l'appliquer :

{
  "expo": {
    "ios": {
      "entitlements": {
        "com.apple.developer.in-app-payments": ["merchant.io.your-domain.com"]
      }
    }
  }
}

Réagir à la CLI native— ajoutez-le à ios/<AppName>/<AppName>.entitlements:

<key>com.apple.developer.in-app-payments</key>
<array>
  <string>merchant.io.your-domain.com</string>
</array>

import { useState, useEffect } from 'react';
import { DeunaSDK } from '@deuna/react-native-sdk';

// 1) Initialize the SDK
const sdk = new DeunaSDK({
  publicApiKey: '<YOUR_PUBLIC_API_KEY>',
  environment: 'sandbox', // 'production' | 'sandbox'
});

// 2) Check availability
const available = await sdk.getWalletsAvailable();

// 3) Launch
if (available.includes('apple_pay')) {
  sdk.initElements({
    orderToken: '<order-token>', // required
    types: [{ name: 'apple_pay' }],
    userInfo: { // required
      email: '<email>',
      firstName: '<firstName>',
      lastName: '<lastName>',
    },
    callbacks: {
      onSuccess: (payload) => {
        const cardId = payload?.card_id;
        // use cardId to process payment on your backend
      },
      onError: (error) => {
        console.error('Payment failed:', error.metadata.message);
      },
      onClosed: (action) => {
        console.log('Sheet dismissed by', action);
      },
    },
  });
}

4. Les pièges#

Référence rapide