Apple Pay

Apple Pay is a virtual wallet. It allows the shopper to make payments in e-commerce stores and apps using, in a practical and safe way, their credit and debit cards stored in their Apple accounts and devices.

Prerequisites

In order to use Apple Pay, your store must be previously registered in the AppleID program. In addition to that, you must also:

1. Enroll your store through this URL, following all steps required by Apple.
2. Follow the procedure set out in this document, in order to complete your integration with Apple.
3. Hire API E-commerce Cielo;
4. Hire Cielo 3.0 as the acquirer;
5. Integrate with Gateway.

Notice: The following integration should be used when sending encrypted card data. If the merchant sends the authorization request with decrypted card data, please refer to decrypted card.

PART 1: Configuring the Merchant Identifier

In this initial step, you will need to create a merchant identifier for your store. Once created, the merchant identifier must be sent to Cielo in a request for a ".CSR" certificate. The ".CSR" certificate created by Cielo must be used to create a new certificate with Apple, the ".CER" certificate, which will serve as a follow-up to the second stage of the process.

Step 1 - Create a Merchant Identifier

The merchant identifier must be created through the Apple Developer website as follows:

1. In the "Certificates, Identifiers & Profiles" section, select "Identifiers" in the side menu, and then click the (+) button next to the title:

2. Select the "Merchant IDs" option and then click Continue:

3. Enter a value in the "Description" and "Identifier" fields, following your specifications, and click Continue:

4. To finish, click on Register:

Step 2 - Request the ".CSR" Certificate

To request Cielo to generate the certificate in ".CSR" format, contact our Support Team and enter:

1. The Merchant Identifier created in "Step 1";
2. The Merchant ID of your Cielo store in production.

Our team will return with the ".CSR" file within 48 business hours.

Step 3 - Create a ".CER" Certificate

1. In the "Certificates, Identifier & Profiles" section, select "Identifiers" on the side menu.
2. Use the filter on the top right corner ("App IDs"), to locate the "Merchant IDs" item:

3. Select the recently created identifier:

4. In the "Apple Pay Payment Processing Certificate" block, click the Create Certificate button right after the short description:

4. Choose "No" in "Edit or Configure Merchant ID":

6. In the dialog box, click Choose File and choose the ".CSR" certificate sent by Cielo:

6. Click Continue:

6. Click Download and save the ".CER" file:

For more details on the process, access Apple's Developer Account Help.

PART 2: Integrating with Apple Pay

Most of the process of enabling the "Pay with Apple Pay" button in your app or site is performed during your wallet integration. For that reason, we recommend you to follow the instructions available in the Apple Developer Documentation website for Apple's self-service implementation.

At the end of the process performed in the Apple API, you will receive a JSON containing two important fields that will be used in "PART 3": the paymentData.data and the ephemeralPublicKey.header.EphemeralPublicKey fields.

{
  "applePayData": {
    "paymentData": {
      "version": "EC_v1",
      "data": "as01vRj+n9crY2vome7zc+u7Tz0+qg2La/8IUHpJIjFN6ThhUqLnSrskQHTrEbcYPiMksFK0+ddo9sZu70uJQJH1I+44N6PrVhilNDem97vOXq2VYDXiVJ27F/Q9wGQDgZBeGcZ6Pml9SIelHqUauBcQoOatrlnWPUL8kbdpT8WqgzXyaCh7oeTz=z6++rp/ofjvSjnGtOqAUsnrzvw4uzkcyKUSsfROdJ6B/Xzgu/T9fMIr5UxXD2DPF1SNh3ydEJABKz4HFjDW7ObvbQeua4GYxJdpQLpI3NgUbJy91E/LOyb/+PcCtO+0=a41tBrfnTTF9qsPuCIw8HWIEEKSRofn27NTofxev/i+nHEfqEtqNrN/epIvhzceD/gDiGetfiLKMzf94ARmpWUAMC==",
      "signature": "(…)",
      "header": {
        "ephemeralPublicKey": "MFkwEwZJKoZIzj0CAQYIKo12zj0DAQcDQgAEo+ReGClSmQ4hDJD1yh9nci3V4l7kPm2AQtKZMMvuNS0iK5sn/1A9l3kw1B1xCqOycZmnPSng7p5hpTvrei1BCA==",
        "publicKeyHash": "KXN06+BtJu6yEfF9zDhr7f4M/2HwVybnx0FGfC520gB=",
        "transactionId": "71c5b61c3791546e94d2b4893a6c69aaac2ab86b5c113c83a7d89057906a9b5f"
      }
    },
    "paymentMethod": {
      "displayName": "MasterCard 1212",
      "network": "MasterCard",
      "type": "credit"
    },
    "transactionIdentifier": "81C5B61C3791646E94D2B4893A6C69BBBC2AB86B5C363C83A7D89057906A9BAC"
  },
  "x_document": "24562608994",
  "x_name": "João da Silva"
}

Important Note

⚠️

Warning

During Apple's implementation, there will be a reference to the ".CER" certificate, generated during STEP 1, to encrypt the data while communicating with Apple. In the integration flow do not implement the process of decrypting the data returned by Apple as this work is done by the API E-commerce Cielo.

PART 3: Integration with API E-commerce Cielo (decryption and authorization)

Authorization with the Apple Pay token happens in the same way as standard credit card authorization. However, instead of providing card details openly, the token received by Apple Pay must be provided, as in the example below:

Request

{
   "MerchantOrderId": "2017051002",
   "Customer": {
     (…)
   },
   "Payment": {
      "Type": "CreditCard",
      "Amount": 1000,
      "Installments": 1,
      "Currency": "BRL",
      "Wallet": {
         "Type": "ApplePay",
         "WalletKey":"['paymentData.data']",
         "AdditionalData": {
            "EphemeralPublicKey": "['ephemeralPublicKey.header.EphemeralPublicKey']"
         }
      }
   }
}

Response

{
    "MerchantOrderId": "2017051002",
    "Customer": {(…)
    },
    "Payment": {
        (…)
        "CreditCard": {
            (…)
        },
        (…)
        "Wallet": {
            "Type": "ApplePay",
            "WalletKey": "as01vRj+n9crY2vome7zc+u7Tz0+qg2La/8IUHpJIjFN6ThhUqLnSrskQHTrEbcYPiMksFK0+ddo9sZu70uJQJH1I+44N6PrVhilNDem97vOXq2VYDXiVJ27F/Q9wGQDgZBeGcZ6Pml9SIelHqUauBcQoOatrlnWPUL8kbdpT8WqgzXyaCh7oeTz=z6++rp/ofjvSjnGtOqAUsnrzvw4uzkcyKUSsfROdJ6B/Xzgu/T9fMIr5UxXD2DPF1SNh3ydEJABKz4HFjDW7ObvbQeua4GYxJdpQLpI3NgUbJy91E/LOyb/+PcCtO+0=a41tBrfnTTF9qsPuCIw8HWIEEKSRofn27NTofxev/i+nHEfqEtqNrN/epIvhzceD/gDiGetfiLKMzf94ARmpWUAMC==",
            "AdditionalData": {
                "EphemeralPublicKey": "MFkwEwZJKoZIzj0CAQYIKo12zj0DAQcDQgAEo+ReGClSmQ4hDJD1yh9nci3V4l7kPm2AQtKZMMvuNS0iK5sn/1A9l3kw1B1xCqOycZmnPSng7p5hpTvrei1BCA=="
            }
        },
        (…)
        "Links": [
            (…)
        ]
    }
}

The wallet authorization response will have the same fields presented in API Reference, however with the addition of the Payment.Wallet node repeating the same fields used in the authorization, as described above.