DoExpressCheckoutPayment API Operation (SOAP)

The DoExpressCheckoutPayment API operation completes an Express Checkout transaction. If you set up a billing agreement in your SetExpressCheckout API call, the billing agreement is created when you call the DoExpressCheckoutPayment API operation.

DoExpressCheckoutPayment Request Message

DoExpressCheckoutPayment Request Fields

Field Description

Token

xs:string

(Required) The timestamped token value that was returned in the SetExpressCheckout response and passed in the GetExpressCheckoutDetails request.

Character length and limitations: 20 single-byte characters.

PayerID

ebl:UserIDType

(Required) Unique PayPal buyer account identification number as returned in the GetExpressCheckoutDetails response

Character length and limitations: 13 single-byte alphanumeric characters.

PaymentDetails

ebl:PaymentDetailsType

(Required) Information about the payment.

UserSelectedOptions

ebl:UserSelectedOptionsType

(Optional) Shipping options and insurance selected by the buyer.

ReturnFMFDetails

xs:int

(Optional) Flag to indicate whether you want the results returned by Fraud Management Filters. By default, you do not receive this information. It is one of the following values:

  • 0 – Do not receive FMF details (default).

  • 1 – Receive FMF details.

GiftMessage

xs:string

(Optional) The gift message the buyer entered on the PayPal pages.

Character length and limitations: 150 single-byte characters

GiftReceiptEnable

xs:string

(Optional) Whether the buyer selected a gift receipt on the PayPal pages. It is one of the following values:

  • true – The buyer selected a gift message.

  • false – The buyer did not select a gift message.

GiftWrapName

xs:string

(Optional) Return the gift wrap name only if the buyer selected the gift option on the PayPal pages.

Character length and limitations: 25 single-byte characters

GiftWrapAmount

ebl:BasicAmounttType

(Optional) Amount only if the buyer selected the gift option on the PayPal pages.

Note You must set the currencyID attribute to one of the three-character currency codes for any of the supported PayPal currencies.

Character length and limitations: Value is a positive number which cannot exceed 10,000.00 USD or the per transaction limit for the currency. It includes no currency symbol. Most currencies require 2 decimal places, the decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Some currencies do not allow decimals. See the currency codes page for details.

BuyerMarketingEmail

ebl:EmailAddressType

(Optional) The buyer email address opted in by the buyer on the PayPal pages.

Character length and limitations: 127 single-byte characters

SurveyQuestion

xs:string

(Optional) Survey question on the PayPal pages.

Limitations: 50 single-byte characters

SurveyChoiceSelected

xs:string

(Optional) Survey response that the buyer selected on the PayPal pages.

Character length and limitations: 15 single-byte characters

ButtonSource

xs:string

(Optional) Identification code for use by third-party applications to identify transactions.

Character length and limitations: 32 single-byte alphanumeric characters

SkipBACreation

xs:boolean

(Optional) Merchant specified flag which indicates whether to create a billing agreement as part of DoExpressCheckout or not. This field is used for reference transactions during billing agreement creation. Merchants who offer a store account can control whether PayPal must create a billing agreement or if billing agreement creation should be skipped. Set the value of this field to true to skip the creation of a billing agreement ID.

UseSessionPaymentDetails

xs:string

(Optional) Merchant specified flag which indicates whether to use the payment details information provided in SetExpressCheckoutDetails or in DoExpressCheckoutPayment. Possible values are true, false, 1, 0. If this is set to true or 1, the payment details information would be used from what was passed in SetExpressCheckoutDetails. Any change in the paymentdetails passed in DoExpressCheckoutPayment will be ignored if this field is set to true.

Added in version 112 of the API.

AddressType Fields

Field Description

Name

xs:string

Person's name associated with this shipping address. It is required if using a shipping address.

Character length and limitations: 32 single-byte characters

Street1

xs:string

First street address. It is required if using a shipping address.

Character length and limitations: 100 single-byte characters

Street2

xs:string

(Optional) Second street address.

Character length and limitations: 100 single-byte characters

CityName

xs:string

Name of city. It is required if using a shipping address.

Character length and limitations: 40 single-byte characters

StateOrProvince

xs:string

State or province.
It is required if the address is in one of the following countries: Argentina, Brazil, Canada, China, Indonesia, India, Japan, Mexico, Thailand or USA. PayPal accepts State codes for some countries.

