Apple Pay

Accept Apple Pay payments through dLocal by collecting an Apple Pay payment token in your website or native iOS app and submitting it in a standard card payment request.

Overview

This guide covers dLocal's native Apple Pay integration through the Full API: collecting the Apple Pay payment token on web or iOS, choosing a token-decryption model, sending the resulting request to dLocal, and handling recurring and merchant-initiated transactions.

This guide does not describe a Smart Fields-managed Apple Pay component. If the merchant expects dLocal to manage the Apple Pay button and Apple-side setup inside Smart Fields, confirm product availability and timing with your Technical Account Manager (TAM) before making a commitment.

Before you start

Apple Pay integration has two independent parts: the Apple Pay frontend and merchant-session setup, and the backend payment request sent to dLocal. Before you integrate, determine who owns the Payment Processing Certificate and who decrypts the Apple Pay token — this decides the request shape, not whether the frontend is web or iOS.

For the list of parties involved and their responsibilities — customer, Apple, you as the merchant, your PSP or orchestrator, and dLocal — see Certificates and setup.

Apple Pay is supported on:

• Web, using Safari and ApplePaySession.
• Native iOS apps, using PassKit.

The backend request format can remain common across web and iOS. Only the frontend setup differs by channel.

Certificates and setup

Roles and responsibilities

The two Apple Pay certificates

The certificates serve different purposes and are independent — one certificate cannot replace the other.

Merchant ID setup

In Apple Developer, create or select the Merchant ID used for the dLocal integration.

If another PSP already processes Apple Pay for the same business, use a dedicated Merchant ID for the dLocal path — do not assume that one active Payment Processing Certificate can be shared across independent processors.

A Merchant ID and its Payment Processing Certificate are normally configured for the merchant and environment, not separately for each country. Confirm the required setup with dLocal when multiple legal entities, PSPs, or environments are involved.

Model A: dLocal decrypts the token

1. Provide dLocal with your merchant name or account identifier, the Apple Merchant ID, and the target environment.
2. Request a CSR through the agreed dLocal support or TAM process. Sandbox and production require separate certificate setup.
3. Upload the CSR in Apple Developer and create the Apple Pay Payment Processing Certificate for the correct Merchant ID.
4. Download the resulting .cer file.
5. Return the .cer file to dLocal through the agreed secure channel. Do not send certificate material through an unsecured channel.
6. Ask dLocal to confirm that the certificate is installed and mapped to the correct merchant and environment before sending live payments.

Model B: you, your PSP, or your orchestrator decrypts the token

1. Confirm that you, your PSP, or your orchestrator owns the Payment Processing Certificate and private key.
2. Complete Apple's certificate setup directly with that certificate owner.
3. Decrypt the Apple Pay token in the upstream component.
4. Send the resulting network token and cryptogram to dLocal using the Model B contract.
5. Confirm with your PSP or orchestrator which fields it forwards, how it preserves the cryptogram, and how it exposes the ECI.

No Payment Processing Certificate exchange with dLocal is required for Model B. You, or your PSP/orchestrator, remain responsible for your own Apple Developer account, Merchant ID, certificate, private key, and token decryption process.

Web domain verification

For web integrations:

1. Configure the checkout domain in Apple Developer under the Merchant ID used by the web payment flow.
2. Serve Apple's domain-association file from the exact path: https://<your-domain>/.well-known/apple-developer-merchantid-domain-association.
3. Serve the file over HTTPS without redirects.
4. Add and verify the domain for the correct Merchant ID.
5. Implement server-side merchant-session validation using your Merchant Identity Certificate.

If an existing PSP Merchant ID and the dLocal Merchant ID are in the same Apple Developer account, an already verified domain generally uses the same domain-association file — still add the domain to the new Merchant ID and complete the verification step. If the Merchant IDs are in different Apple Developer accounts, use separate subdomain configuration so each account can serve its own association file.

Native iOS entitlements

For native iOS:

1. Enable the Apple Pay capability for the App ID.
2. Add the correct Merchant ID to the application entitlements.
3. Use PassKit to create and present the payment request.
4. Test on a physical Apple device with Apple Pay configured.

Native iOS uses PassKit and entitlements. It does not use the web merchant-session validation flow.

<key>com.apple.developer.in-app-payments</key>
<array>
    <string>merchant.com.example.dlocal</string>
</array>

If the same Merchant ID is used for web and native iOS, the Payment Processing Certificate can cover both channels. iOS still uses PassKit entitlements, while web uses Apple Pay JS and merchant-session validation.

Payment flow

