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

Create a Payment Policy

POST /payment_policy

Use this call to create a new payment policy. You can create multiple payment policies, where each policy targets a different marketplace and/or category type. While eBay designates the first payment policy you create as the default policy, you can mark any policy as the default (but only one payment policy can be the default). A successful call returns the URI to the new policy in the Location response header. Note that some site require a specific policy for vehicle item listings.

Policy instructions can be localized by providing a local in the Content-Language HTTP request header. For example: Content-Language: de-DE.

Tip: For details on using your business policies, see eBay business policies

Input

See also Samples.

Resource URI (production)

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

This call has no path or query parameters.


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.

Response headers

Header Meaning
Location URL location of a new payment policy.

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
201 Created
400 Bad Request
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.

Available samples:

Sample: A skeleton payment policy

This call creates a skeleton payment policy using only the required input fields.

Description

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.

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

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

{
  "name": "minimal Payment Policy",
  "marketplaceId": "EBAY_US",
  "categoryTypes": [
    {
      "name": "ALL_EXCLUDING_MOTORS_VEHICLES"
    }
  ],
  "paymentMethods": [
    {
      "paymentMethodType": "PERSONAL_CHECK"
    }
  ]
}

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.

JSON format.
{
  "name": "minimal Payment Policy",
  "marketplaceId": "EBAY_US",
  "categoryTypes": [
    {
      "name": "ALL_EXCLUDING_MOTORS_VEHICLES",
      "default": true
    }
  ],
  "paymentMethods": [
    {
      "paymentMethodType": "PERSONAL_CHECK"
    }
  ],
  "immediatePay": false,
  "paymentPolicyId": "5458288000",
  "warnings": []
}

Back to list of samples

Sample: A detailed payment policy

This call creates a detailed payment policy.

Description

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.

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

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

{
  "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"
      ]
    }
  ]
}

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.

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": "PAYPAL",
      "recipientAccountReference": {
        "referenceType": "PAYPAL_EMAIL",
        "referenceId": "lenrice@paypal.example.com"
      }
    }
  ],
  "immediatePay": false,
  "paymentPolicyId": "5458323000",
  "warnings": []
}


Back to list of samples

Sample: A motor vehicle payment policy

This call creates a detailed payment policy for motor vehicle sales.

Description

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.

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

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

{
    "name": "Vehicle payment: PP deposit; cash, MO, cashier check payment",
    "description": "Vehicle payment policy, $500 down, full in 7 days",
    "marketplaceId": "EBAY_US",
    "categoryTypes": [
        {
            "name": "MOTORS_VEHICLES",
            "default": true
        }
    ],
    "immediatePay": false,
    "paymentInstructions": "A PayPal deposit of $500 is due in 48 hours, payment in full is due in 7 days.",
    "fullPaymentDueIn": {
        "value": 7,
        "unit": "DAY"
    },
    "deposit": {
        "amount": {
            "value": "500.00",
            "currency": "USD"
        },
        "dueIn": {
            "value": 48,
            "unit": "HOUR"
        },
        "paymentMethods": [
            {
                "paymentMethodType": "PAYPAL",
                "recipientAccountReference": {
                    "referenceType": "PAYPAL_EMAIL",
                    "referenceId": "lenrice@paypal.example.com"
                }
            }
        ]
    },
    "paymentMethods": [
        {
            "paymentMethodType": "CASH_ON_PICKUP"
        },
        {
            "paymentMethodType": "MONEY_ORDER"
        },
        {
            "paymentMethodType": "CASHIER_CHECK"
        }
    ]
}

Output

If the call is successful, eBay returns an HTTP status code of 201 Created and the complete payment policy resoruce, 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.

JSON format.
{
  "name": "Vehicle payment: PP deposit; cash, MO, cashier check payment",
  "description": "Vehicle payment policy, $500 down, full in 7 days",
  "marketplaceId": "EBAY_US",
  "categoryTypes": [
    {
      "name": "MOTORS_VEHICLES",
      "default": true
    }
  ],
  "paymentMethods": [
    {
      "paymentMethodType": "MONEY_ORDER"
    },
    {
      "paymentMethodType": "CASHIER_CHECK"
    },
    {
      "paymentMethodType": "CASH_ON_PICKUP"
    }
  ],
  "paymentInstructions": "A PayPal deposit of $500 is due in 48 hours, payment in full is due in 7 days.",
  "fullPaymentDueIn": {
    "value": 7,
    "unit": "DAY"
  },
  "immediatePay": false,
  "deposit": {
    "amount": {
      "value": "500.0",
      "currency": "USD"
    },
    "dueIn": {
      "value": 48,
      "unit": "HOUR"
    },
    "paymentMethods": [
      {
        "paymentMethodType": "PAYPAL",
        "recipientAccountReference": {
          "referenceType": "PAYPAL_EMAIL",
          "referenceId": "lenny.rice@example.com"
        }
      }
    ]
  },
  "paymentPolicyId": "5486492000",
  "warnings": []
}


Back to list of samples



Change History

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