Character length and limitations: 40 single-byte characters

PostalCode

xs:string

U.S. ZIP code or other country-specific postal code. It is required if using a U.S. shipping address and may be required for other countries.

Character length and limitations: 20 single-byte characters

Country

ebl:CountryCodeType

Country code. It is required if using a shipping address.

Character length and limitations: 2 single-byte characters

Phone

xs:string

(Optional) Phone number.

Character length and limitations: 20 single-byte characters

PaymentDetailsType Fields

When implementing parallel payments, you can create up to 10 sets of payment details type parameter fields, each representing one payment you are hosting on your marketplace.

Field Description

OrderTotal

ebl:BasicAmountType

(Required) The total cost of the transaction to the buyer. If shipping cost (not applicable to digital goods) and tax charges are known, include them in this value. If not, this value should be the current sub-total of the order. If the transaction includes one or more one-time purchases, this field must be equal to the sum of the purchases. Set this field to 0 if the transaction does not include a one-time purchase such as when you set up a billing agreement for a recurring payment that is not immediately charged. When the field is set to 0, purchase-specific fields are ignored. For digital goods, the following must be true:

  • total cost > 0

  • total cost <= total cost passed in the call to SetExpressCheckout

Note You must set the currencyID attribute to one of the 3-character currency codes for any of the supported PayPal currencies.

When multiple payments are passed in one transaction, all of the payments must have the same currency code.

Character length and limitations: Value is a positive number which cannot exceed 10,000.00 USD or the per transaction limit for the currency. It includes no currency symbol. Most currencies require 2 decimal places, the decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Some currencies do not allow decimals. See the currency codes page for details.

ItemTotal

ebl:BasicAmountType

Sum of cost of all items in this order. For digital goods, this field is required. PayPal recommends that you pass the same value in the call to DoExpressCheckoutPayment that you passed in the call to SetExpressCheckout.

Note You must set the currencyID attribute to one of the 3-character currency codes for any of the supported PayPal currencies.

Character length and limitations: Value is a positive number which cannot exceed 10,000.00 USD or the per transaction limit for the currency. It includes no currency symbol. Most currencies require 2 decimal places, the decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Some currencies do not allow decimals. See the currency codes page for details.

ShippingTotal

ebl:BasicAmountType

(Optional) Total shipping costs for this order.

Note You must set the currencyID attribute to one of the 3-character currency codes for any of the supported PayPal currencies.

Character length and limitations: Value is a positive number which cannot exceed 10,000.00 USD or the per transaction limit for the currency. It includes no currency symbol. Most currencies require 2 decimal places, the decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Some currencies do not allow decimals. See the currency codes page for details..

InsuranceTotal

ebl:BasicAmountType

(Optional) Total shipping insurance costs for this order. The value must be a non-negative currency amount or null if you offer insurance options.

Note You must set the currencyID attribute to one of the 3-character currency codes for any of the supported PayPal currencies.

Character length and limitations: Value is a positive number which cannot exceed 10,000.00 USD or the per transaction limit for the currency. It includes no currency symbol. Most currencies require 2 decimal places, the decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Some currencies do not allow decimals. See the currency codes page for details.

InsuranceTotal is available since version 53.0.

ShippingDiscount

ebl:BasicAmountType

(Optional) Shipping discount for this order, specified as a negative number.

Note You must set the currencyID attribute to one of the 3-character currency codes for any of the supported PayPal currencies.

Character length and limitations: Value is a negative number. It includes no currency symbol. Most currencies require 2 decimal places, the decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Some currencies do not allow decimals. See the currency codes page for details.

ShippingDiscount is available since version 53.0.

InsuranceOptionOffered

xs:boolean

(Optional) Indicates whether insurance is available as an option the buyer can choose on the PayPal Review page. Is one of the following values:

  • true – The Insurance option displays the string 'Yes' and the insurance amount. If true, the total shipping insurance for this order must be a positive number.

  • false – The Insurance option displays 'No.'

HandlingTotal

ebl:BasicAmountType

(Optional) Total handling costs for this order.

Note You must set the currencyID attribute to one of the 3-character currency codes for any of the supported PayPal currencies.

Character length and limitations: Value is a positive number which cannot exceed 10,000.00 USD or the per transaction limit for the currency. It includes no currency symbol. Most currencies require 2 decimal places, the decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Some currencies do not allow decimals. See the currency codes page for details.

