Scenarios

Profit sharing

Choose automatic or API-initiated profit sharing, configure result notifications, and associate profit shares and reversals with the original payment.

Profit sharing is a platform-model capability that allocates funds after a payment completes. Whether you are a platform merchant is determined by the cooperation model agreed when your merchant number is issued; ordinary merchants do not use profit sharing. The platform merchant typically initiates profit sharing on behalf of the sub-merchant that received the payment. Automatic profit sharing allocates funds to the platform merchant; for API-initiated profit sharing, you specify the recipients and amounts in receivers. Use the receiving sub-merchant's merchantNo when creating the payment, and the same merchant number for subsequent API profit share requests and queries.

Concepts and choices

You must set profitShare=true in paymentMethodOptions.share when creating the payment; only then is the payment eligible for profit sharing. Checkout, Web SDK, and Direct API all use this configuration.

Method	Configuration when creating the payment	After the payment succeeds
Automatic profit sharing	Set both `profitShare=true` and `profitShareRate`	Onerway automatically allocates the specified percentage to the platform merchant after a successful `SALE` or `CAPTURE`; each original payment produces one automatic profit share record
API-initiated profit sharing	Set `profitShare=true` without `profitShareRate`	Your server calls the profit sharing API to specify recipients and amounts

profitShareRate is a whole-number percentage from 1 to 100, submitted as a string: "10" means 10%. Decimals, 0, negative values, and values above 100 are rejected. When a payment with automatic profit sharing is refunded or charged back, Onerway returns the allocated portion at the same percentage.

Setting only profitShare=true or a notification URL does not trigger automatic profit sharing. You must also set profitShareRate for automatic profit sharing. See the API Reference for each integration method for field requirements and complete request examples.

Lifecycle and notifications

Create the payment and configure notifications

Configure paymentMethodOptions.share for your chosen method. To receive automatic profit share and reversal notifications, also set profitShareNotifyUrl. Without this URL, no automatic notification is sent.

The notification URL must use HTTPS and be submitted with profitShare=true. A CAPTURE transaction inherits the URL from its original AUTH transaction. Submit paymentMethodOptions as a JSON string as required by the API; complete examples are available in the references for each integration method below.

Confirm the payment succeeded

Confirm the payment result using your integration method, and store the original transactionId, merchant order number, and receiving merchant number. See Webhooks for payment result handling. Profit sharing uses the separate Profit share result webhook.

For automatic profit sharing, Onerway allocates funds after a successful SALE or CAPTURE; you do not need to call the profit sharing API. Onerway generates the profitReference for automatic profit shares and reversals.

To initiate a profit share through the API, call Create or reverse profit share with profitType=share. Set gatewayReference to the original payment's transactionId. Supply a globally unique profitReference for this request, submit the profit share currency in currency, and specify recipient merchant numbers, purpose codes, and amounts in receivers, serialized as a JSON string as required by the API.

profitCompleted is required when profitType=share. It indicates whether this request completes profit sharing for the payment. Submit false while further profit shares are expected. Once you submit true, further profit share requests for that payment are rejected. See the field descriptions for the complete API requirements.

API-initiated profit shares and reversals use urlCallback for result notifications. You can omit it when the original payment already has profitShareNotifyUrl. Otherwise, you must provide urlCallback in the API request.

Store profitReference and the profitGatewayReference returned by Onerway for later queries and reversals. Associate a notification with the original payment using relatedTxnId and relatedMerchantTxnId; these fields are strings and can be null. You can also match an existing profit share record using its request reference and Onerway order number.

Verify profit share and reversal notifications using the sign field in the notification body; see Profit share and reversal signature verification. Use the raw receivers string as received when calculating the signature; do not parse and re-serialize it. Return HTTP 200 after receiving and accepting the notification. The response body can be empty.

state=completed means processing has finished, not that every detail succeeded. Check each receivers[].result. Use failReason to investigate failures, but do not determine the result by matching its text.

If no notification arrives or you need to check a result, call Query profit share. Use the original payment's receiving merchant number and select profit shares or reversals with profitType=share or return.

Provide at least one of profitReference, gatewayReference, profitGatewayReference, relatedTxnId, or relatedMerchantTxnId. Multiple identifiers are applied together as filters. You can query by the original payment's relatedTxnId or relatedMerchantTxnId, or use a stored profit share request reference or Onerway order number. See the API Reference for the query fields, requirements, and examples.

The meaning of gatewayReference in a query depends on the order type: for share, it is the original SALE payment's transactionId; for return, it is the Onerway order number of the profit share being reversed. Use relatedTxnId to query a reversal by its original payment.

We recommend using strings for merchant numbers and transaction IDs in query requests to avoid numeric precision loss. Query responses include data.sign, but merchants do not need to verify query response signatures. This does not change the requirement to verify profit share webhooks.

To reverse an existing profit share through the API, call Create or reverse profit share with profitType=return:

Supply a new, globally unique profitReference for the reversal, and submit the reversal currency in currency.
Set profitParentReference to the original profit share reference. For automatic profit shares, Onerway generates this reference; obtain it from a query result or notification.
Set profitGatewayReference to the original Onerway profit share order number being reversed.
Supply a profitDetailReference that is unique within this reversal's profitReference for each detail.
In each detail, set profitDetailParentReference to the original detail reference and profitDetailGatewayReference to the original Onerway detail number. Use the original recipient merchant number. See the API field descriptions for amounts and other requirements.
Do not submit gatewayReference when initiating a reversal. This differs from how the field is used when querying reversal results.

Confirm the reversal result through notifications or queries and check each detail. Submitting a reversal request does not mean it has succeeded.

Parameters by integration method

All three integration methods configure paymentMethodOptions.share when creating a payment and follow the same automatic profit sharing rules. Your server calls the profit sharing APIs to initiate a profit share, query a result, or reverse a profit share.

Integration method	Endpoint	Key parameters	Differences	Integration guide
Checkout	Create checkout payment	`paymentMethodOptions.share`: `profitShare`, `profitShareRate`, `profitShareNotifyUrl`	None	Checkout integration
Web SDK	Create SDK transaction	`paymentMethodOptions.share`: `profitShare`, `profitShareRate`, `profitShareNotifyUrl`	None	Web SDK integration
Direct API	Create direct transaction	`paymentMethodOptions.share`: `profitShare`, `profitShareRate`, `profitShareNotifyUrl`	None	Direct API integration

Pre-authorization and capture

Hold funds first and capture on fulfillment — scope of pre-authorization, the lifecycle and notifications from authorization to capture or void, boundaries and status handling, and the parameter differences across integration methods.

Refunds

Request a refund, handle refund results and request rejections, and query the outcome or cancel a request before approval.