Working with eBay Managed Payments
eBay managed payments streamlines the entire end-to-end payments experience on the eBay platform. Sellers no longer need to be concerned about specifying payment methods at listing time, buyers get more payment options like Apple Pay and Google Pay, and sellers are paid directly to their bank accounts.
|NOTE||eBay managed payments is currently available to a select set of sellers in the following countries: US, Germany, Canada, UK, Australia, France, Italy, and Spain. We expect a majority of sellers around the world to have transitioned into managed payments by the end of 2021.|
Overview of APIs supporting eBay managed payments
The list below provides a summary of the APIs and capabilities to support eBay managed payments. A little more detail on functionality is provided in subsequent sections.
- Account API:
- the getPaymentsProgram and getPaymentsProgramOnboarding methods are used to get the managed payments onboarding status of a seller.
- New: getKYC endpoint informs sellers of action they need to take to complete seller onboarding through a process eBay calls KYC (“Know your Customer”).
- Finances API:
- Retrieve seller payout information for eBay orders
- Retrieve details for various transactions, including sales, buyer refunds, seller credits, payment disputes, shipping labels, and transfers
- New: the getTransactions response for sales orders details the selling fees deducted from seller earnings at the time of sale. The remainder of seller earnings will go directly to the sellers bank account at payout. The response shows gross revenue, total fee amount, and net revenue for the order, and also shows the itemized fees associated with each order line item.
- New: a paymentsEntity field was added to indicate the eBay payments entity that is processing a buyer’s payment.
- New: getTransfer endpoint returns more details on transfer transactions, including the seller’s funding source and applicable charge(s) for each transfer
- New. currency conversion enabled to support international selling by managed payments sellers.
- Fulfillment API
- The issueRefund method allows a managed payments seller to voluntarily issue a refund to the buyer
- The payment dispute methods allow the seller to retrieve and manage third-party, buyer-initiated payment disputes
- The payments.paymentMethod field of the getOrders method returns an enum value that identifies an eBay managed payments order
- New: totalFeeBasisAmount field returned in getOrders method indicates the order total used to calculate the final value fee that is deducted from the total amount of the sale at the time of the transaction.
- New: detailed information on electronic waste and mattress recycling fees are returned (when applicable) for getOrder/getOrders.
- Post-Order API:
- Details on the seller payment method used to fund buyer refunds will be returned in the getCancellation, getInquiry, getCase, and getReturn methods
- New: fields added in getCancellation, getInquiry, getCase, and getReturn methods to show the net charge amount to the seller for a buyer refund and any transactional fee credits due back to the seller per eBay fee credit policy. The net charge amount is derived from subtracting the fee credit amount from the total charge.
- New: currency conversion enabled to support international selling by managed payments sellers.
- Trading API
- The CheckoutStatus.PaymentMethod field of the GetOrders call returns an enum value that identifies an eBay managed payments order
- New: the GetAccount call now provides details about fees deducted from seller payouts. See the Retrieving managed payments fees/credits in GetAccount section for more details.
About this page
This page offers a high-level overview of how sellers can use eBay APIs to prepare for and integrate with eBay managed payments once the capability becomes available to them. In addition to discussing what API capabilities for eBay managed payments are currently available, this page will also discuss future API enhancements, and will continue to be updated as more features are rolled out and managed payments are extended to additional eBay marketplaces.
Using eBay APIs to integrate with managed payments
- Retrieving a seller's onboarding status for managed payments
- Listing and revising items as managed payments seller
- Using payment business policies
- Identifying managed payments orders
- Retrieving seller payout information with Finances API
- Handling refunds for order cancellations and returns
- Handling third-party payment disputes
- Retrieving managed payments fees/credits in GetAccount
- Managing payout frequency on Seller Hub
- Tracking ‘fee netting’ fees and seller payout amounts
- Tracking reimbursement funds for buyer refunds and other charges
- Integrating with international selling
If you are a seller and you want to know your current onboarding status for managed payments, or if you are a developer who supports numerous sellers, the seller's onboarding status can be checked using either the getPaymentsProgram or getPaymentsProgramOnboarding methods of the Account API.
The getPaymentsProgram method is used to see if the seller is onboarded or not, and the getPaymentsProgramOnboarding method will return a little more data regarding the seller's onboarding status, and will advise what the next registration step is for the seller. For more information on using these methods, see the reference documentation for these methods.
When listing or revising items with the Trading API or Inventory API, the seller no longer needs to specify any payment methods, as available payment methods are controlled by eBay. If a seller does include one or more payment methods in an API call, eBay will drop those specified payment methods from the listing, and will return a warning message in the API response. Another API field that is no longer needed is the seller's PayPal payment address, and this field will also be dropped by eBay if included in an API call.
|NOTE||If you were notified but did not complete managed payments registration by July 15, you may be blocked from creating new listings. For more information on how to register for managed payments, go to Seller Hub, or use the getPaymentsProgramOnboarding method of the Account API.|
Similar to the new behavior with payment methods in listing and revising API calls, specific payment methods are no longer needed in payment business policies. If the payment business policy associated with the listing has payment methods included, they will be ignored and dropped at listing/revision time. The 'immediate payment' feature in payment business policies is still supported, but PayPal-related information will no longer be necessary.
Payment business policies can be created and managed in the seller's My eBay account, or the payment policy methods of the Account API can be used.
How orders are retrieved using the GetOrders call from Trading API or the getOrders method of the Fulfillment API does not change, but a specific buyer payment method enum value will be returned for managed payments orders, regardless of the actual payment method that was used by the buyer to pay for the order.
The Trading API has not been updated to specify
EBAY for managed payments orders, but managed payment orders can be identified by other
PaymentMethod values. For this API, the payment method enum value returned in the CheckoutStatus.PaymentMethod field will be
CreditCard for managed payments orders, or
CCAccepted for orders where the buyer uses an eBay gift card to pay a portion or the full balance of the order.
One of the main functions of the new Finances API is to retrieve seller payout information, and the eBay orders that are associated with each seller payout. A quick overview of the Finances API methods is provided below:
- getPayouts : retrieves seller payouts; multiple filters available, including date range and status (‘succeeded’, ‘initiated’, ‘failed’, ‘reversed’) filters
- getPayout : retrieves detailed information about a specific seller payout
- getPayoutSummary : retrieves the number of seller payouts, the dollar value of these payouts, and the number of sales orders that are a part of those seller orders; date range filter is typically used
- getTransactions : retrieves monetary transactions (sales orders, buyer refunds, seller credits, etc.), and the seller payouts associated with those transactions; multiple filters available, including date range, transaction type, transaction status and others
- getTransactionSummary : similar to getPayoutSummary, but this method returns aggregate counts and amounts for different monetary transactions such as sales orders, buyer refunds, seller credits, etc.
- getTransfer: retrieves detailed information regarding a
TRANSFERtransaction type, which occurs when a seller reimburses eBay for one or more charges, such as a buyer refund.
- getSellerFundsSummary : retrieves amounts for pending seller payout funds, and these fund amounts are separated into different states - ‘available’, ‘processing’, ‘on-hold’, and the total aggregate amount
To initiate a buyer refund, the seller can use the Post-Order API, or the issueRefund method of the Fulfillment API. The appropriate method of the Post-Order API should be used if the buyer has created an INR inquiry, a return request, or an eBay Buyer Protection case against the seller, but the issueRefund method of the Fulfillment API is recommended otherwise, as this method can be used to:
- Issue a full refund for an order cancellation or a return, or a partial refund as an order adjustment/discount to the buyer.
- Issue a refund at the order level or a refund at the individual line item level for a multiple line item order.
Details on the seller payment instrument used to fund buyer refunds will be returned in the getCancellation, getInquiry, getCase, and getReturn methods of the Post-Order API. Managed payments sellers will have option to “fund” these refunds with available payout funds, or a bank account or credit card on file.
There may be cases when buyers initiate a payment dispute with their payment provider, such as PayPal or their credit card company. The payment dispute methods of the Fulfillment API allow sellers to monitor and retrieve any third-party payment disputes they receive. A quick overview of some of the payment dispute methods is provided below:
- getPaymentDisputeSummaries: retrieves any payment disputes filed against seller; multiple filters available, including date range and status (‘open’, ‘action needed’, etc.) filters
- getPaymentDispute : retrieves detailed information about a specific payment dispute
- acceptPaymentDispute : accepts a payment dispute and can supply a return address if a buyer refund is dependent on the buyer returning the item
- uploadEvidenceFile : this method uploads an image file that will serve as ‘evidence’ if the seller wishes to contest the payment dispute
- contestPaymentDispute : this method is used if seller wishes to contest the payment dispute; this method is only used after one or more evidence
Once a seller receives a third-party payment dispute, they can accept the dispute (and possibly a return request) and issue a refund, or they can contest the dispute. There are payment dispute methods for the seller to accept, contest, and provide evidential files if they do contest.
In July 2020, the GetAccount call in Trading API was enhanced to separate out all fees and credits that have already been settled (through deduction of fees from the seller’s payouts), and all fees and credits payable through a monthly invoice. An AccountEntry.Netted boolean field was added to indicate whether or not each fee/credit has already been settled, and an AccountSummary.NettedTransactionSummary container is also returned to indicate the total amount of fees and the total amount of credits that have already been settled for the specified invoice or time period in the call request. In order to retrieve these fields in the response, the IncludeNettedEntries boolean field must be included in the request and set to true.
Sellers can log in to Seller Hub to schedule their payout at a frequency they choose (daily as funds are available, or weekly).
|NOTE||APIs do not support changes to payout frequency.|
For managed payments sellers, eBay selling fees will be automatically deducted from seller earnings at the time of sale.The new final value fee is a percentage of the total sales amount that varies by category, plus a fixed $0.30 per order. The final value fee is assessed per line item and calculated on the total amount of the sale, inclusive of tax, shipping or handling, and any other applicable fees. The old final value fee was calculated on the total amount of the sale, excluding tax. With the old final value fee, sellers also paid a separate payments processing fee to a third-party based on the total amount of the sale, including tax.
See Simpler fees page for more information on how selling fees are handled for managed payments sellers. The Selling fees for managed payments sellers page provides a little more detail on fees, including the different final value fee percentages for various eBay categories.
The getTransactions method of the Finances API returns fees that will be deducted from the seller payouts. These fields are summarized below. Note that you will have to search for ‘
SALE’ transaction types for the following fields to be returned.
- transactions.orderLineItems.feeBasisAmount: this container shows the total cost (to the buyer) for the line item, and this cost includes sale price, shipping cost, sales tax, and any other applicable fees. The final value fee for the line item is based on the cost in this field.
- transactions.orderLineItems.marketplaceFees: this container shows the amount and type of each fee associated with an order line item, and these fees will be deducted from the seller payout associated with the order. Keep in mind that for orders with multiple line items, only one line item in that order will show the ‘
FINAL_VALUE_FEE_FIXED_PER_ORDER’ fee (in the orderLineItems.marketplaceFees.feeType field), as this is an order-level charge. See the FeeTypeEnum type for the full list.of selling-related fees that may be deducted from a seller payout.
- transactions.totalFeeBasisAmount: this container shows the combined total of the orderLineItems.feeBasisAmount totals for all line items in the order. For single line item orders, this amount and the amount in orderLineItems.feeBasisAmount should be the same.
- transactions.totalFeeAmount: this container shows the total amount of fees associated with the order and deducted from the seller payout associated with the order.
Please note some key differences between the methods in the Fulfillment and Finances APIs:
- The getOrder/getOrders methods of the Fulfillment API only return a totalFeeBasisAmount container, which shows the cumulative total cost of all line items in the order on which final value fees are based.
- The getTransactions method of the Finances API retrieves the breakdown of all fees deducted from the seller payout associated with an order.
- The getOrder/getOrders methods of the Fulfillment API return tax information related to orders, but the getTransactions method of the Finances API does not return tax information
Managed payments-related fees and credits can also be retrieved from the GetAccount call in the Trading API. See the Recognizing managed payments fees/credits in GetAccount section for more details.
In the event of an order cancellation, an order return, or a buyer-initiated case or dispute won by the buyer, the buyer will receive a full refund. In some cases, this refund will be issued by the seller, but in other cases, eBay will issue the order refund to the buyer and then seek reimbursement from the seller. Details related to the seller’s reimbursement (or other charges) can be retrieved with the new getTransfer method of the Finances API. The getTransfer method returns the following information:
- The amount of the reimbursement or charge.
- The timestamp for the reimbursement.
- The seller payment method (could come from available payout fund balance, bank account, or credit card)
- Itemized list of the expenses associated with the reimbursement, as it is possible that charges may be aggregated and settled in a single reimbursement.
- details on the seller payment method used to fund buyer refunds
- the 'net' amount charged to the seller for refunds
- the fees that may be credited to the seller towards a refund as per eBay policy
Currency conversion is now enabled in the Finances and Post-Order APIs. This enhancement allows managed payments sellers to list and sell on eBay sites other than the seller’s registration site. To list on another eBay site, a managed payments seller must agree to the User Agreement and policies of the other site. Selling policies of individual eBay sites can be found on the International selling policy help page.
|NOTE||Integrated international selling only supports listings in eligible corridors. If sellers try to list in an ineligible corridor, the listing will be blocked and error will be returned.|
If sellers list an item outside their home eBay marketplace, and use the Add/Revise/Relist/Verify calls of the Trading API to do so, all listing fees returned under the Fees container of those responses will be in the currency of the listing marketplace, and not in the seller’s billing currency.
To enable the Finances API with this capability, a convertedFromCurrency, a convertedFromValue, and an exchangeRate field was added to the Amount type in the Finances API. These three new fields will only be returned if eBay performed a currency conversion due to an international sale.
If a currency conversion does occur, the existing value and currency fields (of Amount type) will show the amount in the seller’s default currency. The convertedFromValue and convertedFromCurrency fields will show the amount in the listing site’s default currency, and the exchangeRate field will show the currency exchange rate used to do the currency conversion.
To enable the same feature in Post-Order API, the exchangeRate field was added to the Amount type in the Post-Order API. The exchangeRate field and the ‘converted from’ fields are only returned when eBay does currency conversion.
Upcoming features (October 2020 and beyond)
- Additional seller-related fee types will be deducted from seller payouts, including insertion fees, listing upgrades, and subscription fees.
- New transaction type will be added to the Finances API to allow sellers to retrieve non-sales related fee data with the getTransactionsand getTransactionSummary methods.
- Additional features will be added to the Payments tab of Seller Hub, including the option for sellers to set up a seller payout reserve balance that can be used to fund the purchase of shipping labels, buyer refunds, or fees. Go to the Managed payments page on Seller Center to get the latest information on Seller Hub enhancements. Please note that the two features above are not currently on any roadmap to add to the APIs.
What you can do now to prepare
- Ensure you are regularly checking this page for managed payments updates and reading other referenced documentation so you will be more familiar with managed payments APIs and capabilities once you are onboarded.
- As soon as you discover you are eligible to onboard, be sure to complete the necessary onboarding steps.
- Be ready to use and integrate with the new API capabilities as they roll out. This will ensure a seamless transition for both you and our shared customers.
Additional resources on managed payments
The links below offer additional, non-API related information on managed payments:
- eBay Managed Payments Overview
- Seller Center - Managed Payments on eBay
- 2020 Fall Seller Updates - Managed Payments
- 2020 Spring Seller Updates - Managed Payments
- Handling payment disputes as a managed payments seller
- Updating your personal details
- Updating your bank account details
- Selling fees for managed payments sellers
- Store selling fees for managed payments sellers
- Restricted items policy for managed payments (US)
- Restricted items policy for managed payments (DE)
Frequently asked questions about managed payments
The FAQs in this section address some general questions and some API-related questions about eBay managed payments.
What if I didn't complete the managed payments registration process by July 15?
If you were notified but did not complete managed payments registration by July 15, you may be blocked from creating new listings. For more information on how to register for managed payments, go to Seller Hub, or use the getPaymentsProgramOnboarding method of the Account API.
How do sellers enable their accounts for managed payments?
There is a multiple-step onboarding process for managed payments in which sellers submit ownership and bank account details. eBay will generally notify a seller when he/she is eligible to start the onboarding process. Sellers can also use the getPaymentsProgramOnboarding method of the Account API to check their onboarding status. If a seller is eligible to start the onboarding process, this API provides a direct link to a page where they can begin or resume the onboarding process.
How can I tell if my account is enabled for managed payments?
You can use the getPaymentsProgram method in the Account API to determine a seller's status with regards to managed payments. The getPaymentsProgramOnboarding method of the Account API provides even more details about onboarding status, and even provides a direct link to a page where they can begin the onboarding process.
I'm interested in starting on managed payments, but I have yet to receive an onboarding invitation. Is there anything I can do to expedite the process?
Go to the Interested in managed payments? survey page (requires login), and fill out the survey to express your interest in managed payments.
Please note that filling out the survey does not guarantee your account will be expedited for enrollment in managed payments. However, it does signal to eBay that you are interested in the program.
Once my selling account is enabled for managed payments, do I need to revise my existing listings?
No. Once a seller's account is enabled for managed payments, existing listings are automatically migrated to the new experience, including the available payment methods that are managed by eBay for each marketplace.
Does managed payments support listings in all eBay categories?
The managed payments program supports listing in most eBay categories. However, there are currently some categories that are exempted from the program, including motor vehicle categories (P&A categories are supported), coins and paper money, Adult only categories, travel tickets, and event tickets. For a complete list, see the Managed payments restricted items policy help topic. If you have listings in these categories when your account is onboarded for managed payments, these listings will be ended and any listing fees will be refunded.
Will listings supporting charities be supported (for sellers using managed payments) in the near future?
Not at this time, but this feature is expected to be enabled for managed payments sellers beginning in late July 2020. Both the AddItem call of the Trading API and the createOffer method of the Inventory API support the creation of charitable listings. There is also a new REST-based Charity API that can be used to search for charitable organizations on eBay’s platform. At listing time, the eBay-assigned, unique identifier of the charitable organization is required, and the getCharityOrg and getCharityOrgs methods retrieve these IDs. See the eBay for Charity home page for detailed information on charitable giving on eBay.
Is the Global Shipping Program available to sellers using managed payments?
Yes, this feature just recently became available to sellers using managed payments. If you are unfamiliar with how the Global Shipping Program works, and you are interested in shipping internationally, go to the Global Shipping Program page on the Seller Center for more information.
Is there a public API to manage seller payouts?
Yes, the Finances API provides many of the same capabilities available under the Payments tab in Seller Hub, including retrieving detailed seller payout information. See the Retrieving seller payout information with Finances API section for more details on the Finances API.
How are my seller fees affected with managed payments?
With eBay managing your payments, your fees are paid to eBay. See Selling fees for managed payments sellers for more information
What will the managed payments experience be like for my buyers?
The buying experience will be improved with managed payments, because the buyer will have more payment options, including Apple Pay and Google Pay if those buyers are equipped to use those payment methods and they are checking out with a mobile device. In addition, PayPal is also still supported as a payment method, but will no longer handle the buyer’s payment.
Are buyer refunds handled differently with managed payments orders?
The biggest difference with buyer refunds in managed payments is that eBay will refund the buyer (instead of the seller), and then debit the seller’s account to reconcile that money. The seller can initiate the issuing of a buyer refund in My eBay, or they can use the new issueRefund method of the Fulfillment API. The issueRefund method should not be used if one or more line items in the order has an open “Item not Received” (INR) inquiry, an open return request, or an eBay Buyer Protection case filed against it. Instead, these three issues need to be resolved in My eBay or the eBay Resolution Center, or the appropriate issue refund method (there’s one for inquiries, cases, and returns) in the Post-Order API can be used. For cancellation requests (order or line item level), the seller can use the issueRefund method of the Fulfillment API and should just specify a value of
BUYER_CANCEL in the reasonForRefund field.
Please note that the Post-Order API is fully compatible with managed payments orders, so you can continue to use this API if you are already integrated.