GetExpressCheckoutDetails API Operation (SOAP)

APILegacyLast updated: October 12th 2021, @ 6:58:00 pm


Important: NVP/SOAP is a legacy integration method. We accept new integrations and support existing integrations, but there are newer solutions. If you're starting an integration, we recommend our latest solutions.

Shows information about an Express Checkout transaction.

GetExpressCheckoutDetails Request Message

GetExpressCheckoutRequestType Diagram

Note: Only the fields described in this documentation are available for use.

GetExpressCheckoutDetails Request Fields

FieldDescription

Token

xs:string

(Required) A timestamped token, the value of which was returned by SetExpressCheckout response.

Character length and limitations: 20 single-byte characters

GetExpressCheckoutDetails Response Message

GetExpressCheckoutDetails Response Fields

FieldDescription

Token

xs:string

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

Character length and limitations: 20 single-byte characters

Custom

xs:string

A free-form field for your own use, as set by you in the Custom element of the SetExpressCheckout request.

Character length and limitations: 256 single-byte alphanumeric characters

PayerInfo

ebl:PayerInfoType

Information about the payer.

InvoiceID

xs:string

Your own invoice or tracking number, as set by you in the element of the same name in the SetExpressCheckout request.

Character length and limitations: 127 single-byte alphanumeric characters

ContactPhone

xs:string

Buyer's contact phone number.

Note: PayPal returns a contact phone number only if your Merchant Account Profile settings require that the buyer enter one.

Character length and limitations: Field mask is XXX-XXX-XXXX (for US numbers) or +XXX XXXXXXXX (for international numbers)

BillingAgreementAcceptedStatus

xs:boolean

Indicates whether the buyer accepted the billing agreement for a recurring payment. Currently, this field is always returned in the response for agreement based products, such as, subscriptions, reference transactions and recurring payments, as well as for regular single payment transactions.

Note: Starting in 2015, in release 120, this field will no longer be returned for single payment transactions.

RedirectRequired

xs:boolean

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

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

BillingAddress

ebl:AddressType

The buyer's billing address. If a credit card is stored in the buyer's account, then the card billing address is returned; otherwise, the buyer's primary address is returned.

CheckoutStatus

ebl:CheckoutStatusType

Status of the checkout session. If payment is completed, the transaction identification number of the resulting transaction is returned. Value is:

  • PaymentActionNotInitiated
  • PaymentActionFailed
  • PaymentActionInProgress
  • PaymentActionCompleted

PayPalAdjustment

cc:BasicAmountType

A discount or gift certificate offered by PayPal to the buyer. This amount is represented by a negative amount. If the buyer has a negative PayPal account balance, PayPal adds the negative balance to the transaction amount, which is represented as a positive value.

Character length and limitations: `partial:partials/docs/shared/cl_currencylimit_neg.en-XC`

PaymentDetails

ebl:PaymentDetailsType

Information about the purchased items.

UserSelectedOptions

ebl:UserSelectedOptionsType

Shipping options and insurance.

IncentiveDetails

ebl:IncentiveDetailsType

Information about the incentives that were applied from the Ebay Review Your Payment page or PayPal Review Your Payment page.

BuyerMarketingEmail

ebl:EmailAddressType

Buyer's email address if the buyer provided it on the PayPal pages.

Character length and limitations: 127 single-byte characters

PaymentRequestInfo

ebl:PaymentRequestInfoType

Payment request information for each bucket in the cart.

PaymentInfo

ebl:PaymentInfoType

Information about the transaction.

CartChangeTolerance

xs:string

Indicates whether a cart's contents can be modified. If this parameter is not returned, then assume the cart can be modified.

Value is:

  • NONE — The cart cannot be changed because financing was used and the country is Germany.
  • FLEXIBLE — The cart can be changed.

InstrumentDetails

ebl:InstrumentDetailsType

Type of the payment instrument.

PayerInfoType Fields

FieldDescription

Payer

ebl:EmailAddressType

Email address of buyer.

Character length and limitations: 127 single-byte characters

PayerID

ebl:UserIDType

Unique PayPal Customer Account identification number.

Character length and limitations: 13 single-byte alphanumeric characters

PayerStatus

ebl:PayPalUserStatusCodeType

