Overviewβ
This document describes how to integrate credit card payments with Oceanpayment using the embedded method, including payment parameter submission, transaction processing, and result delivery.
For other Apple Pay integration methods, see the Credit Card integration guide.
Flowchartβ
Requestβ
1. Load the Oceanpayment SDKβ
// Load the Oceanpayment JS file
<script src="https://secure.oceanpayment.com/pages/js/oceanpayment.js"></script>
<script src="https://secure.oceanpayment.com/pub/js/jquery/jq.js"></script>
2. Create a Containerβ
// Load the Oceanpayment payment page
<div id="oceanpayment-element"></div>
3. Initializeβ
Use init(); to initialize and render the payment UI component in the container.
- Pass
trueto submit requests to the sandbox environment. - Pass an empty value to submit requests to the production environment.
<script>
$(function() {
var configuration = {"showCardName": true};
// Pass true to submit requests to the sandbox environment; pass an empty value to submit requests to the production environment.
Oceanpayment.init(true,'','',configuration);
});
</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() {
var configuration = {"showCardName": true};
Oceanpayment.init(true,'https://example.com/css/style.css','',configuration);
});
</script>
5. Customize the Payment Languageβ
The payment page adapts to the device language. You can also set the language manually. 24 payment languages are supported. The default is English (en_US).
<script>
$(function() {
var configuration = {"showCardName": true};
//θ―θ¨δ»£η
Oceanpayment.init(true,'https://example.com/css/style.css','en_US',configuration);
});
</script>
6. 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.
// Oceanpayment payment method
<script>
function pay() {
// Get the form element
var register = $("#payForm");
var formData = register.serializeArray();
Oceanpayment.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 oceanpaymentCallBack() method to receive the payment result.
var oceanpaymentCallBack = function(data){}
2. Check the Resultβ
When card information validation fails, data.msg returns an error message, for example:
// Invalid card number
{"code":-1, "msg":"Your credit card number is incorrect."}
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 oceanpaymentCallBack = function(data){
if(data.msg){
// Handle card information errors
console.log(data.msg);
}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>Credit Card</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>Credit Card</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.