Overview
This document describes how to integrate Apple Pay with Oceanpayment via a server-to-server connection, including payment parameter submission, transaction processing, and result delivery.
For other Apple Pay integration methods, see the Apple Pay integration guide.
Flowchart
Before You Begin
When using the embedded Apple Pay integration, merchants must first add the Oceanpayment-hosted domain verification file for each registered domain.
1. Domain Verification File Deployment
The merchant must deploy Apple’s official domain verification file under every website domain where Apple Pay is used and ensure that it is accessible at the following path: ⬇️ Click to download the domain verification file.
https://[DOMAIN_NAME]/.well-known/apple-developer-merchantid-domain-association
The verification file must be deployed for each domain and subdomain.
https://example.com/.well-known/apple-developer-merchantid-domain-association
https://test.example.com/.well-known/apple-developer-merchantid-domain-association
···
2. Initiate Domain Registration
- After deploying the verification file, call the Oceanpayment domain registration API:
- Request
- Response
cURL -X POST 'https://mds.oceanpayment.com/appleregistermerchant'
-H 'Authorization: MVc9Lt1CDY7RBRUvh8iVmvvPbYF3uvWkymUDz'
-d '{
"website": ["example.com","test.example.com"]
}'
| Parameter | Type | Required | Description |
|---|---|---|---|
website | Array | Required | List of domains to register |
{
"statusMessage": "Success",
"statusCode": 200
}
- Error Handling
| Response Code | Description |
|---|---|
| 200 | OK
|
| 400 | Bad Request
|
| 401 | Unauthorized
|
| 417 | Expectation Failed
|
| 500 | Internal Server Error
|
3. Integration
After domain verification is complete, Apple Pay will appear as a payment option on the checkout page where supported.
Embedded Apple Pay integration is available only on supported Apple devices, such as Safari browsers and iOS devices. The payment button is displayed only on iOS 17 or later.
Request
1. Load the Oceanpayment SDK
//Load the Oceanpayment JS file.
<script src="https://secure.oceanpayment.com/pages/js/oceanpayment-applepay.js"></script>
<script src="https://secure.oceanpayment.com/pub/js/jquery/jq.js"></script>
2. Create a Container
// Load the Apple Pay payment button
<div id="oceanpayment-applepayelement"></div>
3. Initialize
Initialize and render the payment UI component in the container using init();.
- Pass true to submit requests to the sandbox environment.
- Pass an empty value to submit requests to the production environment.
billCountry: The country or region code where the store is registered, in ISO 3166 format.
// Initialize Oceanpayment
<script>
$(function() {
// Pass true to submit requests to the sandbox environment; pass an empty value to submit requests to the production environment.
onePageApplePay.init(true, {
terminal: '99514901', /* Oceanpayment terminal */
transactionInfo: {
// Pass the actual order amount and currency
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>
4. Customize Styles
You can use an online CSS file to override the default styles of the Oceanpayment payment page. cssUrl is empty by default during initialization. See cssUrl.
<script>
$(function() {
onePageApplePay.init(true, {
cssUrl: '', /* Pass the URL of an online CSS file to control the button style */
buttonStyle: {
buttonstyle:'', /* Button color */
type:'' /* Button type */
}
});
});
</script>
5. Update the Order Amount and Currency
When the order amount or currency changes—for example, due to changes in product prices, discounts, taxes, or shipping fees—the merchant can call this method to update the transaction information.
<script>
function updateTransactionInfo() {
onePageApplePay.updateTransactionInfo({
transactionInfo: {
orderCurrency: ORDER_CURRENCY, // Currency
orderAmount: ORDER_AMOUNT // Amount
}
});
}
</script>
6. Display the Apple Pay Payment Sheet
- The merchant can control whether the Apple Pay payment sheet is displayed by calling
onePageApplePay.validateResults(). After Apple Pay initialization is complete, call this method at the appropriate time based on your website’s form validation results. - If required fields, such as billing information, fail validation, call
onePageApplePay.validateResults(false)to prevent the payment sheet from appearing. - After all required fields pass validation, call
onePageApplePay.validateResults(true)to display the payment sheet.
<script>
function validateResults() {
onePageApplePay.validateResults(true);
}
</script>
7. Submit the Payment
- Call the payment method and prevent duplicate submissions.
- Use
transformToJson(formData){}to convert the required parameters to JSON format. - Then call
checkout()to submit the required parameters to the Oceanpayment payment gateway.
<script>
// Oceanpayment payment method
function opApplepay() {
// Get the form element
var register = $("#payForm");
var formData = register.serializeArray();
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>
QuickPay
You can also use the QuickPay embedded API to create a subscription for quick payments.
Response
1. Listen for the Result
Listen for the payment result event on the frontend. See the full list of response parameters.
Oceanpayment sends the payment result to the backUrl page. The backUrl value must exactly match the current page’s address and full path for the oceanpaymentApplePayCallBack() method to receive the payment result.
var oceanpaymentApplePayCallBack = function(data){}
2. Check the Result
If data.code = 3, the user closed the Apple Pay payment sheet. The response format is:
{"code":3,"msg":"","method":"ApplePay"}
3. 3DS Flow
When data.code = 2, the Apple Pay button has loaded successfully. Receive the payment response in the else block and handle these two cases:
- If
xml->pay_urlis empty,xmlcontains the payment result. An asynchronous notification is also sent tonoticeUrl. - If
xml->pay_urlis not empty, redirect the user topay_urlto complete 3DS verification. The payment result will then be sent tobackUrlagain. By default, receive it using$_POST. An asynchronous notification is also sent tonoticeUrl.
var oceanpaymentApplePayCallBack = function(data){
if (data.code == 2) {
// Display the button and initiate payment
opApplepay();
}else{
/* Handle the order response */
//console.log(data);
}
}
4. Response Example
- 3DS Scenario
- Non-3DS Scenario
<?xml version="1.0" encoding="UTF-8"?>
<response>
<notice_type>transaction</notice_type>
<push_dateTime>2025-09-03 10:21:14</push_dateTime>
<account>995149</account>
<terminal>99514901</terminal>
<signValue>924347D8E9C9BAC2EC91449C70540FF49E0DD5711F03E8A871DCA34CED023AB6</signValue>
<methods>Applepay</methods>
<order_number>JSCSE-3128790866</order_number>
<card_country>PL</card_country>
<order_currency>USD</order_currency>
<order_amount>0.01</order_amount>
<order_notes></order_notes>
<card_number>411111***1111</card_number>
<card_type>Visa</card_type>
<payment_country></payment_country>
<payment_id>250902111334242179639</payment_id>
<payment_authType>2</payment_authType>
<payment_status>-1</payment_status>
<payment_details>80093:3D Authorized Service not completed</payment_details>
<payment_solutions></payment_solutions>
<payment_risk></payment_risk>
<payment_amount></payment_amount>
<payment_exchangeRate></payment_exchangeRate>
<auth_reason></auth_reason>
<auth_code></auth_code>
<pay_userId></pay_userId>
<pay_url>https://secure.oceanpayment.com:443/gateway/direct/redirect?pay_id=af5e28ee57061f4fd1dd307a7bc56c7289d9041d0b5494195d91b7c5166b6e30</pay_url>
</response>
- Redirect the user to
pay_url:
HTTP/1.2 301 Moved Permanently
Location: {pay_url}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<notice_type>transaction</notice_type>
<push_dateTime>2025-09-03 10:21:14</push_dateTime>
<account>995149</account>
<terminal>99514901</terminal>
<signValue>6E48108837603DF6758BD6CE81C9F8AEE6FDC40D14D056C41EBCC1B28B1F2A0D</signValue>
<methods>Applepay</methods>
<order_number>JSCSE-3128790866</order_number>
<card_country>PL</card_country>
<order_currency>USD</order_currency>
<order_amount>0.01</order_amount>
<order_notes></order_notes>
<card_number>411111***1111</card_number>
<card_type>Visa</card_type>
<payment_country>-</payment_country>
<payment_id>250903102114589130422</payment_id>
<payment_authType>0</payment_authType>
<payment_status>1</payment_status>
<payment_details>80000:Transaction Approved</payment_details>
<payment_solutions>None required.</payment_solutions>
<payment_risk></payment_risk>
<payment_amount></payment_amount>
<payment_exchangeRate></payment_exchangeRate>
<auth_code></auth_code>
<pay_userId></pay_userId>
</response>
Payment Status
See Payment Status for details.
Asynchronous Notification
You also need to receive the transaction’s asynchronous notification via noticeUrl.
Signature
See Signature Generation and Verification for details.