Status of buyer. Value is:

  • verified
  • unverified

Character length and limitations: 10 single-byte alphabetic characters

PayerName

ebl:PersonNameType

First and last name of buyer.

PayerCountry

ebl:CountryCodeType

Buyer's country of residence in the form of ISO standard 3166 two-character country codes.

Character length and limitations: 2 single-byte characters

PayerBusiness

xs:string

Buyer's business name.

Character length and limitations: 127 single-byte characters

Address

ebl:AddressType

Buyer's shipping address information.

ContactPhone

xs:string

Business contact telephone number.

WalletItems

ebl:WalletItemsType

Details about items stored in the buyer's PayPal Wallet. This includes items, such as, merchant coupons and loyalty cards.

InstrumentDetails

ebl:InstrumentDetailsType

Details about any promotional payment instruments used in the payment.

TaxIdDetails

ebl:TaxIdDetailsType

Details about the buyer's tax information.

This field is introduced in API version 72.0.

PersonNameType Fields

FieldDescription

FirstName

ebl:PersonNameType

Buyer's first name.

Character length and limitations: 64 double-byte characters

MiddleName

ebl:NameUser

Buyer's middle name.

Character length and limitations: 64 double-byte characters

LastName

ebl:NameType

Buyer's last name.

Character length and limitations: 64 double-byte characters

Suffix

ebl:SuffixType

Buyer's suffix.

Character length and limitations: 12 single-byte characters

AddressType Fields

FieldDescription

Name

xs:string

Person's name associated with this shipping address.

Character length and limitations: 128 double-byte characters

Street1

xs:string

First street address.

Character length and limitations: 300 single-byte characters

Street2

xs:string

Second street address.

Character length and limitations: 300 single-byte characters

CityName

xs:string

Name of city.

Character length and limitations: 40 single-byte characters

StateOrProvince

xs:string

`partial:partials/docs/shared/cl_shiptostate.en-XC`

Character length and limitations: 40 single-byte characters

PostalCode

xs:string

U.S. ZIP code or other country-specific postal code.

Character length and limitations: 20 single-byte characters

Country

ebl:CountryCodeType

Country code.

Character length and limitations: 2 single-byte characters

Phone

xs:string

Phone number.

Character length and limitations: 20 single-byte characters

addressStatus

ebl:addressStatusTypeCode

Status of street address on file with PayPal. Value is:

  • none
  • Confirmed
  • Unconfirmed
AddressNormalizationStatusebl:AddressNormalizationStatusCodeType
The PayPal address normalization status for Brazilian addresses. It can have one of the following values:
  • None
  • Normalized
  • Unnormalized
  • UserPreferred

PaymentInfoType Fields

Details about the payment.

FieldDescription
PAYMENTINFO_n_CURRENCYCODE

The currency code of the financing amounts; default is USD.

Character length and limitations: Three single-byte characters.

WalletItemsType Fields

Details about items stored in the buyer's PayPal Wallet. This includes items, such as, merchant coupons and loyalty cards.

FieldDescription

Type

ebl:WalletItemType

(Optional) Identifies the type of wallet item.

It is one of the following:

  • LOYALTY_CARD
  • PRIVATE_LABEL_CREDIT_CARD
  • MERCHANT_CLOSED_LOOP_OFFER

Id

xs:string

(Optional) Unique ID of the wallet item.

Character length and limitations: 64 single-byte characters maximum.

Description

xs:string

(Optional) Description of the wallet item.

Character length and limitations: 512 single-byte characters maximum.

InstrumentDetailsType Fields

Details about any promotional payment instruments in the payment.

FieldDescription

InstrumentCategory

xs:string

(Optional) The category of the promotional payment instrument.

It is one of the following:

  • 1 — PayPal Credit® (formerly Bill Me Later®)
  • 2 — A Private Label Credit Card (PLCC) or co-branded payment card

InstrumentID

xs:string

(Optional) An instrument ID (issued by the external party) corresponding to the funding source used in the payment.

Character length and limitations: Only a single promotional funding instrument per transaction is supported at this time.

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.

FieldDescription

OrderTotal

ebl:BasicAmountType

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

