Apple Pay

Introduction

Before accepting payments via Apple Pay, follow the steps in the sections below. On completing these steps, you can start developing your mobile application (mobile app development documentation is not included in this document, for more information see Apple Pay documentation).

Create Merchant ID

To create your Merchant ID, follow these steps.

1. In the personal area of the Apple Member Center, go to Certificates, Identifiers & Profiles.
2. In the Identifiers section select Merchant IDs.
3. On the resulting page click + (Add) in the right upper corner.
4. In the Merchant ID Description and Identifier fields enter a description of your Apple merchant identifier and the identifier itself accordingly.
   
5. Click Continue.
6. On the resulting page check the data you entered and click Register.
7. On the resulting page click Done.

Certificate registration

To receive payments via Apple Pay, you need to have a key pair (private and public key) and the corresponding public key certificate. The required actions in the personal cabinet depend on whether you already have a key pair and the corresponding certificate or not.

Create new certificate

To create a key pair, follow these steps.

1. Log in to your personal cabinet and click in the left panel (Certificates section).
2. Select Apple Pay.
3. Click Create key pair.
   The following form will display.
   
4. Fill in the required fields (see the table below).

• After making the necessary changes click Create.

The created key pair will be displayed in the Apple Pay section (see the figure below).

Proceed to CSR download

Upload previously created certificate

To upload an existing key pair, follow these steps.

1. Log in to your personal cabinet and click in the left panel (Certificates section).
2. Select Apple Pay.
3. In the Merchant identification certificates section click Add key.
   The following form will be displayed.
   
4. Fill in the following fields.
   • Apple ID - enter your Merchant Apple ID.
   • Password - enter the password for your PKCS12 file.
   • Default domain - enter the domain of your online store.
5. Drag your key pair file to the designated area on the page.
   It will be displayed below.
   
6. Click Create. The uploaded key pair will be displayed in the Merchant identification certificates section.

After uploading your key pair the following actions will become available.

• Edit Apple Merchant ID
• Disable key

Export CSR

To download CSR, follow these steps.

1. Log in to your personal cabinet and click in the left panel (Certificates section).
2. Select the required payment service (Apple Pay, Google Pay, or Samsung Pay).
3. Click next to your certificate and select Download CSR (see the figure below).
   
   Save file dialog will display.
4. Specify the path to which the file will be saved or save it to the default folder.

Also, the following actions are available.

• Edit Apple Merchant ID
• Disable key

Edit Merchant ID

To edit your Apple Merchant ID, follow these steps.

1. Log in to your personal cabinet and click in the left panel (Certificates section).
2. Select Apple Pay.
3. Click and select Edit. (see the figure below).
   
   The following form will be displayed.
   
4. Edit Apple ID field and click Confirm.

Disable certificate

To disable a certificate (key), follow these steps.

1. Log in to your personal cabinet and click in the left panel (Certificates section).
2. Select the required payment service (Apple Pay, Google Pay, or Samsung Pay).
3. Click next to your certificate and select Disable key (see the figure below).
   
   The following dialog will display.
   
4. Click Confirm.

Whether a disabled certificate is displayed in the personal cabinet depends on Allowed certificates setting that is at the upper left corner of the Certificates section (see the figure below).

Setting	Description
Allowed certificates enabled	Disabled certificates are not displayed in the Keys list.
Allowed certificates disabled	Disabled certificates are displayed in the Keys list. Allowed cell will have False value (see the figure below).

Actions necessary for web integration

For Web integration, follow these steps.

1. Register and confirm your domain in Apple.
   • If the payment page is located on your side, register your domain.
   • If the payment page is located on the payment gateway side, specify the payment gateway domain.
2. Create a merchant identification certificate, convert it to a .pem file, and upload it to your server.

This certificate is used to authenticate connections to Apple Pay servers.

Registration of a domain in Apple

To register a certificate in Apple, follow these steps.

1. Log in to your Apple developer account at https://developer.apple.com.
2. Follow Apple developer account help instructions to register a domain.

Select the previously created merchant ID when prompted.

Integration scheme

1. The user in the mobile application selects the payment option using Apple Pay.
2. The payment data is sent to the Apple Pay system for processing.
3. To process the payment data an object PKPaymentToken Object, which has paymentData attribute, is created in the Apple Pay system (here and further see Apple Pay documentation).
4. Apple Pay sends a response to the merchant (mobile application).
5. The merchant exctracts paymentData attribute out of received PKPaymentToken Object object and encodes its contents in Base64.
6. The merchant creates a payment request containing paymentDataattribute, which is received from the Apple Pay response and encoded in Base64, and sends it to the payment gateway for processing (see Request for payment via Apple Pay).
7. The payment system processes the request.
8. The payment system returns a response with the result.
9. The mobile application displays the payment result to the user.

