Setting up split payouts for Mainland China sellers

eBay sellers based in Mainland China can configure split payouts between two separate payment instruments, such as between a bank account and payoneer via the Account v2 API and the Finances API.

These methods allow sellers in Mainland China to update payment allocation between payment instruments, retrieve seller payouts, and retrieve transactions.

The following prerequisites are required for a seller to be able to use split payouts:

• The seller is in Mainland China.

• The seller has more than one active payout instrument on file.

• The seller's payout instruments are a bank account and/or Payoneer. Card payouts are currently unavailable.

• The seller must have their payout instruments set up in the eBay web UI. For detailed steps on setting up a payout instrument, see 更新收款 Payoneer 賬戶資料.

Updating payment allocation

Sellers in Mainland China can use the updatePayoutPercentage method of the Account v2 API to configure the split-payout percentage of two payment instruments that are available for seller payouts.

Updating the payment allocation on two payment instruments

To update payment allocation between two instruments, a seller must input in the request payload the instrumentId for each instrument they wish to configure for split payouts, as well as the payout percentage they wish to update for the associated instrument.

The instrumentId value can be found in the response of the getPayoutSettings call of the Account v2 API.

Once the instrumentId for each instrument the seller wishes to configure is retrieved, they can use the updatePayoutPercentage call to configure the split-payout percentage of the two payment instruments.

For an example of the request payload for updating the payment allocation on two payment instruments, see the Samples section of the reference documentation.

If the call was successful, an HTTP status code of 204 No Content is returned. There is no response payload. The seller can retrieve the current payout percentages currently set for their payment instruments using the getPayoutSettings method.

Setting payout to one instrument only

In addition to updating the split payout percentage between two payout instruments, sellers can also set the payout so that the entire payout goes to a single instrument. The process is identical to the scenario discussed above, only the seller sets one instrument to 100 and one instrument to 0. This allows 100% of the payout to go to a preferred instrument, and nothing to the other.

For an example of the request payload for setting the payout to one instrument only, see the Samples section of the reference documentation.

Retrieving seller payouts

A seller can use the getPayout method of the Finances API to retrieve the details of a seller payout corresponding with a provided payout ID. The payout returned is a true(actual) payout. Note that this amount is converted to CNY for bank account payouts. The seller must be in Mainland China.

To do so, a seller must make the getPayout call and pass the payoutId at the end of the call URI.

A successful call returns the details of the specified seller payout. The converted value and currency are returned in CNY. The payout percentage associated with the payout instrument is also returned. The payoutReference ID returned can be used as a filter in the getPayout method to return both payouts associated with that parent ID

For an example of the response payload when retrieving split payouts, see the Samples section of the reference documentation.

Retrieving transactions

Sellers in Mainland China can use the getTransactions call of the Finances API to retrieve all monetary transactions associated with a split payout.

To do so, only the GET HTTP method and the endpoint are used. The payoutReference filter is used in this example to return information on every monetary transaction associated with the specified split payout.

In addition to the usual information returned in a getTransactions response, calls made by sellers in Mainland China using split payout return the payoutDetails container. This container includes the payoutIds and the payoutReference associated with a transaction. The payoutReference is the unique identifier associated with the true(actual) payout ids. The payoutIds array indicates the list of true(actual) payout ids associated with a split payout.

For an example of the response payload for retrieving transactions associated with split payouts, see the Samples section of the reference documentation.