TaxTotal

ebl:BasicAmountType

(Optional) Sum of tax for all items in this order.

Note You must set the currencyID attribute to one of the 3-character currency codes for any of the supported PayPal currencies.

Character length and limitations: Value is a positive number which cannot exceed 10,000.00 USD or the per transaction limit for the currency. It includes no currency symbol. Most currencies require 2 decimal places, the decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Some currencies do not allow decimals. See the currency codes page for details.

OrderDescription

xs:string

(Optional) Description of items the buyer is purchasing.

Note

The value you specify is available only if the transaction includes a purchase. This field is ignored if you set up a billing agreement for a recurring payment that is not immediately charged.

Character length and limitations: 127 single-byte alphanumeric characters

Custom

xs:string

(Optional) A free-form field for your own use.

Note The value you specify is available only if the transaction includes a purchase. This field is ignored if you set up a billing agreement for a recurring payment that is not immediately charged.

Character length and limitations: 256 single-byte alphanumeric characters

InvoiceID

xs:string

(Optional) Your own invoice or tracking number.

Important: The value you specify is available only if the transaction includes a purchase. This field is ignored if you set up a billing agreement for a recurring payment that is not immediately charged.

Note PayPal recommends using the InvoiceID field to associate transactions with your internal tracking IDs or invoice numbers; populating the invoice ID field will help you pull transaction information at a later date using only your internal ID.

Character length and limitations: 256 single-byte alphanumeric characters

NotifyURL

xs:string

(Optional) Your URL for receiving Instant Payment Notification (IPN) about this transaction. If you do not specify this value in the request, the notification URL from your Merchant Profile is used, if one exists.

Important: The notify URL applies only to DoExpressCheckoutPayment. This value is ignored when set in SetExpressCheckout or GetExpressCheckoutDetails.

Character length and limitations: 2,048 single-byte alphanumeric characters

ShipToAddress

ns:AddressType

(Optional) Address to which the order is shipped.

MultiShipping

xs:string

(Optional) The value 1 indicates that this payment is associated with multiple shipping addresses.

Character length and limitations: Four single-byte numeric characters.

PaymentDetailsItem

ebl:PaymentDetailsItemType

(Optional) Details about each individual item included in the order.

EnhancedPaymentData

ed:EnhancedPaymentDataType

(Optional) Enhanced Data section to accept channel-specific data (eBay).

PaymentCategoryType

ebl:PaymentCategoryType

(Optional) Category of a payment. Possible values are:
InternationalShipping
LocalDelivery

NoteText

xs:string

(Optional) Note to the merchant.

Character length and limitations: 255 single-byte characters

SoftDescriptor

xs:string

A per transaction description of the payment that is passed to the buyer's credit card statement.

Note Ignore when PaymentAction=Order.

SellerDetails

ns:SellerDetailsType

(Optional) Details about the merchant. This information is used for emails sent out for eBay transactions.

TransactionId

xs:string

(Optional) Transaction identification number of the transaction that was created.

Note This field is only returned after a successful transaction for DoExpressCheckout has occurred.

AllowedPaymentMethodType

xs:string

(Optional) The payment method type. Specify the value InstantPaymentOnly.

PaymentAction

ebl:PaymentActionCodeType

How you want to obtain payment. When implementing parallel payments, this field is required and must be set to Order. When implementing digital goods, this field is required and must be set to Sale. If the transaction does not include a one-time purchase, this field is ignored. It is one of the following values:

  • Sale – This is a final sale for which you are requesting payment (default).

  • Authorization – This payment is a basic authorization subject to settlement with PayPal Authorization and Capture.

  • Order – This payment is an order authorization subject to settlement with PayPal Authorization and Capture.

Note You cannot set this field to Sale in SetExpressCheckout request and then change the value to Authorization or Order in the DoExpressCheckoutPayment request. If you set the field to Authorization or Order in SetExpressCheckout, you may set the field to Sale.

Character length and limitations: Up to 13 single-byte alphabetic characters

PaymentRequestID

xs:string

A unique identifier of the specific payment request. Required when implementing parallel payments.

Character length and limitations: Up to 127 single-byte characters

RedeemedOffers

ebl:DiscountInfoType

