Skip to content
/
Apple Pay Transactions
Last updated

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

Key idea:
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.
Result:
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.
Token reuse rules matter:
Single-use (and multi-use) Apple Pay tokens will be rejected after their allowed uses are consumed.

Tokenization Flow

High-level flow

  1. Your backend creates a JWT and exchanges it for a session token
  2. Your frontend initializes the Hosted Tokenization Iframe
  3. Your frontend calls tokenize() and includes Apple Pay request parameters
  4. The iframe completes Apple Pay (session + validation + token handling)
  5. The iframe returns an NPS token to the browser
  6. Your frontend sends the token to your backend
  7. 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.

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
Tip:
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
Previous page
Next page