- Get Started
- Guides
- Integrations
- References
- API Reference
- Basic Payment
- Forex
- Authentication
- Card Account
- Apple Pay
- Virtual Account
- Bank Account
- Token Account
- Customer
- Billing Address
- Merchant Billing Address
- Shipping Address
- Merchant Shipping Address
- Corporate
- Sender
- Recipient
- Merchant
- Marketplace & Cart
- Airline
- Lodging
- Passenger
- Tokenization
- Recurring Migration
- 3D Secure
- Custom Parameters
- Async Payments
- Webhook notifications
- Job
- Risk
- Point of Sale
- Response Parameters
- Card On File
- Chargeback
- Result Codes
- Payment Methods
- Transaction Flows
- Regression Testing
- Data Retention Policy
- API Reference
- Support
Apple Pay
Introduction
Apple Pay can be utilized as a checkout option on a payment page as well as a direct checkout option on the cart page (fast checkout). After configuring your environment, loading the Apple Pay button via COPYandPAY payment widget is just like loading any other brand, i.e. in step 2, APPLEPAY (The "Payment Orchestration Platform" handles the decryption of the Applepay token) or APPLEPAYTKN (Acquirer handles the Token decryption) must be specified as a brand. Once the Apple Pay button will be used by the consumer, the Apple Pay payment sheet will appear on the device.
As soon as the consumer starts to interact with the Apple Pay payment sheet, several events will be triggered. All events can be consumed by implementing the COPYandPAY API callback functions. All callback functions offered by the Apple Pay SDK are wrapped into the COPYandPAY API. No interaction with the Apple Pay SDK is required.
For steering the Apple Pay payment sheet or for updating data on the Apple Pay payment sheet after the consumer started to interact with it, several options are available.
Configuration
Processing Apple Pay requires certificates. You can either use our certificates or create your own certificates. Using our certificates is recommended as:
- It is easier and faster to integrate.
- Apple developer account is not required.
- You do not need to worry about expiring certificates. We will re-new them for you.
In addition to the certificates, your server must be set up such that pages are served over HTTPS. See Setting Up Your Server for more details.
Use our Apple Pay certificates
- In Open Payment Platform, select your merchant in the entity tree. Navigate to Administration -> Mobile Payment, expand the section Apple Pay Web Merchant Registration, click Check registration status.
- Download the domain-verification file and host it at the specified path. Note that this step is not mandatory for UAT.
- Enter your domain name and click Register.
Use your own Apple Pay certificates
With your Apple Developer account, create a merchant ID and generate two certificates: Payment Processing Certificate and Merchant Identity Certificate.
Payment Processing Certificate
- In Open Payment Platform, select your merchant in the entity tree. Navigate to Administration -> Mobile Payment, expand the section Apple Pay - Payment Processing Certificate, click Generate keys and download CSR (certificate signing request).
- In Apple Developer, select the merchant ID and choose Create Certificate under Apple Pay Payment Processing Certificate. Upload the CSR from the previous step, and download the certificate.
- Upload the certificate in Open Payment Platform, where the CSR was created.
Merchant Identity Certificate
- In Open Payment Platform, select your merchant in the entity tree. Navigate to Administration -> Mobile Payment, expand the section Apple Pay on the Web, click Generate keys and download CSR (certificate signing request).
- In Apple Developer, select the merchant ID and choose Create Certificate under Apple Pay Merchant Identity Certificate. Upload the CSR from the previous step, and download the certificate.
- Upload the certificate in Open Payment Platform, where the CSR was created.
Finally, add your domain name in Apple Developer. See Configuring Your Environment for more detailed instructions.
Apple Pay on the payment page
Loading the Apple Pay button via COPYandPAY payment widget is just like loading any other brand, i.e. in step 2, APPLEPAY or APPLEPAYTKN(if the Acquirer will handle the Token decryption) must be specified as a brand.
See an example below.
Note that the Apple Pay button only appears on compatible devices.
Apple Pay options
As with other options, you can modify the Apple Pay payment sheet behavior by using wpwlOptions.applePay
.
Parameter | Mandatory | Description | Default value | Examples |
---|---|---|---|---|
version | No | The Apple Pay Javascript API version. For the best compatibility, use the lowest possible version number that supports the features required. See Apple Pay on the Web Version History for version information. The list below gives a quick overview of some selected versions and supported operating systems:
| 1 | version: 3 |
checkAvailability | No | Specify the Apple Pay support detection method. The value must be one of the followings:
|
canMakePayments | checkAvailability: "applePayCapabilities" |
merchantIdentifier | Yes/No | The merchant ID created when the merchant enrolled in Apple Pay.
This parameter is required when checkAvailability is "applePayCapabilities" or "canMakePaymentsWithActiveCard".
If you use our certificates, set this option with our entityId .
|
N/A | merchantIdentifier: "com.company" |
buttonSource | No | The Apple Pay button source. There are two options to render the Apple Pay button:
The "css" option usually works fine. However, if some buttonType does not work for you, please try the "js" option. If |
css | buttonSource: "js" |
buttonStyle | No | The Apple Pay button style. The value must be one of the followings: "white-outline", "white", "black". | white-outline | buttonStyle: "black" |
buttonType | No | A type that indicates the button types that you can display to initiate Apple Pay transactions. The supported values are: "add-money", "book", "buy", "check-out", "continue", "contribute", "donate", "order", "pay", "plain", "reload", "rent", "subscribe", "support", "tip", "top-up". Note that with buttonSource="css" some button types might require specific versions, or might not work at all. See the reference for more details. |
plain | buttonType: "check-out" |
displayName | No | A string of 64 or fewer UTF-8 characters containing the canonical name for your store, suitable for display. Do not localize the name. The value is displayed in the Touch Bar on supported models of MacBook Pro. | N/A | displayName: "MyStore" |
total | Yes/No | An object representing the total for the payment. It can contain the following properties:
|
amount:{checkout amount} type:final |
total: { label: "COMPANY, INC." } |
currencyCode | Yes/No | The three-letter ISO 4217 currency code for the payment. If not specified, the currency from the checkout is used. This parameter is required for the fast checkout. |
{checkout currency} | currencyCode: "USD" |
countryCode | No | The merchant’s two-letter ISO 3166 country code. | wpwlOptions.locale |
countryCode: "US" |
merchantCapabilities | No | The payment capabilities supported by the merchant. The supported values are:
|
supports3DS | merchantCapabilities: ["supports3DS", "supportsCredit"] |
supportedNetworks | No | The payment networks supported by the merchant. The supported values are: "amex", "bancomat" (14), "bancontact" (14), "cartesBancaires" (4), "chinaUnionPay", "dankort" (13), "discover", "eftpos" (4), "electron" (4), "elo" (5), "girocard" (11), "interac", "jcb" (2), "mada" (5), "maestro" (4), "masterCard", "mir" (11), "privateLabel", "visa", "vPay" (4). Note that the numbers in the parentheses indicate the Apple Pay versions where they are first available, e.g. "jcb" is only available starting from version 2. The payment networks without numbers are available from version 1. |
["amex", "discover", "masterCard", "visa"] | supportedNetworks: ["amex", "chinaUnionPay", "discover", "jcb", "masterCard", "visa"] |
lineItems | No | An array of items explaining additional charges, discounts, and pending costs. Each item represents a line on the payment sheet. The item must contain:
|
N/A | lineItems: [{ label: "Bag Subtotal", amount: "35.00" }, { label: "Free Shipping", amount: "0.00" }, { label: "Estimated Tax", amount: "3.06" }] |
shippingMethods | No | An array of available methods for shipping physical goods. Each shipping method must contain:
|
N/A | shippingMethods: [{ label: "Free Shipping", amount: "0.00", identifier: "free", detail: "Delivers in five business days", }, { label: "Express Shipping", amount: "5.00", identifier: "express", detail: "Delivers in two business days", }] |
shippingType | No | Indicate how purchased items are to be shipped. The value must be one of the followings: "shipping", "delivery", "storePickup", "servicePickup". | shipping | shippingType: "shipping" |
supportedCountries | No | An array that limits payment cards to those that were issued in specific countries. Indicate the supported countries by using ISO 3166 country codes. The supportedCountries list does not affect the currency used for the transaction, and it applies to all payment cards in Wallet. Available in Apple Pay JS API version 3. |
N/A | supportedCountries: ["US"] |
supportsCouponCode | No | A Boolean value that determines whether the payment sheet displays the coupon code field. Available in Apple Pay JS API version 12. |
false | supportsCouponCode: true |
couponCode | No | The initial coupon code. Available in Apple Pay JS API version 12. |
N/A | couponCode: "DISCOUNT20" |
requiredShippingContactFields | No | The fields of shipping information the user must provide to fulfill the order. The supported field names are: "email", "name", "phone", "postalAddress", and starting from version 3: "phoneticName". You will receive the customer's name when you request postalAddress. If you don't need the customer's address, you can request the name contact field directly. | N/A | requiredShippingContactFields: [ "postalAddress", "email" ] |
shippingContact | No | If you have an up-to-date shipping address on file, you can set it here. The information you provide in shippingContact is displayed in the payment sheet as the default shipping address. The user can either keep the address you provided or select another address. Provide your user's shipping contact info only if you are requiring shipping contact information. The possible properties are:
|
N/A | shippingContact: { addressLines: ["123 Any Street"], locality: "Any Town", administrativeArea: "CA", postalCode: "95014", countryCode: "US", familyName: "COMPANY, INC." } |
requiredBillingContactFields | No | The fields of billing information the user must provide to process the transaction. The only supported field is: "postalAddress". You will receive the postal address as well as the user's name after the user authorizes the transaction. | N/A | requiredBillingContactFields: [ "postalAddress" ] |
billingContact | No | If you have an up-to-date billing address on file, you can set it here. This billing address appears in the payment sheet. The user can either use the address you specify or select a different address. Note: If you supply a billing address, you must also request "postalAddress" in requiredBillingContactFields. See shippingContact for all available properties. |
N/A | billingContact: { addressLines: ["123 Any Street"], locality: "Any Town", administrativeArea: "CA", postalCode: "95014", countryCode: "US", familyName: "COMPANY, INC." } |
shippingContactEditingMode | No | A value that indicates whether the shipping mode prevents the user from editing the shipping address. The supported values are:
Add postalAddress to requiredShippingContactFields to display the pickup address. Set the shippingContact to the pickup address. Available in Apple Pay JS API version 12. |
enabled | shippingContactEditingMode: "storePickup" |
submitOnPaymentAuthorized | No | Automatically submit customer information and billing address received from Apple Pay as a part of the transaction.
Possible values are:
|
N/A | submitOnPaymentAuthorized: [ "customer", "billing" ] |
Apple Pay callback functions
If the callback functions are used and data will get updated due to the consumer interaction with the Apple Pay payment sheet, the COPYandPAY checkout needs to get updated as well.
The following table lists all available Apple Pay callback functions that you can use with wpwlOptions.applePay
.
Callback function | Description | Examples |
---|---|---|
onCancel | An event handler that is called when the Apple Pay payment sheet is dismissed. Note that this function can be called even after the onPaymentAuthorized event handler has been called. | onCancel: function () { } |
onPaymentMethodSelected | An event handler that is called when a new payment method is selected. The event parameter is an object that describes the selected Apple Pay payment card. The object contains:
|
onPaymentMethodSelected: function (paymentMethod) { // Calculate new costs return { newTotal: { label: "Total", amount: "42.00" }, newLineItems: [{ label: "Shipping", amount: "2.00" }, { label: "Tax", amount: "3.00" }] }; } |
onCouponCodeChanged | An event handler called by the system when the user enters or updates a coupon code. The parameter is the updated coupon code from the payment sheet. The handler should return an object containing:
|
onCouponCodeChanged: function (couponCode) { // Calculate new costs return { newTotal: { label: "Total", amount: "42.00" }, newLineItems: [{ label: "Shipping", amount: "2.00" }, { label: "Tax", amount: "3.00" }] }; } |
onShippingContactSelected | An event handler that is called when a shipping contact is selected in the payment sheet. The event parameter is a redacted shipping contact. The redacted information includes only the necessary data for completing tasks such as calculating taxes or shipping costs. The information may differ based on the user's geographic region. For Canada and United Kingdom, a redacted shipping address excludes the last three characters of the postal code. For US addresses, the redacted zip code contains the first five digits. The full postal code is provided after the user authorizes the transaction. See
|
onShippingContactSelected: function (shippingContact) { // Calculate new costs return { newTotal: { label: "Total", amount: "42.00" }, newLineItems: [{ label: "Shipping", amount: "2.00" }, { label: "Tax", amount: "3.00" }] }; } |
onShippingMethodSelected | An event handler that is called when a shipping method is selected in the payment sheet. The event parameter is an object that describes the selected shipping method for delivering physical goods. The object contains:
|
onShippingMethodSelected: function (shippingMethod) { // Calculate new costs return { newTotal: { label: "Total", amount: "42.00" }, newLineItems: [{ label: "Shipping", amount: "2.00" }, { label: "Tax", amount: "3.00" }] }; } |
onPaymentAuthorized | An event handler that is called when the user has authorized the Apple Pay payment with Touch ID, Face ID, or passcode. The event parameter contains: shippingContact and billingContact. See shippingContact for all available properties. If the handler returns nothing, it is considered successful and the payment will proceeds. Otherwise, the handler can return an object containing:
|
onPaymentAuthorized: function (payment) { //Save contacts from //payment.shippingContact //and //payment.billingContact } |
Promises
Your handler can return a promise if it needs to do an asynchronous work. It can be any thenable object. In particular, both JavaScript Promise and jQuery Promise are supported.
For example, the total amount might have been changed because a different shipping method was selected. You will need to implement onPaymentAuthorized
, and use an ajax call to your server to do a server-to-server call to update the checkout amount. The function should return a promise, which once fulfilled, should signify that the call is completed.
Example:
wpwlOptions.applePay.onPaymentAuthorized = function(payment) {
// Call your server to update the checkout
return $.post("https://your.server", {
amount: theNewAmount
}).then(function() {
return {
status: "SUCCESS"
};
});
};
Options and callback example
For example, you might want to offer several shipping options by using applePay.shippingMethods
,
or calculate the tax when a shipping address is selected by using applePay.onShippingContactSelected
.
To quick start your integration, we recommend use our example code below as a guidance (Click js tab to see the code example).
Apple Pay registration tokens
You can use Apple Pay together with Tokenization during payment,
i.e. add createRegistration=true
in the checkout request, to create a registration token that can be used in subsequent payments.
Add one of the following options to wpwlOptions.applePay
to accordingly adjust the Apple Pay payment sheet:
automaticReloadPaymentRequest, recurringPaymentRequest, deferredPaymentRequest
You can set only one of these options.
Parameter | Description | Examples |
---|---|---|
automaticReloadPaymentRequest | A dictionary that represents a request to set up an automatic reload payment, such as a store card top-up or a prepaid account. See ApplePayAutomaticReloadPaymentRequest for more details. Apple Pay issues an Apple Pay Merchant Token if the user's payment network supports merchant-specific payment tokens. Otherwise, Apple Pay issues a device token as usual. Leave the field tokenNotificationURL empty. We set the value for you and handle token notifications on your behalf, i.e. when life-cycle updates to the merchant token, for example, when the card issuer or the user deletes the merchant token, occur, we receive notifications from Apple Pay and update the token for you. |
automaticReloadPaymentRequest: { paymentDescription: "Card Top-up", automaticReloadBilling: { type: "final", label: "Automatic Top-up", amount: "10.00", paymentTiming: "automaticReload", automaticReloadPaymentThresholdAmount: "2.00", }, billingAgreement: "Reload when below $2", managementURL: "https://your-domain.com/token-management" } |
recurringPaymentRequest | A dictionary that represents a request to set up a recurring payment, typically a subscription. See ApplePayRecurringPaymentRequest for more details. Apple Pay issues an Apple Pay Merchant Token if the user's payment network supports merchant-specific payment tokens. Otherwise, Apple Pay issues a device token as usual. Leave the field tokenNotificationURL empty. We set the value for you and handle token notifications on your behalf, i.e. when life-cycle updates to the merchant token, for example, when the card issuer or the user deletes the merchant token, occur, we receive notifications from Apple Pay and update the token for you. |
recurringPaymentRequest: { paymentDescription: "Subscription", regularBilling: { type: "final", label: "Subscription", amount: "20.00", paymentTiming: "recurring", recurringPaymentStartDate: new Date("2022-01-01T00:00:00"), recurringPaymentIntervalUnit: "month", recurringPaymentIntervalCount: 6, recurringPaymentEndDate: new Date("2024-01-01T00:00:00") }, billingAgreement: "Change $20 every six months starting on 01/01/2022 and ending on 01/01/2024", managementURL: "https://your-domain.com/token-management" } |
deferredPaymentRequest | A dictionary that represents a request to set up a deferred payment, such as a hotel booking or a pre-order. See ApplePayDeferredPaymentRequest for more details. |
deferredPaymentRequest: { paymentDescription: "Hotel", deferredBilling: { type: "final", label: "After Trial Period", amount: "50.00", paymentTiming: "deferred", deferredPaymentDate: new Date("2024-01-01T00:00:00") }, billingAgreement: "Charge $50 on 01/01/2024", managementURL: "https://your-domain.com/token-management" } |
Errors
Your handlers onShippingContactSelected
and onPaymentAuthorized
can return an array of errors if there is something wrong with the given shippingContact or billingContact.
Each error can point to a specific problem in a contact field. The object structure is as follows:
Parameter | Description |
---|---|
code | Must be one of the followings:
|
contactField | Must be one of the followings: "phoneNumber", "emailAddress", "name", "phoneticName", "postalAddress", "addressLines", "locality", "subLocality", "postalCode", "administrativeArea", "subAdministrativeArea", "country", "countryCode", if the code is "shippingContactInvalid" or "billingContactInvalid". Otherwise, this field is optional.
|
message | A localized, user-facing string that describes the error. |