1. The customer taps the Apple Pay button in your website or native iOS app.
2. Apple presents the payment sheet and the customer authorizes the payment with Face ID, Touch ID, or the device passcode.
3. Apple generates the payment token and returns it to your frontend as payment.token.paymentData.
4. Your frontend forwards the token to your backend without parsing or re-serializing it.
5. Your backend sends the payment request to dLocal, using Model A (card.applepay_token) or Model B (card.network_token and card.cryptogram), depending on who decrypts the token.
6. dLocal processes the payment and returns the payment result to your backend and, when configured, a webhook notification.
7. Your backend notifies the customer that the payment was successful.

Step 1: Frontend integration

Web

Use Apple's Apple Pay on the Web documentation and Human Interface Guidelines for Apple Pay buttons and marks.

Your server must perform merchant-session validation using the Merchant Identity Certificate. After authorization, forward the payment token to your backend without changing its structure.

session.onpaymentauthorized = function (event) {
  const tokenData = event.payment.token.paymentData;

  // Send tokenData to your backend without parsing or re-serializing it.
  // Do not log tokenData.
};

Native iOS

Use Apple's PassKit documentation.

In the payment authorization callback, forward payment.token.paymentData to your backend without changing it.

func paymentAuthorizationViewController(
    _ controller: PKPaymentAuthorizationViewController,
    didAuthorizePayment payment: PKPayment,
    handler completion: @escaping (PKPaymentAuthorizationResult) -> Void
) {
    let tokenData = payment.token.paymentData

    // Send tokenData to your backend without parsing or re-serializing it.
    // Do not log tokenData.
}

Step 2: Backend integration

Apple Pay payments use the standard dLocal card payment endpoint. The request shape depends on who decrypts the Apple Pay token.

Canonical fields

Model A: dLocal decryption

Use Model A when dLocal owns the Payment Processing Certificate used for the token and decrypts the encrypted Apple Pay token.

Send the token received from Apple as card.applepay_token. Do not parse, reserialize, normalize, reorder, or otherwise transform the token object.

Submit a standard payment request via the https://api.dlocal.com/secure_payments endpoint using the following parameter values:

• payment_method_id should be CARD.
• card.applepay_token should be the JSON object obtained in the frontend integration step. Send a JSON object, not a string, in this parameter.

{
  "amount": 120.00,
  "currency": "BRL",
  "country": "BR",
  "payment_method_id": "CARD",
  "payment_method_flow": "DIRECT",
  "payer": {
    "name": "Ricardo Gomes",
    "email": "[email protected]",
    "document": "53033315550"
  },
  "card": {
    "wallet_type": "APPLE_PAY",
    "save": true,
    "applepay_token": {
      "version": "EC_v1",
      "data": "<APPLE_PAY_TOKEN_DATA>",
      "signature": "<APPLE_PAY_TOKEN_SIGNATURE>",
      "header": {
        "ephemeralPublicKey": "<EPHEMERAL_PUBLIC_KEY>",
        "publicKeyHash": "<PUBLIC_KEY_HASH>",
        "transactionId": "<APPLE_TRANSACTION_ID>"
      }
    }
  },
  "order_id": "ORDER_12345",
  "notification_url": "https://merchant.example/webhooks/dlocal"
}

Model A rules

• card.wallet_type is mandatory.
• card.applepay_token must use the canonical field name shown above.
• Forward the token exactly as received from Apple.
• Call dLocal immediately after customer authorization. Do not queue, batch, or intentionally delay the token.
• If you want dLocal to save the card credential and return a card token for future use, send card.save: true on the applicable Model A payment request.
• Do not retry the same token after a signature, key, decryption, or expiration error.
• Do not log the raw token or any decrypted output.

Model B: merchant or PSP decryption

Use Model B when you, your PSP, or your payment orchestrator owns the Payment Processing Certificate and decrypts the Apple Pay token before the request reaches dLocal.

Send the decrypted fields as a standard network-token card payment. The cryptogram is the one-time cryptographic value associated with the network token. It must be sent separately and preserved exactly as provided by the decrypting component.

{
  "amount": 120.00,
  "currency": "BRL",
  "country": "BR",
  "payment_method_id": "CARD",
  "payment_method_flow": "DIRECT",
  "payer": {
    "name": "Ricardo Gomes",
    "email": "[email protected]",
    "document": "53033315550"
  },
  "card": {
    "network_token": "<DPAN_OR_MPAN>",
    "cryptogram": "<APPLE_PAY_CRYPTOGRAM>",
    "wallet_type": "APPLE_PAY",
    "holder_name": "Ricardo Gomes",
    "expiration_month": 12,
    "expiration_year": 2028
  },
  "three_dsecure": {
    "eci": "05"
  },
  "order_id": "ORDER_12346",
  "notification_url": "https://merchant.example/webhooks/dlocal"
}