(Optional) The buyer's wallet items redeemed in this transaction, such as, a merchant coupon or a loyalty program.

Limitations: Maximum count is 100

Note This field will be added in version 113 on 4/22/2014.

CummulativePoints

ebl:DiscountInfoType

(Optional) The buyer's loyalty points accumulated by the consumer so far.

Limitations: Maximum count is 100

Note This field will be added in version 113 on 4/22/2014.

PaymentDetailsItemType Fields

Field Description

Name

xs:string

Item name. This field is required when you pass a value for ItemCategory.

Character length and limitations: 127 single-byte characters

This field is introduced in version 53.0.

Description

xs:string

(Optional) Item description.

Character length and limitations: 127 single-byte characters

This field is introduced in version 53.0.

Amount

ebl:BasicAmountType

Cost of item. This field is required when you pass a value for ItemCategory.

Note You must set the currencyID attribute to one of the 3-character currency codes for any of the supported PayPal currencies.

Character length and limitations: Value is a positive number which cannot exceed 10,000.00 USD or the per transaction limit for the currency. It includes no currency symbol. Most currencies require 2 decimal places, the decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Some currencies do not allow decimals. See the currency codes page for details.

This field is introduced in version 53.0.

Number

xs:string

(Optional) Item number.

Character length and limitations: 127 single-byte characters

This field is introduced in version 53.0.

Quantity

xs:integer

Item quantity. This field is required when you pass a value for ItemCategory. For digital goods (ItemCategory=Digital), this field is required.

Character length and limitations: Any positive integer

This field is introduced in version 53.0.

Tax

ebl:BasicAmountType

(Optional) Item sales tax.

Note You must set the currencyID attribute to one of the 3-character currency codes for any of the supported PayPal currencies.

Character length and limitations: Value is a positive number which cannot exceed 10,000.00 USD or the per transaction limit for the currency. It includes no currency symbol. Most currencies require 2 decimal places, the decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Some currencies do not allow decimals. See the currency codes page for details.

ItemWeight

xs:integer

(Optional) Item weight corresponds to the weight of the item. You can pass this data to the shipping carrier as is without having to make an additional database query.

Character length and limitations: Any positive integer

ItemLength

xs:integer

(Optional) Item length corresponds to the length of the item. You can pass this data to the shipping carrier as is without having to make an additional database query.

Character length and limitations: Any positive integer

ItemWidth

xs:integer

(Optional) Item width corresponds to the width of the item. You can pass this data to the shipping carrier as is without having to make an additional database query.

Character length and limitations: Any positive integer

ItemHeight

xs:integer

(Optional) Item height corresponds to the height of the item. You can pass this data to the shipping carrier as is without having to make an additional database query.

Character length and limitations: Any positive integer

EbayItemPayment DetailsItem

ebl:ebayItemPaymentDetailsItemType

(Optional) Information relating to an auction sale on eBay.

ItemURL

xs:string

(Optional) URL for the item.

EnhancedItemData

ed:EnhancedItemDataType

(Optional) Enhanced data for each item in the cart. For eBay use only.

ItemCategory

ns:ItemCategoryType

Indicates whether an item is digital or physical. For digital goods, this field is required and must be set to Digital. It is one of the following values:

  • Digital

  • Physical

This field is available since version 65.1.

EbayItemPaymentDetailsItemType Fields

Field Description

ItemNumber

xs:string

(Optional) Auction item number.

Character length: 765 single-byte characters

AuctionTransactionId

xs:string

(Optional) Auction transaction identification number.

Character length: 255 single-byte characters

OrderID

xs:string

(Optional) Auction order identification number.

Character length: 64 single-byte characters

CartID

xs:string

(Optional) The unique identifier provided by eBay for this order from the buyer.

Character length: 255 single-byte characters

DiscountInfoType Fields

Note These fields will be added in version 113 on 4/22/2014.

Describes discount information.

Fields Description

Name

xs:string

(Optional) Item name.

Character length and limits: 127 single-byte characters

Description

xs:string

(Optional) Description of the discount.

Character length and limits: 127 single-byte characters

Amount

cc:BasicAmountType

(Optional) Amount discounted.

Note You must set the currencyID attribute to one of the 3-character currency codes for any of the supported PayPal currencies.

