Profit Sharing

Profit Sharing lets merchants allocate funds from a completed payment transaction to one or more receivers according to their business agreement. It also supports reversing a previously submitted profit sharing request. This page covers profit sharing and reversal requests, result queries, and asynchronous result notifications sent from Onerway to merchants.

Use Profit Sharing when you need to:

• Allocate funds from a completed payment transaction to multiple receivers.
• Track profit sharing amounts, processing results, and failure reasons at the receiver-detail level.
• Reverse a previously submitted profit sharing request while keeping the original order and detail references.
• Confirm asynchronous results and reconcile them through webhook notifications and active queries.

Prerequisite

Before using the Profit Sharing APIs, enable profit sharing when you create the payment. Set profitSharing to true in the payment creation request, then use the completed payment's gatewayReference in the profit sharing request.

Endpoint Paths

The request examples on this page use sandbox URLs. For production, replace the base URL with the production API domain assigned to your merchant account.

This page does not cover profit sharing eligibility or onboarding checks.

API List

Action	Endpoint	Description
Profit sharing and reversal	POST /profit/share	Start profit sharing, or reverse a previous request.
Profit sharing and reversal query	POST /profit/query	Query the result of profit sharing or reversal.
Result notification	Merchant callback URL	Onerway pushes asynchronous processing results to you.

Profit Sharing and Reversal

POST

Use this API to start profit sharing or reverse a previous profit sharing request. profitReference is the merchant-side request number and idempotency key. Keep it globally unique. For a reversal, provide the original request number, original Onerway profit sharing order number, and original receiver detail information.

Request Parameters

Note

• All JSON fields must be stringified before submission
• Nested objects must be serialized to JSON string format
• JSON fields must not contain unescaped special characters
• Arrays in JSON should be properly formatted
• Example of JSON string field:

{
  "object": "{\"obj-key1\":\"v1\",\"obj-key2\":\"v2\"}",
  "complex": "{\"k1\":\"v1\",\"array\":\"[{\\\"obj-key3\\\":\\\"v3\\\",\\\"obj-key4\\\":\\\"v4\\\"}]\"}"
}

Parameter	Type	Required	Signed	Description
merchantNo	String	Yes	Yes	Merchant number that starts this profit sharing or cancellation request.
profitType	String	Yes	Yes	Business type. Use share for profit sharing and return for profit sharing cancellation. Available values: share / return .
profitReference	String	Yes	Yes	Merchant-side profit sharing or cancellation request number. It is used as an idempotency key and must be globally unique.
gatewayReference	String	Conditional	Yes	Onerway payment transaction ID, corresponding to the existing transactionId field. Required when profitType=share; not required when profitType=return.
profitParentReference	String	Conditional	Yes	Original profit sharing request number. Required when profitType=return.
profitGatewayReference	String	Conditional	Yes	Original Onerway profit sharing order number. Required when profitType=return.
currency	String	Yes	Yes	Profit sharing or cancellation currency. Use a three-letter currency code whenever possible.
urlCallback	String	Yes	Yes	Callback URL used to receive asynchronous profit sharing or cancellation results.
profitCompleted	Boolean	Conditional	Yes	Whether all profit sharing plans for this payment order have been completed. Applies when profitType=share. Available values: true - no further profit sharing will be submitted; false - more profit sharing requests may be submitted later.
receivers	String (JSON array)	Yes	Yes	Receiver list for profit sharing or cancellation. Submit this field as a JSON string. See receivers structure for complete structure.
sign	String	Yes	No	Request signature generated according to the Onerway signature rules.

receivers

Submit receivers as a JSON string. The objects inside the array use the following fields.

Field	Type	Required	Description
profitDetailReference	String	Yes	Merchant-side detail request number. Keep it unique under the same profitReference.
profitDetailParentReference	String	Conditional	Original profit sharing detail request number. Required when profitType=return.
profitDetailGatewayReference	String	Conditional	Original Onerway profit sharing detail order number. Required when profitType=return.
type	String	Yes	Profit sharing detail type code. This field identifies the fund usage or profit sharing reason; it is not the receiver account type. Available values: detail type codes .
account	String	Yes	Receiver merchant number. For cancellation, use the receiver merchant number from the original profit sharing detail.
amount	String	Yes	Profit sharing or cancellation amount, expressed as a decimal string.
description	String	No	Detail description for reconciliation and troubleshooting.

Response

The following table lists the business result fields. Read these business fields according to the actual response structure returned by your integration.

Field	Type	Description
profitType	String	Business type. share means profit sharing and return means profit sharing cancellation. Available values: share / return .
profitReference	String	Merchant-side profit sharing or cancellation request number.
profitGatewayReference	String	Onerway profit sharing or cancellation order number.
state	String	Overall processing state of the profit sharing or cancellation order. Available values: processing / completed .
currency	String	Settlement currency of the profit sharing or cancellation order.
receivers	String (JSON array)	Receiver processing result list returned as a JSON string. See receivers structure for complete structure.

