account APIv1.4.0

createPaymentPolicy

POST
/payment_policy
This method creates a new payment policy where the policy encapsulates seller's terms for purchase payments.

Each policy targets a marketplaceId and categoryTypes.name combination and you can create multiple policies for each combination. Be aware that some marketplaces require a specific payment policy for vehicle listings.

A successful request returns the URI to the new policy in the Location response header and the ID for the new policy is returned in the response payload.

Tip: For details on creating and using the business policies supported by the Account API, see eBay business policies.

Marketplaces and locales

Policy instructions can be localized by providing a locale in the Accept-Language HTTP request header. For example, the following setting displays field values from the request body in German: Accept-Language: de-DE.

Target the specific locale of a marketplace that supports multiple locales using the Content-Language request header. For example, target the French locale of the Canadian marketplace by specifying the fr-CA locale for Content-Language. Likewise, target the Dutch locale of the Belgium marketplace by setting Content-Language: fr-BE.

Tip: For details on headers, see HTTP request headers.

Input

Resource URI (production)

POST https://api.ebay.com/sell/account/v1/payment_policy

URI parameters

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. 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: Required

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

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

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

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.

Default: The currency of the authenticated user's country.

Occurrence: Optional

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

Required in the amount container.

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

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
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
Default: 7 DAYS (Note that 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.
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: Optional

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

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

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

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

See HTTP response headers for details.

HeaderMeaning
LocationThe location response header contains the URL to the newly created payment policy. The URL includes the eBay-assigned paymentPolicyId, which you can use to reference the policy.
{ /* SetPaymentPolicyResponse */
"name" : "string",
}
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 on motor vehicle listings on eBay Motors.

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.

Default: The currency of the authenticated user's country.

Occurrence: Conditional

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

Required in the amount container.

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.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 policy for when final payment is due on invoiced items (in most cases, this payment policy applies to motor vehicles). This value is always returned if categoryTypes is set to MOTORS_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). Your items will be available for other buyers until 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.

Default: false

Occurrence: Always

marketplaceIdMarketplaceIdEnumThe ID of the eBay marketplace to which this 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: 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 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
201Created
400Bad Request
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}
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.

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: A skeleton payment policy

Sellers can create one or more payment policies, and each payment policy is specific to a marketplace and categoryType.name. You can set categoryType.name to one of two types, ALL_EXCLUDING_MOTORS_VEHICLES or MOTORS_VEHICLES.

While you can create multiple policies for each marketplace and categoryType.name combination, there can be only one default payment policy for any marketplace and categoryType.name combination. eBay assigns a default status to the first payment policy created for any marketplace and categoryType.name combination. Note that the default status comes into play only when you create item listings through the eBay Web flow, and you can set any payment policy to be the default using the Update a Payment Policy call.

Input

Provide, at a minimum, all required fields of the payment policy object in the request payload.
POST
https://api.sandbox.ebay.com/sell/account/v1/payment_policy

Output

If the call is successful, eBay returns an HTTP status code of 201 Created and and a payment policy resource with an ID for newly the created resource in the paymentPolicyId field. In addition, the full URL to the newly created resource is returned in the Location HTTP response header.

Sample 2: A detailed payment policy

This sample creates a more complete payment policy than the previous skeleton sample (which creates a basic policy using only the required input fields). This sample is for a categotyTypes set to ALL_EXCLUDING_MOTORS_VEHICLES and includes a couple of supported payment types.

Input

This example shows how to format a PayPal payment method, complete with the recipientAccountReference complex type, plus a complete list of accepted credit card brands.
POST
https://api.sandbox.ebay.com/sell/account/v1/payment_policy

Output

If the call is successful, eBay returns an HTTP status code of 201 Created and the complete payment policy with an ID for the newly created resource in the paymentPolicyId field. In addition, the full URL to the newly created resource is returned in the Location HTTP response header.

Sample 3: A motor vehicle payment policy

This sample creates a payment policy for motor vehicle sales (categotyTypes set to MOTORS_VEHICLES). The policy includes details on payment methods and deposits.

Input

In addition to the required input fields, this sample adds payment methods and due dates for the deposit and full payment.
POST
https://api.sandbox.ebay.com/sell/account/v1/payment_policy

Output

If the call is successful, eBay returns an HTTP status code of 201 Created and the complete payment policy resource, with an ID for the newly created resource in the paymentPolicyId field. In addition, the full URL to the newly created resource is returned in the Location HTTP response header.