Apple Pay

Apple Pay offers a fast, secure way for customers to pay on your website. With Vortex, PRTH manages the heavy lifting for merchant validation so you can implement Apple Pay with fewer steps and start accepting payments quickly.

Prerequisites and Limitations

Prerequisites: Vortex merchant ID and API keys (sandbox or live), HTTPS with a valid TLS certificate, access to the PRTH Dashboard or API.
Limitations: Apple Pay on the web requires Safari on supported Apple devices; domain association must be hosted at a fixed path; supported networks and availability vary by region and gateway.

Apple Pay Implementation Guide

Step 1: Set Up Domain Association for Apple Pay

PRTH handles Apple Pay’s merchant validation for Vortex merchants (creating the Apple Merchant ID and CSR). You don’t need Apple’s manual validation flow—just complete these steps.

1) Save the domain association ID

Copy and keep this domain association id:

7b2276657273696f6e223a312c227073704964223a2236423941383537323431454241453339444337383437374142453845413443364235373132324331464239434531323235344532314146393736433035444446222c22637265617465644f6e223a313733323132303831363731387d

Host the ID

Place the file on your web server at: /.well-known/apple-developer-merchantid-domain-association

For example, if your domain is https://yourwebsite.com, the file must be reachable at: https://yourwebsite.com/.well-known/apple-developer-merchantid-domain-association.

2) Register your domain with PRTH

After hosting the file, ask PRTH to register your domain with Apple via the PRTH Dashboard (Payment Methods → Domain Registration) or the API.

curl https://api.prth.com/v1/payment_method_domains \
  -u "live_api_key_here:" \
  -d domain_name="yourwebsite.com"

Note: Register a domain only once per PRTH account to avoid duplicates.

3) Begin Apple Pay transactions

Once PRTH completes registration, you can start accepting Apple Pay using your live API keys. No extra merchant validation is required on your end.

Why this matters

PRTH’s managed validation removes complex steps, ensuring your domain is fully verified and ready for Apple Pay with less effort.

Step 2: Add the Apple Pay Button to Your Checkout Page

Serve over HTTPS

Apple Pay requires secure pages. Make sure your checkout is fully HTTPS with a valid certificate.

Reference Apple Pay JS

<script type="text/javascript" src="https://applepay.cdn-apple.com/jsapi/v1/apple-pay-sdk.js"></script>

Add the button

Follow Apple’s design rules when rendering the button:

<apple-pay-button buttonstyle="black" type="plain" locale="en-US"></apple-pay-button>

Set up a basic payment request

var request = {
  countryCode: 'US',
  currencyCode: 'USD',
  total: { label: 'Your Store Name', amount: '10.00' }
};

Test the button

Verify rendering and tap/Click-to-Pay flows on supported devices (iPhone, iPad, Mac). Use Apple’s sandbox to simulate payments.

Reference: See Apple’s Apple Pay on the web docs for customization and event lifecycles.

Step 3: Implement Apple Pay with Vortex

Check the API Reference for detailed fields, status codes, and examples.

Now that the button and domain are set, send the encrypted Apple Pay payload to Vortex for authorization.

Configure the payment request for Vortex

var paymentRequest = {
  merchantCapabilities: ['supports3DS'],
  supportedNetworks: ['visa', 'masterCard', 'amex'],
  countryCode: 'US',
  currencyCode: 'USD',
  total: { label: 'Your Store Name', amount: '10.00' }
};

Perform merchant validation via your server

Your backend should call your Vortex endpoint to complete merchant validation.

var validationURL = event.validationURL;
fetch('https://your-vortex-server/merchant-validation', {
  method: 'POST',
  body: JSON.stringify({ validationURL: validationURL })
})
  .then(function(res) { return res.json(); })
  .then(function(session) { event.completeMerchantValidation(session); });

Build the transaction payload for Vortex

Include the Apple Pay token in cardAccount.mobileWallet and use your Vortex merchant ID (not the Apple Merchant ID).

var transactionPayload = {
  provider: 'Apple_Pay',
  tenderType: 'Card',
  amount: '10.00',
  posData: { terminalId: '001', transactionType: 'Purchase' },
  cardAccount: { mobileWallet: { encryptedPayload: event.payment.token } },
  merchantId: 'your-vortex-merchant-id'
};

Authorize the payment with Vortex

fetch('https://your-vortex-server/payment', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer yourAccessToken',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(transactionPayload)
})
  .then(function(response) {
    if (response.status === 200) {
      event.completePayment(ApplePaySession.STATUS_SUCCESS);
    } else {
      event.completePayment(ApplePaySession.STATUS_FAILURE);
    }
  });

Store the response

Persist the returned transaction ID, amount, and status for reconciliation and audit.

Testing the Integration

Use Vortex sandbox keys and Apple’s sandbox test cards/devices.
Confirm domain association file is served with Content-Type: text/plain and is publicly reachable.
Validate success and failure flows (canceled, declined, 3‑D Secure challenged/failed where applicable).

Troubleshooting

Domain registration failed: Re-check file path and contents. The endpoint must return HTTP 200 and the raw file (no HTML wrappers, redirects, or compression issues).
Button not showing: Ensure Safari on a supported device, page over HTTPS, and ApplePaySession.canMakePayments() returns true.
Payment fails at authorization: Inspect Vortex response body; verify token mapping under cardAccount.mobileWallet and that merchantId is your Vortex ID.

NFC and Apple Pay (In‑Person Tap to Pay)

Apple Pay also powers in‑person contactless payments via NFC. While this guide focuses on Apple Pay on the web, the same Vortex payment rails support NFC transactions at the point of sale.

When to Use

Customer taps an NFC‑enabled plastic card or a device wallet (Apple Pay) at a reader.
Best for customer‑facing POS (kiosks, retail counters). Less common where cards are handled by staff away from the customer (e.g., many table‑service restaurants and bars).

Requirements & Equipment

NFC‑capable reader injected with PRTH/PPS keys.
POS or middleware that can read encrypted EMV/NFC TLV data from the device/reader.
Vortex merchant credentials (sandbox or live) and network connectivity.

Implementation Steps

Endpoint and method – Make a POST request to /checkout/v3/payment endpoint with required parameters.
Authentication & headers – Include your credentials in the Authorization header and set Content-Type: application/json.
Payload (EMV/NFC) – Provide the EMV data returned by the reader:
- cardAccount.emvDataKsn ← TLV tag C0 (key serial number)
- cardAccount.emvData ← TLV tag C2 (encrypted EMV/NFC payload)
Echo for debugging (optional) – Append echo=true as a URL parameter to receive the response object in-line.
Handle responses – On success, the sandbox returns HTTP 201 and status: Approved. Use documented test cards to trigger declines.

Example Request (NFC/EMV)

{
  "merchantId": "4xxx0",
  "tenderType": "Card",
  "amount": "0.01",
  "cardAccount": {
    "emvData": "Xym9TXlYqOusxG1JrdlDqThnzBVZHnTziDjptEdBsv0MasvWV8IOF75Ld0OlntfIxxxxxxxxxxxxxxxx\/...",
    "emvDataKsn": "8033xxxxxxx000011"
  }
}

Testing & Expected Responses

Sandbox approvals – Any properly formatted card/device data is typically approved.
Declines – Use the published testing cards and scenarios to simulate declines and edge cases.
Receipts & reconciliation – Persist the returned transaction ID, amount, and status.

Things to Keep in Mind

The payment data is fundamentally EMV/NFC; Apple Pay simply provides a secure, tokenized way to transmit it.
Ensure the domain association for web Apple Pay and the reader key injection for in‑person NFC are handled separately—they are different setup tracks.