This doc page has moved! You should be automatically redirected to the resources page for the eBay Account API. If you are not redirected automatically, follow this link to the Account API.

eBay Account APIVersion 1.2.0

Update a Payment Policy

PUT /payment_policy/{payment_policy_id}

Use this call to update 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

See also Samples.

Resource URI (production)

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

URI parameters

Parameter Type Required? Meaning
payment_policy_id string Required A unique eBay-assigned ID for a payment policy.


HTTP request headers

All requests made to eBay REST operations require you to provide the authorization HTTP header for authentication.
See HTTP request headers for details.



OAuth request scope

This request requires a user access token with the following scope:

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

See Getting Access Tokens for more information.



Payload model

The following lists all fields that could be included in the request.

{ /* PaymentPolicyRequest */
"categoryTypes": [
    { /* CategoryType */
    "default": boolean,
    "name": string
    }
    /* More CategoryType nodes here */
  ],
"deposit":
    { /* Deposit */
    "amount":
        { /* Amount */
        "currency": string,
        "value": string
        },
    "dueIn":
        { /* TimeDuration */
        "unit": string,
        "value": integer
        },
    "paymentMethods": [
        { /* PaymentMethod */
        "brands": [
            string
            /* More string nodes here */
          ],
        "paymentMethodType": string,
        "recipientAccountReference":
            { /* RecipientAccountReference */
            "referenceId": string,
            "referenceType": string
            }
        }
        /* More PaymentMethod nodes here */
      ]
    },
"description": string,
"fullPaymentDueIn":
    { /* TimeDuration */
    "unit": string,
    "value": integer
    },
"immediatePay": boolean,
"marketplaceId": string,
"name": string,
"paymentInstructions": string,
"paymentMethods": [
    { /* PaymentMethod */
    "brands": [
        string
        /* More string nodes here */
      ],
    "paymentMethodType": string,
    "recipientAccountReference":
        { /* RecipientAccountReference */
        "referenceId": string,
        "referenceType": string
        }
    }
    /* More PaymentMethod nodes here */
  ]
}

Request field descriptions



Input Container/Field Type Occurrence Meaning
categoryTypes array of CategoryType Required The 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.)
categoryTypes.default boolean Optional Sellers can create multiple policies for any categoryTypes.name and marketplaceId combination. For example, you can create multiple fulfillment policies for one marketplace, where they all target the same category type; however, only one can be default at a time.

If this value is set to true, it indicates that 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.
categoryTypes.name string Required The category type to which the policy applies (motor vehicles or non-motor vehicles).
Note: The 'MOTORS_VEHICLES' category type is not valid for return policies because motor vehicle listings are non-returnable via eBay processes.

Applicable values are from CategoryTypeEnum:

ALL_EXCLUDING_MOTORS_VEHICLES
Category type name for all non-motor vehicle listings.
MOTORS_VEHICLES
Category type name for motor vehicle listings.
deposit Deposit Optional This 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 and full payments for motor vehicle listings on eBay Motors.
deposit.amount Amount Optional Often used with motor listings, this dollar value indicates the initial deposit amount that a buyer must make to purchase a motor vehicle (eBay Motors). The deposit amount can be as high as $2,000.00. If not specified, this value defaults to '0.0'. If this value is specified, the seller must also specify an hoursToDeposit value.

Deposits on motor vehicles can only be paid using PayPal, so if depositAmount is specified, then one of the acceptedPaymentMethod values must be 'PayPal' (in addition to the payment methods offered for the full payment). Unlike other listings, PayPal is not automatically added to a Motors listing even if the seller has a PayPal preference set in My eBay. The seller also needs to have a linked PayPal account in order to require a deposit from the buyer.

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

Min: 0.0 Max: 2000.0 Default: 0.0
deposit.amount.currency string Optional The currency in which the amount value is expressed. The currency is represented as a 3-letter ISO4217 currency code.

Applicable values are from CurrencyCodeEnum:See currency.
deposit.amount.value string Optional The value of the amount in the specified currency.
deposit.dueIn TimeDuration Optional This 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 HOURS', '48 HOURS' (default), and '72 HOURS'.

The deposit amount is specified in the depositAmount field. If not specified, the depositAmount 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, one of the acceptedPaymentMethod values must be 'PayPal' (in addition to the payment methods offered for the full payment).

Min=24 HOURS, Max=72 HOURS
deposit.dueIn.unit string Conditional Required if a time duration is required by the call.

Specifies a period of time as a unit that is used to define a duration.

