Apple Pay Payments

Process Apple Pay payments through Nuvion's unified payment API.

Overview

Apple Pay provides a fast, secure payment method for customers using Apple devices. Benefits include:

Fast checkout - Pre-filled payment details from Apple Wallet

Enhanced security - Tokenized card data, biometric authentication

Higher conversion - Seamless experience for Apple users

No card entry - Reduces friction and errors

Device authentication - Touch ID, Face ID, or passcode

Important: With Nuvion's unified API, you never handle Apple Pay tokens. We manage everything on our hosted payment page.

Authentication

All requests must include your Client ID in the Authorization header.
See Authentication Guide for details.

No Encryption Needed

Unlike card payments, Apple Pay requires no encryption on your end. Simply specify the payment type:

{
  "payment_method": {
    "type": "apple_pay"
  }
}

The Apple Pay token is obtained and processed entirely on Nuvion's hosted page.

Endpoint

POST /v2/payments

Base URLs:

Sandbox: https://sandbox-acquiring.globalremitfs.com

Production: https://acquiring.globalremitfs.com

Payment Flow

Apple Pay follows a redirect-based flow (no frontend integration needed):

1. Merchant initiates payment → POST /v2/payments with type: "apple_pay"
2. API returns challenge_url → Redirect customer to this URL
3. Customer completes Apple Pay → On Nuvion's hosted page
4. Nuvion processes payment → Customer redirected back to merchant
5. Merchant receives webhook → Payment confirmation (optional)

You never touch the Apple Pay token!

Request Parameters

Field	Type	Required	Description
`merchant_reference`	string	Yes	Your unique order/transaction reference (must be unique)
`merchant_meta`	object	No	Custom metadata (max 10 key-value pairs)
`amount`	integer	Yes	Amount in smallest currency unit (cents for USD, pence for GBP)
`currency`	string	Yes	ISO 4217 currency code (USD, GBP, EUR, etc.)
`description`	string	No	Payment description (shown to customer)
`payment_method`	object	Yes	Payment method details
`payment_method.type`	string	Yes	Must be `"apple_pay"`
`billing_address`	object	Yes	Customer billing address
`billing_address.first_name`	string	Yes	Customer first name
`billing_address.last_name`	string	Yes	Customer last name
`billing_address.email`	string	Yes	Customer email (must be valid format)
`billing_address.address_line_one`	string	Yes	The first line of the billing address
`billing_address.address_line_one`	string	No	The second line of the billing address
`billing_address.country`	string	Yes	ISO 3166-1 alpha-2 country code (US, GB, etc.)
`billing_address.city`	string	Yes	City name
`billing_address.state`	string	Yes	State name
`billing_address.zip`	string	No	Postal/ZIP code
`ip_address`	string	Yes	Customer IP address (for fraud detection)
`redirect_url`	string	Yes	URL to redirect customer after payment completion
`webhook_url`	string	No	URL for payment status webhooks

Note: No payment_method.data field needed! Just send type: "apple_pay".

Response Fields (Initiation)

Success Response (HTTP 200)

Field	Type	Description
`status`	string	Always `"successful"`
`message`	string	Success message
`data`	object	Payment response data
`data.payment_id`	string	Unique payment identifier (ULID format)
`data.merchant_reference`	string	Your original transaction reference
`data.merchant_meta`	object	Your custom metadata (if provided)
`data.amount`	integer	Payment amount
`data.currency`	string	Payment currency
`data.status`	string	`"apple_pay_required"` - customer needs to complete Apple Pay
`data.session_id`	string	Apple Pay session identifier
`data.challenge_url`	string	Redirect customer to this URL
`data.created_at`	number	Payment creation timestamp (Unix ms)
`data.completed_at`	number	`null` (payment not yet complete)

Example Request

Full JSON

