Apple Pay

Feature	Description
Payment Logo - Usage Guidelines
Integration Methods	✅ Hosted Checkout ✅ Embedded ✅ Server-to-Server
Recommended Regions	Global
Virtual Industry Support	✅
Subscription Support	✅ Varies by industry
Supported SaaS	All integrated SaaS platforms
Supported Open-Source Platforms	✅ Magento ✅ WordPress/Woocommerce ✅ OpenCart ✅ PrestaShop ✅ ZenCart

Integration Method

Oceanpayment supports the following Apple Pay integration methods:

Integration Method	Description
Embedded	Merchants are not required to enroll in the Apple Developer Program. Oceanpayment handles Merchant Validation and payment processing.
Server-to-Server	Merchants must enroll in the Apple Developer Program, obtain the Apple Pay Payment Token, and submit payment requests through Oceanpayment's server-side API.

Embedded

1. Deploy the Domain Verification File

Merchants must host Apple's domain verification file on every domain where Apple Pay will be used and ensure that the file is publicly accessible. Click to ⬇️ download the domain verification file.

https://[DOMAIN_NAME]/.well-known/apple-developer-merchantid-domain-association

Notice

The verification file must be deployed on each individual domain and subdomain that will support Apple Pay.

https://example.com/.well-known/apple-developer-merchantid-domain-association  
https://test.example.com/.well-known/apple-developer-merchantid-domain-association
···

2. Register Domains

• After deploying the verification file, call the Oceanpayment domain registration API.

Request

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 be registered.

  </TabItem>
  <TabItem value="Response" label="Response">
