account APIv1.4.0

getPaymentPolicies

GET
/payment_policy/
This method retrieves all the payment policies configured for the marketplace you specify using the marketplace_id query parameter.

Marketplaces and locales

Get the correct policies for a marketplace that supports multiple locales using the Content-Language request header. For example, get the policies for the French locale of the Canadian marketplace by specifying fr-CA for the Content-Language header. Likewise, target the Dutch locale of the Belgium marketplace by setting Content-Language: fr-BE. For details on header values, see HTTP request headers.

Input

Resource URI (production)

GET https://api.ebay.com/sell/account/v1/payment_policy/?

URI parameters

ParameterTypeDescription
marketplace_idMarketplaceIdEnumThis query parameter specifies the eBay marketplace of the policies you want to retrieve.

Occurrence: Required

HTTP request headers

All requests made to eBay REST operations require you to provide the Authorization HTTP header for authentication authorization.

OAuth scope

This request requires an access token created with the authorization code grant flow, using one scope from the following list:

https://api.ebay.com/oauth/api_scope/sell.account

https://api.ebay.com/oauth/api_scope/sell.account.readonly

See OAuth access tokens for more information.

Output

HTTP response headers

{ /* PaymentPolicyResponse */
"href" : "string",
"limit" : "integer",
"next" : "string",
"paymentPolicies" : [],
"prev" : "string",
}
Output container/fieldTypeDescription
hrefstringReturns a URL link to the current result set.

Occurrence: Conditional

limitintegerReturns the maximum number of results that can be returned in result set.

Occurrence: Conditional

nextstringReturns a URL link to the next set of results.

Occurrence: Conditional

offsetintegerReturns how many result sets were skipped before the currently returned result set.

Occurrence: Conditional

paymentPoliciesarray of PaymentPolicyA list of the seller's payment policies.

Occurrence: Conditional

paymentPolicies.categoryTypesarray of CategoryTypeThe CategoryTypeEnum value to which this policy applies. Used to discern accounts that sell motor vehicles from those that don't. (Currently, each policy can be set to only one categoryTypes value at a time.)

Occurrence: Always

paymentPolicies.categoryTypes.defaultbooleanSellers can create multiple policies for any marketplaceId and categoryTypes.name combination. For example, you can create multiple fulfillment policies for one marketplace, where they all target the same category type name. However, only one policy can be the default for any marketplaceId and name combination, and eBay designates the first policy created for a combination as the default.

If set to true, this policy is the default policy for the associated categoryTypes.name and marketplaceId pair.

Note: eBay considers the status of this field only when you create listings through the Web flow. If you create listings using the APIs, you must specifically set the policies you want applied to a listing in the payload of the call you use to create the listing. If you use the Web flow to create item listings, eBay uses the default policy for the marketplace and category type specified, unless you override the default.

For more on default policies, see Changing the default policy for a category type.

Occurrence: Always

paymentPolicies.categoryTypes.nameCategoryTypeEnumThe category type to which the policy applies (motor vehicles or non-motor vehicles).

Note for return policies: The 'MOTORS_VEHICLES' category type is not valid for return policies because eBay flows do not support the return of motor vehicles.

Occurrence: Always

paymentPolicies.depositDepositThis container is applicable only if the categoryTypes.name field is set to MOTORS_VEHICLES. In this case, sellers can use this field to specify amounts and due dates for deposits for motor vehicle listings on eBay Motors.

The deposit amount appears in the shipping, payment details, and return policy sections of the View Item page.

Note: Deposits on motor vehicles can only be paid using PayPal, so if you specify a deposit amount, then you must set the paymetMethodType value to 'PayPal' (and you must not set deposit.paymentMethods.brands field). Because of this, the seller needs to have a linked PayPal account in order to require a deposit from the buyer. Also note that paymetMethodType is not automatically set to PayPal for deposits, even if the seller has PayPal set in their My eBay preferences.