{
  "merchant_reference": "order_54321",
  "merchant_meta": {
    "customer_id": "cust_999",
    "order_type": "premium"
  },
  "amount": 9999,
  "currency": "USD",
  "description": "Premium Subscription - Annual",
  "payment_method": {
    "type": "apple_pay"
  },
  "billing_address": {
    "first_name": "John",
    "last_name": "Appleseed",
    "email": "john.appleseed@example.com",
    "country": "US",
    "city": "Cupertino",
    "zip": "95014"
  },
  "ip_address": "203.0.113.42",
  "redirect_url": "https://yoursite.com/payment/callback",
  "webhook_url": "https://yoursite.com/webhooks/payment"
}

cURL

Node.js

Python

Example Response

Apple Pay Session Created

{
  "status": "successful",
  "message": "Apple Pay session created",
  "data": {
    "payment_id": "01HXYZ123ABC456DEF789GHI",
    "merchant_reference": "order_54321",
    "merchant_meta": {
      "customer_id": "cust_999",
      "order_type": "premium"
    },
    "amount": 9999,
    "currency": "USD",
    "status": "apple_pay_required",
    "session_id": "01HXYZ987APPLEPAY654XYZ",
    "challenge_url": "https://acquiring.globalremitfs.com/apple-pay-sessions/01HXYZ987APPLEPAY654XYZ",
    "created_at": 1699564800000,
    "completed_at": null
  }
}

Action: Redirect the customer to challenge_url.

Redirect URL Parameters

After Apple Pay completion, the customer is redirected to your redirect_url with these query parameters:

Parameter	Description
`payment_id`	Nuvion payment ID
`merchant_reference`	Your original transaction reference
`status`	Either `"success"` or `"failed"`

Example successful redirect:

https://yoursite.com/payment/callback?payment_id=01HXYZ123ABC456DEF789GHI&merchant_reference=order_54321&status=success

Example failed redirect:

https://yoursite.com/payment/callback?payment_id=01HXYZ123ABC456DEF789GHI&merchant_reference=order_54321&status=failed

Your redirect URL may already have query parameters. Nuvion's parameters are appended safely:

https://yoursite.com/callback?session=abc123&payment_id=01HXYZ...&merchant_reference=order_54321&status=success

Handling the Redirect

Webhooks

If you provide a webhook_url, Nuvion will send a POST request with the payment result:

Successful payment webhook:

{
  "event": "payment.completed",
  "payment_id": "01HXYZ123ABC456DEF789GHI",
  "merchant_reference": "order_54321",
  "merchant_meta": {
    "customer_id": "cust_999",
    "order_type": "premium"
  },
  "status": "completed",
  "amount": 9999,
  "currency": "USD",
  "authorization_code": "APPLEPAY123456",
  "created_at": 1699564800000,
  "completed_at": 1699564815000
}

Failed payment webhook:

{
  "event": "payment.failed",
  "payment_id": "01HXYZ123ABC456DEF789GHI",
  "merchant_reference": "order_54321",
  "merchant_meta": {
    "customer_id": "cust_999",
    "order_type": "premium"
  },
  "status": "failed",
  "failure_reason": "Customer cancelled Apple Pay",
  "amount": 9999,
  "currency": "USD",
  "created_at": 1699564800000,
  "completed_at": 1699564810000
}

Always verify webhook signatures (documentation coming soon).

Device Compatibility

Apple Pay is available on:

Device Type	Requirements
iPhone	iPhone 6 and later, iOS 10+
iPad	iPad Pro, iPad Air 2+, iPad mini 3+, iOS 10+
Mac	Safari on macOS Sierra+, with TouchID or paired device
Apple Watch	Series 1 and later

Browser Support:

Safari on iOS/macOS

Chrome, Edge, Firefox on macOS (with Apple Pay enabled)

Testing

Test Environment

In sandbox mode, the Apple Pay button on the hosted page will:

Display normally if accessed from a compatible device

Show a fallback message on incompatible devices/browsers

Use test Apple Pay credentials (no real cards charged)

Test Cards (Sandbox)

When testing in sandbox, you can use:

Any card added to your Apple Wallet in test mode

Apple's test cards (available in Apple Developer Sandbox)