Time-measurement units can be years, months, days, hours, and minutes (see TimeDurationUnitEnum for a complete list of units). The unit is applied to the number in the value field to define a span of time.

Note that supported values for this field vary according to the object using the time duration. See the containing object for details, and call GeteBayDetails in the Trading API to get the allowable values for the specific object your are using.

Applicable values are from TimeDurationUnitEnum:See unit.
deposit.dueIn.value integer Conditional Required if a time duration is required by the call.

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

Note that supported values for this field vary according to the object using the time duration. See the containing object for details, and call GeteBayDetails in the Trading API to get the allowable values for the specific object your are instantiating.
deposit.paymentMethods array of PaymentMethod Optional A list of accepted payment methods.
deposit.paymentMethods.brands array of string Optional A list of credit card brands accepted by the seller. eBay displays the settings in this field if paymentMethodType is set to CREDIT_CARD.

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 your site(s) support. If the GetCategoryFeatures call returns details on credit card brands for the cateogries you sell in to, then you can use this field to list the credit card brands you accept. If, on the other hand, GetCategoryFeatures does not enumerate credit card brands for your tartet site (for example, if it returns PaymentMethod set to CCAccepted), then this field is not supported for that marketplace.

Applicable values are from PaymentInstrumentBrandEnum:

AMERICAN_EXPRESS
Payment instrument brand name for American Express.
DISCOVER
Payment instrument brand name for Discover.
MASTERCARD
Payment instrument brand name for MasterCard.
VISA
Payment instrument brand name for Visa.
deposit.paymentMethods
  .paymentMethodType
string Optional The payment method, selected from the supported payment method types.

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 paymentMethod supported is PayPal).

Applicable values are from PaymentMethodTypeEnum:See paymentMethodType.
deposit.paymentMethods
  .recipientAccountReference
RecipientAccountReference Optional Recipient account information, like PayPal email. If the payment method is PayPal, this structure contains the recipient's PayPal email address.
deposit.paymentMethods
  .recipientAccountReference
  .referenceId
string Optional Contains the PayPal email address of the recipient (buyer) if referenceType is set to PAYPAL_EMAIL.
deposit.paymentMethods
  .recipientAccountReference
  .referenceType
string Optional A reference a recipient's account. Currently only PAYPAL_EMAIL is valid.

Applicable values are from RecipientAccountReferenceTypeEnum:

PAYPAL_EMAIL
The PayPal email address of the PayPal account holder.
description string Optional An optional seller-defined description of the payment policy.