Character length and limitations: Value is a positive number which cannot exceed 10,000.00 USD or the per transaction limit for the currency. It includes no currency symbol. Most currencies require 2 decimal places, the decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Some currencies do not allow decimals. See the currency codes page for details..

RedeemedOfferType

ns:RedeemedOfferType

(Optional) Offer type.

It is one of the following:

  • LOYALTY_CARD
  • MERCHANT_COUPON

RedeemedOfferId

xs:string

(Optional) Offer ID.

Character length and limits: 64 single-byte characters.

PointsAccrued

xs:decimal

(Optional) Loyalty points accrued.

UserSelectedOptionsType Fields

Field Description

InsuranceOptionSelected

xs:boolean

(Optional) The option that the buyer chose for insurance. It is one of the following values:

  • Yes – The buyer opted for insurance.

  • No – The buyer did not opt for insurance.

ShippingOptionIsDefault

xs:boolean

(Optional) Whether the buyer chose the default shipping option. It is one of the following values:

  • true – The buyer chose the default shipping option.

  • false – The buyer did not choose the default shipping option.

ShippingOptionAmount

ebl:BasicAmountType

(Optional) The shipping amount that the buyer chose.

Character length and limitations: Value is a positive number which cannot exceed 10,000.00 USD or the per transaction limit for the currency. It includes no currency symbol. Most currencies require 2 decimal places, the decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Some currencies do not allow decimals. See the currency codes page for details.

ShippingOptionName

xs:string

(Optional) The name of the shipping option, such as air or ground.

SellerDetailsType Fields

Field Description

SellerID

xs:string

(Optional) Unique non-changing identifier for the merchant at the marketplace site. This ID is not displayed.

Character length and limitations: 13 single-byte alphanumeric characters

SellerUserName

xs:string

(Optional) Current name of the merchant or business at the marketplace site. This name may be shown to the buyer.

SellerRegistrationDate

xs:dateTime

(Optional) Date when the merchant registered with the marketplace.

Character length and limitations: Must be a valid date, in UTC/GMT format; for example, 2013-08-24T05:38:48Z. No wildcards are allowed.

DoExpressCheckoutPayment Response Message

DoExpressCheckoutPayment Response Fields

Field Description

Token

xs:string

The timestamped token value that was returned by SetExpressCheckout response and passed on GetExpressCheckoutDetails request.

Character length and limitations: 20 single-byte characters

PaymentInfo

ebl:PaymentInfoType

Information about the payment.

Note

xs:string

The text entered by the buyer on the PayPal website if you set the AllowNote field to 1 in SetExpressCheckout.

This field is available since version 53.0.

Character length and limitations: 255 single-byte characters

RedirectRequired

xs:boolean

Flag to indicate whether you need to redirect the buyer back to PayPal after successfully completing the transaction.

If set to true, you can redirect users to the following URL with the token value appended:

https://www.paypal.com/cgi-bin/webscr?cmd=_complete-express-checkout&token=(token)

Note Use this field only if you are using giropay or bank transfer payment methods in Germany.

SuccessPageRedirectRequested

xs:boolean

Flag to indicate whether you would like to redirect the buyer to sign up for

PayPal after completing the transaction.

If set to true, you can redirect users to the following URL with the token value appended::

https://www.paypal.com/cgi-bin/webscr?cmd=_express-checkout-success&token=(token)

BillingAgreementID

xs:string

The ID of the billing agreement associated with the Express Checkout transaction.

CoupledPaymentInfo

ebl:CoupledPaymentInfoType

Information about coupled payment transactions.

ShipAmount

xs:string

Amount of shipping charged on this transaction.

Character length and limitations: Value is a positive number which cannot exceed 10,000.00 USD or the per transaction limit for the currency. It includes no currency symbol. Most currencies require 2 decimal places, the decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Some currencies do not allow decimals. See the currency codes page for details.

SellerId

xs:string

Unique, non-changing identifier for the merchant at the marketplace site. (Optional)

Character length and limitations: 13 single-byte alphanumeric characters.

SellerUserName

xs:string

Current name of the merchant or business at the marketplace site. This name may be shown to the buyer.

SellerRegistrationDate

xs:dateTime

Date when the merchant registered with the marketplace.

Character length and limitations: Date and time are in UTC/GMT format; for example, 2013-08-24T05:38:48Z.

ParentTransactionID

ns:TransactionId