receivers

The response returns receivers as a JSON string. The objects inside the array use the following fields.

Field	Type	Description
profitDetailReference	String	Merchant-side profit sharing or cancellation detail request number.
profitDetailGatewayReference	String	Onerway profit sharing or cancellation detail order number.
type	String	Nullable. Profit sharing detail type code when returned. Available values: detail type codes .
amount	String	Actual profit sharing or cancellation amount, expressed as a decimal string.
result	String	Processing result of this receiver detail. Available values: pending / success / failed .
failReason	String	Nullable. Failure reason when result=failed; otherwise returns null.
createdAt	String	Detail creation time. Format: yyyy-MM-dd HH:mm:ss; do not treat it as a timestamp.
finishedAt	String	Nullable. Returns null when result=pending. Format: yyyy-MM-dd HH:mm:ss; do not treat it as a timestamp.

API Usage Examples

Profit Sharing Request

{
  "merchantNo": "800209",
  "profitType": "share",
  "profitReference": "ps_202606220001",
  "gatewayReference": "203000000000000001",
  "currency": "USD",
  "urlCallback": "https://merchant.example.com/webhooks/profit-sharing",
  "profitCompleted": false,
  "receivers": "[{\"profitDetailReference\":\"psd_202606220001\",\"type\":\"1\",\"account\":\"800210\",\"amount\":\"80.00\",\"description\":\"Seller settlement\"},{\"profitDetailReference\":\"psd_202606220002\",\"type\":\"2\",\"account\":\"800211\",\"amount\":\"20.00\",\"description\":\"Platform service fee\"}]",
  "sign": "a1b2c3d4e5f6..."
}

Reversal Request

{
  "merchantNo": "800209",
  "profitType": "return",
  "profitReference": "psr_202606220001",
  "profitParentReference": "ps_202606220001",
  "profitGatewayReference": "pg_203000000000000001",
  "currency": "USD",
  "urlCallback": "https://merchant.example.com/webhooks/profit-sharing",
  "receivers": "[{\"profitDetailReference\":\"psrd_202606220001\",\"profitDetailParentReference\":\"psd_202606220001\",\"profitDetailGatewayReference\":\"pgd_203000000000000001\",\"type\":\"1\",\"account\":\"800210\",\"amount\":\"80.00\",\"description\":\"Reverse seller settlement\"}]",
  "sign": "a1b2c3d4e5f6..."
}

Response

{
  "profitType": "share",
  "profitReference": "ps_202606220001",
  "profitGatewayReference": "pg_203000000000000001",
  "state": "processing",
  "currency": "USD",
  "receivers": "[{\"profitDetailReference\":\"psd_202606220001\",\"profitDetailGatewayReference\":\"pgd_203000000000000001\",\"type\":\"1\",\"amount\":\"80.00\",\"result\":\"pending\",\"failReason\":null,\"createdAt\":\"2026-06-22 10:00:00\",\"finishedAt\":null}]"
}

Example Note

The examples above only illustrate the field structure. Do not use them directly as production request parameters.

Profit Sharing and Reversal Query

POST

Use this API to query the processing result of profit sharing or reversal. Provide profitType, profitReference, and the Onerway-generated profitGatewayReference.

Request Parameters

Parameter	Type	Required	Signed	Description
merchantNo	String	Yes	Yes	Merchant number that starts the query.
profitType	String	Yes	Yes	Business type to query. Use share for profit sharing results and return for cancellation results. Available values: share / return .
profitReference	String	Yes	Yes	Merchant-side profit sharing or cancellation request number.
gatewayReference	String	No	Yes	Onerway payment transaction ID, corresponding to the existing transactionId field. Optional for queries.
profitGatewayReference	String	Yes	Yes	Onerway profit sharing or cancellation order number.
sign	String	Yes	No	Request signature generated according to the Onerway signature rules.

Response

The query API returns the same business result fields as the profit sharing request API.

Field	Type	Description
profitType	String	Business type. share means profit sharing and return means profit sharing cancellation. Available values: share / return .
profitReference	String	Merchant-side profit sharing or cancellation request number.
profitGatewayReference	String	Onerway profit sharing or cancellation order number.
state	String	Overall processing state of the profit sharing or cancellation order. Available values: processing / completed .
currency	String	Settlement currency of the profit sharing or cancellation order.
receivers	String (JSON array)	Receiver processing result list returned as a JSON string. See receivers structure for complete structure.

receivers

Field	Type	Description
profitDetailReference	String	Merchant-side profit sharing or cancellation detail request number.
profitDetailGatewayReference	String	Onerway profit sharing or cancellation detail order number.
type	String	Nullable. Profit sharing detail type code when returned. Available values: detail type codes .
amount	String	Actual profit sharing or cancellation amount, expressed as a decimal string.
result	String	Processing result of this receiver detail. Available values: pending / success / failed .
failReason	String	Nullable. Failure reason when result=failed; otherwise returns null.
createdAt	String	Detail creation time. Format: yyyy-MM-dd HH:mm:ss; do not treat it as a timestamp.
finishedAt	String	Nullable. Returns null when result=pending. Format: yyyy-MM-dd HH:mm:ss; do not treat it as a timestamp.