Character length and limitations: `partial:partials/docs/shared/cl_currencylimit.en-XC`

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: `partial:partials/docs/shared/cl_currencylimit.en-XC`

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: `partial:partials/docs/shared/cl_currencylimit.en-XC`

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: `partial:partials/docs/shared/cl_currencylimit.en-XC`

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: `partial:partials/docs/shared/cl_currencylimit_neg.en-XC`

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 pages. 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: `partial:partials/docs/shared/cl_currencylimit.en-XC`

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: `partial:partials/docs/shared/cl_currencylimit.en-XC`

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.

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

NotifyURL

xs:string

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

FulfillmentReferenceNumber

xs:string

(Optional) The reference number associated with the third-party shipping or fulfillment center.

Character length and limitations: 32 single-byte alphanumeric characters

FulfillmentAddress

ebl:AddressType

(Optional) The address of the third-party shipping or fulfillment center

PaymentCategoryType

ebl:PaymentCategoryType

(Optional) Category of a payment. Value is:
InternationalShipping
LocalDelivery

ShipToAddress

ebl:AddressType

Address the order is shipped to.

PaymentDetailsItem

ebl:PaymentDetailsItemType

Details about each individual item included in the order.

NoteText

xs:string

Note to the merchant.

Character length and limitations: 255 single-byte characters

TransactionId

xs:string

Transaction identification number of the transaction that was created.

Note: This field is only returned after a successful transaction for DoExpressCheckout has occurred.
`partial:partials/docs/shared/cl_transactionid.en-XC`

AllowedPaymentMethodType

xs:string

The payment method type. If this is an Immediate Payment, specify the value InstantPaymentOnly.

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

PaymentDetailsItemType Fields

FieldDescription

Name

xs:string

Item name.

Character length and limitations: 127 single-byte characters

Description

xs:string

Item description.

Character length and limitations: 127 single-byte characters

This field is available since version 53.0.

Amount

ebl:BasicAmountType

Cost of item.

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: `partial:partials/docs/shared/cl_currencylimit.en-XC`

Note: If the line item is a discount, a negative value must be passed in this field.

Number

xs:string

Item number.

Character length and limitations: 127 single-byte characters

Quantity

xs:integer

Item quantity.

Character length and limitations: Any positive integer

Tax

ebl:BasicAmountType

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: `partial:partials/docs/shared/cl_currencylimit.en-XC`

ItemWeight

xs:integer

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

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

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

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

Information relating to an auction sale on eBay.

ItemCategory

ns:ItemCategoryType

Indicates whether the item is digital or physical. For digital goods (ItemCategory=Digital), this field is required. Value is:

  • Digital
  • Physical

This field is available since version 65.1.

EbayItemPaymentDetailsItemType Fields

FieldDescription

ItemNumber

xs:string

Auction item number.

Character length: 765 single-byte characters

AuctionTransactionId

xs:string

Auction transaction identification number.

Character length: 255 single-byte characters

OrderID

xs:string

Auction order identification number.

Character length: 64 single-byte characters

CartID

xs:string

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

Character length: 255 single-byte characters

UserSelectedOptionsType Fields

FieldDescription

ShippingCalculationMode

xs:string

Describes how the options that were presented to the buyer were determined. Value is:

  • API – Callback
  • API – Flatrate

InsuranceOptionSelected

xs:boolean

The option that the buyer chose for insurance. Value is:

  • 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. Value is:

  • 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: `partial:partials/docs/shared/cl_currencylimit.en-XC`

ShippingOptionName

xs:string

The name of the shipping option, such as Air or Ground.

ScheduledShippingDate

xs:string

The scheduled shipping date is returned only if scheduled shipping options are passed in the request.
Character length and limitations: A string returned in a date format that corresponds to locale of the buyer; for example, the date could be in MM/DD/YYYY or MM-DD-YYYY format.
ScheduledShippingPeriod

xs:string

The scheduled shipping period is returned only if scheduled shipping options are passed in the request.
Character length and limitations: The option selected by the buyer from the drop down on the Review Your Information page. It is one of the values in a string array passed by the merchant in the request; for example, it could be Morning or 5:00PM-9:00PM.

IncentiveDetailsType Fields

Information about the incentives that were applied from the eBay Review Your Payment page and PayPal Review Your Payment page.

FieldDescription
UniqueIdentifier

