Skip to main content

Overview​

Using the Oceanpayment SDK, merchants can embed the payment form directly into their checkout page. Customers can complete payments without redirection, improving conversion rates while maintaining full brand consistency. Only credit cards, GooglePay, and ApplePay integrations are supported.

How It Works​

<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8">
    <title>Oceanpayment Debit/Credit Card|One-Page Checkout</title>
  </head>
  <body>
    <!--Form submission -->
    <form id="payForm">
                
      <label>Account number: </label>
      <input class="form-control" type="text" id="account" name="account" value='provided by Oceanpayment technical support'/>
      
      <label>Terminal number:</label>
      <input class="form-control" type="text" id="terminal" name="terminal" value='provided by Oceanpayment technical support'/>
         
      <label>signValue</label>
      <input class="form-control" type="text" id="signValue" name="signValue" value=""/>
      
      <label>Key-public key</label>
      <input class="form-control" type="text" id="key" name="key" value='provided by Oceanpayment technical support'/>
       
      <label>Website order number: </label>
      <input class="form-control" type="text" id="order_number" name="order_number" value=""/>
       
      <label>Trading currency:</label>
      <input class="form-control" type="text" id="order_currency" name="order_currency" value="USD"/>
         
      <label>Transaction amount:</label>
      <input class="form-control" type="text" id="order_amount" name="order_amount"value="0.01"/>
         
      <label>Return address:</label>
      <input class="form-control" type="text" id="backUrl" name="backUrl" value="">
          
      <label>Payment method:</label>
      <input class="form-control" type="text" id="methods" name="methods" value="Credit Card"/>
      
      <label>Cardholder name:</label>
      <input class="form-control" type="text" id="billing_lastName" name="billing_lastName" value="test"/>
       
      <label>Cardholder Last Name:</label>
      <input class="form-control" type="text" id="billing_firstName" name="billing_firstName" value="test"/>
                                          
      <label>Cardholder Email:</label>
      <input class="form-control" type="text" id="billing_email" name="billing_email" value="20200312@ebanx.com"/>
                                    
      <label>Cardholder Country::</label>
      <input class="form-control" type="text" id="billing_country" name="billing_country" value="CN"/>
                                         
      <label>Cardholder State/Province:</label>
      <input class="form-control" type="text" id="billing_state" name="billing_state" value="GD"/>
                                                                      
      <label>Cardholder City:</label>
      <input class="form-control" type="text" id="billing_city" name="billing_city" value="sz"/>
                                                                     
      <label>Cardholder address:</label>
      <input class="form-control" type="text" id="billing_address" name="billing_address" value="test"/>
                                         
      <label>Cardholder Zip Code:</label>
      <input class="form-control" type="text" id="billing_zip" name="billing_zip" value="100000"/>
                                 
      <label>Cardholder IP:</label>
      <input class="form-control" type="text" id="billing_ip" name="billing_ip" value="127.0.0.1"/>
                                     
      <label>Product name:</label>
      <input class="form-control" type="text" id="productName" name="productName" value="NOKIA N78"/>
                                   
      <label>Quantity:</label>
      <input class="form-control" type="text" id="productNum" name="productNum" value="2"/>
                                   
      <label>SKU:</label>
      <input class="form-control" type="text" id="productSku" name="productSku" value="SKU026123"/>
      
      <!--Load Oceanpayment payment page Div-->
      <div id="oceanpayment-element"></div>
                                    
      <div class="row">
        <div class="col-md-7">
            <div class="form-group">
                <button id="payNow" type="button" class="btn btn-success footable-show" onclick="pay();">Pay Now</button>
            </div>
        </div>
      </div>
    </form>
  </body>
</html>

<!-- sha256 Js encryption reference, it is recommended to use back-end sha256 encryption, the encryption structure can not be exposed to the front-end -->
<script src="https://developers.oceanpayment.com/assets/img/payment/sha256.js"></script>
<script src="https://secure.oceanpayment.com/pub/js/jquery/jq.js"></script>
<!-- Loading oceanpayment JS -->
<script src="https://secure.oceanpayment.com/pages/js/oceanpayment.js"></script>

<script>

  //Initialization
  $(function() {
      //Pass true to submit to the sandbox environment, and pass empty to submit to the production environment.
      Oceanpayment.init('','','');
  });

  //Signature example, for encryption security, it must be encrypted on the backend! ! !
  var signValue = sha256_digest($('#account').val()+$('#terminal').val()+$('#order_number').val()
                  +$('#order_currency').val()+$('#order_amount').val()+$('#billing_firstName').val()
                  +$('#billing_lastName').val()+$('#billing_email').val()+'SecureCode->provided by Oceanpayment technical support');
  $("#signValue").val(signValue);
    
  //Get the backUrl of the current page
   var url = window.parent.location.href;
   $("#backUrl").val(url);  

  //Callback processing
  var oceanpaymentCallBack = function(data){
      if(data.msg){
        //Processing card information error
        console.log(data.msg);
      }else{
        //Handle the order and return
        console.log(data);
      }
  }

  //Call payment
  function pay() {
    var register = $("#payForm");
    //Jquery serialize() method
     var formData = register.serializeArray();
     Oceanpayment.checkout(transformToJson(formData));

   }

   //Collate the json of the submitted data
   function transformToJson(formData){
     var obj={}
     for (var i in formData) {
         obj[formData[i].name]=formData[i]['value'];
     }
     return obj;
   }

   //An example of randomly generating an order number
   var order_number ='JSCSE-'+Math.floor(Math.random()*Math.pow(10,10));
   $("#order_number").val(order_number);
  
</script>

Handling Payment Results​

  • Frontend: Listen for payment result events to get immediate feedback.
  • Backend: Use noticeUrl to receive asynchronous notifications and confirm the final payment status.
Note

Oceanpayment sends the payment result to your backUrl page. The backUrl must exactly match the current page URL, including the full path, to allow the CallBack() method to receive the payment response.

var oceanpaymentCallBack = function(data){}
  1. If card information fails validation, data.msg will contain an error message, for example:
//Incorrect card number
{"code":-1, "msg":"Your credit card number is incorrect."}
  1. If data.msg is empty, the card information is valid. In this case, handle the payment response and check the following scenarios:
  • If xml->pay_url is empty, no 3D verification is required; he XML contains the payment result directly. An asynchronous notification will also be sent to noticeUrl.
  • If xml->pay_url is present, redirect the customer to complete 3D verification. After verification, the payment result will be sent again to backUrl (default received via $_POST). An asynchronous notification will also be triggered via noticeUrl.
var oceanpaymentCallBack = function(data){	
    if(data.msg){
       //Card information error processing
       console.log(data.msg);
    }else{
       //Processing order return
       //Receive the backUrl response and parse the returned XML.
       console.log(data);
    }	
}
  1. Payment Response Example：
<?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>
  • Merchants redirect users to pay_url:
HTTP/1.2 301 Moved Permanently
Location: {pay_url}
  1. Check payment status, and verify the final transaction status using asynchronous notifications sent to noticeUrl.

Signature​

The signature (signValue) format differs depending on the Hosted Checkout redirect mode you choose. Refer the Signature and Verification section for detailed instructions.