Parent or related transaction identification number. This field is populated for the following transaction types:

  • Reversal

  • Capture of an authorized transaction

  • Reauthorization of a transaction

  • Capture of an order. The value of ParentTransactionID is the original OrderID.

  • Authorization of an order. The value of ParentTransactionID is the original OrderID.

  • Capture of an order authorization

  • Void of an order. The value of ParentTransactionID is the original OrderID.

Character length and limits: 19 single-byte characters maximum.

ReceiptID

ns:ReceiptID

Character length and limitations: 16 digits in xxxx-xxxx-xxxx-xxxx format.

ExpectedeCheckClearDate

xs:dateTime

eCheck latest expected clear date.

ShippingMethod

xs:string

Shipping method selected by the user during check-out.

OfferCode

xs:string

Code used to identify the promotion offer.

OfferTrackingID

xs:string

Unique identification for merchant/buyer/offer combo.

PaymentInfoType Fields

When implementing parallel payments, up to 10 payment information type sets of payment information type parameter fields can be returned, each representing one payment you are hosting on your marketplace.

Field Description

TransactionID

xs:string

Unique transaction ID of the payment.

Note If the PaymentAction of the request was Authorization or Order, this value is your AuthorizationID for use with the Authorization & Capture APIs.

Character length and limitations: 19 single-byte characters

TransactionType

ns:PaymentTransactionCodeType

Type of transaction. It is one of the following values:

  • cart

  • express-checkout

Character length and limitations: 15 single-byte characters

PaymentType

ebl:PaymentCodeType

Indicates whether the payment is instant or delayed. It is one of the following values:

  • none

  • echeck

  • instant

Character length and limitations: 7 single-byte characters

PaymentDate

xs:dateTime

Date/time stamp of the payment.

Character length and limitations: Date and time are in UTC/GMT format; for example, 2013-08-24T05:38:48Z.

GrossAmount

ebl:BasicAmountType

The final amount charged, including any shipping and taxes from your Merchant Profile.

Character length and limitations: Value is a positive number which cannot exceed 10,000.00 USD or the per transaction limit for the currency. It includes no currency symbol. Most currencies require 2 decimal places, the decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Some currencies do not allow decimals. See the currency codes page for details.

FeeAmount

ebl:BasicAmountType

PayPal fee amount charged for the transaction.

Character length and limitations: Value is a positive number which cannot exceed 10,000.00 USD or the per transaction limit for the currency. It includes no currency symbol. Most currencies require 2 decimal places, the decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Some currencies do not allow decimals. See the currency codes page for details.

SettleAmount

ebl:BasicAmountType

Amount deposited in your PayPal account after a currency conversion.

Character length and limitations: Value is a positive number which cannot exceed 10,000.00 USD or the per transaction limit for the currency. It includes no currency symbol. Most currencies require 2 decimal places, the decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Some currencies do not allow decimals. See the currency codes page for details.

TaxAmount

ebl:BasicAmountType

Tax charged on the transaction.

Character length and limitations: Value is a positive number which cannot exceed 10,000.00 USD or the per transaction limit for the currency. It includes no currency symbol. Most currencies require 2 decimal places, the decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Some currencies do not allow decimals. See the currency codes page for details.

ExchangeRate

xs:string

Exchange rate if a currency conversion occurred. Relevant only if your are billing in their non-primary currency. If the buyer chooses to pay with a currency other than the non-primary currency, the conversion occurs in the buyer's account.

Character length and limitations: Decimal value that does not exceed 17 characters, including decimal point

PaymentStatus

ebl:PaymentStatusCodeType

The status of the payment. It is one of the following values:

  • None – No status.

  • Canceled-Reversal – A reversal has been canceled; for example, when you win a dispute and the funds for the reversal have been returned to you.

  • Completed – The payment has been completed, and the funds have been added successfully to your account balance.

  • Denied – You denied the payment. This happens only if the payment was previously pending because of possible reasons described for the PendingReason element.

  • Expired – the authorization period for this payment has been reached.

  • Failed – The payment has failed. This happens only if the payment was made from your buyer's bank account.

  • In-Progress – The transaction has not terminated, e.g. an authorization may be awaiting completion.

  • Partially-Refunded – The payment has been partially refunded.

  • Pending – The payment is pending. See the PendingReason field for more information.

  • Refunded – You refunded the payment.

  • Reversed – A payment was reversed due to a chargeback or other type of reversal. The funds have been removed from your account balance and returned to the buyer. The reason for the reversal is specified in the ReasonCode element.

  • Processed – A payment has been accepted.

  • Voided – An authorization for this transaction has been voided.

  • Completed-Funds-Held – The payment has been completed, and the funds have been added successfully to your pending balance.

    See the HoldDecision field for more information.

