account APIv1.6.0

updatePaymentPolicy

PUT
/payment_policy/{payment_policy_id}
This method updates an existing payment policy. Specify the policy you want to update using the payment_policy_id path parameter. Supply a complete policy payload with the updates you want to make; this call overwrites the existing policy with the new details specified in the payload.

Input

Resource URI (production)

PUT 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 update.

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

See OAuth access tokens for more information.

Input container/fieldTypeDescription
categoryTypesarray of CategoryTypeThe CategoryTypeEnum value to which this policy applies. This container is used to discern accounts that sell motor vehicles from those that do not.

Restriction: Currently, each policy can be set to only one categoryTypes value at a time.

Occurrence: Required

categoryTypes.defaultbooleanSpecifies the default policy for a marketplaceId and categoryTypes.name pair. Sellers 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: Optional

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

Restrictions:
  • The MOTORS_VEHICLES category type is not valid for return policies. eBay flows do not support the return of motor vehicles.
  • Only the ALL_EXCLUDING_MOTORS_VEHICLES category type is supported for sellers who opt-in to the managed payments program. Managed payments does not currently support the sale of motor vehicles.

Occurrence: Required

depositDepositThe specified amounts and due dates for motor vehicle deposits on eBay Motors listings. The deposit amount appears in the shipping, payment details, and return policy sections of the View Item page.

Deposits on motor vehicles can only be paid using PayPal. If you specify a deposit amount, then you must set the paymentMethodType value to PayPal, and you must not set the deposit.paymentMethods.brands field.

The seller must have a linked PayPal account in order to require a deposit from the buyer.

Note: The paymentMethodType 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, you must also set the paymentMethods for the final payment amount.

Restrictions:
  • This container is applicable only if the categoryTypes.name field is set to MOTORS_VEHICLES.
  • This container is not supported for sellers who opt-in to the managed payments program. Managed payments does not currently support the sale of motor vehicles.

Occurrence: Optional

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 paymentMethodType 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: Optional

deposit.amount.currencyCurrencyCodeEnumThe base currency applied to the value field to establish a monetary amount.

The currency is represented as a 3-letter ISO 4217 currency code. For example, the code for the Canadian Dollar is CAD.

Default: The default currency of the eBay marketplace that hosts the listing.

Occurrence: Optional

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

Required in the amount type.

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 paymentMethodType value to 'PayPal' (in addition to the payment methods offered for the full payment).

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

Occurrence: Optional

deposit.dueIn.unitTimeDurationUnitEnumA time-measurement unit that specifies a singular period of time.

A span of time is defined when you apply the value specified in the value field to the value specified for unit.

Time-measurement units can be YEAR, MONTH, DAY, and so on. See TimeDurationUnitEnum for a complete list of possible time-measurement units.

Occurrence: Required

deposit.dueIn.valueintegerAn integer that represents an amount of time, as measured by the time-measurement unit specified in the unit field.

Occurrence: Required

deposit.paymentMethodsarray of PaymentMethodFor 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.

Required if your motor vehicles listing requires a deposit.

Occurrence: Conditional

deposit.paymentMethods.brandsarray of PaymentInstrumentBrandEnumIt'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.

Required if paymentMethodType is set to CREDIT_CARD.

A list of credit card brands accepted by the seller.

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: Optional

deposit.paymentMethods.recipientAccountReferenceRecipientAccountReferenceThis 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.)

Required if the payment method is set to PAYPAL.

Occurrence: Conditional

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

Occurrence: Optional

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

Occurrence: Optional

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

Max length: 250

Occurrence: Optional

fullPaymentDueInTimeDurationThe 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. This container applies to motor vehicles listings only and indicates when a final payment for the vehicle is due.

Note: This value is always returned if categoryTypes is set to MOTORS_VEHICLES.

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
In order for a buyer to make a full payment on a US or CA motor vehicle, at least one of the following paymentMethods values must be specified for the corresponding payment policy:
  • CASH_ON_PICKUP
  • CASHIER_CHECK
  • LOAN_CHECK
  • MONEY_ORDER
  • PAYPAL
  • PERSONAL_CHECK
Restriction: This container is not supported for sellers who opt-in to the managed payments program. Managed payments does not currently support the sale of motor vehicles.

Default: 7 DAYS (this value is supported by a compound type)

Occurrence: Optional

fullPaymentDueIn.unitTimeDurationUnitEnumA time-measurement unit that specifies a singular period of time.

A span of time is defined when you apply the value specified in the value field to the value specified for unit.

Time-measurement units can be YEAR, MONTH, DAY, and so on. See TimeDurationUnitEnum for a complete list of possible time-measurement units.

Occurrence: Required

fullPaymentDueIn.valueintegerAn integer that represents an amount of time, as measured by the time-measurement unit specified in the unit field.

Occurrence: Required

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.

Note: This container can be used for sellers who opt-in to the managed payments program, but some requirements do not apply.

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 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 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: Optional

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

