Apple Pay merchant setup

Note

Payment processing certificates expire every 25 months.
Domain verification expires when its SSL certificate expires.

Client-side integration

Refer to the official Apple documentation: Offering Apple Pay in Your App

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": {
        "merchantIdentifier": "merchant.com.osl-test",
        "displayName": "OSL PAY",
        "merchantCapabilities": [
            "3DS",
            "debit",
            "credit"
        ],
        "supportedNetworks": [
            "visa",
            "masterCard"
        ],
        "requiredBillingContactFields": [
            "postalAddress"
        ],
        "countryCode": "GB",
        "currencyCode": "EUR",
        "requiredShippingContactFields": [],
        "shippingMethods": []
    }
}

Retrieve the encrypted raw message for Apple Pay payment

The raw message format for 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 for Apple Pay billing information is as follows:

{
    "address": {
        "postalCode": "215831",
        "street": "xx Building 441041",
        "country": "Singapore",
        "city": "Shanghai",
        "ISOCountryCode": "SG"
    },
    "name": {
        "middleName": "",
        "familyName": "Bruce",
        "givenName": "Li"
    }
}

Pass Apple Pay parameters to OSL Pay

When creating an order, merchants need to provide both the Apple Pay payment information and billing information to OSL Pay. Some billing fields in Apple Pay differ from OSL Pay’s field names and require mapping. The mapping rules are as follows:

familyName  ->  lastName
givenName ->  firstName
ISOCountryCode -> countryCode
country -> state
postalCode -> zip
street -> addressLines

The Apple Pay payment information must be decrypted. Currently, 2 methods are supported:

Merchant-side decryption

Refer to the Apple Pay documentation: Payment token format reference Merchants integrate the Apple SDK, invoke Apple Pay, and decrypt the Apple Pay request parameters locally before sending the decrypted data to OSL Pay.

The decrypted data format is as follows:

{
    "applicationExpirationDate": "190131",
    "applicationPrimaryAccountNumber": "370295XXXXX5435",
    "currencyCode": "840",
    "deviceManufacturerIdentifier": "XXXXXXXXXX",
    "paymentData": {
        "emvData": "nycBgJ82AgDCnyYIG2vuQydGkMafEAcGhgEDoLABXzQBAJUFgAABAACCAhzAnwMGAAAAAAAAnxoCCECaAxQQBJwBAJ83BLnvab4="
    },
    "paymentDataType": "EMV",
    "transactionAmount": 100
}

OSL Pay-assisted decryption

Merchants integrate the Apple SDK according to the official documentation and obtain the encrypted payment message. The encrypted message is then sent directly to OSL Pay via the OpenAPI, and OSL Pay performs the decryption.

Since OSL Pay performs the decryption on behalf of the merchant, the merchant must provide their certificate and payment private key to OSL Pay. These credentials are securely encrypted and stored by OSL Pay.

Additionally, the merchant must provide their ID to OSL Pay, which does not require encryption.

Pros and cons of different decryption methods

Merchant-side decryption

Pros:

Full control: The merchant manages the entire decryption process. Cons:
Complexity: Requires writing and maintaining decryption code, increasing development and testing effort.
Security risk: Managing private keys and certificates securely can be challenging.
Compliance pressure: Must meet PCI DSS requirements.

OSL Pay-assisted decryption

Pros:

Simplified process: Merchants only provide the certificate and private key; OSL Pay handles decryption, saving development time.
Security assurance: OSL Pay manages the decryption workflow with professional security measures.
Reduced compliance burden: OSL Pay ensures compliance, relieving the merchant of responsibility. Cons:
Third-party dependency: Merchants rely on OSL Pay’s service stability.
Privacy risk: Merchants must share certificates and private keys with OSL Pay, which introduces some privacy considerations.