PendingReason

ebl:PendingStatusCodeType

Reason the payment is pending. It is one of the following values:

  • none – No pending reason.

  • address – The payment is pending because your buyer did not include a confirmed shipping address and your Payment Receiving Preferences is set such that you want to manually accept or deny each of these payments. To change your preference, go to the Preferences section of your Profile.

  • authorization – The payment is pending because it has been authorized but not settled. You must capture the funds first.

  • echeck – The payment is pending because it was made by an eCheck that has not yet cleared.

  • intl – The payment is pending because you hold a non-U.S. account and do not have a withdrawal mechanism. You must manually accept or deny this payment from your Account Overview.

  • multi-currency – You do not have a balance in the currency sent, and you do not have your Payment Receiving Preferences set to automatically convert and accept this payment. You must manually accept or deny this payment.

  • order – The payment is pending because it is part of an order that has been authorized but not settled.

  • paymentreview – The payment is pending while it is being reviewed by PayPal for risk.

  • regulatory-review - The payment is pending while we make sure it meets regulatory requirements. You will be contacted again in 24-72 hours with the outcome of the review.
  • unilateral – The payment is pending because it was made to an email address that is not yet registered or confirmed.

  • verify – The payment is pending because you are not yet verified. You must verify your account before you can accept this payment.

  • other – The payment is pending for a reason other than those listed above. For more information, contact PayPal customer service.

Note PendingReason is returned in the response only if PaymentStatus is Pending.

ReasonCode

ebl:ReasonCodeType

Reason for a reversal if TransactionType is reversal. It is one of the following values:

  • none – No reason code.

  • chargeback – A reversal has occurred on this transaction due to a chargeback by your buyer.

  • guarantee – A reversal has occurred on this transaction due to your buyer triggering a money-back guarantee.

  • buyer-complaint – A reversal has occurred on this transaction due to a complaint about the transaction from your buyer.

  • refund – A reversal has occurred on this transaction because you have given the buyer a refund.

  • other – A reversal has occurred on this transaction due to a reason not listed above.

HoldDecision

xs:string

Reason that this payment is being held. It is one of the following values:

  • newsellerpaymenthold – This is a new merchant.

  • paymenthold – A hold is placed on the merchant's transaction for a reason not listed.

This field is available since version 71.0 and is returned only if PaymentStatus is Completed-Funds-Held.

ProtectionEligibility

xs:string

Prior to version 64.4, the kind of seller protection in force for the transaction. It is one of the following values:

  • Eligible – Merchant is protected by PayPal's Seller Protection Policy for Unauthorized Payments and Item Not Received.

  • PartiallyEligible – Merchant is protected by PayPal's Seller Protection Policy for Item Not Received.

  • Ineligible – Merchant is not protected under the Seller Protection Policy.

ProtectionEligibilityType

xs:string

Since version 64.4, the kind of seller protection in force for the transaction. It is one of the following values:

  • Eligible – Merchant is protected by PayPal's Seller Protection Policy for both Unauthorized Payment and Item Not Received

  • ItemNotReceivedEligible – Merchant is protected by PayPal's Seller Protection Policy for Item Not Received

  • UnauthorizedPaymentEligible – Merchant is protected by PayPal's Seller Protection Policy for Unauthorized Payment

  • Ineligible – Merchant is not protected under the Seller Protection Policy

This field is available since version 64.4.

StoreId

xs:string

StoreId as entered in the transaction

TerminalId

xs:string

TerminalId as entered in the transaction

EbayTransactionId

xs:string

eBay transaction identification number.

Character length and limitations: 255 single-byte characters

PaymentRequestID

xs:string

Unique identifier of the specific payment request. The value should match the one you passed in the DoExpressCheckout request.

Character length and limitations: Up to 127 single-byte characters

EnhancedPaymentInfo

xs:EnhancedPaymentInfoType

Enhanced payment information.

SellerDetails

xs:SellerDetailsType

Details about this merchant.

FMFDetails

