Integration flow

Prepare the information you need

Before you start integrating Checkout, make sure the following are ready:

• An active Onerway merchant account and your merchantNo
• API keys for signing requests, together with the target environment
• A reachable HTTPS domain for returnUrl and notifyUrl
• A local or sandbox setup that can receive and verify webhooks

Once these basics are ready, you can continue with the integration.

Build the Checkout request

The Checkout request needs to prepare the payer, amount, redirect target, and asynchronous notification target in one place.

Start by confirming these fields:

The minimal request usually includes these fields:

{
  "merchantNo": "800209",
  "merchantTxnId": "e868e769-afe5-41f7-9882-04835122e0b3",
  "orderAmount": "100.00",
  "orderCurrency": "USD",
  "txnType": "SALE",
  "txnOrderMsg": {
    "returnUrl": "https://your-domain.com/checkout/result?merchantTxnId=YOUR_TXN_ID",
    "notifyUrl": "https://your-domain.com/webhook"
  }
}

For subscription Checkout, you can add subProductType and subscription in the subscription guide.

Configure returnUrl / notifyUrl

Both returnUrl and notifyUrl should be included in the Checkout request, but they serve different purposes:

Test integration

Local webhook test

You can simulate webhook events locally to validate the integration quickly:

1. Start your local server (for example localhost:3000)
2. Use a tunneling tool to generate a public URL:

# Expose the local port with ngrok
ngrok http 3000

# Get the HTTPS URL (for example https://abc123.ngrok.io)

3. Configure the webhook in the payment request:
   • Set notifyUrl to the generated public URL (for example https://abc123.ngrok.io/webhook)
   • Save the webhook secret for signature verification

Test the full payment flow

1. Create a test session: use sandbox API keys to create a Checkout session
2. Complete the payment: use a test card to finish the payment flow
3. Verify the webhook:
   • Check whether the server logs received the webhook request
   • Confirm signature verification passed
   • Confirm fulfill_checkout was called and the merchantTxnId matched

Verify fulfillment results

After the payment test is complete, check the following items one by one:

• The server logs show that the webhook event was received
• Signature verification passed
• The fulfill_checkout function was called correctly
• The fulfillment action was actually executed (check database records or service provisioning state)
• Simulate sending the same webhook again and confirm there was no duplicate fulfillment (idempotency check)

Production deployment

Configure webhook and landing page URLs

When you create a Checkout session, specify both notifyUrl and returnUrl in the txnOrderMsg parameter:

{
  "merchantNo": "800209",
  "merchantTxnId": "e868e769-afe5-41f7-9882-04835122e0b3",
  "orderAmount": "100.00",
  "orderCurrency": "USD",
  "txnType": "SALE",
  // ... other required parameters
  "txnOrderMsg": "{
    \"notifyUrl\": \"https://your-domain.com/webhook\",
    \"returnUrl\": \"https://your-domain.com/order-complete?merchantTxnId=e868e769-afe5-41f7-9882-04835122e0b3\",
    \"appId\": \"your-app-id\",
    \"products\": \"[...]\",
    // ... other txnOrderMsg fields
  }"
}

Parameter details:

We recommend appending merchantTxnId to returnUrl (for example https://your-domain.com/order-complete?merchantTxnId=YOUR_TXN_ID) so the page can query and display the final payment status when it loads.