Max length: 250
Max: 250.
fullPaymentDueIn TimeDuration Optional The 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.

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 business policy:
  • CashOnPickup
  • LoanCheck
  • MOCC (money order or cashier's check)
  • PaymentSeeDescription (payment instructions are in the item's description)
  • PersonalCheck
Default: 7 DAYS (Note that this value is provided in a compound type.)
fullPaymentDueIn.unit string Conditional Required if a time duration is required by the call.

Specifies a period of time as a unit that is used to define a duration.

Time-measurement units can be years, months, days, hours, and minutes (see TimeDurationUnitEnum for a complete list of units). The unit is applied to the number in the value field to define a span of time.

Note that supported values for this field vary according to the object using the time duration. See the containing object for details, and call GeteBayDetails in the Trading API to get the allowable values for the specific object your are using.

Applicable values are from TimeDurationUnitEnum:See unit.
fullPaymentDueIn.value integer Conditional Required if a time duration is required by the call.

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

Note that supported values for this field vary according to the object using the time duration. See the containing object for details, and call GeteBayDetails in the Trading API to get the allowable values for the specific object your are instantiating.
immediatePay boolean Optional Set this value to true to indicate that payment is due upon receipt (eBay generates a receipt when the buyer agrees to purchage 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 lifecyle 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 paymentProfile.paymentInfo.paypalEmailAddress 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
marketplaceId string Required The ID of the eBay marketplace to which the payment policy applies. If this value is not specified, value defaults to the seller's eBay registration site.

Applicable values are from MarketplaceIdEnum:See marketplaceId.
name string Required A user-defined name for this payment policy. Names must be unique for policies assigned to the same marketplace.

Max length: 64
Max: 64.
paymentInstructions string Optional This user-defined field allows the seller to give payment instructions to the buyer. These instructions appear on the eBay View Item and Checkout pages.

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

Max length: 500
Max: 500.
paymentMethods array of PaymentMethod Required A list of the payment methods accepted by the seller. Each payment policy must specify at least one payment method.

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

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 your site(s) support. If the GetCategoryFeatures call returns details on credit card brands for the cateogries you sell in to, then you can use this field to list the credit card brands you accept. If, on the other hand, GetCategoryFeatures does not enumerate credit card brands for your tartet site (for example, if it returns PaymentMethod set to CCAccepted), then this field is not supported for that marketplace.

Applicable values are from PaymentInstrumentBrandEnum:

AMERICAN_EXPRESS
Payment instrument brand name for American Express.
DISCOVER
Payment instrument brand name for Discover.
MASTERCARD
Payment instrument brand name for MasterCard.
VISA
Payment instrument brand name for Visa.
paymentMethods
  .paymentMethodType
string Optional The payment method, selected from the supported payment method types.

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 paymentMethod supported is PayPal).

Applicable values are from PaymentMethodTypeEnum:See paymentMethodType.
paymentMethods
  .recipientAccountReference
RecipientAccountReference Optional Recipient account information, like PayPal email. If the payment method is PayPal, this structure contains the recipient's PayPal email address.
paymentMethods
  .recipientAccountReference
  .referenceId
string Optional Contains the PayPal email address of the recipient (buyer) if referenceType is set to PAYPAL_EMAIL.
paymentMethods
  .recipientAccountReference
  .referenceType
string Optional A reference a recipient's account. Currently only PAYPAL_EMAIL is valid.

Applicable values are from RecipientAccountReferenceTypeEnum:

PAYPAL_EMAIL
The PayPal email address of the PayPal account holder.

Output

See also Samples.

HTTP status codes

This call can return one of the following HTTP status codes. See the HTTP Status Code Registry for a complete overview of HTTP status codes.

Status Meaning
200 OK
400 Bad Request
404 Not Found
500 Internal Server Error

Payload model

Note: For information about the error fields and how to work with them, see Error Handling.

The following lists all fields that could be included in the response.

{ /* SetPaymentPolicyResponse */
"categoryTypes": [
    { /* CategoryType */
    "default": boolean,
    "name": string
    }
    /* More CategoryType nodes here */
  ],
"deposit":
    { /* Deposit */
    "amount":
        { /* Amount */
        "currency": string,
        "value": string
        },
    "dueIn":
        { /* TimeDuration */
        "unit": string,
        "value": integer
        },
    "paymentMethods": [
        { /* PaymentMethod */
        "brands": [
            string
            /* More string nodes here */
          ],
        "paymentMethodType": string,
        "recipientAccountReference":
            { /* RecipientAccountReference */
            "referenceId": string,
            "referenceType": string
            }
        }
        /* More PaymentMethod nodes here */
      ]
    },
"description": string,
"fullPaymentDueIn":
    { /* TimeDuration */
    "unit": string,
    "value": integer
    },
"immediatePay": boolean,
"marketplaceId": string,
"name": string,
"paymentInstructions": string,
"paymentMethods": [
    { /* PaymentMethod */
    "brands": [
        string
        /* More string nodes here */
      ],
    "paymentMethodType": string,
    "recipientAccountReference":
        { /* RecipientAccountReference */
        "referenceId": string,
        "referenceType": string
        }
    }
    /* More PaymentMethod nodes here */
  ],
"paymentPolicyId": string,
"warnings": [
    { /* ErrorDetailV3 */
    "category": string,
    "domain": string,
    "errorId": integer,
    "inputRefIds": [
        string
        /* More string nodes here */
      ],
    "longMessage": string,
    "message": string,
    "outputRefIds": [
        string
        /* More string nodes here */
      ],
    "parameters": [
        { /* ErrorParameterV3 */
        "name": string,
        "value": string
        }
        /* More ErrorParameterV3 nodes here */
      ],
    "subdomain": string
    }
    /* More ErrorDetailV3 nodes here */
  ]
}

Response field descriptions



Output Container/Field Type Occurrence Meaning
categoryTypes array of CategoryType Always The 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.)
categoryTypes.default boolean Always Sellers can create multiple policies for any categoryTypes.name and marketplaceId combination. For example, you can create multiple fulfillment policies for one marketplace, where they all target the same category type; however, only one can be default at a time.

If this value is set to true, it indicates that 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.
categoryTypes.name string Always The category type to which the policy applies (motor vehicles or non-motor vehicles).
Note: The 'MOTORS_VEHICLES' category type is not valid for return policies because motor vehicle listings are non-returnable via eBay processes.

Applicable values are from CategoryTypeEnum:

ALL_EXCLUDING_MOTORS_VEHICLES
Category type name for all non-motor vehicle listings.
MOTORS_VEHICLES
Category type name for motor vehicle listings.

Code so that your app gracefully handles any future changes to this list.
deposit Deposit Conditionally This 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 and full payments for motor vehicle listings on eBay Motors.
deposit.amount Amount Conditionally Often used with motor listings, this dollar value indicates the initial deposit amount that a buyer must make to purchase a motor vehicle (eBay Motors). The deposit amount can be as high as $2,000.00. If not specified, this value defaults to '0.0'. If this value is specified, the seller must also specify an hoursToDeposit value.

Deposits on motor vehicles can only be paid using PayPal, so if depositAmount is specified, then one of the acceptedPaymentMethod values must be 'PayPal' (in addition to the payment methods offered for the full payment). Unlike other listings, PayPal is not automatically added to a Motors listing even if the seller has a PayPal preference set in My eBay. The seller also needs to have a linked PayPal account in order to require a deposit from the buyer.

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

Min: 0.0 Max: 2000.0 Default: 0.0
deposit.amount.currency string Conditionally The currency in which the amount value is expressed. The currency is represented as a 3-letter ISO4217 currency code.

Applicable values are from CurrencyCodeEnum:See currency.
Code so that your app gracefully handles any future changes to this list.
deposit.amount.value string Conditionally The value of the amount in the specified currency.
deposit.dueIn TimeDuration Conditionally This 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 HOURS', '48 HOURS' (default), and '72 HOURS'.

The deposit amount is specified in the depositAmount field. If not specified, the depositAmount 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, one of the acceptedPaymentMethod values must be 'PayPal' (in addition to the payment methods offered for the full payment).

Min=24 HOURS, Max=72 HOURS
deposit.dueIn.unit string Conditionally Required if a time duration is required by the call.

Specifies a period of time as a unit that is used to define a duration.

Time-measurement units can be years, months, days, hours, and minutes (see TimeDurationUnitEnum for a complete list of units). The unit is applied to the number in the value field to define a span of time.

Note that supported values for this field vary according to the object using the time duration. See the containing object for details, and call GeteBayDetails in the Trading API to get the allowable values for the specific object your are using.

Applicable values are from TimeDurationUnitEnum:See unit.
Code so that your app gracefully handles any future changes to this list.
deposit.dueIn.value integer Conditionally Required if a time duration is required by the call.

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

Note that supported values for this field vary according to the object using the time duration. See the containing object for details, and call GeteBayDetails in the Trading API to get the allowable values for the specific object your are instantiating.
deposit.paymentMethods array of PaymentMethod Conditionally A list of accepted payment methods.
deposit.paymentMethods.brands array of string Conditionally A list of credit card brands accepted by the seller. eBay displays the settings in this field if paymentMethodType is set to CREDIT_CARD.

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 your site(s) support. If the GetCategoryFeatures call returns details on credit card brands for the cateogries you sell in to, then you can use this field to list the credit card brands you accept. If, on the other hand, GetCategoryFeatures does not enumerate credit card brands for your tartet site (for example, if it returns PaymentMethod set to CCAccepted), then this field is not supported for that marketplace.

Applicable values are from PaymentInstrumentBrandEnum:

AMERICAN_EXPRESS
Payment instrument brand name for American Express.
DISCOVER
Payment instrument brand name for Discover.
MASTERCARD
Payment instrument brand name for MasterCard.
VISA
Payment instrument brand name for Visa.

Code so that your app gracefully handles any future changes to this list.
deposit.paymentMethods
  .paymentMethodType
string Conditionally The payment method, selected from the supported payment method types.

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 paymentMethod supported is PayPal).

