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.
// Initialize Oceanpayment
<script>
   $(function() {
        // Set to `true` for the sandbox environment. Leave empty for the production environment.
        onePageApplePay.init(true, {
            terminal: '', /*Oceanpayment terminal*/
            mode: "quickpay",
            cssUrl: '', /* Provide the online CSS file URL to control the button size. */
            transactionInfo: {
                // Pass the actual order amount, currency, and country information.
                orderCurrency:ORDER_CURRENCY, /* Transaction currency */
                orderAmount:ORDER_AMOUNT, /* Transaction amount */
                billCountry:BILLING_COUNTRY, /* Billing country code */
                orderNumber:ORDER_NUMBER, /*Order number*/
                billAddress:BILLING_ADDRESS /*Billing address*/
            },
            buttonStyle: {
                buttonstyle:'', /* Button color */
                type:'' /* Button type */
            }
        });
  });
</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.