1.19. Apple Pay Web

Introduction

Apple Pay is an electronic wallet system that allows Payer to make one-click payment using a card token issued together with Apple and Issuer bank. There is no need to enter card details during Apple Pay transaction. Access to this payment mechanism is possible from any device, which supports Apple Pay. After choosing Apple Pay payment method, the payer will see the form on which he confirms his Apple account and card he is going to use to pay for order. If payer doesn’t have a previously registered card, he may do it while making payment.

See terms definitions in Glossary.

If accepting payments occurs on the Payneteasy payment page, no additional integration with Apple is required from the Connecting Party.
To use Apple Pay on the Payneteasy payment page, do the following:

  1. Enable Apple Pay on the payment page template by adding macro.

  2. Inform Payneteasy support about the need to connect Apple Pay and send updated templates.

The Apple Pay button will automatically appear on the Payneteasy checkout page if:

  1. The payer uses the Safari browser on a device that supports Apple Pay.

  2. The payer has Apple Pay cards available for payment.

Note

It might be necessary for Connecting Party to register Merchant ID, issue Payment Processing Certificate and Merchant Identity Certificate in Apple in order to launch Apple Pay. For details please contact Payneteasy support manager.

Apple Pay Flow

participant Payer as C participant "Connecting Party" as cp autonumber C -> cp: Checkout activate cp alt sale/preauth cp -> Payneteasy: sale-form/ENDPOINTID activate Payneteasy cp -> Payneteasy: preauth-form/ENDPOINTID end Payneteasy --> cp: status=processing\nredirect-url deactivate Payneteasy cp --> C: Provide **redirect-url** to payer's browser deactivate cp activate C loop cp -> Payneteasy: Request /api/v2/status activate cp activate Payneteasy Payneteasy --> cp: status=processing deactivate cp deactivate Payneteasy end C -> "Apple Pay": Check if Apple Pay is supported on Payer's device activate "Apple Pay" "Apple Pay" --> C: Apple Pay response deactivate "Apple Pay" C -> C: Display Apple Pay button C -> "Apple Pay": Provide Apple payment data for processing deactivate C activate "Apple Pay" "Apple Pay" --> Payneteasy: Processing with Apple Pay payment data deactivate "Apple Pay" activate Payneteasy Payneteasy -> Payneteasy: Process payment Payneteasy --> C: Redirect to **redirect_url** activate C C -> cp: Return to the Shop deactivate C activate cp group Get Final Status == Receive Connecting Party Callback == cp <- Payneteasy : callback with final status Payneteasy <-- cp: HTTP 200 deactivate Payneteasy == Order Status request == cp -> Payneteasy: Get status by Order ID\napi/v2/status activate Payneteasy Payneteasy --> cp : Response\nstatus,order-stage deactivate Payneteasy end cp --> C: Show result deactivate cp

(2) To implement sale-form payment request see /api/v2/sale-form.
(3) Instead of sale-form it is possible to implement preauth-form payment request, see /api/v2/preauth-form. Preauth allows to hold the specified amount in the Payer’s card account for a limited time. Preauth can be followed by Capture or Cancel.
(14) Payer is returned to Connecting Party site. To implement final redirect see Final Redirect.
(16) To implement callback with final status handling see Connecting Party Callbacks.
(18) To implement order status request see /api/v2/status. Status should be requested multiple times with 3-5 seconds interval until final status will be received in response.

Capture Flow

Capture is a transaction followed after preauth which deducts the locked amount from Payer’s card. It is important to know that the block remains for a definite period of time depending on whether this is a debit or a credit card (usually the maximum block period is 7 days for debit cards and 28 days for credit cards).

skinparam roundcorner 20 skinparam sequenceArrowThickness 1 skinparam maxmessagesize 100 skinparam sequenceParticipant underline actor Payer participant "Connecting party" as A participant "Payneteasy" as B hnote over A,B : Successful Preauth Transaction autonumber group Optional Payer -> A: Initiate Capture activate A end == Capture == A -> B: api/v2/capture activate B B --> A: Order ID B -> B: Process Capture group Get Final Status == Receive Callback == A <- B: Callback with Final Status A --> B: HTTP 200 deactivate B == Order Status Request == A -> B: Get Status by Order ID api/v2/status activate B B --> A: Response with Status, Order-stage deactivate B end group Optional A --> Payer: Final Status deactivate A end