xs:FMFDetailsType

List of fraud management filters.

PaymentError

ns:ErrorType

Indicates the payment status for an individual payment request in the case of parallel payments.

InstrumentDetails

ns:InstrumentDetailsType

Type of the payment instrument.

InstrumentDetailsType Fields

Field Description

InstrumentCategory

xs:string

Returns the category of the instrument only when it is promotional. Possible values are:
1 represents Bill Me Later

InstrumentID

xs:string

Reserved for future use.
Returns an instrument ID (issued by the external party) corresponding to the funding source used in the payment.

UserSelectedOptions Fields

Field Description

ShippingCalculationMode

xs:string

Describes how the options that were presented to the buyer were determined. It is one of the following values:

  • API - Callback

  • API - Flatrate

InsuranceOptionSelected

xs:boolean

The option that the buyer chose for insurance. It is one of the following values:

  • Yes – The buyer opted for insurance.

  • No – The buyer did not opt for insurance.

ShippingOptionIsDefault

xs:boolean

Indicates whether the buyer chose the default shipping option. It is one of the following values:

  • true – The buyer chose the default shipping option.

  • false – The buyer did not choose the default shipping option.

Character length and limitations: true or false

ShippingOptionAmount

ebl:BasicAmountType

The shipping amount that the buyer chose.

Character length and limitations: Value is a positive number which cannot exceed 10,000.00 USD or the per transaction limit for the currency. It includes no currency symbol. Most currencies require 2 decimal places, the decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Some currencies do not allow decimals. See the currency codes page for details.

ShippingOptionName

xs:string

The name of the shipping option, such as air or ground.

PaymentErrorType Fields

Field Description

ShortMessage

xs:string

Payment error short message.

LongMessage

xs:string

Payment error long message.

ErrorCode

xs:string

Payment error code.

SeverityCode

xs:string

Payment error severity code.

ErrorParameters

xs:string

Application-specific error values indicating more about the error condition.

SellerDetailsType Fields

Field Description

PayPalAccountID

xs:string

Unique identifier for the merchant. For parallel payments, this field contains either the Payer Id or the email address of the merchant.

Character length and limitations: 127 single-byte alphanumeric characters

SecureMerchantAccountID

xs:useridtype

Unique PayPal customer account number (of the merchant). This field is returned in the response. It is ignored if passed in the request.

FMFDetailsType Fields

Field Description

AcceptFilters

xs:RiskFilterListType

List of filters that recommend acceptance of the payment.

DenyFilters

xs:RiskFilterListType

List of filters that recommend denial of the payment.

PendingFilters

xs:RiskFilterListType

List of filters that caused the payment to become pending.

ReportsFilters

xs:RiskFilterListType

List of filters that caused the payment to become flagged.

RiskFilterListType Fields

Field Description

ID

xs:int

Filter ID. It is one of the following values:

  • 1 - AVS No Match

  • 2 - AVS Partial Match

  • 3 - AVS Unavailable/Unsupported

  • 4 - Card Security Code (CSC) Mismatch

  • 5 - Maximum Transaction Amount

  • 6 - Unconfirmed Address

  • 7 - Country Monitor

  • 8 - Large Order Number

  • 9 - Billing/Shipping Address Mismatch

  • 10 - Risky ZIP Code

  • 11 - Suspected Freight Forwarder Check

  • 12 - Total Purchase Price Minimum

  • 13 - IP Address Velocity

  • 14 - Risky Email Address Domain Check

  • 15 - Risky Bank Identification Number (BIN) Check

  • 16 - Risky IP Address Range

  • 17 - PayPal Fraud Model

Name

xs:string

Filter name.

Description

xs:string

Filter description.

Deprecated Fields

The following fields have been deprecated. Use the newer fields in the following tables instead.

Deprecated DoExpressCheckoutPayment Request Field

The following field has been deprecated.

Field Description
PaymentAction Use the PaymentAction field in PaymentDetailsType Fields instead.

Deprecated PaymentDetailsType Field

The following field has been deprecated since version 63.0.

Field Description
ButtonSource Use the ButtonSource field in DoExpressCheckoutPayment Request Fields instead.

Deprecated DoExpressCheckoutPayment Response Field

The following field has been deprecated since version 63.0.

Field Description
FMFDetails Use the FMFDetails field in PaymentInfoType Fields instead.