POST/payment_policy
This method creates a new payment policy where the policy encapsulates seller's terms for order payments.
Each policy targets a specific eBay marketplace and category group, and you can create multiple policies for each combination.
A successful request returns the getPaymentPolicy 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.
Input
Resource URI
This method is supported in Sandbox environment. To access the endpoint, just replace the api.ebay.com root URI with api.sandbox.ebay.com
URI parameters
This method has no URI parameters.
HTTP request headers
All requests made to eBay REST operations require you to provide the Authorization HTTP header for authentication authorization.
The table below shows additional HTTP request headers that are either required, conditionally required, or strongly recommended for this method. Other standard HTTP request headers- opens rest request components page (not in this table) can also be used, but they are optional.
| Header | Type | Description |
|---|---|---|
| Content-Type | string | This header indicates the format of the request body provided by the client. Its value should be set to application/json. For more information, refer to HTTP request headers. Occurrence: Required |
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.
Request payload
Copy complete valid JSON to clipboardRequest fields
| Input container/field | Type | Description |
|---|---|---|
| categoryTypes | array of CategoryType | This container is used to specify whether the payment business policy applies to motor vehicle listings, or if it applies to non-motor vehicle listings. Occurrence: Required |
| categoryTypes.default | boolean | Note: This field has been deprecated and is no longer used. Occurrence: Optional |
| categoryTypes.name | CategoryTypeEnum | The category type to which the policy applies (motor vehicles or non-motor vehicles). Occurrence: Required |
| deposit | Deposit | This container is used if the seller wants to require an initial deposit on a motor vehicle listing. In this container, the seller sets the deposit amount and the due date for the deposit. Note: The 'due date' specified in the deposit container will be overridden if the payment business policy requires immediate payment (in this case, for the deposit), and the buyer commits to purchase the motor vehicle through a fixed-price listing or through the 'Buy it Now' option of an auction listing. Occurrence: Optional |
| deposit.amount | Amount | This value indicates the initial deposit amount required from the buyer in order to purchase a motor vehicle. This value can be as high as $2,000.00 if immediate payment is not required, and up to $500.00 if immediate payment is required. Occurrence: Conditional |
| deposit.amount.currency | CurrencyCodeEnum | The base currency applied to the value field to establish a monetary amount. Occurrence: Conditional |
| deposit.amount.value | string | The monetary amount in the specified currency. Occurrence: Conditional |
| deposit.dueIn | TimeDuration | This value indicates the number of hours that the buyer has (after they commit to buy) to pay the initial deposit on a motor vehicle. Valid dueIn times are 24, 48, and 72 hours. Occurrence: Conditional |
| deposit.dueIn.unit | TimeDurationUnitEnum | These enum values represent the time measurement unit, such as Occurrence: Conditional |
| deposit.dueIn.value | integer | An integer that represents an amount of time, as measured by the time-measurement unit specified in the unit field. Occurrence: Conditional |
| deposit.paymentMethods | array of PaymentMethod | This array is no longer applicable and should not be used since eBay now manages the electronic payment options available to buyers to pay the deposit. Occurrence: Optional |
| deposit.paymentMethods.brands | array of PaymentInstrumentBrandEnum | Note: This array is no longer applicable and should not be used. eBay now controls all electronic payment methods available for a marketplace, and a seller never has to specify any electronic payment methods, including any credit card brands accepted. Occurrence: Conditional |
| deposit.paymentMethods.paymentMethodType | PaymentMethodTypeEnum | eBay now controls all electronic payment methods available for a marketplace, so only offline payment method enum values may be used in this field, and offline payment methods will only be applicable to listings that require or support offline payments. See the PaymentMethodTypeEnum type for supported offline payment method enum values. Occurrence: Optional |
| deposit.paymentMethods.recipientAccountReference | RecipientAccountReference | Note: This container is no longer applicable and should not be used. eBay now controls all electronic payment methods available for a marketplace, and a seller never has to specify any electronic payment methods, including PayPal. Occurrence: Conditional |
| deposit.paymentMethods.recipientAccountReference.referenceId | string | Note: DO NOT USE THIS FIELD. eBay now controls all electronic payment methods available for a marketplace, and a seller never has to specify any electronic payment methods. Occurrence: Optional |
| deposit.paymentMethods.recipientAccountReference.referenceType | RecipientAccountReferenceTypeEnum | Note: DO NOT USE THIS FIELD. eBay now controls all electronic payment methods available for a marketplace, and a seller never has to specify any electronic payment methods. Occurrence: Optional |
| description | string | A seller-defined description of the payment business policy. This description is only for the seller's use, and is not exposed on any eBay pages. Occurrence: Optional |
| fullPaymentDueIn | TimeDuration | This container is used to specify 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. This container must be specified for motor vehicles listings.
7 DAYS Occurrence: Conditional |
| fullPaymentDueIn.unit | TimeDurationUnitEnum | These enum values represent the time measurement unit, such as Occurrence: Conditional |
| fullPaymentDueIn.value | integer | An integer that represents an amount of time, as measured by the time-measurement unit specified in the unit field. Occurrence: Conditional |
| immediatePay | boolean | This field should be included and set to
Default: False Occurrence: Optional |
| marketplaceId | MarketplaceIdEnum | The ID of the eBay marketplace to which this payment business policy applies. Occurrence: Required |
| name | string | A seller-defined name for this payment business policy. Names must be unique for policies assigned to the same marketplace. Occurrence: Required |
| paymentInstructions | string | Note: DO NOT USE THIS FIELD. Payment instructions are no longer supported by payment business policies. A free-form string field that allows sellers to add detailed payment instructions to their listings.Occurrence: Optional |
| paymentMethods | array of PaymentMethod | Note: This field applies only when the seller needs to specify one or more offline payment methods. eBay now manages the electronic payment options available to buyers to pay for the item. This array is used to specify one or more offline payment methods that will be accepted for payment that occurs off of eBay's platform.Occurrence: Conditional |
| paymentMethods.brands | array of PaymentInstrumentBrandEnum | Note: This array is no longer applicable and should not be used. eBay now controls all electronic payment methods available for a marketplace, and a seller never has to specify any electronic payment methods, including any credit card brands accepted. Occurrence: Conditional |
| paymentMethods.paymentMethodType | PaymentMethodTypeEnum | eBay now controls all electronic payment methods available for a marketplace, so only offline payment method enum values may be used in this field, and offline payment methods will only be applicable to listings that require or support offline payments. See the PaymentMethodTypeEnum type for supported offline payment method enum values. Occurrence: Optional |
| paymentMethods.recipientAccountReference | RecipientAccountReference | Note: This container is no longer applicable and should not be used. eBay now controls all electronic payment methods available for a marketplace, and a seller never has to specify any electronic payment methods, including PayPal. Occurrence: Conditional |
| paymentMethods.recipientAccountReference.referenceId | string | Note: DO NOT USE THIS FIELD. eBay now controls all electronic payment methods available for a marketplace, and a seller never has to specify any electronic payment methods. Occurrence: Optional |
| paymentMethods.recipientAccountReference.referenceType | RecipientAccountReferenceTypeEnum | Note: DO NOT USE THIS FIELD. eBay now controls all electronic payment methods available for a marketplace, and a seller never has to specify any electronic payment methods. Occurrence: Optional |
Output
HTTP response headers
See HTTP response headers for details.
| Header | Meaning |
|---|---|
| Location | The 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. |
Response payload
Response fields
| Output container/field | Type | Description |
|---|---|---|
| categoryTypes | array of CategoryType | This container indicates whether the payment business policy applies to motor vehicle listings, or if it applies to non-motor vehicle listings. Occurrence: Always |
| categoryTypes.default | boolean | Note: This field has been deprecated and is no longer used. Occurrence: Conditional |
| categoryTypes.name | CategoryTypeEnum | The category type to which the policy applies (motor vehicles or non-motor vehicles). Occurrence: Always |
| deposit | Deposit | This container is only returned if the seller just created or updated a motor vehicles payment business policy and requires buyers to pay an initial deposit after they commit to buying a motor vehicle. Occurrence: Conditional |
| deposit.amount | Amount | This value indicates the initial deposit amount required from the buyer in order to purchase a motor vehicle. This value can be as high as $2,000.00 if immediate payment is not required, and up to $500.00 if immediate payment is required. Occurrence: Conditional |
| deposit.amount.currency | CurrencyCodeEnum | The base currency applied to the value field to establish a monetary amount. Occurrence: Conditional |
| deposit.amount.value | string | The monetary amount in the specified currency. Occurrence: Conditional |
| deposit.dueIn | TimeDuration | This value indicates the number of hours that the buyer has (after they commit to buy) to pay the initial deposit on a motor vehicle. Valid dueIn times are 24, 48, and 72 hours. Occurrence: Conditional |
| deposit.dueIn.unit | TimeDurationUnitEnum | These enum values represent the time measurement unit, such as Occurrence: Conditional |
| deposit.dueIn.value | integer | An integer that represents an amount of time, as measured by the time-measurement unit specified in the unit field. Occurrence: Conditional |
| deposit.paymentMethods | array of PaymentMethod | This array is no longer applicable and should not be used since eBay now manages the electronic payment options available to buyers to pay the deposit. Occurrence: Conditional |
| deposit.paymentMethods.brands | array of PaymentInstrumentBrandEnum | Note: This array is no longer applicable and should not be used. eBay now controls all electronic payment methods available for a marketplace, and a seller never has to specify any electronic payment methods, including any credit card brands accepted. Occurrence: Conditional |
| deposit.paymentMethods.paymentMethodType | PaymentMethodTypeEnum | eBay now controls all electronic payment methods available for a marketplace, so only offline payment method enum values may be used in this field, and offline payment methods will only be applicable to listings that require or support offline payments. See the PaymentMethodTypeEnum type for supported offline payment method enum values. Occurrence: Conditional |
| deposit.paymentMethods.recipientAccountReference | RecipientAccountReference | Note: This container is no longer applicable and should not be used. eBay now controls all electronic payment methods available for a marketplace, and a seller never has to specify any electronic payment methods, including PayPal. Occurrence: Conditional |
| deposit.paymentMethods.recipientAccountReference.referenceId | string | Note: DO NOT USE THIS FIELD. eBay now controls all electronic payment methods available for a marketplace, and a seller never has to specify any electronic payment methods. Occurrence: Conditional |
| deposit.paymentMethods.recipientAccountReference.referenceType | RecipientAccountReferenceTypeEnum | Note: DO NOT USE THIS FIELD. eBay now controls all electronic payment methods available for a marketplace, and a seller never has to specify any electronic payment methods. Occurrence: Conditional |
| description | string | A seller-defined description of the payment business policy. This description is only for the seller's use, and is not exposed on any eBay pages. This field is returned if set for the policy. Occurrence: Conditional |
| fullPaymentDueIn | TimeDuration | The number of days (after the buyer commits to buy) that a buyer has to pay the remaining balance of a motor vehicle transaction. Sellers can set this value to 3, 7, 10, or 14 days. Note: This value is always returned if categoryTypes is set to Occurrence: Conditional |
| fullPaymentDueIn.unit | TimeDurationUnitEnum | These enum values represent the time measurement unit, such as Occurrence: Conditional |
| fullPaymentDueIn.value | integer | An integer that represents an amount of time, as measured by the time-measurement unit specified in the unit field. Occurrence: Conditional |
| immediatePay | boolean | The value returned in this field will reflect the value set by the seller in the immediatePay request field. A value of
It is possible for the seller to set this field as true in the payment business policy, but it will not apply in some scenarios. For example, immediate payment is not applicable for auction listings that have a winning bidder, for buyer purchases that involve the Best Offer feature, or for transactions that happen offline between the buyer and seller. Occurrence: Always |
| marketplaceId | MarketplaceIdEnum | The ID of the eBay marketplace to which this payment business policy applies. Occurrence: Always |
| name | string | A seller-defined name for this payment business policy. Names must be unique for policies assigned to the same marketplace. Occurrence: Always |
| paymentInstructions | string | Note: NO LONGER SUPPORTED. Although this field may be returned for some older payment business policies, payment instructions are no longer supported by payment business policies. If this field is returned, it can be ignored and these payment instructions will not appear in any listings that use the corresponding business policy. A free-form string field that allows sellers to add detailed payment instructions to their listings.Occurrence: Conditional |
| paymentMethods | array of PaymentMethod | This array shows the available payment methods that the seller has set for the payment business policy. Occurrence: Always |
| paymentMethods.brands | array of PaymentInstrumentBrandEnum | Note: This array is no longer applicable and should not be used. eBay now controls all electronic payment methods available for a marketplace, and a seller never has to specify any electronic payment methods, including any credit card brands accepted. Occurrence: Conditional |
| paymentMethods.paymentMethodType | PaymentMethodTypeEnum | eBay now controls all electronic payment methods available for a marketplace, so only offline payment method enum values may be used in this field, and offline payment methods will only be applicable to listings that require or support offline payments. See the PaymentMethodTypeEnum type for supported offline payment method enum values. Occurrence: Conditional |
| paymentMethods.recipientAccountReference | RecipientAccountReference | Note: This container is no longer applicable and should not be used. eBay now controls all electronic payment methods available for a marketplace, and a seller never has to specify any electronic payment methods, including PayPal. Occurrence: Conditional |
| paymentMethods.recipientAccountReference.referenceId | string | Note: DO NOT USE THIS FIELD. eBay now controls all electronic payment methods available for a marketplace, and a seller never has to specify any electronic payment methods. Occurrence: Conditional |
| paymentMethods.recipientAccountReference.referenceType | RecipientAccountReferenceTypeEnum | Note: DO NOT USE THIS FIELD. eBay now controls all electronic payment methods available for a marketplace, and a seller never has to specify any electronic payment methods. Occurrence: Conditional |
| paymentPolicyId | string | A unique eBay-assigned ID for a payment business policy. This ID is generated when the policy is created. Occurrence: Always |
| warnings | array of ErrorDetailV3 | An array of one or more errors or warnings that were generated during the processing of the request. If there were no issues with the request, this array will return empty. Occurrence: Always |
| warnings.category | string | The category type for this error or warning. It is a string that can have one of three values:
Occurrence: Conditional |
| warnings.domain | string | Name of the domain ,or primary system, of the service or application where the error occurred. Occurrence: Conditional |
| warnings.errorId | integer | A 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.inputRefIds | array of string | Identifies specific request elements associated with the error, if any. inputRefId's response is format specific. For JSON, use JSONPath notation. Occurrence: Conditional |
| warnings.longMessage | string | A more detailed explanation of the error than given in the Occurrence: Conditional |
| warnings.message | string | Information 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.outputRefIds | array of string | Identifies specific response elements associated with the error, if any. Path format is the same as Occurrence: Conditional |
| warnings.parameters | array of ErrorParameterV3 | This optional list of name/value pairs that contain context-specific Occurrence: Conditional |
| warnings.parameters.name | string | Name of the parameter that caused the error. Occurrence: Conditional |
| warnings.parameters.value | string | The value of the parameter that caused the error. Occurrence: Conditional |
| warnings.subdomain | string | If 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.
| Status | Meaning |
|---|---|
| 201 | Created |
| 400 | Bad Request |
| 500 | Internal Server Error |
Error codes
For more on errors, plus the codes of other common errors, see Handling errors.
| Code | Domain | Category | Meaning |
|---|---|---|---|
| 20400 | API_ACCOUNT | REQUEST | Invalid request. {additionalInfo} |
| 20401 | API_ACCOUNT | REQUEST | Missing field {fieldName}. {additionalInfo} |
| 20403 | API_ACCOUNT | REQUEST | Invalid {fieldName}. {additionalInfo} |
| 20404 | API_ACCOUNT | REQUEST | {fieldName} not found. |
| 20405 | API_ACCOUNT | REQUEST | Invalid payment method. {fieldName} |
| 20500 | API_ACCOUNT | APPLICATION | System error. |
| 20501 | API_ACCOUNT | APPLICATION | Service unavailable. Please try again in next 24 hours. |
Warnings
For more on warnings, plus the codes of other common warnings, see Handling errors.
| Code | Domain | Category | Meaning |
|---|---|---|---|
| 20200 | API_ACCOUNT | BUSINESS | Warning. {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: 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.
POSThttps://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 a 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.
Sample 2: A motor vehicle payment policy
This sample creates a payment policy for motor vehicle sales (categoryTypes 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.
POSThttps://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.