account APIv1.4.0

getPaymentPolicy

GET
/payment_policy/{payment_policy_id}
This method retrieves the complete details of a payment policy. Supply the ID of the policy you want to retrieve using the paymentPolicyId path parameter.

Input

Resource URI (production)

GET https://api.ebay.com/sell/account/v1/payment_policy/{payment_policy_id}

URI parameters

ParameterTypeDescription
payment_policy_idstringThis path parameter specifies the ID of the payment policy 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 or more scopes from the following list (please check your Application Keys page for a list of OAuth scopes available to your application):

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

Output container/fieldTypeDescription
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

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

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

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

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

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

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

Occurrence: Conditional

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

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

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

deposit.paymentMethodsarray of PaymentMethodRequired if your motor vehicles listing requires a deposit.

For deposits (which are applicable to only motor listings), the paymentMethodType must be set to 'PAYPAL' and you must also populate the fields in the recipientAccountReference object.

Occurrence: Conditional

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

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

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

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

Occurrence: Conditional

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

Occurrence: Conditional

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

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

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

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

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

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

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

Max length: 64

Occurrence: Required

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

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).

Note that 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

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

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

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

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

Occurrence: Conditional

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

Occurrence: Conditional

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

Occurrence: Required

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
404Not Found
500Internal Server Error

Error codes

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

CodeDomainCategoryMeaning
20403API_ACCOUNTREQUESTInvalid {fieldName}. {additionalInfo}
20404API_ACCOUNTREQUEST{fieldName} not found.
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 a payment policy by ID

This example retrieves a payment policy by the policy's unique eBay-assigned ID.

Input

Specify the policy you want to get using the paymentPolicyId path parameter. This call does not use a request payload.
GET
https://api.sandbox.ebay.com/sell/account/v1/payment_policy/5486492000

Output

A successful call returns an HTTP status code of 200 OK and a response body containing the specified payment policy.