Note: A limited number of sellers, on a limited number of eBay marketplaces, are currently opted-in to the eBay managed payments program. To view the eBay marketplaces where managed payments are currently supported, see the managed payments landing page.

Occurrence: Required

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

Note: eBay will create a new payment policy for sellers who opt-in to the managed payments program.

Max length: 64

Occurrence: Required

paymentInstructionsstringA free-form string field that allows sellers to 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.

Restriction: This container is not supported for sellers who opt-in to the managed payments program.

Max length: 1000

Occurrence: Optional

paymentMethodsarray of PaymentMethodA list of the payment methods accepted by the seller.

Important: Do not populate this container if you are opted-in to managed payments.

To verify whether or not you are opted-in to the managed payments program, call getPaymentsProgram.

If you are not opted-in to the managed payments program, each payment policy you create must specify at least one payment method.

In addition, if you are not opted-in to managed payments, the listings you create 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).

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

Note: Each eBay marketplace supports and requires its own set of payment methods and not all marketplaces support the same set of 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.

Occurrence: Conditional

paymentMethods.brandsarray of PaymentInstrumentBrandEnumIt'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.

Required if paymentMethodType is set to CREDIT_CARD.

A list of credit card brands accepted by the seller.

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: Optional

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

Required if the payment method is set to PAYPAL.

Occurrence: Conditional

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

Occurrence: Optional

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

Occurrence: Optional

Output

HTTP response headers

{ /* SetPaymentPolicyResponse */
"name" : "string",
}
Output container/fieldTypeDescription
categoryTypesarray of CategoryTypeThe CategoryTypeEnum value to which this policy applies. This container is used to discern accounts that sell motor vehicles from those that do not.

Restriction: Currently, each policy can be set to only one categoryTypes value at a time.

Occurrence: Always

categoryTypes.defaultbooleanSpecifies the default policy for a marketplaceId and categoryTypes.name pair. Sellers 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).

Restrictions:
  • The MOTORS_VEHICLES category type is not valid for return policies. eBay flows do not support the return of motor vehicles.
  • Only the ALL_EXCLUDING_MOTORS_VEHICLES category type is supported for sellers who opt-in to the managed payments program. Managed payments does not currently support the sale of motor vehicles.

Occurrence: Always

depositDepositThe specified amounts and due dates for motor vehicle deposits on eBay Motors listings. The deposit amount appears in the shipping, payment details, and return policy sections of the View Item page.

Restrictions:
  • This container is applicable only if the categoryTypes.name field is set to MOTORS_VEHICLES.
  • This container is not supported for sellers who opt-in to the managed payments program. Managed payments does not currently support the sale of motor vehicles.

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 paymentMethodType 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 ISO 4217 currency code. For example, the code for the Canadian Dollar is CAD.

Default: The default currency of the eBay marketplace that hosts the listing.

Occurrence: Conditional

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

Required in the amount type.

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 paymentMethodType 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.unitTimeDurationUnitEnumA time-measurement unit that specifies a singular period of time.

A span of time is defined when you apply the value specified in the value field to the value specified for unit.

Time-measurement units can be YEAR, MONTH, DAY, and so on. See TimeDurationUnitEnum for a complete list of possible time-measurement units.

Occurrence: Conditional

deposit.dueIn.valueintegerAn integer that represents an amount of time, as measured by the time-measurement unit specified in the unit field.

Occurrence: Conditional

deposit.paymentMethodsarray of PaymentMethodFor 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.

Required if your motor vehicles listing requires a deposit.

Occurrence: Conditional

deposit.paymentMethods.brandsarray of PaymentInstrumentBrandEnumIt'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.

Required if paymentMethodType is set to CREDIT_CARD.

A list of credit card brands accepted by the seller.

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

Required if the payment method is set to PAYPAL.

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

Occurrence: Conditional

fullPaymentDueInTimeDurationThe 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. This container applies to motor vehicles listings only and indicates when a final payment for the vehicle is due.

Note: This value is always returned if categoryTypes is set to MOTORS_VEHICLES.

Restriction: This container is not supported for sellers who opt-in to the managed payments program. Managed payments does not currently support the sale of motor vehicles.

Occurrence: Conditional

fullPaymentDueIn.unitTimeDurationUnitEnumA time-measurement unit that specifies a singular period of time.

A span of time is defined when you apply the value specified in the value field to the value specified for unit.

Time-measurement units can be YEAR, MONTH, DAY, and so on. See TimeDurationUnitEnum for a complete list of possible time-measurement units.

Occurrence: Conditional

fullPaymentDueIn.valueintegerAn integer that represents an amount of time, as measured by the time-measurement unit specified in the unit field.

Occurrence: Conditional

immediatePaybooleanIf set to true, payment is due upon receipt (eBay generates a receipt when the buyer agrees to purchase an item). The items will be available for other buyers until the payment is complete.

This boolean must be set in the payment policy if the seller wants to create a listing that has an immediate payment requirement.

Note: This container can be used for sellers who opt-in to the managed payments program, but some requirements do not apply.

Default: False

