# Apple Pay transaction

Process an online transaction using Apple Pay.

## Overview

You can submit an Apple Pay transaction in two ways:

- **Encrypted token (recommended):** Pass the payment token from the Apple Pay sheet in `fundingData.card.applePayToken`. PXP decrypts it during transaction processing.
- **Decrypted token:** Decrypt the token on your backend using `POST /v1/wallets/ApplePay/decrypt-token`, then submit the decrypted card details using the card not present card type with `walletType` set to `ApplePay`.


## Initiate an Apple Pay transaction

/v1/transactions

### Request examples

Encrypted token
Use the following request when you have the encrypted payment token from the Apple Pay sheet on the client device.

```json
{
  "merchant": "MERCHANT-1",
  "site": "SITE-1",
  "merchantTransactionId": "This_is_my_merchant_transaction_id",
  "merchantTransactionDate": "2024-01-27T08:51:02.826445+00:00",
  "transactionMethod": {
    "intent": "Authorisation",
    "entryType": "Ecom",
    "fundingType": "Card"
  },
  "fundingData": {
    "card": {
      "applePayToken": "{\"version\":\"EC_v1\",\"data\":\"eyJhbGciOiJSU0EtT0FFUC0yNTYiLCJlbmMiOiJBMjU2R0NNIn0...\",\"signature\":\"MIAGCSqGSIb3DQEHAqCAMIACAQEx...\",\"header\":{\"ephemeralPublicKey\":\"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE...\",\"publicKeyHash\":\"h0j3M6S0X8/x...\",\"transactionId\":\"32b030ca0603b2c5f0e2c5c8f0c0e0c0\"}}"
    }
  },
  "amounts": {
    "transaction": 30.32,
    "currencyCode": "EUR"
  },
  "shopper": {
    "id": "Shopper_01",
    "firstName": "John",
    "lastName": "Doe",
    "dateOfBirth": "1980-03-01",
    "email": "shopper@example.com"
  }
}
```

