# Apple Pay Transactions

NPS supports Apple Pay payments through the **Hosted Tokenization Iframe**. Your application does **not** integrate directly with Apple’s JavaScript APIs. Instead, you pass Apple Pay “payment request” parameters to the iframe, and NPS handles the end-to-end Apple Pay on the web flow on your behalf.

## What NPS Does for You

div
strong
Key idea:
br

  You never handle Apple’s payment token blob. NPS handles the Apple Pay session, merchant validation, and credential extraction inside the iframe.

In a typical Apple Pay on the web integration, your frontend creates an `ApplePaySession`, performs merchant validation (server-side), and receives an encrypted payment token (“payment blob”) for your gateway/processor to decrypt and process. Apple’s documentation emphasizes that merchant validation is performed by your server and completed in the session via `completeMerchantValidation`.

With NPS:

- The iframe creates and manages the Apple Pay session.
- NPS performs merchant validation and session handling.
- NPS receives Apple’s payment token and handles decryption/translation steps needed for processing.
- The iframe returns an **NPS Token** to the browser.


## What You Do

Your responsibilities are intentionally small:

1. Create a session token (server-to-server) and initialize the iframe.
2. Provide Apple Pay payment request parameters on the tokenization call.
3. Receive an NPS token in the browser.
4. Send the token to your backend and process the payment using the Payments API.


div
strong
Result:
br

  Apple Pay is processed the same way as card or ACH once you have an NPS token.

## Apple Pay Payment Request Parameters

Apple Pay on the web uses an “Apple Pay payment request” structure that includes the information shown on the payment sheet (total, line items, currency/country, supported networks, etc.). Apple documents this as `ApplePayPaymentRequest`.

In NPS, you **do not** create Apple objects directly. You simply supply the values NPS needs to construct the equivalent request.

### Common inputs you should be prepared to provide

- **Amount / total**
- **Currency** (e.g., `USD`)
- **Country** (e.g., `US`)
- Optional **line items** (tax, fees, discounts)
- Optional payer requirements (billing/shipping fields), if applicable


## Transaction Modes Supported by NPS

NPS supports multiple Apple Pay modes. These are determined from the Apple Pay request semantics, and NPS marks the resulting token accordingly.

### 1) Single Transaction

- Intended for a one-time Apple Pay purchase.
- The Hosted Tokenization Iframe returns a **single-use token**.
- After the token is used once, it is **disabled** and cannot be used again.


### 2) Multi‑Merchant (Service Fee) Transaction

- Intended for scenarios where a platform or partner needs to split a payment into:
  - a primary merchant transaction
  - a service fee or secondary merchant transaction
- The Hosted Tokenization Iframe returns a token that is valid for **two uses**.
- After the token is used twice, it is **disabled**.


### 3) Recurring Transaction

- Intended for subscription or recurring Apple Pay payments.
- The Hosted Tokenization Iframe returns a **reusable token**.
- This token may be used multiple times according to the recurring agreement.


div
strong
Token reuse rules matter:
br

  Single-use (and multi-use) Apple Pay tokens will be rejected after their allowed uses are consumed.

## Tokenization Flow

### High-level flow

div
ol
li
Your backend creates a JWT and exchanges it for a session token
li
Your frontend initializes the Hosted Tokenization Iframe
li
Your frontend calls 
code
tokenize()
 and includes Apple Pay request parameters
li
The iframe completes Apple Pay (session + validation + token handling)
li
The iframe returns an NPS token to the browser
li
Your frontend sends the token to your backend
li
Your backend submits a payment using the Payments API
### Example (conceptual): Tokenize with Apple Pay parameters

> The property names below are illustrative. The key concept is that you pass Apple Pay request parameters to the iframe at tokenization time.



```js
nps.tokenize({
  paymentMethod: "applepay",
  amount: 49.99,
  applePay: {
    countryCode: "US",
    currencyCode: "USD",
    total: { label: "Example Merchant", amount: "49.99" },
    lineItems: [
      { label: "Subtotal", amount: "45.00" },
      { label: "Service Fee", amount: "4.99" }
    ]
    // additional Apple Pay request parameters as needed
  }
});
```

## Processing the Payment

Once tokenization completes, your backend processes the payment using the **same pattern** as credit card or ACH token payments:

1. Receive the token from the browser
2. Call the Payments API using your Bearer JWT
3. Include the token in the payment request


div
strong
Tip:
br

  Payment responses include token metadata such as token type used and token last four (where applicable), as defined by the Payments API.

## Notifications and Lifecycle Management

Apple Pay tokens participate in **Payment Credential Lifecycle Management** and use the same notification model as other token types.

- NPS can emit a “credential updated” event through the Push Notification Service
- Subscriptions can be configured in the OSI Portal (email or webhook)
- The event indicates that something about the token changed, without disclosing sensitive details
- If needed, clients can retrieve current token details using:
  - `GET https://api.nelnetpay.com/tokenization/{token}/details`


## Summary

- Merchants do not implement Apple’s web SDK directly
- The Hosted Tokenization Iframe runs the Apple Pay session and merchant validation internally
- Tokenization returns an NPS token to the browser
- Payments are processed with the token the same way as card/ACH token payments
- NPS supports:
  - Single (1 use)
  - Multi‑merchant / service fee (2 uses)
  - Recurring (reusable)
- Apple Pay tokens participate in credential lifecycle events and notifications