Apple Pay merchant setup

Register an Apple Developer Account
Enroll in the Apple Developer Program
Configure Apple Pay for your merchant account:
1. Create an Apple Pay Merchant ID
2. Create a Payment Processing Certificate
3. Create a Merchant Identity Certificate Learn more about the certificate creation reference
Domain configuration
1. Register a merchant domain
2. Verify the merchant domain
Server configuration
1. Allow Apple Pay IP Addresses (note the difference between sandbox and production domains)
2. Allow Apple IP Addresses for Domain Verification (note sandbox vs. production difference)

Note

Payment processing certificates expire every 25 months.
Merchant identity certificates expire every 25 months.
Domains must be publicly accessible HTTPS domains for Apple Pay domain verification.
Domain verification expires if the SSL certificate expires.
Apple Pay cannot be used while screen sharing or taking screenshots, otherwise the payment flow may be blocked.

Web Integration

Refer to the official Apple Pay demo: Apple Pay on the Web Interactive Demo

Note

For the Apple Pay payment button, please use the official SDK provided by Apple. You can use the tag in the browser. However, in React code, this tag cannot be used directly, so you should use the native createElement method to implement it. Here’s a reference:

useEffect(() => {
    if (!payButtonRef.current) return;

    const button = document.createElement('apple-pay-button');
    button.setAttribute('buttonstyle', 'black');
    button.setAttribute('type', 'pay');
    button.setAttribute('locale', locale);
    button.addEventListener('click', paymentBegin);
    payButtonRef.current.appendChild(button);

    return () => {
      button.removeEventListener('click', paymentBegin);
    };
  }, []);
  
  <div ref={payButtonRef} onClick={paymentBegin} className="h-48 w-full" />

Due to Safari security restrictions, using window.open or location.href='xxx' may fail to load the page. You can try alternative methods:

Server-side integration

Invoke Apple Pay Merchants can either construct the invocation parameters according to Apple Pay documentation or call OSL Pay’s API to obtain the parameters, and then pass the parameters to the client to request Apple Pay. Call the OSL Pay API to get the Apple Pay invoke parameters (https://openapitest.osl-pay.com/api/v1/config/waken/query), which will return the following data:

{
    "provider": "apple_pay",
    "data": {
        "countryCode": "GB",
        "supportedNetworks": [
            "visa",
            "masterCard",
            "amex",
            "chinaUnionPay"
        ],
        "requiredBillingContactFields": [
            "postalAddress"
        ],
        "merchantCapabilities": [
            "supports3DS",
            "supportsEMV"
        ],
        "total": {
            "label": "OSL PAY"
        }
    }
}

Domain verification After the client requests Apple Pay using the invoke parameters, Apple Pay will return the domain that needs to be verified. The client must pass this parameter to the backend, which will request Apple Pay to verify the domain. Once the domain verification is successful, Apple Pay can be fully invoked.
Retrieve encrypted Apple Pay payment information The format of the original encrypted Apple Pay payment information is as follows:

{
    "data": "2DzU9u6byIY4qCs3lW4KgK3JWC6Ac+x28Ck5PLCjQPJ+y6vCrEXqmBfdEm8uWT02lpGtYeo51WVOevuyX6cFguHIUzsCrhdvfSCV456G768lzbH6SwEk5ST/qiKI/rTQbeDAle7l5Njlil50hmVUTLqhmhS3ouC43+rf2NDR7y7Fr+JVkkHBqdEcONJnqFms+SfEPdNXNVccITdO/dkw3FAkXIy1lro1upZkjZSFdm5HCApRkDiTv6FLiUz/osKZsYKWQV+IEZdXjZZ3WF7Zmn8tOvwZdZy4NMq39oQFVt7VA7VRWs/RgPl0BK2xiGqTz1YFW+J6XE62MfW7yc8tFsJlIwTW7uCHY2ENwTFn11flN+7R64PSfPobUWlMjI3jiY+hMtynSkuSUImxXV0J76N4ItX60ce4E8o3ipZe0v6hLjNapr4Y6OcmTKnG0hy0X3f/cczN1K/YXLWkFco=",
    "header": {
        "ephemeralPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEtxcxQw0rS30y28P45MB/owA1H9OSeTIkiiuACxEpY7usak/He4suC446HPrPimw4+vZKO2nx+Ntyu13uALT3bA==",
        "publicKeyHash": "spzGX6upCJhx5UD8vCo1+LcIi7+fkxEUaVmhbX18cJM=",
        "transactionId": "79ccd07eb432f80067d8e5bbc4c38ee1def7fcc1827f6ba5b63bf47b283ebf89"
    },
    "signature": "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",
    "version": "EC_v1"
}

Retrieve Apple Pay billing information The format of the Apple Pay billing information is as follows:

{
    "administrativeArea": "CA",
    "country": "United States",
    "countryCode": "US",
    "familyName": "",
    "givenName": "",
    "locality": "San Francisco",
    "phoneticFamilyName": "",
    "phoneticGivenName": "",
    "postalCode": "94114",
    "subAdministrativeArea": "",
    "subLocality": ""，
    "addressLines": [
    "123 Main St",
    "Apt 4B"
    ]
}

Pass Apple Pay parameters to OSL Pay When placing an order, the merchant needs to pass the Apple Pay payment information and billing information to OSL Pay. The Apple Pay payment information needs to be decrypted, and OSL Pay supports 2 decryption methods: merchants can either decrypt the data themselves or allow OSL Pay to assist with the decryption. The decryption method was explained earlier. Additionally, some fields in the Apple Pay billing information do not match the field names used by OSL Pay, so they need to be mapped according to the following rules:

givenName -> firstName
familyName -> lastName
postalCode -> zip
administrativeArea -> state
locality -> city