Skip to main content

Overview​

'Initiate Deduction' is the core step of the Subscription feature. Once a user completes the initial payment authorization (i.e., a QuickPay ID is successfully generated), the merchant can use this API to automatically charge the user’s original payment method on the agreed schedule, without requiring the user to re-enter card details or confirm the payment.

Flow Chart​

How It Works​

  1. The merchant server calls the Direct API mode and submits the required parameters, where the quickpay_id parameter represents the card information token.
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 'quickpay_id=9ead3654-8f84-4d02-acab-6ac9dd10531f' \
-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={{methods}}' \
-d 'order_notes=' \
-d 'service_mode=Y1' \
-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' \

Business Mode​

Note

In recurring payment scenarios, the service_mode field is critical and required. It is used to identify the role in the current subscription flow (e.g., first-time purchase, renewal) and the subscription cycle type (e.g., monthly, yearly).

  • The service_mode parameter should be set according to the following scenarios:
TypePeriodservice_mode
Single Purchase-S1
First-time PurchaseWeeklyW1
MonthlyM1
QuarterlyQ1
Semi-AnnualH1
AnnualY1
First Automatic RenewalWeeklyW2
MonthlyM2
QuarterlyQ2
Semi-AnnualH2
AnnualY2
Subsequent Automatic Renewal (second or more)WeeklyW3
MonthlyM3
QuarterlyQ3
Semi-AnnualH3
AnnualY3
  • Example of values
-d 'service_mode = Y1' \

Processing the Response​

  1. In the Response Parameters:
  • When the pay_url field in the XML response is empty, no 3D Secure authentication is required. The XML response contains the final payment result. An asynchronous notification will also be sent to the configured noticeUrl.
  • When the pay_url field in the XML response is provided, 3D Secure authentication is required. Redirect the customer to the specified pay_url to complete the authentication process. Once the authentication is completed, the payment result will be returned to the configured backUrl via HTTP POST. In addition, an asynchronous notification containing the payment result will be sent to the noticeUrl.
<?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>
  • The merchant redirects the user to the pay_url.：
HTTP/1.2 301 Moved Permanently
Location: {pay_url}
  1. Check the payment status as explained, and you should also use noticeUrl to receive asynchronous transaction notifications.

Signature​

See Signature and Verification for details on request signing and response validation.

API Reference​

👉Explore our to continue your integration.