In addition to setting the paymentMethods for deposits, be sure to also set paymentMethods for the final payment amount.

Occurrence: Conditional

paymentPolicies.deposit.amountAmountDeposits are used only with Motors listings and the amount value indicates the initial deposit that a buyer must make to purchase a motor vehicle. The deposit amount can be as high as $2,000.00 and if an amount is not specified, this value defaults to '0.0'. If the seller specifies a deposit amount, they must also specify an hoursToDeposit value.

Deposits on motor vehicles can only be paid using PayPal, so if you specify a deposit amount, then you must also set the paymetMethodType value to 'PayPal'. Unlike other listings, PayPal is not automatically added to a Motors listing even if the seller has a PayPal preference set in My eBay. Because of these requirements, the seller must have a linked PayPal account in order to require a deposit.

The deposit amount appears in the shipping, payment details and return policy section of the View Item page.

Min: 0.0, Max: 2000.0, Default: 0.0

Occurrence: Conditional

paymentPolicies.deposit.amount.currencyCurrencyCodeEnumThe base currency applied to the value field to establish a monetary amount. The currency is represented as a 3-letter ISO4217 currency code. For example, the code for the Canadian Dollar is CAD.

Occurrence: Conditional

paymentPolicies.deposit.amount.valuestringThe value of the monetary amount in the specified currency.

Occurrence: Conditional

paymentPolicies.deposit.dueInTimeDurationThis value indicates the number of hours the buyer has (after they commit to buy) to make an initial deposit to the seller as a down payment on a motor vehicle. Valid values are '24 HOUR', '48 HOUR' (default), and '72 HOUR'.

The deposit amount is specified in the deposit.amount field. If not specified, the deposit amount value defaults to '0.0', in which case, a deposit on the vehicle is not required.

In order for a buyer to make an initial deposit on a US or CA motor vehicle, you must set a paymetMethodType value to 'PayPal' (in addition to the payment methods offered for the full payment).

Min=24 (hours), Max=72 (hours), Default=48 )hours)

Occurrence: Conditional

paymentPolicies.deposit.dueIn.unitTimeDurationUnitEnumRequired in the TimeDuration container.

A time-measurement unit used to specify a period of time.

Time-measurement units can be years, months, days, hours, minutes, and other time units (see TimeDurationUnitEnum for a complete list of possible units). The unit is applied to the number in the value field to define a span of time. See the containing object for details and call GeteBayDetails in the Trading API to get the allowable values for the specific object you're configuring.

Occurrence: Conditional

paymentPolicies.deposit.dueIn.valueintegerRequired in the TimeDuration container.

An amount of time, as measured by the time-measurement units specified in the unit field.

Supported values for this field vary according to the object using the time duration. See the containing object for details and call GeteBayDetails in the Trading API to get the allowable values for the specific object you're configuring.

Occurrence: Conditional

paymentPolicies.deposit.paymentMethodsarray of PaymentMethodA list of accepted payment methods. For deposits (which are applicable to only motor listings), the paymentMethodType must be set to 'PAYPAL'.

Occurrence: Conditional

paymentPolicies.deposit.paymentMethods.brandsarray of PaymentInstrumentBrandEnumRequired if paymentMethodType is set to CREDIT_CARD.

A list of credit card brands accepted by the seller.

It's important to note that the credit card brands Visa and MasterCard must both be listed if either one is listed, as is shown in the following code fragment:

"paymentMethods": [{ "brands": [VISA, MASTERCARD] }] ...

Note: Different eBay marketplaces may or may not support this field.

Use the Trading API GetCategoryFeatures call with FeatureID set to PaymentMethods and DetailLevel set to ReturnAll to see what credit card brands different marketplaces support. If the GetCategoryFeatures call returns details on credit card brands for the categories in which you sell, then you can use this field to list the credit card brands the seller accepts. If, on the other hand, GetCategoryFeatures does not enumerate credit card brands for your target site (for example, if it returns PaymentMethod set to CCAccepted), then you cannot enumerate specific credit card brands with this field for that marketplace.