Applicable values are from PaymentMethodTypeEnum:See paymentMethodType.
Code so that your app gracefully handles any future changes to this list.
deposit.paymentMethods
  .recipientAccountReference
RecipientAccountReference Conditionally Recipient account information, like PayPal email. If the payment method is PayPal, this structure contains the recipient's PayPal email address.
deposit.paymentMethods
  .recipientAccountReference
  .referenceId
string Conditionally Contains the PayPal email address of the recipient (buyer) if referenceType is set to PAYPAL_EMAIL.
deposit.paymentMethods
  .recipientAccountReference
  .referenceType
string Conditionally A reference a recipient's account. Currently only PAYPAL_EMAIL is valid.

Applicable values are from RecipientAccountReferenceTypeEnum:

PAYPAL_EMAIL
The PayPal email address of the PayPal account holder.

Code so that your app gracefully handles any future changes to this list.
description string Conditionally An optional seller-defined description of the payment policy.

Max length: 250
Max: 250.
fullPaymentDueIn TimeDuration Conditionally The 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.
fullPaymentDueIn.unit string Conditionally Required if a time duration is required by the call.

Specifies a period of time as a unit that is used to define a duration.

Time-measurement units can be years, months, days, hours, and minutes (see TimeDurationUnitEnum for a complete list of units). The unit is applied to the number in the value field to define a span of time.

