# 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.

<note>

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.

</note>

## Lifecycle and notifications

<steps level="3">

### 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](/payments/get-started/webhooks) for payment result handling. Profit sharing uses the separate [Profit share result webhook](/payments/api-reference/webhooks/profit-share-result).

### Use automatic profit sharing or call the profit sharing API

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](/payments/api-reference/endpoints/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.

### Process the profit share result

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](/payments/get-started/request-signing#profit-share-and-reversal-notifications). 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.

</steps>

## Query a profit share result

If no notification arrives or you need to check a result, call [Query profit share](/payments/api-reference/endpoints/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.

<note>

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.

</note>

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.

## Reverse a profit share

To reverse an existing profit share through the API, call [Create or reverse profit share](/payments/api-reference/endpoints/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](/payments/api-reference/endpoints/create-checkout-payment#request-paymentMethodOptions) | `paymentMethodOptions.share`: `profitShare`, `profitShareRate`, `profitShareNotifyUrl` | None | [Checkout integration](/payments/online-payments/checkout#profit-sharing) |
| Web SDK | [Create SDK transaction](/payments/api-reference/endpoints/sdk-create-transaction#request-paymentMethodOptions) | `paymentMethodOptions.share`: `profitShare`, `profitShareRate`, `profitShareNotifyUrl` | None | [Web SDK integration](/payments/online-payments/sdk#profit-sharing) |
| Direct API | [Create direct transaction](/payments/api-reference/endpoints/direct-create-transaction#request-paymentMethodOptions) | `paymentMethodOptions.share`: `profitShare`, `profitShareRate`, `profitShareNotifyUrl` | None | [Direct API integration](/payments/online-payments/api#profit-sharing) |