Reference links

Google Pay

Introduction

There are several implementation options for Google Pay™ that support both CRYPTOGRAM_3DS and PAN_ONLY authentication methods.

Integration schemes

Payment from a mobile app

1. A customer selects to pay via Google Pay.
2. The application requests masked card data from Google Pay.
3. Google Pay returns masked card data to the application.
4. The application displays the masked card data to the customer.
5. The customer confirms payment.
6. The application requests encrypted card data from Google Pay .
7. Google Pay encrypts the data using merchant's public key.
8. Google returns the encrypted payment data to the application.
9. The application sends a Google Pay payment request to the payment gateway, the request contains the token received from Google Pay.
10. The payment gateway decrypts the received token and processes the payment.
11. The payment gateway returns the payment result to the application.
12. The application displays the payment result to the customer.

Payment page is on the the online store side

1. The customer creates an order on the online store Website and chooses to pay via Google Pay.
2. The online store generates a request for Google Pay.
3. The Google Pay generates the encrypted payment data.
4. The online store receives the encrypted payment data.
5. The online store generates a Google Pay payment request, the request contains the received encrypted payment data.
6. The payment gateway decrypts the received data and makes the payment.
7. The payment gateway returns the payment result to the online store.
8. The payment result is displayed to the customer.

Payment page is on the payment gateway side

If the payment page is located on the Google Pay side, the scheme is the following.

1. A customer creates an order on the merchant's Website.
2. The merchant registers the order in the payment gateway.
   • One-phase payment;
   • Two-phase payment.
3. The payment gateway returns a unique order number and the URL to which the customer must be redirected.
4. The store system redirects the customer to the URL from step 3.
5. The customer's browser opens the URL.
6. The customer receives a payment form.
7. The customer choose to pay via Google Pay and confirms the choice.
8. The payment data is exchanged between the payment gateway and Google Pay - the payment gateway receives the payment data.
9. The payment gateway processes the payment.
10. The customer is redirected to the final page.
11. The customer's browser displays the final page.
12. The payment status is displayed.

Payment via Google Pay using 3DS 2.0

When you use payment via Google Pay with the /google/payment.do or google/paymentDirect.do request, you can use customer authentication with 3DS 2.0. In this case, you must send a payment request to the payment gateway twice for each transaction. Sending the first request initiates the 3DS 2.0 authentication procedure, and sending the second request continues the procedure with the data received from the 3DS server (an additional component that interacts with payment systems and ACS).

If the customer is redirected to the online store's page after authentication, you must complete the payment by sending the finish3dsVer2Payment.do request.

Payment with google/paymentDirect.do using 3DS 2.0

Below is the integration scheme with the google/paymentDirect.do request (token decryption on your side) using 3DS 2.0.

1. A customer selects to pay via Google Pay.
2. The application requests the list of cards from Google Pay.
3. Google Pay returns the list of masked cards to the application.
4. The customer selects a card for payment, the card data is sent to Google Pay.
5. Google Pay sends encrypted paymentToken to the application.
6. The merchant decrypts paymentToken.
7. Order payment - stage 1. The merchant sends decrypted paymentToken to the payment gateway by sending the google/paymentDirect.do request.
8. The payment gateway checks on the 3DS server whether the customer can authenticate using the 2.0 Protocol and sends the response. The response also returns the following parameters:
   • is3DSVer2 - 3DSv2 authentication capability flag (true/false)
   • threeDSServerTransId - transaction identifier assigned by the 3DS server.
   • threeDSMethodURLServer - address of the 3DS server for collecting browser data.
   • threeDSMethodURL - (optional) address of the ACS server for collecting browser data.
   • threeDSMethodDataPacked - (optional) data for collecting browser data on ACS.
9. The merchant calls threeDSMethodURLServer in a separate "iframe" with the help of the POST method. This allows the 3DS server to collect data about the customer's browser.
10. (Optional step) If threeDSMethodURL and threeDSMethodDataPacked parameters were received in the response to the order payment request, the merchant calls threeDSMethodURL in a separate iframe using the POST method. In this method, it's necessary to pass the value, received in the threeDSMethodDataPacked parameter in the response to the order payment request. It is necessary to pass it in a parameter called threeDSMethodData. This allows the ACS to collect data about the customer's browser.
11. Order payment - stage 2. The merchant resends the google/paymentDirect.do request to complete the order (or make a money transfer). You must pass the threeDSServerTransId parameter - the transaction identifier which was created by the 3DS server and returned at step 8. Additionally, to redirect the customer to the store's page after the order is paid, the redirect link may be passed in the parameter threeDSVer2FinishUrl.
12. The payment gateway interacts with 3DS server and ACS to find out if the customer needs to authenticate on ACS and sends the response to the payment request. If the customer needs to authenticate on ACS, the response returns acsUrl – the URL for redirecting to ACS and packedCReq – the packed data for challenge request. Else – the successful payment response is received.