Occurrence: Conditional

paymentPolicies.deposit.paymentMethods.paymentMethodTypePaymentMethodTypeEnumThe payment method, selected from the supported payment method types.

Use GetCategoryFeatures in the Trading API to retrieve the payment methods allowed for a category on a specific marketplace, as well as the default payment method for that marketplace (review the SiteDefaults.PaymentMethod field). For example, the response from GetCategoryFeatures shows that on the US marketplace, most categories allow only electronic payments via credit cards, PayPal, and the like. Also, note that GeteBayDetails does not return payment method information.

Note: If you create item listings using the Inventory API, you must set this field to PAYPAL (currently, the Inventory API supports only fixed-prince GTC items where the only supported paymentMethod is PayPal).

Occurrence: Conditional

paymentPolicies.deposit.paymentMethods.recipientAccountReferenceRecipientAccountReferenceRequired if the payment method is set to PAYPAL.

This field contains information that eBay uses to identify the recipient's account to which electronic funds are sent and must contain the email address associated with the PayPal account selected by the seller.

eBay uses this information to identify the correct PayPal account when the buyer pays for an order using PayPal. (Because it's possible to have more than a single PayPal account, eBay cannot rely on account data returned by GetUser for determining the correct PayPal eddress.)

Occurrence: Conditional

paymentPolicies.deposit.paymentMethods.recipientAccountReference.referenceIdstringContains the PayPal email address of the recipient (buyer) if referenceType is set to PAYPAL_EMAIL.

Occurrence: Conditional

paymentPolicies.deposit.paymentMethods.recipientAccountReference.referenceTypeRecipientAccountReferenceTypeEnumA reference a recipient's account. Currently only PAYPAL_EMAIL is valid.

Occurrence: Conditional

paymentPolicies.descriptionstringAn optional seller-defined description of the payment policy for internal use (this value is not displayed to end users).

Max length: 250

Occurrence: Conditional

paymentPolicies.fullPaymentDueInTimeDurationThis field applies to motor vehicles listings only and indicates when a final payment for the vehicle is due. This value is always returned if categoryTypes is set to MOTORS_VEHICLES.

This seller-specified value indicates the number of days that a buyer has to make their full payment to the seller and close the remaining balance on a motor vehicle transaction. The period starts when the buyer commits to buy. The valid values, as specified with TimeDuration, are:
  • 3 DAYS
  • 7 DAYS (the default)
  • 10 DAYS
  • 14 DAYS
For motor vehicles sales (where categoryTypes.name is set to MOTORS_VEHICLES), the payment policy must specify at least one of the following paymentMethods values for the final payment:
  • CASH_ON_PICKUP
  • CASHIER_CHECK
  • LOAN_CHECK
  • MONEY_ORDER
  • PAYPAL
  • PERSONAL_CHECK
Default: 7 DAYS (Note that this value is supported by a compound type.)

Occurrence: Conditional

paymentPolicies.fullPaymentDueIn.unitTimeDurationUnitEnumRequired in the TimeDuration container.

A time-measurement unit used to specify a period of time.

Time-measurement units can be years, months, days, hours, minutes, and other time units (see TimeDurationUnitEnum for a complete list of possible units). The unit is applied to the number in the value field to define a span of time. See the containing object for details and call GeteBayDetails in the Trading API to get the allowable values for the specific object you're configuring.

Occurrence: Conditional

paymentPolicies.fullPaymentDueIn.valueintegerRequired in the TimeDuration container.

An amount of time, as measured by the time-measurement units specified in the unit field.

Supported values for this field vary according to the object using the time duration. See the containing object for details and call GeteBayDetails in the Trading API to get the allowable values for the specific object you're configuring.

Occurrence: Conditional

paymentPolicies.immediatePaybooleanIf set to true, payment is due upon receipt (eBay generates a receipt when the buyer agrees to purchase an item).

This boolean must be set in the payment policy if the seller wants to create a listing that has an "immediate payment" requirement. The seller can change the immediate payment requirement at any time during the life cycle of a listing.

The following must be true before a seller can apply an immediate payment requirement to an item:
  • The seller must have a PayPal Business account.
  • The Buy It Now price cannot be higher than $60,000 USD.
  • The eBay marketplace on which the item is listed must support PayPal payments.
  • The listing type must be fixed-price, or an auction with a Buy It Now option.
To enable the immediate payment requirement, the seller must also perform the following actions via API calls:
  • Provide a valid paymentMethods.recipientAccountReference.referenceId value.
  • Offer PayPal as the only payment method for the item(s).
  • Specify all related costs to the buyer (because the buyer is not be able to use the Buyer Request Total feature in an immediate payment listing); these costs include flat-rate shipping costs for each domestic and international shipping service offered, package handling costs, and any shipping surcharges.
  • Include and set the shippingProfileDiscountInfo container values if you are going to use promotional shipping discounts.
For more information, see the Understanding immediate payment Help page.

Note: Listings created with the Inventory API must reference a payment policy that has immediatePay is set to true. Items listed with the Inventory API must also be fixed-price good-till-canceled (GTC) listings where PayPal is the only supported payment method (paymentMethod must be set to PAYPAL).Default: false

Occurrence: Always

paymentPolicies.marketplaceIdMarketplaceIdEnumThe ID of the eBay marketplace to which the payment policy applies. If this value is not specified, value defaults to the seller's eBay registration site.

Occurrence: Required

paymentPolicies.namestringA user-defined name for this payment policy. Names must be unique for policies assigned to the same marketplace.

Max length: 64

Occurrence: Required

paymentPolicies.paymentInstructionsstringThis free-form string field gives sellers the ability add detailed payment instructions to their listings. The payment instructions appear on eBay's View Item and Checkout pages.

eBay recommends sellers use this field to clarify payment policies for motor vehicle listings on eBay Motors. For example, sellers can include the specifics on the deposit (if required), pickup/delivery arrangements, and full payment details on the vehicle.

The field allows only 500 characters as input, but due to the way the eBay web site UI treats characters, this field can return more than 500 characters in the response. For example, characters like & and ' (ampersand and single quote) count as 5 characters each.

Max length: 1000.

Occurrence: Conditional

paymentPolicies.paymentMethodsarray of PaymentMethodA list of the payment methods accepted by the seller. Each payment policy must specify at least one payment method.

Note: Each eBay marketplace supports and requires its own set of payment methods, and not all marketplaces allow all payment methods. Check the specifics of the marketplaces where you list items to ensure your payment policies meet the payment method requirements needed for any specific listing. Note: Item listings created with the Inventory API must reference a payment policy that has this value set to PAYPAL (currently, the Inventory API supports only fixed-prince GTC items with immediate pay (which required payments to be made via PayPal). Payment policies used with motor vehicle listings that require a deposit must have PayPal listed has a payment method (deposits require PayPal as the payment method). Also, in order for a buyer to make a full payment on a US or CA motor vehicle, the payment policy must specify at least one of the following as a payment method:
  • CashOnPickup
  • LoanCheck
  • MOCC (money order or cashier's check)
  • PaymentSeeDescription (payment instructions are in the paymentInstructions field)
  • PersonalCheck

Occurrence: Always

paymentPolicies.paymentMethods.brandsarray of PaymentInstrumentBrandEnumRequired if paymentMethodType is set to CREDIT_CARD.

A list of credit card brands accepted by the seller.

It's important to note that the credit card brands Visa and MasterCard must both be listed if either one is listed, as is shown in the following code fragment:

"paymentMethods": [{ "brands": [VISA, MASTERCARD] }] ...

Note: Different eBay marketplaces may or may not support this field.

Use the Trading API GetCategoryFeatures call with FeatureID set to PaymentMethods and DetailLevel set to ReturnAll to see what credit card brands different marketplaces support. If the GetCategoryFeatures call returns details on credit card brands for the categories in which you sell, then you can use this field to list the credit card brands the seller accepts. If, on the other hand, GetCategoryFeatures does not enumerate credit card brands for your target site (for example, if it returns PaymentMethod set to CCAccepted), then you cannot enumerate specific credit card brands with this field for that marketplace.

Occurrence: Conditional

paymentPolicies.paymentMethods.paymentMethodTypePaymentMethodTypeEnumThe payment method, selected from the supported payment method types.

Use GetCategoryFeatures in the Trading API to retrieve the payment methods allowed for a category on a specific marketplace, as well as the default payment method for that marketplace (review the SiteDefaults.PaymentMethod field). For example, the response from GetCategoryFeatures shows that on the US marketplace, most categories allow only electronic payments via credit cards, PayPal, and the like. Also, note that GeteBayDetails does not return payment method information.

Note: If you create item listings using the Inventory API, you must set this field to PAYPAL (currently, the Inventory API supports only fixed-prince GTC items where the only supported paymentMethod is PayPal).

Occurrence: Conditional

paymentPolicies.paymentMethods.recipientAccountReferenceRecipientAccountReferenceRequired if the payment method is set to PAYPAL.

This field contains information that eBay uses to identify the recipient's account to which electronic funds are sent and must contain the email address associated with the PayPal account selected by the seller.

eBay uses this information to identify the correct PayPal account when the buyer pays for an order using PayPal. (Because it's possible to have more than a single PayPal account, eBay cannot rely on account data returned by GetUser for determining the correct PayPal eddress.)

Occurrence: Conditional

paymentPolicies.paymentMethods.recipientAccountReference.referenceIdstringContains the PayPal email address of the recipient (buyer) if referenceType is set to PAYPAL_EMAIL.

Occurrence: Conditional

paymentPolicies.paymentMethods.recipientAccountReference.referenceTypeRecipientAccountReferenceTypeEnumA reference a recipient's account. Currently only PAYPAL_EMAIL is valid.

Occurrence: Conditional

paymentPolicies.paymentPolicyIdstringA unique eBay-assigned ID for a payment policy. This ID is generated when the policy is created.

Occurrence: Required

prevstringReturns a URL link to the previous set of results.

Occurrence: Conditional

totalintegerReturns the total number of result sets in the paginated collection.

Occurrence: Conditional

HTTP status codes

This call can return one of the following HTTP status codes. For an overview of the status codes, see HTTP status codes in Using eBay RESTful APIs.

StatusMeaning
200Success
400Bad Request
500Internal Server Error

Error codes

For more on errors, plus the codes of other common errors, see Handling errors.

CodeDomainCategoryMeaning
20401API_ACCOUNTREQUESTMissing field {fieldName}. {additionalInfo}
20403API_ACCOUNTREQUESTInvalid {fieldName}. {additionalInfo}
20500API_ACCOUNTAPPLICATIONSystem error.
20501API_ACCOUNTAPPLICATIONService unavailable. Please try again in next 24 hours.

Samples

New to making API calls? Please see Making a Call.

Note: Identifiers, such as order IDs or user IDs, and personal data in these samples might be anonymized or may no longer be active on eBay. If necessary, substitute current, relevant eBay data in your requests.

Sample 1: Get all Payment Policies

Sellers can create one or more payment policies for a particular marketplace. This call returns all the current payment policies for the specified marketplace.

Input

Specify the marketplace for the policies you want to retrieve useing the marketplace_id query parameter.
GET
https://api.sandbox.ebay.com/sell/account/v1/payment_policy?marketplace_id=EBAY_US

Output

If the call is successful, eBay returns an HTTP status code of 200 OK and a complete list of the payment policies associated with the specified marketplace.