```json
{
    "statusMessage": "Success",
    "statusCode": 200
}

• Errors Handling

Response code	Description
200	OK Success.
400	Bad Request The request is malformed or invalid.
401	Unauthorized The request is malformed or invalid.
417	Expectation Failed The e-commerce platform isn’t registered with Apple Developer.
500	Internal Server Error An internal server error occurred.

3. Integration

Notice

Apple Pay via the Embedded integration method is only available on supported Apple devices and browsers, such as Safari on macOS, iPhone, and iPad. The Apple Pay button is displayed only on devices running iOS 17 or later.

Initiate Payment

Use the Embedded Integration solution to complete the payment processing.

Create QuickPay

Use the Embedded Integration solution to complete QuickPay ID creation for the subscription payment scenario.

Server to Server

When using the Server-to-Server integration method, merchants are responsible for completing the Apple Pay developer setup.

1. Enroll in the Apple Developer Program

• Visit https://developer.apple.com and enroll in the Apple Developer Program.

2. Create Merchant ID

• Sign in to Apple Developer.
• Navigate to Certificates, Identifiers & Profiles.
• Select Identifiers → Merchant IDs.
• Click (+) to create a Merchant ID. Example: merchant.com.example.store

3. Create a Payment Processing Certificate

• Generate a CSR (Certificate Signing Request) using Keychain Access on macOS or OpenSSL.
• Sign in to Apple Developer and navigate to Certificates.
• Create a certificate of type Payment Processing Certificate.
• Upload the CSR file.
• Download the generated .cer certificate from Apple.
• Install the certificate into your local Keychain.
• Export the certificate as a .p12 file, including the private key. The exported .p12 file is used to decrypt Apple Pay Payment Tokens on the server side.

4. Configure Merchant Domain Verification

• Sign in to Apple Developer.
• Navigate to Merchant IDs → Domain Verification.
• Add your merchant domain name (e.g., payments.oceanpayment.com).
• Download the verification file apple-developer-merchantid-domain-association.
• Upload the file to the following location. For example: https://payments.oceanpayment.com/.well-known/apple-developer-merchantid-domain-association
• Click Verify to complete domain verification.

5. Obtain the Payment Token

Refer to the official Apple Pay demo site for Payment Token examples:

Response

{
    "paymentData": {
        "data": "",
        "signature": "",
        "header": {
            "publicKeyHash": "",
            "ephemeralPublicKey": "",
            "transactionId": ""
        },
        "version": "EC_v1"
    },
    "paymentMethod": {
        "displayName": "Visa 0112",
        "network": "Visa",
        "type": "credit"
    },
    "transactionIdentifier": ""
}

6. Payment Token Mapping

• When submitting a payment request to Oceanpayment, pay_accountNumber is used to pass the paymentData object from the Apple Pay Payment Token.
• Mapping Rules: Pass the complete paymentData object as the value of pay_accountNumber.

Request

{
  "data": "",
  "signature": "",
  "header": {
	"publicKeyHash": "",
	"ephemeralPublicKey": "",
	"transactionId": ""
  },
  "version": "EC_v1"
}

Notice

1. The pay_accountNumber parameter must contain the complete paymentData object returned by Apple Pay.
2. Payment requests should be submitted immediately after the Payment Token is obtained to avoid token expiration.
3. Only the EC_v1 encryption format is currently supported.

7. card_type Mapping

When submitting a payment request to Oceanpayment, the card_type parameter is used to identify the card network returned in paymentMethod.network. Merchants must map the value of paymentMethod.network to a supported Oceanpayment card_type enumeration before submitting the payment request.

paymentMethod.network	card_type
visa	VISA
masterCard	MASTERCARD
maestro	MAESTRO
JCB	JCB
elo	ELO
discover	DISCOVER
chinaUnionPay	CHINAUNIONPAY
cartesBancaires	CARTESBANCAIRES
amex	AMEX

Request

-d 'card_type=VISA' \

8. Complete Integration

Initiate Payment

Submit the Apple Pay Payment Token to Oceanpayment through the pay_accountNumber parameter and complete the integration using the Server-to-Server Integration flow.

const paymentRequest = {
  countryCode: 'US',
  currencyCode: 'USD',
  total: {
    label: 'OceanPayment Checkout',
    amount: '10.00',
  },
  supportedNetworks: ['visa', 'masterCard', 'amex'],
  merchantCapabilities: ['supports3DS'],
  merchantIdentifier: 'merchant.oceanpayment.test',
};

session.onpaymentauthorized = function (event) {
  const payment = event.payment;
  console.log(JSON.stringify(payment));
  console.log(JSON.stringify(payment.token));

  processPayment(payment.token).then(function (response) {
    console.log("response from datatrans received");
    console.log(response);

    if (response.match(/status=.error./)) {
       console.log("an error occured!");
       console.log(response);
       return session.abort();
    }

    session.completePayment(ApplePaySession.STATUS_SUCCESS);
    window.location.href = "/success.html";
  });
        
};


function processPayment(paymentToken) {
    let paymentMethod = paymentToken.paymentMethod;
    let cardType = paymentMethod.network;
    let environment = document.getElementById('environment').value;

    let account = payParams[environment].account;
    let terminal = payParams[environment].terminal;
    let orderNo = new Date().getTime();
    let orderCurrency = document.getElementById('#order_currency').value;
    let orderAmount = document.getElementById('#order_amount').value;

    document.getElementById('form').action = payParams[environment].url;
    document.getElementById('account').value = account;
    document.getElementById('terminal').value = terminal;
    document.getElementById('pay_accountNumber').value = paymentToken.paymentData;
    document.getElementById('card_type').value = cardType;
    document.getElementById('order_number').value = orderNo;
    document.getElementById('order_amount').value = orderAmount;
    document.getElementById('methods').value = 'ApplePay';

    let billingId = document.getElementById('billing_id').value;
    let billingFirstName = document.getElementById('billing_firstName').value;
    let billingLastName = document.getElementById('billing_lastName').value;
    let billingEmail = document.getElementById('billing_email').value;

    let signString = account + terminal + orderNo + orderCurrency + orderAmount
        + billingId + billingFirstName + billingLastName + billingEmail + payParams[environment].secureCode;

    document.getElementById('signValue').value = sha256_digest(signString);
    document.getElementById('form').submit();

}

Create QuickPay

Pass the Payment Token to Oceanpayment through the pay_accountNumber parameter to create a QuickPay ID for subscription-based quick payment scenarios.