Skip to main content

Overview​

There are two supported approaches for integrating Apple Pay to bind a card and create a QuickPay ID. Choose the integration method that best fits your business and technical requirements.

  • Embedded Creation: The merchant integrates the Apple Pay button using the Oceanpayment Embedded Component. Upon successful payment, a QuickPay ID is automatically generated.
  • Direct Integration Creation: The merchant integrates the official Apple Pay button and directly calls the Oceanpayment server-side API to create a QuickPay ID after a successful payment.

How It Works​

Before You Start

When using Embedded Integration with Apple Pay, the merchant must first add the Oceanpayment-hosted domain verification file for each registered domain.

  1. Include the Oceanpayment SDK on your page:
<script src="https://secure.oceanpayment.com/pages/js/oceanpayment-applepay.js"></script>
<script src="https://secure.oceanpayment.com/pub/js/jquery/jq.js"></script>
  1. Create a <div> container on your page:
// Load the Apple Pay button
<div id="oceanpayment-applepayelement"></div>
  1. Initialize and render the payment UI component into the container by calling init().
  • Pass true to use the sandbox environment.
  • Leave this parameter empty to use the production environment.
  • Set mode to quickpay to enable QuickPay ID creation mode.
  • billCountry: The country/region code of the store's registered location, in ISO 3166 format.
// Initialize Oceanpayment
<script>
   $(function() {
        // Set to `true` for the sandbox environment. Leave empty for the production environment.
        onePageApplePay.init(true, {
            terminal: '99514901', /*Oceanpayment terminal*/
            mode: "quickpay",
            transactionInfo: {
                // Pass the actual order amount, currency, and country information.
                orderCurrency:ORDER_CURRENCY, /* Transaction currency */
                orderAmount:ORDER_AMOUNT, /* Transaction amount */
                billCountry:BILLING_COUNTRY, /* Store Registration Country/Region Code */
                orderNumber:ORDER_NUMBER, /*Order number*/
                billAddress:BILLING_ADDRESS /*Billing address*/
            }
        });
  });
</script>
  1. Custom Styling
  • You can override the default styles of the Oceanpayment payment page by providing an online CSS stylesheet to customize its appearance. The cssUrl parameter is optional and defaults to an empty value during initialization. For details, see cssUrl.
<script>
   $(function() {
        onePageApplePay.init(true, {
            cssUrl: '',/*The URL of the online CSS stylesheet used to customize the style and size of the Apple Pay button.*/
            buttonStyle: {
                buttonstyle:'', /*Button color*/
                type:'' /*Button type*/
            }     
        });
  });
</script>
  1. Update Order Amount and Currency
  • When the order amount or currency changes, such as due to changes in product prices, discounts, taxes, or shipping fees, merchants can call this method to update the transaction information.
<script>
  function updateTransactionInfo() {
    onePageApplePay.updateTransactionInfo({   
      transactionInfo: {   
        orderCurrency: ORDER_CURRENCY, //Currency
        orderAmount: ORDER_AMOUNT //Amount  
      }   
    }); 
  } 
</script>
  1. Trigger the Google Pay Payment Popup
  • Merchants can use the onePageApplePay.validateResults() method to control whether the Apple Pay payment popup is displayed. Call this method at the appropriate time after Google Pay has been initialized, based on the results of the website's form validation.
    • If required fields, such as billing information, fail validation, call onePageApplePay.validateResults(false) to prevent the payment popup from being displayed.
    • Once all required fields pass validation, call onePageApplePay.validateResults(true) to display the payment popup.
<script>
  function validateResults() {
    onePageApplePay.validateResults(true);
  }
</script>
  1. QuickPay ID Creation
  • When calling the Create QuickPay ID method, implement duplicate submission prevention during the payment process.
  • Use the transformToJson(formData){} method to convert the required submission parameters into JSON format.
  • Then call onePageApplePay.checkout() to submit the required parameters to the Oceanpayment. For details, see Create QuickPay ID Parameters.
// Submit parameters
<script>
  function opApplepay() {
    // Get the form element
    var register = $("#payForm");
    var formData = register.serializeArray();
    // Submit payment parameters to the Oceanpayment
    onePageApplePay.checkout(transformToJson(formData));
  }
  // Output JSON data
  function transformToJson(formData){
    var obj={}
    for (var i in formData) {
      obj[formData[i].name]=formData[i]['value'];
    }
    return obj;
  }
</script>

Handle the Response​

The merchant should save the returned card information quickpay_id, which is in UUID format and is used to initiate QuickPay/Subscription Payments.

NOTE

Oceanpayment will redirect the card binding result to the backUrl page. The backUrl value must exactly match the current page URL, including the complete path. Otherwise, the oceanpaymentApplePayCallBack() method cannot be triggered to receive the payment response information.

var oceanpaymentApplePayCallBack = function(data){}
  1. When card information validation fails, data.msg will return the corresponding error message. For example:
{"code":-1, "msg":"xxx"}
  1. The card binding response is returned as follows:
  • If data.msg is empty, the card information verification is successful.
  • If data.code= 2, the Apple Pay button has been successfully loaded.
var oceanpaymentApplePayCallBack = function(data){	
   if (data.code == 2) {
      // Trigger the button to create a QuickPay ID
      opApplepay();
   }else{
      /* Handle the response result */
      //console.log(data);
   }
}
  1. When data.code= 3, it indicates that the user has closed the Apple Pay payment dialog. The returned data format is as follows:
{"code":3,"msg":"","method":"ApplePay"}
  1. Response example
<?xml version="1.0" encoding="UTF-8"?>
<response>
  <account>995149</account>
  <terminal>99514901</terminal>
  <signValue>79e63f6995a84934da921bab8a2ba8cb492971a36130a76d58ea18355af7f578</signValue>
  <customer_id>customer_id20240507174225</customer_id>
  <order_notes></order_notes>
  <card_number>411111***1111</card_number>
  <card_type>VISA</card_type>
  <card_country>PL</card_country>
  <quickpay_id>37ca4cff-4e99-4cd6-9869-8d6c7ad259d7</quickpay_id>
  <quickpay_status>1</quickpay_status>
  <quickpay_details>1:Success</quickpay_details>
</response>

Signature​

See Signature and Verification for details on request signing and response validation.

API Reference​

👉Explore our to continue your integration.