(1) Capture can be initiated by Connecting Party based on internal business model or Payer’s request.
(2) To implement capture request see /api/v2/capture/.
(5) Callback for Capture will be sent only if notify_url was provided in initial transaction request or additional callback URL for Capture transactions is specified on the endpoint level. If server_callback_url was provided in initial transaction request, callback for Capture will not be sent. To implement callback with final status handling see Connecting Party Callbacks.
(7) To implement order status request see /api/v2/status/. Status should be requested multiple times with 3-5 seconds interval until final status will be received in response.
(9) Final Status can be sent by Connecting Party based on internal business model or by Payer’s request.

Cancel Flow

Cancel is opposite of Capture which cancels the deduction and returns locked by Preauth amount back to Payer’s card. It is important to know that the block remains for a definite period of time depending on whether this is a debit or a credit card (usually the maximum block period is 7 days for debit cards and 28 days for credit cards).

skinparam roundcorner 20 skinparam sequenceArrowThickness 1 skinparam maxmessagesize 100 skinparam sequenceParticipant underline actor Payer participant "Connecting party" as A participant "Payneteasy" as B hnote over A,B : Successful Preauth Transaction autonumber group Optional Payer -> A: Initiate Cancel activate A end == Cancel == A -> B: api/v2/cancel activate B B --> A: Order ID B -> B: Process Cancel group Get Final Status == Receive Callback == A <- B: Callback with Final Status A --> B: HTTP 200 deactivate B == Order Status Request == A -> B: Get Status by Order ID api/v2/status activate B B --> A: Response with Status, Order-stage deactivate B end group Optional A --> Payer: Final Status deactivate A end

(1) Cancel can be initiated by Connecting Party based on internal business model or Payer’s request.
(2) To implement cancel request see /api/v2/return/.
(5) Callback for Cancel will be sent only if notify_url was provided in initial transaction request or additional callback URL for Cancel transactions is specified on the endpoint level. If server_callback_url was provided in initial transaction request, callback for Cancel will not be sent. To implement callback with final status handling see Connecting Party Callbacks.
(7) To implement order status request see /api/v2/status/. Status should be requested multiple times with 3-5 seconds interval until final status will be received in response.
(9) Final Status can be sent by Connecting Party based on internal business model or by Payer’s request.

Apple Pay Account Setup

To configure the terminal on the Payment Gateway side, the following data needs to be sent to the Payneteasy support service:

  • Merchant ID.

  • The private key of the Payment Processing Certificate.

  • Private key password.

To get the necessary data, the following steps are required:
1. Register Merchant ID.
2. Create Certificate Signing Request.
3. Issue Payment Processing Certificate.
4. Get the certificate private key and private key password.

Note

Please note that the Payment Processing Certificate lasts 25 months. To renew the certificate, see the section “Reissue of Payment Processing Certificate”.

Register Merchant ID

Merchant ID - Apple Merchant Site ID (or MID) is a unique identification number that tells the payment processing systems involved in a transaction where to send which funds.

  1. Open developer account. Go to Certificate, Identifiers & Profiles.

  2. Go to Identifiers.

  3. Click on “+”.

  4. Select Merchant IDs.

  5. Specify the description and the Merchant ID. It is recommended to use the website domain in reverse order with the Connecting Party’s prefix. Example: connecting party.com.Payneteasy.applepay.test.

  6. Click Register.

Merchant ID is now registered.

Create Certificate Signing Request

Certificate Signing Request is a request to issue a certificate, in our case in order to get Payment Processing Certificate.

  1. Open Keychain Access on Mac.

  2. Certification assistant -> Request a certificate from a Certificate Authority.

  3. Specify the email, to which the developer’s account was registered, the name (also key name). Select Saved to disk and Specify information about a pair of keys manually.

  4. Select the key size 256 bits and the ECC Algorithm. Click Continue button. Save the .certSigningRequest file.

Issue Payment Processing Certificate

  1. Return to the developer’s office. Go to Certificates, Identifiers & Profiles / Identifiers. Select needed Merchant ID.

  2. Click Create Certificate in Apple Pay Payment Processing Certificate section.

  3. Select “No” and click Continue.

  4. Choose .certSigningRequest file from step 2 and click Continue.

  5. Download Payment Processing Certificate.

