# Apple Pay™

<img height="131" width="212" alt="apple pay logo" title="Apple Pay logo" src="https://static-devportal-ux.sensedia-eng.com/Pagonxt/staging/documentations/applepay-logo-1766428922455-ek5n9qou.png" />

Apple Pay™ is a digital wallet that allows customers to pay using credit or debit cards saved in their Apple Wallet. Instead of sharing card details directly with the merchant, Apple Pay generates a **secure payment token** representing the customer's payment information. This tokenization process helps protect sensitive card data during the transaction.

Apple Pay enables customers to perform **fast and secure payments with a single interaction** on websites (Safari) or iOS and macOS applications using any card linked to their Apple Wallet.

## How Apple Pay Works with Getnet

When a customer chooses Apple Pay during checkout, the following flow occurs:

1. The customer selects **Apple Pay** as the payment method.
2. Apple Pay returns an **encrypted payment token** (`pkPaymentToken`) containing the customer's payment credentials or the card credentials stored in the customer's Apple Wallet.
3. The merchant sends the required Apple Pay payment data to **Getnet** as part of the payment request.
4. Getnet processes the transaction through the configured payment processor or card network.
5. The authorization result is returned to the merchant.

## Integration Overview

To process Apple Pay payments with Getnet, the integration involves two main components:

1. [Integrating the Apple Pay API](https://developer.apple.com/apple-pay/implementation/) in your application or website.
2. Sending the required Apple Pay payment data to Getnet for payment processing.

After integrating with Apple Pay, you can display the **Apple Pay button** in your checkout and request payment information from your customers.

If you offer Apple Pay as a payment method to your customers, use only official Apple Pay brand assets according to Apple's brand guidelines. Do not modify the colors, proportions, layout, or appearance of Apple Pay assets.

* Include the [Apple Pay Identity Guidelines within your websites](https://developer.apple.com/design/human-interface-guidelines/apple-pay)
* Include the [Apple Pay Identity Guidelines within your iOS app](https://developer.apple.com/apple-pay/marketing/)

## Requirements

Before integrating Apple Pay, ensure the following:

* Apple Pay payment with Getnet is available only in **Brazil** and **Spain**.
* Your integration complies with the [Apple Pay Acceptable Use Policy](https://developer.apple.com/apple-pay/acceptable-use-guidelines-for-websites/) and [Terms of Service](https://developer.apple.com/apple-pay/terms/).
* Your frontend environment must be served over **HTTPS** to initialize the Apple Pay SDK.
* Before going live, you must complete the **domain verification** and **certificate setup** in the Apple Developer Portal (see Step 2 below).
* Your backend must be able to send the required payment data to Getnet according to the selected processing scenario.

## Integration Steps

### Step 1: Integrate with Apple Pay

Follow Apple's official documentation to implement the Apple Pay API:

* Web integration (Safari): [https://developer.apple.com/documentation/apple_pay_on_the_web](https://developer.apple.com/documentation/apple_pay_on_the_web)

* iOS/macOS integration (PassKit): [https://developer.apple.com/documentation/passkit/apple_pay](https://developer.apple.com/documentation/passkit/apple_pay)

This integration allows your checkout to display the Apple Pay button and request payment data from the user's device or Apple Wallet.

### Step 2: Configure your Apple Pay account

Before moving to production, you must complete the following in the [Apple Developer Portal](https://developer.apple.com/):

1. **Create a Merchant ID** — a unique identifier for your business.
2. **Domain verification** — host the `apple-developer-merchantid-domain-association` file provided by Apple at `https://yourdomain.com/.well-known/apple-developer-merchantid-domain-association`.
3. **Payment Processing Certificate**:
   1. **Obtain the CSR**: Log in to your Getnet Merchant Portal (or contact your account manager) to download the specific `.csr` file for Apple Pay.
   2. **Apple Portal Upload**: In the Apple Developer Portal, go to your Merchant ID settings, select **Create Certificate** under Payment Processing Certificate, and upload the Getnet `.csr` file.
   3. **Download & Handover**: Apple will generate a `.cer` file; download this and upload it back into the Getnet Merchant Portal to complete the handshake.
4. **Merchant Identity Certificate** — generate this to allow your server to authenticate with Apple's servers during the payment session (Merchant Validation).

These steps ensure your website or application is authorized to request Apple Pay payments.

### Step 3: Tokenize and process the payment

Once the customer authorizes the payment:

1. Apple Pay returns a **payment token** (`pkPaymentToken`) to the merchant.
2. Your system sends the required Apple Pay payment data to **Getnet**.
3. Getnet processes the transaction through the configured payment processor or card network.
4. Getnet returns the authorization result to the merchant.

### Merchant Validation

Before the Apple Pay payment sheet appears, your frontend must perform a **Merchant Validation** step. The `onvalidatemerchant` event is triggered when the Apple Pay session starts. Your frontend forwards the `validationURL` to your backend, which then performs an authenticated POST to Apple's servers using your **Merchant Identity Certificate** (mutual TLS).

#### Backend request to Apple

Your backend must POST to the `validationURL` received from the frontend with the following JSON body:

| Field | Description | Example |
|---|---|---|
| `merchantIdentifier` | Your Apple Merchant ID. | `"merchant.com.your-store"` |
| `displayName` | Name shown on the Apple Pay sheet (max 64 characters). | `"Your Store"` |
| `initiative` | `"web"` for Apple Pay on the Web, `"messaging"` for in-app messaging. | `"web"` |
| `initiativeContext` | The fully qualified domain that hosts the checkout. | `"checkout.yourdomain.com"` |

The TLS connection must present your **Merchant Identity Certificate** issued by Apple. Apple rejects calls that are not authenticated by this certificate.

Apple returns an opaque `merchantSession` object. Pass it back to the frontend unchanged.

<Callout type="note">

Each `merchantSession` is valid for a short window (around 5 minutes) and is single-use. Do not cache.

</Callout>

#### Frontend handler

```javascript
session.onvalidatemerchant = async (event) => {
  // POST event.validationURL to your backend.
  // The backend completes the mTLS handshake with Apple
  // and returns Apple's merchantSession object.
  const merchantSession = await callYourBackend(event.validationURL);
  session.completeMerchantValidation(merchantSession);
};
```

#### Backend example (Node.js)

```javascript
import https from 'https';
import fs from 'fs';

async function validateMerchant(validationURL) {
  const cert = fs.readFileSync('./merchant_identity.pem');
  const key = fs.readFileSync('./merchant_identity.key');

  const body = JSON.stringify({
    merchantIdentifier: 'merchant.com.your-store',
    displayName: 'Your Store',
    initiative: 'web',
    initiativeContext: 'checkout.yourdomain.com'
  });

  const response = await fetch(validationURL, {
    method: 'POST',
    body,
    headers: { 'Content-Type': 'application/json' },
    agent: new https.Agent({ cert, key })
  });

  return response.json(); // opaque merchantSession object
}
```

## Apple Pay authorization methods and Getnet processing models

Apple Pay supports card payments through two processing flows: a **decrypted flow** (DAN and CRYPTOGRAM) and an **encrypted flow** (Authorization Token).

Use the sections below to understand which Apple Pay authorization methods are supported and when to use Getnet's Authorization Token flow.

<Callout type="note">

Apple Pay does not have a `PAN_ONLY` equivalent. The card credentials provided by Apple Pay are always either a Device Account Number (DAN) with optional cryptogram or an encrypted `pkPaymentToken`.

</Callout>

### How to choose your flow

Use the following criteria to pick a processing model:

| Criteria | Recommended flow |
|---|---|
| You can decrypt Apple Pay tokens server-side and hold the required PCI-DSS scope. | DAN or CRYPTOGRAM (Decrypted) |
| You prefer Getnet to decrypt the token and don't want to manage the Payment Processing Certificate private key in your environment. | Authorization Token (Encrypted) |
| Spain (SCA required) and you cannot decrypt tokens. | Authorization Token (Encrypted) — Getnet handles 3DS data extracted from the token. |
| Brazil, non-SDWO checkout. | Any flow — CRYPTOGRAM provides the strongest authentication evidence. |
| Brazil, SDWO wallet operator scenario. | SDWO card data (Decrypted) or SDWO Authorization Token (Encrypted). |

If unsure, start with **Authorization Token** — it has the lightest PCI scope and works in both supported countries.

### Decrypting the Apple Pay payment token

The DAN and CRYPTOGRAM flows require the merchant to **decrypt** the `pkPaymentToken` server-side before sending data to Getnet. Apple Pay never returns the raw card number or cryptogram in plaintext to the frontend.

Decryption uses the **Payment Processing Certificate** private key configured during onboarding (see Step 2). After decrypting, extract the following fields from the decrypted payload and map them to the Getnet payment request:

| Apple Pay decrypted field | Getnet field | Notes |
|---|---|---|
| `applicationPrimaryAccountNumber` | `data.payment.card.number` | The Device Account Number (DAN) — not the cardholder's real PAN. |
| `applicationExpirationDate` | `data.payment.card.expiration_year`, `data.payment.card.expiration_month` | Returned as `YYMMDD`. Take chars 1–2 for `expiration_year`, chars 3–4 for `expiration_month`. |
| `paymentData.onlinePaymentCryptogram` | `data.payment.tokenization.cryptogram` | Required for CRYPTOGRAM flow. Send the value Base64-encoded as returned by the device. |
| `paymentData.eciIndicator` | `data.payment.tokenization.eci` (or `data.payment.eci` for 3DS) | Two-digit ECI value. |

> **PCI scope:** Decrypting the Apple Pay token brings the DAN into your environment, so the decryption service must operate within an appropriate PCI-DSS scope. If this is not feasible, use the Authorization Token (Encrypted) flow instead.

For the full decrypted token schema, refer to Apple's [Payment Token format reference](https://developer.apple.com/documentation/passkit/payment_token_format_reference).

### DAN (Decrypted Flow)

`DAN` uses the **Device Account Number** — a tokenized representation of the card stored in the customer's Apple Wallet. The transaction is processed similarly to a card-not-present payment.

If 3D Secure authentication is required by local regulation, issuer rules, merchant configuration, or transaction risk, an additional 3DS flow may be triggered.

#### 3DS for DAN transactions

For `DAN` transactions, 3D Secure may be required depending on the country, merchant configuration, issuer rules, or transaction risk.

> For Spain, 3DS/SCA is required. For Brazil, 3DS may be optional depending on merchant configuration and risk rules.

To process a `DAN` transaction with 3DS, merchants must follow the standard Getnet 3DS authentication flow before creating or confirming the payment. After authentication is completed, send the 3DS authentication fields in the payment request, such as `eci`, `xid`, `ucaf`, `tdsver`, and `tdsdsxid`, according to the [Create a 3DS Authenticated Payment](/en/global-api/sep-api/payment-guides-api/card-payments/3ds-guide) documentation.

If 3DS is required and the authentication data is not provided, the transaction may be declined or returned as pending for additional authentication.

### CRYPTOGRAM (Decrypted Flow)

`CRYPTOGRAM` uses tokenized device card credentials and includes a **TAVV cryptogram** generated by the Apple device during the payment process.

This method provides stronger authentication evidence through the device-generated cryptogram. Because of this, additional 3D Secure authentication is generally not required, unless required by local regulation, issuer rules, merchant configuration, or transaction risk.

### Authorization Token (Encrypted Flow)

Authorization Token is a Getnet processing model used when the merchant sends the Apple Pay payment token to Getnet instead of sending card data fields.

Use this flow when your backend sends the encrypted `pkPaymentToken` to Getnet.

In this flow, extract the `pkPaymentToken` returned by Apple Pay, serialize it exactly as returned, **encode it in hexadecimal**, and send the encoded value in `data.payment.wallet.authorization_token`. Getnet uses this token to extract and process the payment data required for authorization.

<Callout type="warning">

Apple Pay's Authorization Token must be encoded in **hexadecimal**, not Base64. Do not decrypt, change, trim, or remove any field from the token content before encoding it.

</Callout>

## Payment acceptance

For the best payment acceptance rates, Apple recommends supporting both decrypted and encrypted flows in your configuration. Supporting multiple methods allows Apple Pay to automatically choose the **most secure and compatible option** based on the customer's device and card configuration.

Through the Getnet Regional API, merchants can process Apple Pay payments using multiple backend scenarios, including DAN, CRYPTOGRAM, Authorization Token, and SDWO-specific transactions.

You must define the payment capabilities you accept in `merchantCapabilities`, based on the methods implemented during your technical onboarding with Apple.

| Authorization method | Credential type | 3DS requirement | Supported countries |
|---|---|---|---|
| `DAN` | Device Account Number associated with the customer's Apple Wallet | Required in Spain. Optional in Brazil depending on merchant configuration and transaction risk. | Brazil and Spain |
| `CRYPTOGRAM` | Tokenized device card credentials with TAVV cryptogram | Generally not required, unless required by regulation, issuer rules, merchant configuration, or transaction risk. | Brazil and Spain |
| `APPLE TOKEN` | Encrypted `pkPaymentToken` returned by Apple Pay | Handled according to token content and configuration. | Brazil and Spain |

## Cards

Cards available for the transaction.

| Type | Spain | Brazil |
|---|---:|---:|
| Mastercard | ✅ | ✅ |
| Visa | ✅ | ✅ |

You must define the card networks you accept in `supportedNetworks`, based on the networks implemented during your technical onboarding with Apple.

| Attribute | Type | Description | Example |
|---|---|---|---|
| `merchantCapabilities` | Array | Authentication methods your merchant supports. | `["supports3DS"]` |
| `supportedNetworks` | Array | All the supported cards by Apple Pay and Getnet. | `["masterCard", "visa"]` |

The following is an example of how to support all available card networks:

```json
{
  "merchantCapabilities": ["supports3DS"],
  "supportedNetworks": ["masterCard", "visa"]
}
```

## Billing address

<Callout type="note">

Request billing address only when required for authorization, fraud prevention, AVS, or local compliance. Asking for additional information may increase checkout friction.

</Callout>

Use `requiredBillingContactFields` to request billing address fields from Apple Pay when required for authorization, fraud prevention, AVS, or local compliance.

| Attribute | Type | Description | Example |
|---|---|---|---|
| `requiredBillingContactFields` | Array | Billing contact fields to request from the customer. | `["postalAddress", "name", "phoneticName"]` |
| `requiredShippingContactFields` | Array | Shipping contact fields to request from the customer (if applicable). | `["postalAddress", "name", "phone", "email"]` |

```json
{
  "requiredBillingContactFields": ["postalAddress", "name"],
  "requiredShippingContactFields": ["postalAddress", "name", "phone", "email"]
}
```

## Handling the Apple Pay payload

When a customer pays with Apple Pay, Apple returns payment data in the `pkPaymentToken` response object.

For the Authorization Token flow, the encrypted Apple Pay payment token must be extracted from:

```text
payment.token.paymentData
```

The merchant must then:

1. Extract the `pkPaymentToken` returned by Apple Pay.
2. Serialize the token exactly as returned by Apple Pay.
3. **Encode the serialized token in hexadecimal** (not Base64).
4. Send the encoded value in `data.payment.wallet.authorization_token` in the Getnet payment request.

Do not decrypt, change, trim, or remove any field from the token content before encoding it.

> **Encoding note:** The `tokenization.cryptogram` field used in the CRYPTOGRAM flow is **Base64**-encoded as returned by the device. By contrast, the `authorization_token` field used in the Encrypted (Apple Token) flow must be **hexadecimal**-encoded. These encodings are not interchangeable.

Example of hex-encoding the `pkPaymentToken` in Node.js:

```javascript
const hexToken = Buffer.from(JSON.stringify(pkPaymentToken)).toString('hex');
```

Example of the Getnet payment request using the Authorization Token flow:

```json
{
  "data": {
    "amount": 500,
    "currency": "EUR",
    "payment": {
      "payment_method": "CREDIT",
      "transaction_type": "FULL",
      "number_installments": 1,
      "wallet": {
        "id": "103",
        "type": "10",
        "authorization_token": "<HEX_ENCODED_APPLE_PAY_PAYMENT_TOKEN>"
      }
    }
  }
}
```

## Integrate via Regional API

To integrate Apple Pay via the Regional API, ensure the following prerequisites are met:

* Generate an access token through the [Authentication endpoint](https://docs.globalgetnet.com/en/products/online-payments/regional-api/swagger#tag/authentication).
* **Wallet configuration:** Use the correct `wallet.id`, `wallet.type`, and `wallet.tag` according to the selected Apple Pay processing scenario.
* **PCI Compliance:** Scenarios involving `card` objects, such as DAN and CRYPTOGRAM, require the merchant to operate within the appropriate PCI-DSS scope for handling sensitive card data.
* **HTTPS:** Your frontend environment must be served over a secure connection to initialize the Apple Pay SDK.

### Wallet field configuration

Use the table below to identify the correct wallet configuration for each scenario.

| Scenario | `data.payment.wallet.id` | `data.payment.wallet.type` | `data.payment.wallet.tag` |
|---|---|---|---|
| Standard Apple Pay — DAN | `103` | `10` | Not required |
| Standard Apple Pay — CRYPTOGRAM | `103` | `10` | Not required |
| Authorization Token (Apple Token) | `103` | `10` | Not required |
| SDWO card data | `103` | `55` | Not required |
| SDWO Authorization Token | `103` | `55` | `AP` |

<Callout type="warning">

For Apple Pay, `wallet.id` is always `103`.  
For SDWO transactions in Brazil, set `wallet.type = 55`. For SDWO Authorization Token, also set `wallet.tag = AP`.

</Callout>

## Characteristics

| Capability | Details |
|---|---|
| **Customer Experience** | **One-Tap** — Fast checkout via Face ID, Touch ID, or passcode. |
| **Settlement** | **Real-time** — Transactions are authorized and settled according to card network rules. |
| **Confirmation** | **Synchronous** — The API provides an immediate `APPROVED`, `DECLINED`, or intermediate status such as `PENDING` when additional authentication is required. |
| **Device Support** | Limited to compatible Apple devices using Safari browser or iOS/macOS apps. |

## Available Features

Use the matrix below to confirm the supported operations for Apple Pay in the Regional API.

| Features | Supported Countries | Purchases | Refunds | Partial Refunds | Pre-authorizations | 3DS | SDWO |
|---|---|---:|---:|---:|---:|---:|---:|
| Direct / API | Brazil and Spain | ✅ | ✅ | ✅ | ✅ | ✅ | Brazil only |

## Integration Flow

The lifecycle of an Apple Pay transaction begins with the frontend SDK obtaining a secure payload and ends with the server-side authorization call.

### Transaction Flow Diagram

The following diagram illustrates the end-to-end payment flow when a customer completes a purchase using Apple Pay and the payment is processed through Getnet.

![](https://static-devportal-ux.sensedia-eng.com/Pagonxt/staging/documentations/applepay-flow2-1766428977436-f5lcr30r.png)

#### Flow Description

1. The customer selects Apple Pay as the payment method at checkout.
2. The merchant application requests a payment session from Apple's servers (Merchant Validation).
3. Apple validates the merchant and returns a session object.
4. The Apple Pay sheet is displayed to the customer with their saved payment methods.
5. The customer selects a card and authorizes the payment via Face ID, Touch ID, or passcode.
6. Apple Pay generates and returns a payment token (`pkPaymentToken`) to the merchant.
7. The merchant sends the required Apple Pay payment data to Getnet.
8. Getnet prepares the transaction according to the selected processing scenario.
9. Getnet sends the authorization request to the card network or configured payment processor.
10. The processor returns the authorization result.
11. Getnet forwards the response to the merchant, which then displays the final payment result to the customer.

## Server-Side Implementation Scenarios

The following scenarios detail the JSON structures required based on the data provided by the Apple Pay frontend and the selected Getnet processing scenario.

### DAN

**DAN** is a card payment method within Apple Pay in which the transaction uses the **Device Account Number** — a tokenized representation of the user's card linked to their Apple Wallet.

In this model, the card credentials are retrieved from the customer's Apple Wallet. The DAN represents the primary identifier of the card within payment networks and is used to process the transaction through acquiring systems and card networks. This method follows a processing flow similar to traditional online card payments.

| Attribute | Type | Description | Example |
|---|---|---|---|
| `data.payment.card` | Object | Card data set. | -- |
| `data.payment.card.number` | String | Card number (DAN). | `4012001037141112` |
| `data.payment.card.expiration_month` | String | Two-digit card expiry month. | `12` |
| `data.payment.card.expiration_year` | String | Two-digit card expiry year. | `25` |
| `data.payment.wallet` | Object | Wallet data set. | -- |
| `data.payment.wallet.id` | String | Wallet identifier. Apple Pay id is always `103`. | `103` |
| `data.payment.wallet.type` | String | Wallet type. For standard Apple Pay transactions, use `10`. | `10` |
| `data.payment.eci` | String | Electronic Commerce Indicator used for 3DS authentication. Optional for transactions without 3DS. | `02` |

<Callout type="warning">

For Spain, 3DS authentication is required. In Brazil, 3DS is optional depending on merchant configuration, issuer rules, and transaction risk.

</Callout>

#### Example of request

```json
{
  "idempotency_key": "63c7f8ee-51a6-470d-bb76-ef762b62bfb7",
  "request_id": "daac03dc-73db-453f-9bea-b1391669d5d3",
  "order_id": "ORDER-10187383",
  "data": {
    "amount": 500,
    "currency": "BRL",
    "customer_id": "0258789",
    "payment": {
      "payment_id": "173f9e8d-4e0b-4503-8016-5cdafba89bee",
      "payment_method": "CREDIT",
      "transaction_type": "FULL",
      "number_installments": 1,
      "card": {
        "number": "4012001037141112",
        "expiration_month": "09",
        "expiration_year": "30"
      },
      "wallet": {
        "id": "103",
        "type": "10"
      }
    },
    "additional_data": {
      "customer": {
        "document_number": "77415914000148"
      }
    }
  }
}
```

#### Example of response

```json
{
  "idempotency_key": "e61674fa-f50c-46e0-a7e4-3adb048d423f",
  "seller_id": "a9c99f03-025c-4261-a9f5-de73ef593623",
  "payment_id": "mkysz8d0llo8",
  "order_id": "mkysz8d0llo8",
  "amount": "500",
  "currency": "BRL",
  "status": "APPROVED",
  "payment_method": "CREDIT",
  "received_at": "2026-04-08T17:14:54.000Z",
  "transaction_id": "MCC00KJ50408",
  "original_transaction_id": "MCC00KJ50408",
  "authorized_at": "2026-04-08T17:14:55.717Z",
  "reason_code": "00",
  "reason_message": "captured",
  "acquirer": "GETNET",
  "soft_descriptor": "EC TESTES PAGONXT - NA",
  "brand": "VISA",
  "authorization_code": "810172",
  "acquirer_transaction_id": "000454195865"
}
```

### DAN with 3DS

For DAN transactions that require 3D Secure authentication (mandatory in Spain, optional in Brazil), complete the 3DS authentication flow first as described in the [Create a 3DS Authenticated Payment](/en/global-api/sep-api/payment-guides-api/card-payments/3ds-guide) documentation. Then include the 3DS result fields in the payment request.

| Attribute | Type | Description | Example |
|---|---|---|---|
| `data.payment.xid` | String | MPI identifier (CAVV value for Visa). | `yFNXIadjt0mEsP5ob44vQPd0Zbg=` |
| `data.payment.ucaf` | String | UCAF authentication code (Mastercard only). | `B5kBAHNwQAAAAYdqmGESdiZwFVg=` |
| `data.payment.eci` | String | Electronic Commerce Indicator. Visa: `05`. Mastercard: `02`. | `05` |
| `data.payment.tdsver` | String | 3DS version. | `2.3.1` |
| `data.payment.tdsdsxid` | String | 3DS Server transaction identifier. | `9c2410c8-07c7-4e07-ac76-185e620970cf` |

<Callout type="note">

Use `xid` for Visa and `ucaf` for Mastercard. Do not send both fields for the same transaction.

</Callout>

#### Example of DAN with 3DS request (Spain)

```json
{
  "idempotency_key": "63c7f8ee-51a6-470d-bb76-ef762b62bfb7",
  "request_id": "daac03dc-73db-453f-9bea-b1391669d5d3",
  "order_id": "ORDER-10187383",
  "data": {
    "amount": 500,
    "currency": "EUR",
    "payment": {
      "payment_id": "173f9e8d-4e0b-4503-8016-5cdafba89bee",
      "payment_method": "CREDIT",
      "transaction_type": "FULL",
      "number_installments": 1,
      "xid": "yFNXIadjt0mEsP5ob44vQPd0Zbg=",
      "eci": "05",
      "tdsver": "2.3.1",
      "tdsdsxid": "9c2410c8-07c7-4e07-ac76-185e620970cf",
      "card": {
        "number": "4012001037141112",
        "expiration_month": "09",
        "expiration_year": "30"
      },
      "wallet": {
        "id": "103",
        "type": "10"
      }
    },
    "additional_data": {
      "customer": {
        "document_number": "12345678Z",
        "document_type": "DNI"
      }
    }
  }
}
```

#### Example of DAN with 3DS response

```json
{
  "idempotency_key": "63c7f8ee-51a6-470d-bb76-ef762b62bfb7",
  "seller_id": "a9c99f03-025c-4261-a9f5-de73ef593623",
  "payment_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "order_id": "ORDER-10187383",
  "amount": "500",
  "currency": "EUR",
  "status": "APPROVED",
  "payment_method": "CREDIT",
  "received_at": "2026-04-08T17:14:54.000Z",
  "transaction_id": "MCC00KJ50408",
  "original_transaction_id": "MCC00KJ50408",
  "authorized_at": "2026-04-08T17:14:55.717Z",
  "reason_code": "00",
  "reason_message": "Transaction authorized (payment/preauthorization)",
  "acquirer": "GETNET",
  "brand": "VISA",
  "authorization_code": "810172",
  "acquirer_transaction_id": "000454195865"
}
```

### SDWO — Staged Digital Wallet Operator

SDWO is a payment framework typically used by digital wallet providers where the wallet acts as an intermediary between the cardholder and the final recipient.

It facilitates two stages: funding the account and transferring funds to a sub-merchant. This ensures transparency of the end receiver for payment networks.

For SDWO transactions in Brazil, the fields inside the `wallet` object must be filled as follows:

* `data.payment.wallet.id` must be set to `103`
* `data.payment.wallet.type` must be set to `55`

| Attribute | Type | Description | Example |
|---|---|---|---|
| `data.payment.card` | Object | Card data set. | -- |
| `data.payment.card.number` | String | Card number (DAN). | `4012001037141112` |
| `data.payment.card.expiration_month` | String | Two-digit card expiry month. | `12` |
| `data.payment.card.expiration_year` | String | Two-digit card expiry year. | `25` |
| `data.payment.wallet` | Object | Wallet data set. | -- |
| `data.payment.wallet.id` | String | Wallet identifier. Apple Pay id is always `103`. | `103` |
| `data.payment.wallet.type` | String | Wallet type for SDWO transactions. Always use `55`. | `55` |
| `data.payment.wallet.fund_transfer` | Object | Fund transfer data required for SDWO transactions. | -- |

#### Example of SDWO request

```json
{
  "idempotency_key": "63c7f8ee-51a6-470d-bb76-ef762b62bfb7",
  "request_id": "daac03dc-73db-453f-9bea-b1391669d5d3",
  "order_id": "ORDER-10187383",
  "data": {
    "amount": 1200,
    "currency": "BRL",
    "customer_id": "0258789",
    "payment": {
      "payment_id": "173f9e8d-4e0b-4503-8016-5cdafba89bee",
      "payment_method": "CREDIT",
      "save_card_data": false,
      "transaction_type": "FULL",
      "number_installments": 1,
      "dynamic_mcc": 6051,
      "card": {
        "number": "4012001037141112",
        "expiration_month": "09",
        "expiration_year": "30"
      },
      "wallet": {
        "type": "55",
        "id": "103",
        "fund_transfer": {
          "pay_action": "FT",
          "receiver": {
            "account_number": "9999999999999995",
            "account_type": "00",
            "first_name": "Jane",
            "middle_name": "T",
            "last_name": "Smith",
            "addr_street": "1 Main ST",
            "addr_city": "SAO PAULO",
            "addr_state": "SP",
            "addr_country": "BRA",
            "addr_postal_code": "1408000"
          }
        }
      }
    },
    "additional_data": {
      "customer": {
        "document_number": "77415914000148"
      }
    }
  }
}
```

#### Example of SDWO response

```json
{
  "idempotency_key": "e61674fa-f50c-46e0-a7e4-3adb048d423f",
  "seller_id": "a9c99f03-025c-4261-a9f5-de73ef593623",
  "payment_id": "mkysz8d0llo8",
  "order_id": "mkysz8d0llo8",
  "amount": "1200",
  "currency": "BRL",
  "status": "APPROVED",
  "payment_method": "CREDIT",
  "received_at": "2026-04-08T17:14:54.000Z",
  "transaction_id": "MCC00KJ50408",
  "original_transaction_id": "MCC00KJ50408",
  "authorized_at": "2026-04-08T17:14:55.717Z",
  "reason_code": "00",
  "reason_message": "captured",
  "acquirer": "GETNET",
  "soft_descriptor": "EC TESTES PAGONXT - NA",
  "brand": "MASTERCARD",
  "authorization_code": "810172",
  "acquirer_transaction_id": "000454195865"
}
```

### SDWO with 3DS Transactions

For transactions using 3DS, please follow all the steps provided in the [Create a 3DS Authenticated Payment](/en/global-api/sep-api/payment-guides-api/card-payments/3ds-guide) document.

<Callout type="warning">

When creating SDWO requests, the fields inside the `wallet` object must be filled as follows:
* `data.payment.wallet.id` must be set to `103`
* `data.payment.wallet.type` must be set to `55`

</Callout>

The table below shows the fields required for transactions with 3DS.

| Attribute | Type | Description | Example |
|---|---|---|---|
| `data.payment.xid` | String | MPI identifier for each authenticated transaction. | `yFNXIadjt0mEsP5ob44vQPd0Zbg=` |
| `data.payment.ucaf` | String | Authentication code encrypted by the card network. | `B5kBAHNwQAAAAYdqmGESdiZwFVg=` |
| `data.payment.eci` | String | Electronic Commerce Indicator used for 3DS authentication. | `5` |
| `data.payment.tdsver` | String | 3DS version used in authentication. | `2.3.1` |
| `data.payment.tdsdsxid` | String | 3DS Server transaction identifier. | `9c2410c8-07c7-4e07-ac76-185e620970cf` |

#### Example of SDWO with 3DS request

```json
{
  "idempotency_key": "63c7f8ee-51a6-470d-bb76-ef762b62bfb7",
  "request_id": "daac03dc-73db-453f-9bea-b1391669d5d3",
  "order_id": "ORDER-10187383",
  "data": {
    "amount": 3000,
    "currency": "BRL",
    "customer_id": "test",
    "payment": {
      "payment_id": "173f9e8d-4e0b-4503-8016-5cdafba89bee",
      "payment_method": "CREDIT",
      "save_card_data": false,
      "transaction_type": "FULL",
      "number_installments": 1,
      "soft_descriptor": "APAY Test",
      "xid": "yFNXIadjt0mEsP5ob44vQPd0Zbg=",
      "ucaf": "B5kBAHNwQAAAAYdqmGESdiZwFVg=",
      "eci": "5",
      "tdsver": "2.3.1",
      "tdsdsxid": "9c2410c8-07c7-4e07-ac76-185e620970cf",
      "card": {
        "number": "4012001037141112",
        "expiration_month": "09",
        "expiration_year": "30"
      },
      "wallet": {
        "type": "55",
        "id": "103",
        "fund_transfer": {
          "pay_action": "FT",
          "receiver": {
            "account_number": "9999999999999995",
            "account_type": "00",
            "first_name": "Jane",
            "middle_name": "T",
            "last_name": "Smith",
            "addr_street": "1 Main ST",
            "addr_city": "SAO PAULO",
            "addr_state": "SP",
            "addr_country": "BRA",
            "addr_postal_code": "1408000",
            "nationality": "BRA",
            "phone": "5511977778888",
            "date_of_birth": "19901230",
            "id_type": "03",
            "id_num": "12345678900000"
          },
          "sender": {
            "account_number": "9999999999999995",
            "account_type": "00",
            "first_name": "Jane",
            "middle_name": "T",
            "last_name": "Smith",
            "addr_street": "1 Main ST",
            "addr_city": "SAO PAULO",
            "addr_state": "SP",
            "addr_country": "BRA",
            "addr_postal_code": "1408000",
            "nationality": "BRA",
            "phone": "5511977778888",
            "date_of_birth": "19901230",
            "id_type": "03",
            "id_num": "12345678900000"
          }
        }
      }
    },
    "additional_data": {
      "customer": {
        "document_number": "77415914000148"
      }
    }
  }
}
```

#### Example of SDWO with 3DS response

> The response follows the same structure as the standard payment response. If additional authentication is required, the transaction may return `PENDING` with 3DS challenge data.

```json
{
  "idempotency_key": "ff9c7c47-22f4-437b-af20-1f227a6bcaae",
  "seller_id": "a9c99f03-025c-4261-a9f5-de73ef593623",
  "payment_id": "21911ab4-85c7-4906-a56c-d75c5b7ea185",
  "order_id": "ORDER-10187383",
  "amount": "3000",
  "currency": "BRL",
  "status": "APPROVED",
  "payment_method": "CREDIT",
  "received_at": "2026-04-08T17:14:54.000Z",
  "transaction_id": "MCC00CVZ20408",
  "original_transaction_id": "MCC00CVZ20408",
  "authorized_at": "2026-04-08T17:14:55.283Z",
  "reason_code": "00",
  "reason_message": "captured",
  "acquirer": "GETNET",
  "soft_descriptor": "EC TESTES PAGONXT - NA",
  "brand": "MASTERCARD",
  "authorization_code": "446201",
  "acquirer_transaction_id": "000018185087"
}
```

### CRYPTOGRAM

**CRYPTOGRAM** is a card payment method within Apple Pay in which the transaction uses **tokenized card credentials associated with a device** and includes a **security cryptogram (TAVV) generated during the payment process**.

In this model, instead of the real card number, a Device Account Number (DAN) is used along with a TAVV cryptogram that proves the transaction was initiated from the user's authenticated Apple device.

The cryptogram is a dynamically generated cryptographic value that enables payment networks to validate the authenticity of the transaction.

| Attribute | Type | Description | Example |
|---|---|---|---|
| `data.payment.card` | Object | Card data set. | -- |
| `data.payment.card.number` | String | Tokenized card number (DAN) returned by Apple Pay. | `4761120000000148` |
| `data.payment.card.expiration_month` | String | Two-digit card expiry month. | `12` |
| `data.payment.card.expiration_year` | String | Two-digit card expiry year. | `25` |
| `data.payment.wallet` | Object | Wallet data set. | -- |
| `data.payment.wallet.id` | String | Wallet identifier. Apple Pay id is always `103`. | `103` |
| `data.payment.wallet.type` | String | Wallet type. For standard Apple Pay transactions, use `10`. | `10` |
| `data.payment.tokenization` | Object | Tokenization data set containing cryptographic values from the device. | -- |
| `data.payment.tokenization.cryptogram` | String | Value of the TAVV cryptogram generated by the device. | `AgAAAAAABk4DWZ4C28yUQAAAAAA=` |
| `data.payment.tokenization.eci` | String | Electronic Commerce Indicator associated with the tokenized payment. | `02` |

#### Example of request

```json
{
  "idempotency_key": "f6e5cb13-a5fe-46f9-b467-29bd13c29e59",
  "request_id": "d808b53a-aa47-4484-8c99-cbe83624474c",
  "order_id": "izgyekkmb8sd",
  "data": {
    "amount": 500,
    "currency": "EUR",
    "customer_id": "02587894152",
    "payment": {
      "payment_id": "izgyekkmb8sd",
      "payment_method": "CREDIT",
      "transaction_type": "FULL",
      "number_installments": 1,
      "card": {
        "number": "4761120000000148",
        "expiration_month": "12",
        "expiration_year": "49"
      },
      "wallet": {
        "id": "103",
        "type": "10"
      },
      "tokenization": {
        "cryptogram": "AgAAAAAABk4DWZ4C28yUQAAAAAA=",
        "eci": "02"
      }
    },
    "additional_data": {
      "customer": {
        "phone_number": "+34911234567",
        "email": "customer@example.com",
        "document_number": "12345678Z",
        "document_type": "DNI",
        "name": "Jose da Silva",
        "billing_address": {
          "street": "Calle Mayor",
          "number": "10",
          "district": "Centro",
          "city": "Madrid",
          "state": "Madrid",
          "country": "ES",
          "postal_code": "28013",
          "complement": "N/A"
        }
      }
    }
  }
}
```

#### Example of response

```json
{
  "idempotency_key": "2e7b86be-201d-4a82-a8f9-7102500faf78",
  "seller_id": "7c966bb3-a8dc-4428-aa95-61081719ed80",
  "payment_id": "omczgrvmxdt5",
  "order_id": "omczgrvmxdt5",
  "amount": "500",
  "currency": "EUR",
  "status": "APPROVED",
  "payment_method": "CREDIT",
  "received_at": "2026-02-23T15:10:52.664Z",
  "original_transaction_id": "",
  "authorized_at": "2026-02-23T15:10:53.688Z",
  "reason_code": "00",
  "reason_message": "Transaction authorized (payment/preauthorization)",
  "acquirer": "GETNET",
  "brand": "UNKNOWN"
}
```

<Callout type="note">

In sandbox environments, the `brand` field may be returned as `UNKNOWN` depending on the test token configuration.

</Callout>

### Authorization Token (Apple Token)

The **Authorization Token** flow is a Getnet processing model used when the merchant sends the Apple Pay payment token to Getnet instead of sending card data fields.

When a customer pays with Apple Pay, Apple returns an encrypted `pkPaymentToken` containing the customer's payment data.

In this model, the merchant does not send `card.number`, `card.expiration_month`, `card.expiration_year`, `tokenization.cryptogram`, or `tokenization.eci` as separate fields. Instead, the merchant must extract the `pkPaymentToken` returned by Apple Pay, serialize it exactly as returned, **encode it in hexadecimal**, and send the encoded value in `data.payment.wallet.authorization_token`.

Getnet uses the `authorization_token` to extract and process the payment data required for authorization.

<Callout type="warning">

Apple Pay's Authorization Token must be encoded in **hexadecimal**, not Base64. Do not decrypt, change, trim, or remove any field from the token content before encoding it.

</Callout>

| Attribute | Type | Description | Required |
|---|---|---|---|
| `idempotency_key` | String | Unique identifier to prevent duplicate charges. | Yes |
| `order_id` | String | Merchant reference ID used for reconciliation. | Yes |
| `request_id` | String | Trace identifier for idempotency audits and support follow-up. | Recommended |
| `data.amount` | Number | Transaction amount in cents. | Yes |
| `data.currency` | String | ISO currency code used in the transaction. | Yes |
| `data.customer` | Object | Customer details such as name, email, phone, document, and billing address. Mandatory in production to reduce antifraud blocks. | Yes |
| `data.payment.payment_method` | String | Payment method used for the transaction. | Yes |
| `data.payment.transaction_type` | String | Defines how the transaction is processed. Examples: `FULL`, `INSTALL_NO_INTEREST`, `INSTALL_WITH_INTEREST`. | Yes |
| `data.payment.number_installments` | Number | Number of installments. Use `1` for a single payment. | Yes |
| `data.additional_data.device` | Object | Device fingerprint information for antifraud analysis, such as `ip_address`, `device_id`, and `finger_print`. | Production required |
| `data.payment.wallet` | Object | Wallet data set. | Yes |
| `data.payment.wallet.id` | String | Wallet identifier. Apple Pay id is always `103`. | Yes |
| `data.payment.wallet.type` | String | Wallet type. Use `10` for standard Apple Pay Authorization Token transactions or `55` for SDWO Authorization Token transactions. | Conditional |
| `data.payment.wallet.tag` | String | Wallet tag. Required only for SDWO Authorization Token transactions. Use `AP`. | Conditional |
| `data.payment.wallet.authorization_token` | String | Hexadecimal-encoded Apple Pay payment token (`pkPaymentToken`). Send the token content exactly as returned by Apple Pay, encoded in hexadecimal, without decrypting, changing, trimming, or removing any field. | Yes |

The antifraud payload must also include the following fields.

| Object / Field | Description |
|---|---|
| `customer.first_name` | Customer's first name. |
| `customer.last_name` | Customer's last name. |
| `customer.email` | Customer email address. |
| `customer.phone_number` | Phone number in international format. |
| `customer.document_type` | Document type, such as CPF, DNI, or equivalent. |
| `customer.document_number` | Document number without punctuation. |
| `customer.billing_address.street` | Street name. |
| `customer.billing_address.number` | Address number. |
| `customer.billing_address.district` | District or neighbourhood. |
| `customer.billing_address.city` | City. |
| `customer.billing_address.state` | State or province. |
| `customer.billing_address.country` | Country code. |
| `customer.billing_address.postal_code` | Postal or ZIP code. |
| `additional_data.device.ip_address` | Customer's IP address. |
| `additional_data.device.device_id` | Device fingerprint session ID. |
| `additional_data.device.finger_print` | Fingerprint hash generated by the antifraud script. |

#### Example of request

```json
{
  "idempotency_key": "4c3cbdc2-b41e-4e1c-b7fe-90ed10abd9bb",
  "request_id": "4802c01b-5aee-4962-a4f0-cff50439fda0",
  "order_id": "izgyekkmb8sd",
  "data": {
    "amount": 500,
    "currency": "EUR",
    "customer_id": "02587894152",
    "payment": {
      "payment_id": "izgyekkmb8sd",
      "payment_method": "CREDIT",
      "transaction_type": "FULL",
      "number_installments": 1,
      "wallet": {
        "id": "103",
        "type": "10",
        "authorization_token": "<HEX_ENCODED_APPLE_PAY_PAYMENT_TOKEN>"
      }
    },
    "additional_data": {
      "customer": {
        "first_name": "Jose",
        "last_name": "da Silva",
        "phone_number": "+34911234567",
        "email": "customer@example.com",
        "document_number": "12345678Z",
        "document_type": "DNI",
        "billing_address": {
          "street": "Calle Mayor",
          "number": "10",
          "district": "Centro",
          "city": "Madrid",
          "state": "Madrid",
          "country": "ES",
          "postal_code": "28013",
          "complement": "N/A"
        }
      },
      "device": {
        "ip_address": "192.0.2.1",
        "device_id": "{{$guid}}",
        "finger_print": "<DEVICE_FINGERPRINT>"
      }
    }
  }
}
```

#### Example of response

```json
{
  "idempotency_key": "ae010d29-997f-4b8b-9890-32ab6c927a85",
  "seller_id": "7c966bb3-a8dc-4428-aa95-61081719ed80",
  "payment_id": "c7pk1y8j97o0",
  "order_id": "c7pk1y8j97o0",
  "amount": "500",
  "currency": "EUR",
  "status": "PENDING",
  "payment_method": "CREDIT",
  "received_at": "2026-02-23T15:16:37.589Z",
  "original_transaction_id": "",
  "authorized_at": "2026-02-23T15:16:38.853Z",
  "reason_code": "00",
  "reason_message": "Transaction is pending of EMV3DS authentication",
  "acquirer": "GETNET",
  "brand": "UNKNOWN",
  "additional_data": {
    "_links": [
      {
        "rel": "3ds_html",
        "type": "POST",
        "href": "https://example.com/3ds/challenge",
        "creq": "<3DS_CREQ_VALUE>"
      }
    ]
  }
}
```

### SDWO Authorization Token

For SDWO Authorization Token transactions, the merchant sends the hexadecimal-encoded Apple Pay payment token together with the SDWO fund transfer data.

<Callout type="warning">

Only for SDWO Authorization Token transactions:
* `data.payment.wallet.id` must be set to `103`
* `data.payment.wallet.type` must be set to `55`
* `data.payment.wallet.tag` must be set to `AP`

</Callout>

#### Example of SDWO Authorization Token request

```json
{
  "idempotency_key": "4c3cbdc2-b41e-4e1c-b7fe-90ed10abd9bb",
  "request_id": "4802c01b-5aee-4962-a4f0-cff50439fda0",
  "order_id": "izgyekkmb8sd",
  "data": {
    "amount": 1200,
    "currency": "BRL",
    "payment": {
      "payment_id": "{{$guid}}",
      "payment_method": "CREDIT",
      "save_card_data": false,
      "transaction_type": "FULL",
      "number_installments": 1,
      "dynamic_mcc": 6051,
      "wallet": {
        "type": "55",
        "id": "103",
        "tag": "AP",
        "authorization_token": "<HEX_ENCODED_APPLE_PAY_PAYMENT_TOKEN>",
        "fund_transfer": {
          "pay_action": "FT",
          "receiver": {
            "account_number": "9999999999999995",
            "account_type": "00",
            "first_name": "Jane",
            "middle_name": "T",
            "last_name": "Smith",
            "addr_street": "1 Main ST",
            "addr_city": "SAO PAULO",
            "addr_state": "SP",
            "addr_country": "BRA",
            "addr_postal_code": "1408000",
            "nationality": "BRA",
            "phone": "5511977778888",
            "date_of_birth": "19901230",
            "id_type": "03",
            "id_num": "12345678900000"
          },
          "sender": {
            "account_number": "9999999999999995",
            "account_type": "00",
            "first_name": "Jane",
            "middle_name": "T",
            "last_name": "Smith",
            "addr_street": "1 Main ST",
            "addr_city": "SAO PAULO",
            "addr_state": "SP",
            "addr_country": "BRA",
            "addr_postal_code": "1408000",
            "nationality": "BRA",
            "phone": "5511977778888",
            "date_of_birth": "19901230",
            "id_type": "03",
            "id_num": "12345678900000"
          }
        }
      }
    }
  }
}
```

#### Example of SDWO Authorization Token response

```json
{
  "idempotency_key": "ff9c7c47-22f4-437b-af20-1f227a6bcaae",
  "seller_id": "a9c99f03-025c-4261-a9f5-de73ef593623",
  "payment_id": "21911ab4-85c7-4906-a56c-d75c5b7ea185",
  "order_id": "e478c15e-fd0a-40f4-8b70-48233ca203bd",
  "amount": "1200",
  "currency": "BRL",
  "status": "APPROVED",
  "payment_method": "CREDIT",
  "received_at": "2026-04-08T17:14:54.000Z",
  "transaction_id": "MCC00CVZ20408",
  "original_transaction_id": "MCC00CVZ20408",
  "authorized_at": "2026-04-08T17:14:55.283Z",
  "reason_code": "00",
  "reason_message": "captured",
  "acquirer": "GETNET",
  "soft_descriptor": "EC TESTES PAGONXT - NA",
  "brand": "MASTERCARD",
  "authorization_code": "446201",
  "acquirer_transaction_id": "000018185087"
}
```

## Comparison Table

Use the table below to identify which technical fields are required for each Apple Pay processing scenario.

| Scenario | What merchant sends to Getnet | Card object | Tokenization object | Authorization token | 3DS data | Wallet fields |
|---|---|---:|---:|---:|---:|---|
| DAN | Card DAN + expiry | Required | No | No | Optional or required by country/configuration | `id=103`, `type=10` |
| DAN with 3DS | Card DAN + expiry + 3DS authentication fields | Required | No | No | Required | `id=103`, `type=10` |
| CRYPTOGRAM | Tokenized card/DAN + expiry + TAVV cryptogram + ECI | Required | Required | No | Usually not required | `id=103`, `type=10` |
| Authorization Token (Apple Token) | Hexadecimal-encoded Apple Pay payment token | No | No | Required | Handled according to token content and configuration | `id=103`, `type=10` |
| SDWO card data | Card data + fund transfer data | Required | Depends on scenario | No | Optional or required by configuration | `id=103`, `type=55` |
| SDWO Authorization Token | Hexadecimal-encoded Apple Pay payment token + fund transfer data | No | No | Required | Depends on token content and configuration | `id=103`, `type=55`, `tag=AP` |

## Additional resources

* [Apple Pay on the Web documentation](https://developer.apple.com/documentation/apple_pay_on_the_web)
* [Apple Pay Web integration checklist](https://developer.apple.com/documentation/apple_pay_on_the_web/apple_pay_js_api/checking_for_apple_pay_availability)
* [Apple Pay iOS/macOS documentation](https://developer.apple.com/documentation/passkit/apple_pay)
* [Apple Pay Identity Guidelines](https://developer.apple.com/apple-pay/marketing/)
* [Authentication](https://docs.globalgetnet.com/en/products/online-payments/regional-api%3Fdoc%3Dauthentication) for token management.
* [Publish your integration](https://developer.apple.com/apple-pay/implementation/)