Note: Sandbox Apple Pay requires:

Safari browser (or compatible browser on macOS)

Apple Pay enabled in System Preferences (Mac) or Settings (iOS)

Desktop Testing

You can test Apple Pay on macOS using:

Safari browser

An iPhone/Apple Watch with Apple Pay set up nearby

Or a Mac with Touch ID

Common Errors

Duplicate merchant_reference

Error: "A payment with this merchant reference already exists"
Solution: Each merchant_reference must be unique

Client ID not found

Error: "Client ID not found"
Solution: Verify your Client ID. See Authentication Guide

Apple Pay not available

Issue: Customer sees "Apple Pay not available" on hosted page
Cause: Incompatible device/browser, or Apple Pay not set up
Solution: Provide alternative payment methods (card payment)

Payment cancelled

Issue: Customer redirected back with status=failed
Cause: Customer cancelled Apple Pay or authentication failed
Solution: Allow customer to retry or choose different payment method

What You Don't Need

Unlike traditional Apple Pay integrations, with Nuvion you don't need:

❌ Apple Developer Account

❌ Apple Pay Merchant Identity Certificate

❌ Domain verification with Apple

❌ Apple Pay JS SDK integration

❌ Merchant validation endpoints

❌ Apple Pay token handling/decryption

❌ Frontend Apple Pay button implementation

We handle all of that for you!

What Nuvion Handles

On the hosted Apple Pay page, we:

✅ Display the Apple Pay button

✅ Validate the merchant with Apple

✅ Create the Apple Pay session

✅ Handle payment authorization

✅ Decrypt and process the Apple Pay token

✅ Process the payment with card networks

✅ Redirect customer back to you

✅ Send webhook notifications

Security

What's Protected

Apple Pay tokens - Never touch your servers

Card details - Tokenized by Apple, never exposed

Biometric authentication - Face ID, Touch ID, or passcode required

Device verification - Secure Element chip validates device

Your Responsibilities

Use HTTPS for all URLs (redirect_url, webhook_url)

Validate webhook signatures (when implemented)

Store payment_id for reference and support

Don't log sensitive customer data

Best Practices

✅ DO

Show "Pay with Apple Pay" option clearly to Apple users

Handle both success and failure redirects gracefully

Implement webhook handling for reliability

Provide alternative payment methods (not all customers have Apple Pay)

Test on real Apple devices before production

Log payment_id for support inquiries

❌ DON'T

Assume all customers have Apple Pay

Skip alternative payment methods

Ignore failed payment redirects

Use same merchant_reference for retries

Try to implement Apple Pay SDK yourself (we handle it!)

Integration Checklist

Implement payment initiation endpoint (backend)

Handle redirect to challenge_url (backend)

Implement redirect_url handler (backend)

Implement webhook_url handler (optional but recommended)

Test with real Apple device in sandbox

Verify success and failure flows

Add alternative payment methods

Go live!

Support

Email: support@nuvion.com

Documentation: https://acquiring-docs.globalremitfs.com

Non-3DS Card Payments - Alternative payment method

3DS Card Payments - Secure card payments

Authentication Guide - API authentication

Apple Pay

Apple Pay Payments#

Overview#

Authentication#

No Encryption Needed#

Endpoint#

Payment Flow#

Request Parameters#

Response Fields (Initiation)#

Success Response (HTTP 200)#

Example Request#

Full JSON#

cURL#

Node.js#

Python#

Example Response#

Apple Pay Session Created#

Redirect URL Parameters#

Handling the Redirect#

Webhooks#

Device Compatibility#

Testing#

Test Environment#

Test Cards (Sandbox)#

Desktop Testing#

Common Errors#

Duplicate merchant_reference#

Client ID not found#

Apple Pay not available#

Payment cancelled#

What You Don't Need#

What Nuvion Handles#

Security#

What's Protected#

Your Responsibilities#

Best Practices#

✅ DO#

❌ DON'T#

Integration Checklist#

Support#

Related Documentation#