API Usage Examples

Request

{
  "merchantNo": "800209",
  "profitType": "share",
  "profitReference": "ps_202606220001",
  "gatewayReference": "203000000000000001",
  "profitGatewayReference": "pg_203000000000000001",
  "sign": "a1b2c3d4e5f6..."
}

Response

{
  "profitType": "share",
  "profitReference": "ps_202606220001",
  "profitGatewayReference": "pg_203000000000000001",
  "state": "completed",
  "currency": "USD",
  "receivers": "[{\"profitDetailReference\":\"psd_202606220001\",\"profitDetailGatewayReference\":\"pgd_203000000000000001\",\"type\":\"1\",\"amount\":\"80.00\",\"result\":\"success\",\"failReason\":null,\"createdAt\":\"2026-06-22 10:00:00\",\"finishedAt\":\"2026-06-22 10:00:08\"}]"
}

Profit Sharing and Reversal Notification

After the profit sharing or reversal result is processed, Onerway sends a notification to the urlCallback provided in the request. The receivers field in the notification is also sent as a JSON string.

Webhook Request Parameters

Field	Type	Required	Description
profitType	String	Yes	Business type. share means profit sharing and return means profit sharing cancellation. Available values: share / return .
profitReference	String	Yes	Merchant-side profit sharing or cancellation request number.
profitGatewayReference	String	Yes	Onerway profit sharing or cancellation order number.
state	String	Yes	Overall processing state of the profit sharing or cancellation order. Available values: processing / completed .
currency	String	Yes	Settlement currency of the profit sharing or cancellation order.
receivers	String (JSON array)	Yes	Receiver processing result list sent as a JSON string. See receivers structure for complete structure.
sign	String	Yes	Notification signature. Verify it according to the Onerway webhook signature rules.

receivers

Field	Type	Required	Description
profitDetailReference	String	Yes	Merchant-side profit sharing or cancellation detail request number.
profitDetailGatewayReference	String	Yes	Onerway profit sharing or cancellation detail order number.
type	String	No	Profit sharing detail type code. It identifies the fund usage or profit sharing reason. Available values: detail type codes .
amount	String	Yes	Actual profit sharing or cancellation amount, expressed as a decimal string.
result	String	Yes	Processing result of this receiver detail. Available values: pending / success / failed .
failReason	String	No	Failure reason when result=failed; returns null when the detail is not failed.
createdAt	String	Yes	Detail creation time. Format: yyyy-MM-dd HH:mm:ss; do not treat it as a timestamp.
finishedAt	String	No	Detail completion time. Returns null when result=pending. Format: yyyy-MM-dd HH:mm:ss; do not treat it as a timestamp.

Webhook Response

Return HTTP 200 to indicate that the notification was received successfully. No fixed JSON payload is required in the response body.

Webhook Example

Notification

{
  "profitType": "share",
  "profitReference": "ps_202606220001",
  "profitGatewayReference": "pg_203000000000000001",
  "state": "completed",
  "currency": "USD",
  "receivers": "[{\"profitDetailReference\":\"psd_202606220001\",\"profitDetailGatewayReference\":\"pgd_203000000000000001\",\"type\":\"1\",\"amount\":\"80.00\",\"result\":\"success\",\"failReason\":null,\"createdAt\":\"2026-06-22 10:00:00\",\"finishedAt\":\"2026-06-22 10:00:08\"}]",
  "sign": "a1b2c3d4e5f6..."
}

Response

HTTP/1.1 200 OK

Common Response Handling

Situation	Recommended Handling
Signature verification fails	Check the non-empty signed parameters, parameter order, secret key, and the rule that excludes sign.
Invalid receivers format	Ensure receivers is a JSON string and that the array fields match the required fields on this page.
Result is still processing	When state=processing or a detail has result=pending, wait for the webhook or query again later.
Detail processing failed	Use receivers[].failReason to identify the failure reason and follow your reconciliation process.

The API may also return errors for IP allowlists, permission validation, parameter validation, or downstream system mappings. Use the actual response as the source of truth.

Best Practices

1. Use a globally unique profitReference, and store profitGatewayReference for later query and reversal.
2. Submit receivers as a JSON string. Before signing, make sure the string content matches the actual request body.
3. For a reversal, keep and submit the original request number, original profit sharing order number, and original detail order number.
4. Do not treat state=completed as proof that every detail succeeded. Check receivers[].result for each detail.
5. Use the webhook as the asynchronous result channel, and use POST /profit/query as the fallback query and reconciliation method.

Related Documentation

• Signature
• Transaction Webhooks
• Transaction Order Query
• Payment Query
• Currency Support