Skip to main content

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.

Before You Begin​

For server-to-server Apple Pay integration, the merchant must register an Apple Developer account, use the Payment Token flow to obtain a card information token, and pass the token to Oceanpayment as a parameter.

Flowchart​

Request​

1. Register for an Apple Developer Account​

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

2. Create a Merchant ID​

  • Sign in to Apple Developer and go to Certificates, Identifiers & Profiles.
  • Select Identifiers > Merchant IDs in the left menu, then click (+) to create a Merchant ID. Example: merchant.com.example.store

3. Create a Payment Processing Certificate​

  • On a Mac, use Keychain or OpenSSL to generate a CSR (Certificate Signing Request).
  • Sign in to Apple Developer and go to Certificates.
  • Select Payment Processing Certificate to create a certificate.
  • Upload the CSR. Apple will return a .cer file.
  • Download the certificate and install it in your local Keychain.
  • Export a .p12 file from Keychain. It contains the private key.

The .p12 file is used to decrypt the Payment Token returned by Apple Pay on the server.

4. Configure the Merchant Domain Allowlist​

  • Sign in to Apple Developer and go to Merchant IDs > Domain Verification.
  • Add the merchant domain (e.g., example.com or www.example.com).
  • Download the verification file apple-developer-merchantid-domain-association.txt as prompted. You must deploy the file and click Verify within 7 days of generating it. Otherwise, it will expire and you’ll need to generate it again.
  • Upload the file to your website’s root directory, for example: https://example.com/.well-known/apple-developer-merchantid-domain-association.txt
  • Click Verify to complete verification.

5. Obtain a Payment Token​

See the Apple Pay official demo to obtain a Payment Token.

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

6. Payment Token Parameter​

  • When submitting an Oceanpayment payment request, use pay_accountNumber to pass the paymentData object from the Apple Pay Payment Token.
  • Value: Pass the following node in full to pay_accountNumber.
{
"data": "",
"signature": "",
"header": {
"publicKeyHash": "",
"ephemeralPublicKey": "",
"transactionId": ""
},
"version": "EC_v1"
}
Note
  1. Preserve the complete paymentData object returned by Apple in pay_accountNumber.
  2. Submit the payment request immediately after obtaining the Payment Token to avoid expiration.
  3. The EC_v1 encryption format returned by Apple Pay is supported.

7. card_type Parameter​

Use card_type to pass the paymentMethod.network value from the Apple Pay Payment Token. Convert the returned paymentMethod.network value to a supported Oceanpayment card_type enum value before submitting it.

paymentMethod.networkcard_type
visaVISA
masterCardMASTERCARD
maestroMAESTRO
JCBJCB
eloELO
discoverDISCOVER
chinaUnionPayCHINAUNIONPAY
cartesBancairesCARTESBANCAIRES
amexAMEX
-d 'card_type=VISA' \

8. Submit the Payment Request​

The merchant’s server submits the required parameters via direct integration and passes the card information token returned by Apple Pay in the pay_accountNumber parameter.

cURL -X POST 'https://test-secure.oceanpayment.com/gateway/direct/pay'
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'account=995149' \
-d 'terminal=99514901' \
-d 'signValue=6b86b273ff34fce19d6b804eff5a3f5747ada4eaa22f1d49c01e52ddb7875b4b' \
-d 'backUrl=https://www.abc.com/back.php' \
-d 'noticeUrl=https://www.abc.com/notice.php' \
-d 'order_number=NO12345678' \
-d 'order_currency=USD' \
-d 'order_amount=0.01' \
-d 'methods=ApplePay' \
-d 'order_notes=' \
-d 'pay_accountNumber={"data":"ned7UHi3Uti0VPrayQVZ7lIEBBeahdv02bFf65k4xVNzoMCm1ansTK+dbeoCb5doLRIm7FWYjJOmUE2/HMARrDShl0fNWn5V+2sX6WhhY7RwV13XD5BFJ3bqb8LvuzeWhX2ILKfQ9n3KqGXrTQC8M+YrbHS0eQZXBFBSlNeebn+izrbSzk+xmxBXGrK1R8/ov7q+i5/1q64+a0Eh1QGscBbweOuvBOsJl1CSSYvoRXF3GTHO1c80fGE1GWtHBPjDmhtjl7Al57lZPBenfnA/PXCx1NeUQPJcfNIXY/Ax9q2GjVk2nfXyGepvB8cXpdYZ7gqCo6V13B28D7qX3/AJo1CWEeH8ulVNbRu2sJKoE5/vIOmXXmUJY/2gwCQOnebXxtLjGlOJO8DiOAFDEdQx6pGpi9Ckzi8S7IU294s=","signature":"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","header":{"publicKeyHash":"sLiXc1clhfuSZN/HBtYjdW81oXfXcqdRXsd6nB3Rua8=","ephemeralPublicKey":"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEAKwAnvO9+06yugF6pninfzLfwNOyHvKDdOM+MweabfSU1GjG3fN9tLc6mvz1g1RGuIQrrqhfb2MCSzBGcY7R2Q==","transactionId":"627f630d5f403f676697ee779752abe338e9a05e8ba92b111bb69dd1f43cbb15"},"version":"EC_v1"}' \
-d 'card_type=VISA' \
-d 'billing_firstName=test' \
-d 'billing_lastName=test' \
-d 'billing_email=test@gmail.com' \
-d 'billing_phone=13800138000' \
-d 'billing_country=US' \
-d 'billing_state=AL' \
-d 'billing_city=Washington D.C.' \
-d 'billing_address=705A big Road' \
-d 'billing_zip=529012' \
-d 'billing_ip=127.0.0.1' \
-d 'productNum=1' \
-d 'productName=Red Dress' \
-d 'productSku=#001' \
-d 'productPrice=0.01' \

QuickPay​

Pass the Payment Token to Oceanpayment using the pay_accountNumber parameter to create a subscription through the QuickPay direct integration API.

Response​

  1. Check the pay_url field in the payment response to determine whether 3DS verification is required. See the full list of response parameters.
<?xml version="1.0" encoding="UTF-8"?>
<response>
<notice_type>transaction</notice_type>
<push_dateTime>2025-12-19 09:52:47</push_dateTime>
<account>995149</account>
<terminal>99514901</terminal>
<signValue>D6315600AE0002C1468DC9B943E17E90B314E73581393ABC332B92985E41B100</signValue>
<methods>ApplePay</methods>
<order_number>NO12345678</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>231219095247018026021</payment_id>
<payment_authType>3</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></pay_url>
</response>
  • If xml->pay_url is empty, no 3DS verification is required, and xml contains the payment result. An asynchronous notification is sent to noticeUrl.
  • If xml->pay_url is not empty, 3DS verification is required. Redirect the user to pay_url to complete verification. The payment result will then be sent to backUrl again. By default, receive it using $_POST. An asynchronous notification is also sent to noticeUrl.
    • Redirect the user to pay_url:
HTTP/1.2 301 Moved Permanently
Location: {pay_url}

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.