Occurrence: Always

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

Note: A limited number of sellers, on a limited number of eBay marketplaces, are currently opted-in to the eBay managed payments program. To view the eBay marketplaces where managed payments are currently supported, see the managed payments landing page.

Occurrence: Required

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

Note: eBay will create a new payment policy for sellers who opt-in to the managed payments program.

Max length: 64

Occurrence: Required

paymentInstructionsstringA free-form string field that allows sellers to 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.

Restriction: This container is not supported for sellers who opt-in to the managed payments program.

Max length: 1000

Occurrence: Conditional

paymentMethodsarray of PaymentMethodIf the seller is not opted-in to managed payments, this container returns a list of the payment methods accepted by the seller.

When not opted-in to managed payments, each payment policy must specify at least one payment method.

Note: The paymentMethods container is not returned if the seller is opted-in to the managed payments program.

Occurrence: Conditional

paymentMethods.brandsarray of PaymentInstrumentBrandEnumIt'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.

Required if paymentMethodType is set to CREDIT_CARD.

A list of credit card brands accepted by the seller.

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

Required if the payment method is set to PAYPAL.

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

warningsarray of ErrorDetailV3A list of warnings related to request. This field normally returns empty, which indicates the request did not generate any warnings.

Occurrence: Always

warnings.categorystringThe category type for this error or warning. It is a string that can have one of three values:
  • Application: Indicates an exception or error occurred in the application code or at runtime. Examples include catching an exception in a service's business logic, system failures, or request errors from a dependency.
  • Business: Used when your service or a dependent service refused to continue processing on the resource because of a business rule violation such as "Seller does not ship item to Antarctica" or "Buyer ineligible to purchase an alcoholic item". Business errors are not syntactical input errors.
  • Request: Used when there is anything wrong with the request, such as authentication, syntactical errors, rate limiting or missing headers, bad HTTP header values, and so on.

Occurrence: Conditional

warnings.domainstringName of the domain ,or primary system, of the service or application where the error occurred.

Occurrence: Conditional

warnings.errorIdintegerA positive integer that uniquely identifies the specific error condition that occurred. Your application can use error codes as identifiers in your customized error-handling algorithms.

Occurrence: Conditional

warnings.inputRefIdsarray of stringIdentifies specific request elements associated with the error, if any. inputRefId's response is format specific. For JSON, use JSONPath notation.

Occurrence: Conditional

warnings.longMessagestringA more detailed explanation of the error than given in the message error field.

Occurrence: Conditional

warnings.messagestringInformation on how to correct the problem, in the end user's terms and language where applicable. Its value is at most 50 characters long. If applicable, the value is localized in the end user's requested locale.

Occurrence: Conditional

warnings.outputRefIdsarray of stringIdentifies specific response elements associated with the error, if any. Path format is the same as inputRefId.

Occurrence: Conditional

warnings.parametersarray of ErrorParameterV3This optional list of name/value pairs that contain context-specific ErrorParameter objects, with each item in the list being a parameter (or input field name) that caused an error condition. Each ErrorParameter object consists of two fields, a name and a value.

Occurrence: Conditional

warnings.parameters.namestringName of the parameter that caused the error.

Occurrence: Conditional

warnings.parameters.valuestringThe value of the parameter that caused the error.

Occurrence: Conditional

warnings.subdomainstringIf present, indicates the subsystem in which the error occurred.

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
200OK
400Bad Request
404Not Found
500Internal Server Error

Error codes

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

CodeDomainCategoryMeaning
20400API_ACCOUNTREQUESTInvalid request. {additionalInfo}
20401API_ACCOUNTREQUESTMissing field {fieldName}. {additionalInfo}
20402API_ACCOUNTREQUESTInvalid input. {additionalInfo}
20403API_ACCOUNTREQUESTInvalid {fieldName}. {additionalInfo}
20404API_ACCOUNTREQUEST{fieldName} not found.
20405API_ACCOUNTREQUESTInvalid payment method. {fieldName}
20500API_ACCOUNTAPPLICATIONSystem error.
20501API_ACCOUNTAPPLICATIONService unavailable. Please try again in next 24 hours.

Warnings

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

CodeDomainCategoryMeaning
20200API_ACCOUNTBUSINESSWarning. {additionalInfo}

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: Update a Payment Policy

This example updates an existing payment policy.

Input

This example updates the categoryTypes field in a payment policy, changing it to be the default policy for the ALL_EXCLUDING_MOTORS_VEHICLES category. Note that when you make this update, eBay changes the default status of the existing default policy from true to false.

When updating an existing policy, be sure to provide the entire policy object in your request payload with the changes made to the fields that you want to update. To obtain the existing policy object, call getPaymentPolicy using the ID of the policy you want to update. Use this same policy ID value in the paymentPolicyId path parameter of the PUT request.

Note that you cannot update all the fields in the policy object; for example, you cannot update the policy ID value.
PUT
https://api.sandbox.ebay.com/sell/account/v1/payment_policy/5458323000

Output

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