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 instead of to their PayPal accounts.
|NOTE||eBay managed payments is currently available to a limited number of sellers on the eBay marketplace in the US and Germany. 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. We expect most sellers around the world to have transitioned into managed payments by the end of 2021.|
Quick overview of APIs supporting eBay managed payments
The list below provides a quick 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.
- Finances API: this new API is used to retrieve seller payout information, and provides an API solution to some of the other capabilities offered through the Payments tab of Seller Hub
- Fulfillment API
- The new issueRefund method allows a managed payments seller to voluntarily issue a refund to the buyer
- The new 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
- Post-Order API: details on the seller payment instrument used to fund buyer refunds will be returned in the getCancellation, getInquiry, getCase, and getReturn methods
- Trading API
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
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 to the seller that the payment methods were dropped. 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.
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 SOAP 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.
- 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 Post-Order API 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.
The GetAccount call of the Trading API can be used by a seller to retrieve all fees and credits on a monthly invoice or during a specified date range, including managed payments-related fees and credits. A few of the current fees and credits related to managed payments are highlighted below. These fee enums are returned in the AccountEntry.AccountDetailsEntryType field of the GetAccount response:
PaymentIntermediationFee: the payment processing fee, formerly charged by PayPal, is now charged to managed payments sellers. The upcoming restructuring (July 2020) removes this fee and contains a new final value fee rate structure
UspsLabelFeeCredit: fees/credits to handle use case where eBay invoices the seller for a USPS shipping label instead of the seller paying for with PayPal account
UspsShortpaidFeeCredit: fees/credits to handle use case where the purchased USPS shipping label does not cover the actual cost to ship a package
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.|
Upcoming features for July release
Below is a summary of changes expected to roll out in July 2020:
- Final value fees deducted from seller payouts: instead of billing the final value fee for each sale to the seller’s monthly invoice, eBay will start deducting applicable fees from the order total when the order is created, before the order proceeds are distributed to the seller’s bank account via a seller payout. See Selling fees for managed payments sellers for more information, including the different final value fee percentage and fixed rates charged for the various eBay categories.
- Finances API updates:
- To support this change of collecting the final value fee upfront and deducting this from the seller’s payout, the Finances API will be enhanced to show gross revenue, total fee amount, and net revenue at the order level, and will also show the itemized fees at the line item level
- A new field will be added to indicate the eBay payments entity that is processing a buyer’s payment.
- Fulfillment API Updates: detailed information on electronic waste and mattress recycling fees will be returned (when applicable) for getOrder/getOrders.
- Trading API updates: the GetAccount call in Trading API will be 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. A boolean field will be added at the AccountEntry level to indicate whether or not each fee/credit has already been settled. In addition to this boolean field, a container will also be returned at the AccountSummary level to indicate the total amount of fees and total amount of credits that have already been settled for the specified time period in the call request. The GetAccount call can retrieve the last invoice, a specified invoice from prior months, or a custom date range can be entered.
- Account API: a new endpoint will be added to the Account API that will inform sellers if they need to take any action to keep their account in good standing under KYC (“Know your customer”) laws.
- Post-Order API: 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, a bank account or credit card on file, or seller can be billed in monthly invoice.
Upcoming features (fall 2020 and later)
- Additional seller-related fee types will be deducted from seller payouts instead of being charged to the seller’s monthly invoice
- The Finances API will be enhanced with a currency conversion capability to support cross-border transactions. For example, if a US buyer buys an item on the UK site, it will show converted costs/fees in USD and GBP.
- Additional features will be added to the Payments tab of Seller Hub, including the ability for sellers to choose between daily and weekly seller payouts, 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 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.
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.