Note: This is the third General Availability (GA) release of the Finances API. All new users should use the GA version instead of the alpha version. The alpha version endpoints will still be supported for a limited time, but users that are using the alpha version should make plans to migrate to the GA version. Documentation for the alpha version can now be accessed at this URL: https://developer.ebay.com/api-docs/sell/finances-v1_alpha/resources/methods.
The Finances API is used by sellers in eBay's managed payments program to retrieve seller payout information. The data provided through this public API is similar to the data that the seller will see under the Payments tab of Seller Hub in My eBay. With eBay's managed payments program, eBay manages the entire payments process, including the available payment methods, and shortly after a buyer's payment clears, eBay distributes payouts directly to the seller's preferred bank account.
Below is a summary of the three resources and six operations available through the Finances API.
- payout: a payout is distributed to the seller's bank account shortly after the buyer's payment for an order clears. A single seller payout may be for one order or numerous orders, depending on the number of orders paid for on a given day.
- getPayout: this operation retrieves details on a specific payout. The unique identifier of the payout is needed to run this operation.
- getPayouts: this operation retrieves details on multiple payouts. There are available filters to search for payouts processed within a date range, or sellers can search for payouts in different states (e.g., successful, failed, etc.). There are query parameters available for sorting and pagination control.
- getPayoutSummary: this operation retrieves counts and dollar values for payouts, and the number of monetary transactions associated with the payouts. Similar to the getPayouts operation, this operation has filters to search for payouts processed within a date range, or payouts in different states (e.g., successful, failed, etc.).
- transaction: in the Finances API, a 'transaction' can have one of six types - a sales transaction (or order), a buyer refund, a seller credit (issued by eBay), a monetary transaction involving a payment dispute initiated by a buyer through their payment provider, a shipping label purchase, or a transfer to eBay for a buyer reimbursement. The transaction object contains identifiers for the order and payout, and the status and dollar value of the order/payout.
- getTransactions: this operation retrieves details on one or more monetary transactions. There are available filters to search for transactions by type (sale, refund, credit, payment dispute, shipping label, or transfer), transactions within a date range, transactions in different states, or sellers can search for a specific transaction according to order ID, payout ID, or buyer user name. There are query parameters available for sorting and pagination control.
- getTransactionSummary: this operation retrieves counts and dollar values for payouts, seller credits, buyer refunds, payment holds, payment disputes, and shipping labels. Similar to the getTransactions operation, this operation has filters to search for transactions by type (sale, refund, credit, payment dispute, shipping label, or transfer), transactions within a date range, transactions in different states, or sellers can search for a specific transaction according to order ID, payout ID, or buyer user name.
- seller fund summary: this resource gives the seller dollar values for all pending sales funds that are eligible for a seller payout.
- getSellerFundsSummary: this operation retrieves dollar values for funds available for payouts (but not yet in processing stage), funds being processed for payouts, funds currently locked in payment holds, and the total aggregate amount of all pending funds.
Finances API requirements and restrictions
The Finances API can be considered a 'standalone' API. Users do not have to be integrated with any other eBay public APIs in order to use the Finances API. The only user requirement is that the seller's account must be enabled for eBay managed payments. The getPaymentsProgram method of the Account API can be used to see if a seller is opted in to eBay Managed Payments.
eBay managed payments is currently available to a limited number of sellers on the eBay US and Germany marketplaces. In July 2020, eBay managed payments will expand in the US and Germany, and become available to a limited number of sellers in Canada, UK, and Australia. See the Managed Payments landing page for more information.