Documentation

Apple Pay via direct API

This guide covers how to integrate Apple Pay directly with DEUNA's API. Direct integration gives you full control over the payment flow, making it ideal for merchants who need custom implementations or have existing payment systems. This integration supports one-time payments.

šŸ“˜

Apple Pay via API is only supported in Purchase V2. Purchase V1 is not supported.

Apple Pay with DEUNA

The following is the standard process for an Apple Pay purchase with DEUNA:

  1. Get the payment methods
  2. Initialize the Apple Pay Web SDK
  3. Purchase with Apple Pay

1. Get the payment methods

Retrieve the Apple Pay credential ID and SDK configuration parameters.

ā†’ See Get Payment Methods API reference

Response

{
  "data": [
    {
      "allow_installments_plan": true,
      "credentials": {
        "external_merchant_id": "merchant.test.io.deuna.pay"
      },
      "enabled": true,
      "extra_params": {
        "allowed_auth_methods": [
          "supports3DS"
        ],
        "allowed_card_networks": [
          "visa",
          "masterCard",
          "amex"
        ],
        "merchant_name": "Test DEUNA"
      },
      "id": "ef2319fe-f88d-4d8d-b4d1-e4fa08f18651",
      "method_type": "card_wallet",
      "payment_provider": "apple_pay",
      "processor_name": "apple_pay"
    }
  ]

2. Initialize the Apple Pay Web SDK

Refer to the Apple Pay Web SDK documentation for the full reference.

šŸ“˜

The snippet below shows the complete Apple Pay SDK flow. If you're already familiar with the Apple Pay Web SDK, you can skip to step 3 in the code comments (onvalidatemerchant) ā€” that's where the DEUNA-specific integration happens.

Import the Apple Pay JS SDK

Add the following script to your page:

<script src="https://applepay.cdn-apple.com/jsapi/1.latest/apple-pay-sdk.js" crossorigin=""></script>
<script src="https://applepay.cdn-apple.com/jsapi/1.latest/apple-pay-sdk.js" crossorigin=""></script>

Complete integration example

// 1. Check availability
if (!window.ApplePaySession || !ApplePaySession.canMakePayments()) {
  // Apple Pay not available ā€” hide the button or show a fallback
}

// 2. Initialize the session on button click (must be inside a user gesture)
// Use the values returned by the Get Payment Methods endpoint
const request = {
  countryCode: 'MX',
  currencyCode: 'MXN',
  supportedNetworks: ['visa', 'masterCard', 'amex', 'discover'], // from extra_params.allowed_card_networks
  merchantCapabilities: ['supports3DS'],                          // from extra_params.allowed_auth_methods
  total: { label: 'Your Store Name', amount: '1.00', type: 'final' },
};

const session = new ApplePaySession(3, request);

// 3. Validate the merchant
// The credential-id comes from the `id` field in the Get Payment Methods response
session.onvalidatemerchant = async (event) => {
  const response = await fetch(
    'https://api.{env}.deuna.io/wallet/credentials/{credential-id}/payment-session',
    {
      method: 'POST',
      headers: {
        'X-Merchant-Id': '{merchant-id}',
        'X-Store-Code': '{store-code}',
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        validation_url: event.validationURL,
        domain: '{your-domain}',
      }),
    }
  );

  const { data } = await response.json();
  session.completeMerchantValidation(data);
};

// 4. Handle payment authorization
// Once the customer authorizes the payment, send the token to DEUNA
// Use applePayToken in step 3 ā€” Create Card or Purchase V2
session.onpaymentauthorized = (event) => {
  const applePayToken = event.payment;

  session.completePayment(ApplePaySession.STATUS_SUCCESS);
};

session.begin();
āš ļø

ApplePaySession must be instantiated synchronously within a user gesture (e.g. a button click). Calling it outside of one will throw an error.

3. Purchase with Apple Pay

Once the customer authorizes the payment on their Apple device, the onpaymentauthorized event fires and delivers an encrypted card token via event.payment. This token must be sent as-is, without any modification, to DEUNA.

3.1 Create Card

The token from event.payment is sent to the Create Card endpoint, which returns a card_id that can be reused in the purchase.

ā†’ See Create Card API reference

{
  "apple_pay": {
    "paymentData": {
      "token": {
        "transactionIdentifier": "7a94479858348...",
        "paymentMethod": {
          "type": "debit",
          "displayName": "Visa 7553",
          "network": "Visa"
        },
        "paymentData": {
          "data": "EOeLQTsv8X7f...",
          "header": {
            "publicKeyHash": "MpXcCgm...",
            "ephemeralPublicKey": "MFkwEwYH...",
            "transactionId": "7a94479858348..."
          },
          "version": "EC_v1"
        }
      }
    }
  },
  "credential_source": "apple_pay"
}

3.2 Purchase with Card ID

Use this option when the card has already been tokenized via Create Card. This is a standard Purchase V2 request using the card_id returned by the Create Card endpoint ā€” no Apple Pay token needed.

ā†’ See Purchase V2 API reference

{
  "order_token": "{order-token}",
  "order_type": "DEUNA_CHECKOUT",
  "payer_info": {
    "email": "[email protected]",
    "card_holder_dni": "12345678"
  },
  "payment_source": {
    "method_type": "credit_card",
    "card_info": {
      "card_id": "{deuna-card-id}"
    }
  }
}

3.3 Direct Purchase

This is for the cases that the card are not tokenized. The token from event.payment is sent directly in the purchase request.

ā†’ See Purchase V2 API reference

{
    "order_token": "{{order-token}}",
    "order_type": "DEUNA_CHECKOUT",
    "payer_info": {
        "email": "{{random_user}}@testuser.com",
        "card_holder_dni": "12345678"
    },
    "payment_source": {
        "method_type": "credit_card",
        "method_type_specific_fields": {
            "apple_pay": {
                "token": {
                    "paymentMethod": {
                        "network": "MasterCard",
                        "displayName": "MasterCard 7599",
                        "type": "credit"
                    },
                    "transactionIdentifier": "349ebc0637f7b2c26a9b45263f08de...",
                    "paymentData": {
                        "data": "FYiIWVcLoParLZ6...",
                        "signature": "MIAGCSqGWdy...",
                        "header": {
                            "publicKeyHash": "MpXcCgmmfOwEAU/hVunjLHnu737QA6QvJ1m8Q=...",
                            "ephemeralPublicKey": "MFkwEwYHKoZIzj0CAQA4n0ORkDfDyLLMzg==...",
                            "transactionId": "349ebc0637f7b2c0f69b139aeeda31c08de..."
                        },
                        "version": "EC_v1"
                    }
                }
            }
        }
    },
    "anti_fraud_info": {
        "device": {
            "id": "eyJPUEVOUEFZIjoiIiwiTUVSQ0FET1BBzAzLTk2NjRkYzE3MWQzYiJ9..."
        }
    }
}

Response

{
  "order_type": "DEUNA_CHECKOUT",
  "order_token": "4598f493-de86-4fe0-b9fd-c4c6c9847e39",
  "order": {
    "order_id": "DEUNA_CHECKOUT_b6a5c0b6-3df9-4b3b-b778-7086c190062b",
    "currency": "MXN",
    "total_amount": 10000,
    "display_total_amount": "MXN 100,00",
    "status": "succeeded",
    "payment": {
      "data": {
        "status": "processed"
      }
    }
  }
}

Updated about 10 hours ago