xs:string

A unique identifier consisting of a redemption code, a user friendly description, incentive type, campaign code, incentive application order and the site on which it was redeemed.

SiteAppliedOn

ebl:IncentiveSiteAppliedOnType

Defines if the incentive has been applied on eBay or PayPal.

It is one of the following:

  • INCENTIVE-SITE-APPLIED-ON-UNKNOWN
  • INCENTIVE-SITE-APPLIED-ON-MERCHANT
  • INCENTIVE-SITE-APPLIED-ON-PAYPAL
TotalDiscountAmount

cc:BasicAmountType

The total discount amount for the incentive; a summation of discounts up across all the buckets/items.

Status

ebl:IncentiveAppliedStatusType

Status of incentive processing. Sussess or Error. It is one of the following:

  • INCENTIVE-APPLIED-STATUS-SUCCESS
  • INCENTIVE-APPLIED-STATUS-ERROR
ErrorCode

xs:integer

The error code if there are any errors; otherwise, zero is returned.

IncentiveAppliedDetails

ebl:IncentiveAppliedDetailsType

Details of the incentive applied to an individual bucket / item.

IncentiveAppliedDetailsType Fields

Details of the incentive applied to an individual bucket / item.

FieldDescription
PaymentRequestID

xs:string

Uniquely identifies a bucket or a bucket ID in Express Checkout.

ItemId

xs:string

The item ID passed by the merchant.

ExternalTxnId

xs:string

The item transaction ID passed through by the merchant.

DiscountAmount

cc:BasicAmountType

The discount offerred for this bucket or item.

SubType

xs:string

The sub-category type for the coupon.

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

PaymentRequestInfoType Fields

FieldDescription

TransactionId

xs:string

Transaction ID for up to 10 parallel payment requests.

`partial:partials/docs/shared/cl_transactionid.en-XC`

This field is available since version 64.0.

PaymentRequestID

xs:string

Payment request ID for up to 10 payment requests.

This field is available since version 64.0.

PaymentError

ebl:ErrorType

Errors associated with the bucket of parallel payment requests.

This field is available since version 64.0.

ErrorType Fields

FieldDescription

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.

TaxIdDetailsType Fields

FieldDescription

TaxIdType

xs:string

Buyer's tax ID type. This field is required for Brazil and used for Brazil only.

For Brazil use only: The tax ID type is BR_CPF for individuals and BR_CNPJ for businesses.

This field is introduced in API version 72.0.

TaxId

xs:string

Buyer's tax ID. This field is required for Brazil and used for Brazil only.

For Brazil use only: The tax ID is 11 single-byte characters for individuals and 14 single-byte characters for businesses.

This field is introduced in API version 72.0.

Deprecated Fields

The following fields are deprecated.

Deprecated GetExpressCheckoutDetails Response Fields

FieldDescription
GiftMessage

Discontinued Sept. 8, 2016. (No replacement.)

xs:string

Gift message entered by the buyer on the PayPal checkout pages.

Character length and limitations: 150 single-byte characters

GiftReceiptEnable

Discontinued Sept. 8, 2016. (No replacement.)

xs:string

Whether the buyer requested a gift receipt. Value is:

  • true — The buyer requested a gift receipt.
  • false — The buyer did not request a gift receipt.
GiftWrapName

Discontinued Sept. 8, 2016. (No replacement.)

xs:string

Returns the gift wrap name only if the buyer selects gift option on the PayPal pages.

Character length and limitations: 25 single-byte characters

GiftWrapAmount

Discontinued Sept. 8, 2016. (No replacement.)

ebl:BasicAmountType

Returns the gift wrap amount only if the buyer selects the gift option on the PayPal pages.

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: `partial:partials/docs/shared/cl_currencylimit.en-XC`

SurveyQuestion

Discontinued Sept. 8, 2016. (No replacement.)

xs:string

Survey question on the PayPal checkout pages.

Character length and limitations: 50 single-byte characters

SurveyChoiceSelected

Discontinued Sept. 8, 2016. (No replacement.)

xs:string

Survey response the buyer selects on the PayPal pages.

Character length and limitations: 15 single-byte characters

Note

(No replacement.)

xs:string

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

Character length and limitations: 255 single-byte characters.

Additional information