13. If the customer does not need to authenticate on ACS, go to the step 19 of this procedure.

    If the customer needs to authenticate to the ACS, the payment page is redirected to acsUrl with the creq=packedCReq parameter received at step 12.

14. ACS displays an HTML form for authentication to the customer.

15. The customer is authenticated.

16. ACS redirects the customer to the store's page.

17. To complete a transaction, the merchant sends the finish3dsVer2Payment.do request to the payment gateway passing the threeDSServerTransId parameter - the transaction identifier which was created by the 3DS server and returned at step 8.

18. The payment gateway sends the merchant a response to the request.

19. The merchant sends an extended request for the order status getOrderStatusExtended.do to the payment gateway to find out the order status.

20. The payment gateway sends a response to the request.

21. The merchant displays the result page to the customer.

Payment with /google/payment.do using 3DS 2.0

Below is the scheme of payment with the /google/payment.do request (token decryption on the Payment Gateway side) using 3DS 2.0.

1. A customer chooses to pay via Google Pay.
2. The application requests Google Pay masked card data.
3. Google Pay returns the masked card data.
4. The application displays the masked card data to the customer.
5. The customer confirms payment.
6. The application requests Google Pay the encrypted card data.
7. Google Pay encrypts the data using your public key.
8. Google Pay returns the encrypted payment data to the application.
9. Order payment - stage 1. The merchant sends decrypted paymentToken to the payment gateway by sending the /google/payment.do request.
10. The payment gateway decrypts the received token.
11. The payment gateway checks on the 3DS server whether the customer can authenticate using the 2.0 Protocol and sends the response. The response also returns the following parameters:
    • is3DSVer2 - 3DSv2 authentication capability flag (true/false)
    • threeDSServerTransId - transaction identifier assigned by the 3DS server.
    • threeDSMethodURLServer - address of the 3DS server for collecting browser data.
    • threeDSMethodURL - (optional) address of the ACS server for collecting browser data.
    • threeDSMethodDataPacked - (optional) data for collecting browser data on ACS.
12. The merchant calls threeDSMethodURLServer in a separate "iframe" with the help of the POST method. This allows the 3DS server to collect data about the customer's browser.
13. (Optional step) If threeDSMethodURL and threeDSMethodDataPacked parameters were received in the response to the order payment request, the merchant calls threeDSMethodURL in a separate iframe using the POST method. In this method, it's necessary to pass the value, received in the threeDSMethodDataPacked parameter in the response to the order payment request. It is necessary to pass it in a parameter called threeDSMethodData. This allows the ACS to collect data about the customer's browser.
14. Order payment - stage 2. The merchant resends the /google/payment.do request to complete the order (or make a money transfer). You must pass the threeDSServerTransId parameter - the transaction identifier which was created by the 3DS server and returned at step 11. Additionally, to redirect the customer to the store's page after the order is paid, the redirect link may be passed in the parameter threeDSVer2FinishUrl.
15. The payment gateway interacts with 3DS server and ACS to find out if the customer needs to authenticate on ACS and sends the response to the payment request. If the customer needs to authenticate on ACS, the response returns acsUrl – the URL for redirecting to ACS and packedCReq – the packed data for challenge request. Else – the successful payment response is received.

16. If the customer does not need to authenticate on ACS, go to the step 22 of this procedure.

    If the customer needs to authenticate to the ACS, the payment page is redirected to acsUrl with the creq=packedCReq parameter received at step 15.

17. ACS displays an HTML form for authentication to the customer.

18. The customer is authenticated.

19. ACS redirects the customer to the store's page.

20. To complete a transaction, the merchant sends the finish3dsVer2Payment.do request to the payment gateway passing the threeDSServerTransId parameter - the transaction identifier which was created by the 3DS server and returned at step 8.

21. The payment gateway sends the merchant a response to the request.

22. The merchant sends an extended request for the order status getOrderStatusExtended.do to the payment gateway to find out the order status.

23. The payment gateway sends a response to the request.

24. The merchant displays the result page to the customer.

Requirements for the payment page on merchant's side