| Parameter | Description |
|  --- | --- |
| `merchant`string (≤ 20 characters) | Your unique merchant identifier, as assigned by PXP. |
| `site`string (≤ 20 characters) | Your unique site identifier, as assigned by PXP. |
| `merchantTransactionId`string (≤ 50 characters) | A unique identifier for this transaction. |
| `merchantTransactionDate`date-time | The date and time when the transaction happened, in ISO 8601 format. |
| `transactionMethod`object | Details about the transaction method. |
| `transactionMethod.entryType`string | The entry type. For e-commerce transactions, this is always `Ecom`. |
| `transactionMethod.fundingType`string | The funding type. For card transactions, this is always `Card`. |
| `transactionMethod.intent`string | The payment intent. [Learn more about intents](/guides/transactions/how-it-works#intents). Possible values:`Authorisation``EstimatedAuthorisation``Purchase``Payout``Refund` |
| `amounts`object | Details about the transaction amount. |
| `amounts.transaction`number | The transaction amount. The numbers after the decimal will be zero padded if they are less than the expected `currencyCode` exponent. For example, GBP 1.1 = GBP 1.10, EUR 1 = EUR 1.00, or BHD 1.3 = 1.300. The transaction will be rejected if numbers after the decimal are greater than the expected `currencyCode` exponent (e.g., GBP 1.234), or if a decimal is supplied when the `currencyCode` exponent does not require it (e.g., JPY 1.0). |
| `amounts.currencyCode`string (1-3 characters) | The currency code associated with the transaction, in ISO 4217 format. |
| `fundingData`object | Details about the payment method used for the transaction. |
| `fundingData.card`object | Apple Pay card details. Use the **Apple Pay** card type and submit only `applePayToken` (and optional `dynamicDescriptors`). |
| `fundingData.card.applePayToken`string | The encrypted payment token returned by Apple Pay on the client device. Submit this value as a JSON string serialisation of the Apple Pay payment token object (including `version`, `data`, `signature`, and `header`). PXP decrypts this server-side during transaction processing. |
| `fundingData.card.dynamicDescriptors`object | Optional merchant-defined descriptors that appear on the cardholder's statement. [Learn more about dynamic descriptors](/guides/transactions/e-commerce/dynamic-descriptors). |
| `fundingData.card.dynamicDescriptors.cardAcceptorName`string (≤ 22 characters) | A description of the transaction that will appear on the cardholder's statement. |
| `shopper`object | Details about the shopper making the payment. |


Decrypted token
Use the following request when you have already decrypted the Apple Pay token on your backend. Map the values returned from [POST /v1/wallets/ApplePay/decrypt-token](/apis/wallets/other/decrypt-apple-pay-token) into the card not present fields and set `walletType` to `ApplePay`.

```json
{
  "merchant": "MERCHANT-1",
  "site": "SITE-1",
  "merchantTransactionId": "This_is_my_merchant_transaction_id",
  "merchantTransactionGroupId": "This_is_my_merchant_transaction_group_id",
  "merchantTransactionDate": "2024-01-27T08:51:02.826445+00:00",
  "transactionMethod": {
    "intent": "Authorisation",
    "entryType": "Ecom",
    "fundingType": "Card"
  },
  "fundingData": {
    "card": {
      "primaryAccountNumber": "4111111111111111",
      "expiryMonth": "03",
      "expiryYear": "2027",
      "holderName": "John Doe",
      "walletType": "ApplePay"
    }
  },
  "amounts": {
    "transaction": 30.32,
    "currencyCode": "EUR"
  },
  "threeDSecureData": {
    "cardHolderAuthenticationVerificationValue": "MjAwNjI0MDkwMTEwMjA4NjU0MTY=",
    "electronicCommerceIndicator": "05"
  },
  "shopper": {
    "id": "Shopper_01",
    "firstName": "John",
    "lastName": "Doe",
    "dateOfBirth": "1980-03-01",
    "email": "shopper@example.com"
  }
}
```

| Parameter | Description |
|  --- | --- |
| `merchant`string (≤ 20 characters) | Your unique merchant identifier, as assigned by PXP. |
| `site`string (≤ 20 characters) | Your unique site identifier, as assigned by PXP. |
| `merchantTransactionId`string (≤ 50 characters) | A unique identifier for this transaction. |
| `merchantTransactionDate`date-time | The date and time when the transaction happened, in ISO 8601 format. |
| `transactionMethod`object | Details about the transaction method. |
| `transactionMethod.entryType`string | The entry type. For e-commerce transactions, this is always `Ecom`. |
| `transactionMethod.fundingType`string | The funding type. For card transactions, this is always `Card`. |
| `transactionMethod.intent`string | The payment intent. [Learn more about intents](/guides/transactions/how-it-works#intents). Possible values:`Authorisation``EstimatedAuthorisation``Purchase``Payout``Refund` |
| `amounts`object | Details about the transaction amount. |
| `amounts.transaction`number | The transaction amount. The numbers after the decimal will be zero padded if they are less than the expected `currencyCode` exponent. For example, GBP 1.1 = GBP 1.10, EUR 1 = EUR 1.00, or BHD 1.3 = 1.300. The transaction will be rejected if numbers after the decimal are greater than the expected `currencyCode` exponent (e.g., GBP 1.234), or if a decimal is supplied when the `currencyCode` exponent does not require it (e.g., JPY 1.0). |
| `amounts.currencyCode`string (1-3 characters) | The currency code associated with the transaction, in ISO 4217 format. |
| `threeDSecureData`object | Details about the 3DS data returned when you decrypt the Apple Pay token. If `authenticationId` is provided, PXP looks up the associated 3D Secure authentication data. If `authenticationId` is not provided, provide the authentication data from the decrypt response instead. |
| `threeDSecureData.authenticationId`string | A unique reference provided by PXP for the authentication request, represented as a GUID. |
| `threeDSecureData.cardHolderAuthenticationVerificationValue`string | The Cardholder Authentication Verification Value (CAVV) generated by the card issuer as part of the 3D Secure authentication process. This field can also be used for Apple Pay cryptograms returned from the decrypt endpoint. |
| `threeDSecureData.electronicCommerceIndicator`string | The Electronic Commerce Indicator (ECI) specifies the security level of an online transaction and the authentication outcome, crucial for determining liability in the event of a dispute. Possible values:`01`: Transaction processed with SSL or equivalent but without cardholder authentication (considered less secure, higher risk).`02`: Transaction processed with cardholder authentication (e.g., 3D Secure), indicating a higher level of security.`05`: Transaction processed with 3D Secure authentication, cardholder authenticated successfully (high security).`06`: Transaction attempted 3D Secure authentication but could not be completed; cardholder not authenticated (medium security).`07`: Transaction processed without 3D Secure authentication, due to issuer or cardholder not participating in 3D Secure (considered less secure, higher risk). |
| `fundingData`object | Details about the payment method used for the transaction. |
| `fundingData.card`object | Card not present details for a decrypted Apple Pay token. Set `walletType` to `ApplePay`. |
| `fundingData.card.primaryAccountNumber`string (13-19 characters) | The unique number assigned to a payment card, such as a credit or debit card. |
| `fundingData.card.expiryMonth`string (2 characters) | The expiry month (`MM`) of the card. |
| `fundingData.card.expiryYear`string (4 characters) | The expiry year (`YYYY`) of the card. |
| `fundingData.card.holderName`string (≤ 100 characters) | The full name of the individual who owns the payment card. |
| `fundingData.card.walletType`string | The digital wallet used for this card not present transaction. Set to `ApplePay` when submitting decrypted Apple Pay card details. |
| `fundingData.card.dynamicDescriptors`object | Optional merchant-defined descriptors that appear on the cardholder's statement. [Learn more about dynamic descriptors](/guides/transactions/e-commerce/dynamic-descriptors). |
| `fundingData.card.dynamicDescriptors.cardAcceptorName`string (≤ 22 characters) | A description of the transaction that will appear on the cardholder's statement. |
| `shopper`object | Details about the shopper making the payment. |


### Response example

If your request is successful, you'll receive a `200` response that includes the transaction's `state`. You'll also receive a Transaction (Card Authorised) webhook notification. [Learn more about webhooks](/guides/get-started/about-webhooks).

```json
{
  "state": "Authorised",
  "stateData": {
    "code": "CRD000",
    "message": "Approved"
  },
  "approvalCode": "123456",
  "merchantTransactionId": "This_is_my_merchant_transaction_id",
  "systemTransactionId": "1ed768bb-e88a-4636-91ae-67927ccbb02b",
  "merchantTransactionDate": "2024-01-27T08:51:02.826Z",
  "providerTransactionId": "1ed768bb-e88a-4636-91ae-67927ccbb02b",
  "fundingData": {
    "cardScheme": "Visa",
    "primaryAccountNumber": "************1111",
    "expiryMonth": "12",
    "expiryYear": "2026",
    "gatewayTokenId": "1ed768bb-e88a-4636-91ae-67927ccbb02b",
    "schemeTokenNumber": "4837261112345678",
    "addressVerificationServiceResult": "NoInformationAvailable",
    "cardVerificationCodeResult": "NoInformationAvailable",
    "providerResponse": {
      "provider": "PXPFinancial",
      "code": "00",
      "message": "Approved",
      "merchantId": "77772182",
      "terminalId": "75836665",
      "cardVerificationCodeResult": "A",
      "addressVerificationServiceResult": "D",
      "schemeTransactionId": "TX1234567890123456",
      "schemeTransactionLinkId": "TX1234567890123456",
      "paymentAccountReference": "V001ABCDEFGHIJKLMNOPQRSTUVWXY",
      "retrievalReferenceNumber": "613808317649",
      "electronicCommerceIndicatorAdjustment": "01",
      "settlementDate": "2024-01-25T00:00:00.000Z"
    }
  }
}
```