Model B rules

• card.wallet_type is mandatory even though dLocal does not decrypt the Apple Pay token.
• card.network_token is the network token extracted from the decrypted Apple Pay token. It is normally a DPAN for a standard CIT and may be an MPAN when Apple returns one for a qualifying recurring-payment request.
• card.cryptogram is the one-time cryptogram associated with that network token.
• three_dsecure.eci is transmitted separately from the card fields when it is provided by the decrypted Apple Pay payload and required by the API contract.
• Do not substitute a card PAN for the network token.
• Do not reuse the cryptogram for another authorization.

Choosing between the models

If your PSP or orchestrator's behavior is unclear, ask whether it forwards the raw Apple Pay token unchanged or decrypts it before sending the payment request — that answer determines the model.

Recurring and merchant-initiated transactions

Customer-initiated Apple Pay payments

A standard Apple Pay authorization is a customer-initiated transaction. The resulting payment credential includes a network token and a transaction-specific cryptogram.

The cryptogram is single-use for the authorization. Do not store it for later use and do not reuse it for a subsequent payment.

Request recurring behavior in the Apple Pay session

If recurring or MIT processing is in scope, request recurring behavior when creating the initial Apple Pay session. Apple exposes this through the recurringPaymentRequest property on the Apple Pay payment request:

• On iOS, set the recurring payment request on the PKPaymentRequest used by PassKit.
• On the web, set recurringPaymentRequest on the Apple Pay payment request used by ApplePaySession.
• Populate the recurring request with your billing description and recurring billing details required by Apple's current SDK/API contract.

Requesting recurring behavior does not guarantee that Apple or the issuer will return an MPAN. Validate the exact property names and required fields against Apple's current PassKit and Apple Pay on the Web documentation before implementing.

DPAN and MPAN

• DPAN is a device- and card-specific network token used for a customer-initiated Apple Pay authorization, with a fresh cryptogram for each transaction.
• MPAN is a merchant-specific network token that may be requested for recurring use, subject to Apple Pay, issuer, network, acquirer, and market support.

When the token is decrypted upstream in Model B, pass the network token, cryptogram, expiry, and three_dsecure.eci exactly as produced by the wallet or processor path. The network token may be a DPAN or, when returned for the recurring request, an MPAN. In Model A, dLocal receives the encrypted token and extracts the applicable values.

Card-on-File fields for MIT payments

For subsequent Merchant Initiated Transactions, send the corresponding Card-on-File fields in the card object:

The exact card.stored_credential_type depends on your use case. Use SUBSCRIPTION for fixed, regular billing and UNSCHEDULED_CARD_ON_FILE for non-fixed recurring charges. Other supported types include CARD_ON_FILE, INSTALLMENTS, and STANDING_ORDER.

For a subsequent MIT, send the corresponding Card-on-File flags described in dLocal's Merchant Initiated Transactions documentation, including the applicable card.stored_credential_type and card.stored_credential_usage values.

Recommended recurring-payment pattern

1. Initiate the first Apple Pay payment as a customer-initiated transaction.
2. Include recurringPaymentRequest in the initial Apple Pay session when recurring behavior is required.
3. For Model A, include card.save: true when you want dLocal to save the credential and return a card token for future use.
4. Store the resulting dLocal payment method, card token, and network payment reference according to the applicable security and stored-credential requirements.
5. Use the stored credential for later MITs with the required Card-on-File fields and network payment references.
6. Do not reuse the first payment's cryptogram.
7. Confirm the required combination of stored-credential fields and network references for the target acquirer.

Error handling

Apple Pay issues can originate in the Apple frontend, the dLocal API, or the downstream acquirer/issuer. Classify the error by layer before deciding what to retry.

Apple frontend and setup errors

dLocal API errors

Acquirer and issuer outcomes

An acquirer or issuer may decline an authorization even when Apple Pay tokenization and dLocal processing succeeded. Handle these outcomes using the standard dLocal payment status and status-detail contract.

• Do not retry a decline indiscriminately.
• Show the customer an appropriate payment-failure experience.
• Follow the configured payment-status and webhook flow.
• Contact dLocal if the decline pattern suggests a market, network-token, wallet-flagging, or acquirer configuration issue.

Getting ready to go live

Apple Pay availability is not global by default. Before launch, confirm support for each intended combination of country and settlement configuration, card network, acquirer or downstream route, network-token processing, Apple Pay wallet flagging, and customer/issuer conditions — do not assume a country is fully supported merely because Apple Pay is available there.

Contact your Technical Account Manager (TAM) to confirm the countries, networks, and acquirer routes in scope, and to check that your certificates, domain verification, and entitlements are correctly configured before switching to production.