Payment page on the merchant's side must meet the following requirements.

• The payment page must be able to redirect a customer to 3-D Secure server after calling requesting the payment method if the decrypted token contains payment method CARD.
• The payment page must contain the Google Pay button.
• The payment page must contain a script that checks whether the Google Pay payment button can be displayed (see the code example below).

paymentsClient.isReadyToPay({allowedPaymentMethods: allowedPaymentMethods})
    .then(function(response) {
      if (response.result) {
        // in this case the button should be displayed
        addGooglePayButton();
      }
    })
    .catch(function(err) {
      // show error in developer console for debugging
      console.error(err);
    });

function addGooglePayButton() {
  var button = document.createElement('button');
  button.className = 'google-pay';
  button.appendChild(document.createTextNode('Google Pay'));
  sbutton.addEventListener('click', onGooglePaymentButtonClicked);
  document.getElementById('container').appendChild(button);
}

• Google JavaScript must be enabled (for more information see Google documentation:
  • https://developers.google.com/pay/api/web/guides/tutorial);
  • https://payments.developers.google.com/js/apis/pay.js.
• For a testing, the value of the environment attribute must be set as TEST (see the code example below).

var paymentsClient =
    new google.payments.api.PaymentsClient({environment: 'TEST'});

• The value for the main version of the page must be obtained from Google after performing checks (for more information see. Google documentation: https://developers.google.com/pay/api/web/guides/test-and-deploy/integration-checklist)).

• The payment page must contain paymentDataRequest object (see the code example below). Use following test data:

  • gateway - bpcpay (or - as provided during sandbox on-boarding)
  • gatewayMerchantId - as provided during sandbox on-boarding

function getGooglePaymentDataConfiguration() {
  return {
    merchantId: '00000000000000000000', //constant for the bank's RBE; for the environment: 'TEST' is not indicated
    transactionInfo = {
        totalPriceStatus: 'FINAL',
        totalPrice: '123.45', //amount in major units
        currencyCode: 'BGN' //ISO 4217
    },
    paymentMethodTokenizationParameters: {
        tokenizationType: 'PAYMENT_GATEWAY',
        parameters: {
            gateway: 'some-bank', //constant for the bank's RBE
            gatewayMerchantId: 'exampleGatewayMerchantId' //merchant identifier in the payment gateway
        }
    },
    allowedPaymentMethods: ['CARD', 'TOKENIZED_CARD'],
    cardRequirements: {
        allowedCardNetworks: ['MASTERCARD', 'VISA']
    }
  };
}

• After clicking Google Pay button the paymentDataRequest object must be passed to Google Pay (see the code example below).

var paymentDataRequest = getGooglePaymentDataConfiguration();
paymentsClient.loadPaymentData(paymentDataRequest).then(function(paymentData){
  processPayment(paymentData);
}).catch(function(err){
  // show error in developer console for debugging
  console.error(err);
});

Create key pair

To create a key pair, follow these steps.

1. Log in to your personal cabinet and click in the left panel (Certificates section).
2. Select Google Pay.
3. In the Keys section click Create key pair.
   The following form will be displayed.
   
4. Fill in the Google ID field with your Google ID obtained from Google Pay, then click Confirm.
5. The created key pair will be displayed in the Keys section (see the figure below).
   

Download public key

To download your public key, follow these steps.

1. Log in to your personal cabinet and click in the left panel (Certificates section).
2. Select Google Pay.
3. Click next to your certificate and select Download key (see the figure below).
   
4. In the Save file window select the path to which the file will be saved or save it to your default folder.

Also, the following action are available.

• Edit Google ID
• Disable key

Edit Google ID

To edit your Google ID, follow these steps.

1. Log in to your personal cabinet and click in the left panel (Certificates section).
2. Select Google Pay.
3. Click next to your certificate and select Edit (see the figure below).
   The following form will be displayed.
   
4. Edit the Google ID field, then click Confirm.

Disable certificate

To disable a certificate (key), follow these steps.

1. Log in to your personal cabinet and click in the left panel (Certificates section).
2. Select the required payment service (Apple Pay, Google Pay, or Samsung Pay).
3. Click next to your certificate and select Disable key (see the figure below).
   
   The following dialog will display.
   
4. Click Confirm.

Whether a disabled certificate is displayed in the personal cabinet depends on Allowed certificates setting that is at the upper left corner of the Certificates section (see the figure below).

Setting	Description
Allowed certificates enabled	Disabled certificates are not displayed in the Keys list.
Allowed certificates disabled	Disabled certificates are displayed in the Keys list. Allowed cell will have False value (see the figure below).