Note that supported values for this field vary according to the object using the time duration. See the containing object for details, and call GeteBayDetails in the Trading API to get the allowable values for the specific object your are using.

Applicable values are from TimeDurationUnitEnum:See unit.
Code so that your app gracefully handles any future changes to this list.
fullPaymentDueIn.value integer Conditionally Required if a time duration is required by the call.

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

Note that supported values for this field vary according to the object using the time duration. See the containing object for details, and call GeteBayDetails in the Trading API to get the allowable values for the specific object your are instantiating.
immediatePay boolean Always When this value is set to true, it indicates that payment is due upon receipt (eBay generates a receipt when the buyer agrees to purchage 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
marketplaceId string Always The 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.

Applicable values are from MarketplaceIdEnum:See marketplaceId.
Code so that your app gracefully handles any future changes to this list.
name string Always A user-defined name for this payment policy. Names must be unique for policies assigned to the same marketplace.

Max length: 64
Max: 64.
paymentInstructions string Conditionally This user-defined field allows the seller to give payment instructions to the buyer. These instructions appear on the eBay View Item and Checkout pages.

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

Max length: 500
Max: 500.
paymentMethods array of PaymentMethod Always A list of the payment methods accepted by the seller. Each payment policy must specify at least one payment method.

Payment policies used with motor vehicle listings that require a deposit must have PayPal listed has a payment method (deposits require PayPal as the payment method). Also, in order for a buyer to make a full payment on a US or CA motor vehicle, the payment policy must specify at least one of the following as a payment method:
  • CashOnPickup
  • LoanCheck
  • MOCC (money order or cashier's check)
  • PaymentSeeDescription (payment instructions are in the paymentInstructions field)
  • PersonalCheck
paymentMethods.brands array of string Conditionally A list of credit card brands accepted by the seller. eBay displays the settings in this field if paymentMethodType is set to CREDIT_CARD.

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 your site(s) support. If the GetCategoryFeatures call returns details on credit card brands for the cateogries you sell in to, then you can use this field to list the credit card brands you accept. If, on the other hand, GetCategoryFeatures does not enumerate credit card brands for your tartet site (for example, if it returns PaymentMethod set to CCAccepted), then this field is not supported for that marketplace.

Applicable values are from PaymentInstrumentBrandEnum:

AMERICAN_EXPRESS
Payment instrument brand name for American Express.
DISCOVER
Payment instrument brand name for Discover.
MASTERCARD
Payment instrument brand name for MasterCard.
VISA
Payment instrument brand name for Visa.

Code so that your app gracefully handles any future changes to this list.
paymentMethods
  .paymentMethodType
string Conditionally The payment method, selected from the supported payment method types.

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 paymentMethod supported is PayPal).

Applicable values are from PaymentMethodTypeEnum:See paymentMethodType.
Code so that your app gracefully handles any future changes to this list.
paymentMethods
  .recipientAccountReference
RecipientAccountReference Conditionally Recipient account information, like PayPal email. If the payment method is PayPal, this structure contains the recipient's PayPal email address.
paymentMethods
  .recipientAccountReference
  .referenceId
string Conditionally Contains the PayPal email address of the recipient (buyer) if referenceType is set to PAYPAL_EMAIL.
paymentMethods
  .recipientAccountReference
  .referenceType
string Conditionally A reference a recipient's account. Currently only PAYPAL_EMAIL is valid.

Applicable values are from RecipientAccountReferenceTypeEnum:

PAYPAL_EMAIL
The PayPal email address of the PayPal account holder.

Code so that your app gracefully handles any future changes to this list.
paymentPolicyId string Always A unique eBay-assigned ID for this policy.
warnings array of ErrorDetailV3 Always A list of warnings related to request. This field normally returns empty, which indicates the request did not generate any warnings.
warnings.category string Conditionally The category type for this error or warning. It takes an ErrorCategory object which 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.
warnings.domain string Conditionally Name of the domain containing the service or application.
warnings.errorId integer Conditionally 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.
warnings.inputRefIds array of string Conditionally Identifies specific request elements associated with the error, if any. inputRefId's response is format specific. For JSON, use JSONPath notation.
warnings.longMessage string Conditionally An expanded version of message that should be around 100-200 characters long, but is not required to be such.
warnings.message string Conditionally An end user and app developer friendly device agnostic message. It explains what the error or warning is, and how to fix it (in a general sense). Its value is at most 50 characters long. If applicable, the value is localized in the end user's requested locale.
warnings.outputRefIds array of string Conditionally Identifies specific response elements associated with the error, if any. Path format is the same as inputRefId.
warnings.parameters array of ErrorParameterV3 Conditionally This optional complex field type contains a list of one or more context-specific ErrorParameter objects, with each item in the list entry being a parameter (or input field name) that caused an error condition. Each ErrorParameter object consists of two fields, a name and a value.
warnings.parameters.name string Conditionally Name of the entity that threw the error.
warnings.parameters.value string Conditionally A description of the error.
warnings.subdomain string Conditionally Name of the domain's subsystem or subdivision. For example, checkout is a subdomain in the buying domain.



Error Codes

Code Domain Category Nature Meaning
20200 API_ACCOUNT BUSINESS WARNING Warning. {additionalInfo}
20400 API_ACCOUNT REQUEST ERROR Invalid request. {additionalInfo}
20401 API_ACCOUNT REQUEST ERROR Missing field {fieldName}. {additionalInfo}
20402 API_ACCOUNT REQUEST ERROR Invalid input. {additionalInfo}
20403 API_ACCOUNT REQUEST ERROR Invalid {fieldName}. {additionalInfo}
20404 API_ACCOUNT REQUEST ERROR {fieldName} not found.
20405 API_ACCOUNT REQUEST ERROR Invalid payment method. {fieldName}
20500 API_ACCOUNT APPLICATION ERROR System error.
20501 API_ACCOUNT APPLICATION ERROR Service unavailable. Please try again in next 24 hours.



Samples

Note: Some item IDs, user IDs, or other data in these samples might no longer be active on eBay. If necessary, you can substitute current eBay data in your requests.

Sample: Update a Payment Policy

Description

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, perform a GET operation using ID of the policy you want to update. Use this same policy ID value in the payPolicyId 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.

URL format. See also the non-wrapped version of this URL.

PUT https://api.sandbox.ebay.com/sell/account/v1/payment_policy/5458323000

{
  "categoryTypes": [
    {
      "name": "ALL_EXCLUDING_MOTORS_VEHICLES",
      "default": true
    }
  ],
  "name": "default payment policy",
  "description": "Standard payment policy, PP & CC payments",
  "marketplaceId": "EBAY_US",
  "immediatePay": false,
  "paymentMethods": [
    {
      "paymentMethodType": "PAYPAL",
      "recipientAccountReference": {
        "referenceId": "lenrice@paypal.example.com",
        "referenceType": "PAYPAL_EMAIL"
      }
    },
    {
      "paymentMethodType": "CREDIT_CARD",
      "brands": [
        "AMERICAN_EXPRESS",
        "DISCOVER",
        "MASTERCARD",
        "VISA"
      ]
    },
    {
      "paymentMethodType": "MONEY_ORDER"
    }
  ]
}

Output

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

JSON format.
{
  "name": "default payment policy",
  "description": "Standard payment policy, PP & CC payments",
  "marketplaceId": "EBAY_US",
  "categoryTypes": [
    {
      "name": "ALL_EXCLUDING_MOTORS_VEHICLES",
      "default": true
    }
  ],
  "paymentMethods": [
    {
      "paymentMethodType": "CREDIT_CARD",
      "brands": [
        "AMERICAN_EXPRESS",
        "DISCOVER",
        "VISA",
        "MASTERCARD"
      ]
    },
    {
      "paymentMethodType": "MONEY_ORDER"
    },
    {
      "paymentMethodType": "CASHIER_CHECK"
    },
    {
      "paymentMethodType": "PAYPAL",
      "recipientAccountReference": {
        "referenceType": "PAYPAL_EMAIL",
        "referenceId": "lenrice@paypal.example.com"
      }
    }
  ],
  "immediatePay": false,
  "paymentPolicyId": "5458323000",
  "warnings": []
}



Change History

Change Date Description
1.0.0
2016-10-19
  • Call (added): New call.