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

Get Payment Policies by Marketplace

GET /payment_policy

Use this call to retrieve all the payment policies configured for the marketplace you specify using the marketplace_id query parameter.

Input

See also Samples.

Resource URI (production)

GET https://api.ebay.com/sell/account/v1/payment_policy?
  marketplace_id=MarketplaceIdEnum

URI parameters

Parameter Type Required? Meaning
marketplace_id string Required A unique identifier for an eBay marketplace.

Applicable values are from MarketplaceIdEnum.


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

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

See Getting Access Tokens for more information.



Payload model

This call has no request payload.


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

{ /* PaymentPolicyResponse */
"href": string,
"limit": integer,
"next": string,
"offset": integer,
"paymentPolicies": [
    { /* PaymentPolicy */
    "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
    }
    /* More PaymentPolicy nodes here */
  ],
"prev": string,
"total": integer
}

Response field descriptions



Output Container/Field Type Occurrence Meaning
href string Conditionally Returns a URL link to the current result set.
limit integer Conditionally Returns the maximum number of results that can be returned in result set.
next string Conditionally Returns a URL link to the next set of results.
offset integer Conditionally Returns how many result sets were skipped before the currently returned result set.
paymentPolicies array of PaymentPolicy Conditionally A list of the seller's payment policies.
paymentPolicies.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.)
paymentPolicies.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.
paymentPolicies.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.
paymentPolicies.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.
paymentPolicies.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
paymentPolicies.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.
paymentPolicies.deposit.amount
  .value
string Conditionally The value of the amount in the specified currency.
paymentPolicies.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
paymentPolicies.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.
paymentPolicies.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.
paymentPolicies.deposit
  .paymentMethods
array of PaymentMethod Conditionally A list of accepted payment methods.
paymentPolicies.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.
paymentPolicies.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.
paymentPolicies.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.
paymentPolicies.deposit
  .paymentMethods
  .recipientAccountReference
  .referenceId
string Conditionally Contains the PayPal email address of the recipient (buyer) if referenceType is set to PAYPAL_EMAIL.
paymentPolicies.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.
paymentPolicies.description string Conditionally An optional seller-defined description of the payment policy.

Max length: 250
Max: 250.
paymentPolicies
  .fullPaymentDueIn
TimeDuration Conditionally This field applies to motor vehicles listings only and indicates when a final payment for the vehicle is due. This value is always returned if categoryTypes is set to MOTORS_VEHICLES.

This seller-specified value indicates the number of days that a buyer has to make their full payment to the seller and close the remaining balance on a motor vehicle transaction. The period starts when the buyer commits to buy. The valid values, as specified with TimeDuration, are:
  • 3 DAYS
  • 7 DAYS (the default)
  • 10 DAYS
  • 14 DAYS
In order for a buyer to make a full payment on a US or CA motor vehicle, at least one of the following paymentMethods values must be specified for the corresponding payment policy:
  • CASH_ON_PICKUP
  • MONEY_ORDER
  • CASHIER_CHECK
  • PERSONAL_CHECK
  • LOAN_CHECK
  • PAYPAL
Default: 7 DAYS (Note that this value is supported by a compound type.)
paymentPolicies
  .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.
paymentPolicies
  .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.
paymentPolicies.immediatePay boolean Always 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
paymentPolicies.marketplaceId string Always 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.
Code so that your app gracefully handles any future changes to this list.
paymentPolicies.name string Always A user-defined name for this fulfillment policy. Names must be unique for policies assigned to the same marketplace.

Max length: 64
Max: 64.
paymentPolicies
  .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.
paymentPolicies.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.

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
paymentPolicies.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.
paymentPolicies.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.
paymentPolicies.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.
paymentPolicies.paymentMethods
  .recipientAccountReference
  .referenceId
string Conditionally Contains the PayPal email address of the recipient (buyer) if referenceType is set to PAYPAL_EMAIL.
paymentPolicies.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.
paymentPolicies
  .paymentPolicyId
string Always A unique eBay-assigned ID for this policy.
prev string Conditionally Returns a URL link to the previous set of results.
total integer Conditionally Returns the total number of result sets in the paginated collection.



Error Codes

Code Domain Category Nature Meaning
20401 API_ACCOUNT REQUEST ERROR Missing field {fieldName}. {additionalInfo}
20403 API_ACCOUNT REQUEST ERROR Invalid {fieldName}. {additionalInfo}
20404 API_ACCOUNT REQUEST ERROR {fieldName} not found.
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: Get all Payment Policies

This call retrieves all payment policies for the specified marketplace.

Description

Sellers can create one or more payment policies for a particular marketplace. This call returns all the current payment policies for the specified marketplace.

Input

Specify the marketplace for the policies you want to retrieve useing the marketplace_id query parameter.

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

GET https://api.sandbox.ebay.com/sell/account/v1/payment_policy?
   marketplace_id=EBAY_US

Output

If the call is successful, eBay returns an HTTP status code of 200 OK and a complete list of the payment policies associated with the specified marketplace.

JSON format.
{
  "total": 3,
  "paymentPolicies": [
    {
      "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"
    },
    {
      "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": "lenrice@paypal.example.com"
            }
          }
        ]
      },
      "paymentPolicyId": "5486492000"
    },
    {
      "name": "minimal Payment Policy",
      "marketplaceId": "EBAY_US",
      "categoryTypes": [
        {
          "name": "ALL_EXCLUDING_MOTORS_VEHICLES",
          "default": false
        }
      ],
      "paymentMethods": [
        {
          "paymentMethodType": "PERSONAL_CHECK"
        }
      ],
      "immediatePay": false,
      "paymentPolicyId": "5458288000"
    }
  ]
}



Change History

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