Get the Certificate Private Key and Private Key Password

  1. Double click Payment Processing Certificate on Mac to install.

  2. Open Keychain Access and go to Certificates section.

  3. Find the certificate. Select the created key by clicking on the arrow next to it.

  4. Select Export with the right mouse button.

  5. Select the folder to save the key file in .p12 format, click Save.

  6. Create password and click OK. Private key <name>.p12 and private key password are ready to work.

Reissue of Payment Processing Certificate

The Connecting Party must independently monitor the validity period of the Apple Pay certificate (25 months). Before the certificate expires, a new certificate must be issued.
This requires the following:

  1. Create a new Certificate Signing Request, as described in step 2.

  2. Issue a new Payment Processing Certificate as in step 3. After creating a new certificate for the current Merchant ID, there will be two certificates: old (active) and new (requiring activation). At this step there is no need to activate the new certificate.

  3. Get the certificate private key, private key password and send them to Payneteasy support service as in step 4.

  4. Activate a new certificate only in consultation with Payneteasy support service. After activation, only the new certificate will be used, the old one will become inactive.

Merchant Identity Certificate

The following data needs to be sent to the Payneteasy support service:

  1. Merchant ID.

  2. The private key of the Merchant Identity Certificate.

  3. Private key password.

Note

Please note that the validity period of the Merchant Identity Certificate and domain verification is 25 months. To renew the certificate and re-verify domains, see the section Re-verification of domains and reissue of the Merchant Identity Certificate.

Domain Registration and Verification

Warning

Before receiving the Merchant Identity Certificate, it is compulsory to create and validate domains where Apple Pay will be used.

  1. Go to the developer’s office and go to Certificates, Identifiers & Profiles. Create a Merchant ID before domain registration.

  2. Go to Identifiers.

  3. App IDs -> Merchant IDs.

  4. Select the needed Merchant ID.

  5. Click Add Domain in Merchant Domains.

  6. Specify the domain where Apple Pay will be used and click Save.

  7. To confirm ownership of a domain, download the file and place ot at the specified address, the file at the specified address must be accessible from outside the Connecting Party’s network.

  8. Click Verify to verify the domain.

Creation of Merchant Identity Certificate

Step 1. Create Certificate Signing Request
Step 2. Issue Merchant Identity Certificate
Step 3. Get the certificate private key and private key password

Create Certificate Signing Request

Certificate Signing Request is a request to issue a certificate, in our case in order to get Payment Processing Certificate.

  1. Open Keychain Access on Mac.

  2. Certification assistant -> Request a certificate from a Certificate Authority.

  3. Specify the email, to which the developer’s account was registered, the name (also key name). Select Saved to disk and Specify information about a pair of keys manually.

  4. Select the key size 2048 bits and the RSA Algorithm. Click Continue button. Save the .certSigningRequest file.

Issue Merchant Identity Certificate

  1. Return to the developer’s office. Go to Certificates, Identifiers & Profiles / Identifiers.

  2. Go to Identifiers.

  3. App IDs -> Merchant IDs.

  4. Select the needed Merchant ID.

  5. Create Certificate in Apple Pay Merchant Identity Certificate section.

  6. Select created in step 1 .certSigningRequest file and click Continue.

  7. Download Merchant Identity Certificate.

Get the Certificate Private Key and Private Key Password

  1. Double click Merchant Identity Certificate on Mac to install.

  2. Open Keychain Access and go to Certificates section.

  3. Find the certificate. Select Export with the right mouse button.

  4. Select the folder to save the key file in .p12 format, click Save.

  5. Create password and click OK. Private key <name>.p12 and private key password are ready to work.

Domain Re-verification and Merchant Identity Certificate Reissue

The Connecting Party must independently monitor the validity of the certificate and domains’ verification (25 months). A new Merchant Identity Certificate must be issued before the certificate expires. Certificates can be used concurrently, so the procedure for issuing a new one is as described in the “Creating a Merchant Identity Certificate” section. Before the expiration of the domain verification period, the Verify button is activated next to it. The verification procedure corresponds to that described in the section “Domain registration and verification”.