DoAuthorization API Operation (SOAP)

Authorizes a payment.

DoAuthorization Request Message

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

DoAuthorization Request Fields

Field Description

TransactionID

xs:string

(Required) Value of the order's transaction identification number returned by PayPal.

Character length and limitations: 17 characters except for transactions of the type Order have a character length of 19.

Amount

ebl:BasicAmountType

(Required) Amount to authorize.

Character length and limitations:

Value is typically a positive number that cannot exceed 10,000.00 USD or the per transaction limit for the currency. It includes no currency symbol. Most currencies require two decimal places. The decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Some currencies do not allow decimals. For details, see the currency codes page.

TransactionEntity

ebl:TransactionEntityType

(Optional) Type of transaction to authorize. The only allowable value is Order, which means that the transaction represents a buyer order that can be fulfilled over 29 days.

PaymentDetailsItem

ebl:PaymentDetailsItemType

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

ShipToAddress

ebl:AddressType

(Optional) Shipping address for this order.

ItemTotal

cc:BasicAmountType

(Optional) Sum of cost of all items in this order.

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 typically a positive number that cannot exceed 10,000.00 USD or the per transaction limit for the currency. It includes no currency symbol. Most currencies require two decimal places. The decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Some currencies do not allow decimals. For details, see the currency codes page.

ShippingTotal

cc:BasicAmountType

(Optional) Total shipping costs for this order.

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 typically a positive number that cannot exceed 10,000.00 USD or the per transaction limit for the currency. It includes no currency symbol. Most currencies require two decimal places. The decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Some currencies do not allow decimals. For details, see the currency codes page.

HandlingTotal

cc:BasicAmountType

(Optional) Total handling costs for this order.

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 typically a positive number that cannot exceed 10,000.00 USD or the per transaction limit for the currency. It includes no currency symbol. Most currencies require two decimal places. The decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Some currencies do not allow decimals. For details, see the currency codes page.

TaxTotal

cc:BasicAmountType

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

Character length and limitations:

Value is typically a positive number that cannot exceed 10,000.00 USD or the per transaction limit for the currency. It includes no currency symbol. Most currencies require two decimal places. The decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Some currencies do not allow decimals. For details, see the currency codes page.

InsuranceTotal

cc:BasicAmountType

(Optional) Total shipping insurance costs for this order.

Character length and limitations:

Value is typically a positive number that cannot exceed 10,000.00 USD or the per transaction limit for the currency. It includes no currency symbol. Most currencies require two decimal places. The decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Some currencies do not allow decimals. For details, see the currency codes page.

ShippingDiscount

cc:BasicAmountType

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

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.

OrderDescription

xs:string

(Optional) Description of items the customer is purchasing.

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

Custom

xs:string

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

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

IPAddress

xs:string

(Optional) IP address of the buyer.

ShipToStore

xs:string

(Optional) Indicates if the item purchased will be shipped to a store location.

Added in version 116 of the Merchant API.

MsgSubId

xs:string

(Optional) A message ID used for idempotence to uniquely identify a message. This ID can later be used to request the latest results for a previous request without generating a new request. Examples of this include requests due to timeouts or errors during the original request.

Character length and limitations: string of up to 38 single-byte characters.

This field is available since version 92.0.

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: 128 double-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 for transactions only if the address is in one of the following countries: Argentina, Brazil, Canada, China, Indonesia, India, Japan, Mexico, Thailand or USA. See the list of PayPal State codes.

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

PaymentDetailsItemType Fields

Field Description

Name

xs:string

(Optional) Item name.

Character length and limitations: 127 single-byte characters

Number

xs:string

(Optional) Item number.

Character length and limitations: 127 single-byte characters

Quantity

xs:integer

(Optional) Item quantity.

Character length and limitations: Any positive integer

Tax

cc: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 typically a positive number that cannot exceed 10,000.00 USD or the per transaction limit for the currency. It includes no currency symbol. Most currencies require two decimal places. The decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Some currencies do not allow decimals. For details, see the currency codes page.

Amount

cc:BasicAmountType

(Optional) 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:

Value is typically a positive number that cannot exceed 10,000.00 USD or the per transaction limit for the currency. It includes no currency symbol. Most currencies require two decimal places. The decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Some currencies do not allow decimals. For details, see the currency codes page.

EbayItemPaymentDetailsItem

ns:ebayItemPaymentDetailsItemType

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

PromoCode

xs:string

(Optional) Promotional financing code for item. Part of the Merchant Services Promotion Financing feature.

ProductCategory

ns:ProductCategoryType

(Optional)

Description

xs:string

(Optional) Item description.

Character length and limitations: 127 single-byte characters

ItemWeight

cc:MeasureType

(Optional) Information about the Item weight.

ItemLength

cc:MeasureType

(Optional) Information about the Item length.

ItemWidth

cc:MeasureType

(Optional) Information about the Item width.

ItemHeight

cc:MeasureType

(Optional) Information about the Item height.

ItemURL

xs:string

(Optional) URL for the item.

Character length and limitations: no limit.

EnhancedItemData

ed:EnhancedItemDataType

(Optional) Enhanced data for each item in the cart.

ItemCategory

ns:ItemCategoryType

(Optional) Item category - physical or digital.

DoAuthorization Response Message

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

DoAuthorization Response Fields

Field Description
TransactionID

xs:string

(Optional) Authorization identification number.

Character length and limitations: 17 characters except for transactions of the type Order have a character length of 19.

Amount

ebl:BasicAmountType

Amount you specified in the request.

Character length and limitations:

Value is typically a positive number that cannot exceed 10,000.00 USD or the per transaction limit for the currency. It includes no currency symbol. Most currencies require two decimal places. The decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Some currencies do not allow decimals. For details, see the currency codes page.

AuthorizationInfo

ns:AuthorizationInfoType

Details on the Authorization transaction such as the payment status, pending reason (if applicable), and protection eligibility.

MsgSubId

xs:string

(Optional) A message ID used for idempotence to uniquely identify a message. This ID can later be used to request the latest results for a previous request without generating a new request. Examples of this include requests due to timeouts or errors during the original request.

Character length and limitations: string of up to 38 single-byte characters.

This field is available since version 92.0.

AuthorizationInfoType Fields

Field Description

PaymentStatus

ebl:PaymentStatusCodeType

Status of the payment. Value is:

  • None — No status.

  • Canceled-Reversal — A reversal has been canceled. For example, when you win a dispute, PayPal returns the funds for the reversal 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 the buyer's bank account.

  • In-Progress — The transaction has not terminated. For example, 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. PayPal removes the funds from your account balance and returns them to the buyer. The ReasonCode element specifies the reason for the reversal.

  • Processed — A payment has been accepted.

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

PendingReason

ebl:PendingStatusCodeType

Reason the payment is pending. Value is:

  • none — No pending reason.

  • address — The payment is pending because your customer 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.

ProtectionEligibility

xs:string

Prior to version 64.4, the kind of seller protection in force for the transaction. Value is:

  • Eligible — Merchant is protected by PayPal's Seller Protection Policy for Unauthorized Payment 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 or more of the following values:

  • 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.
Note: If more than one of these values is returned in this field, they will be returned in a comma-delimited string; for example, ItemNotReceivedEligible,UnauthorizedPaymentEligible.

This field is available since version 64.4.

Additional information