# DoAuthorization API Operation (SOAP) (/api/nvp-soap/do-authorization-soap)



> **Note:** **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](/).

Authorizes a payment.

## DoAuthorization Request Message [#doauthorization-request-message]

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

### DoAuthorization Request Fields [#doauthorization-request-fields]

| Field                      | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `TransactionID`<br />      | `xs:string`<br /&#x3E; &#x2A;(Required)* Value of the order's transaction identification number returned by PayPal.<br /> Character length and limitations: 17 characters. [Orders](/api/nvp-soap/paypal-payments-standard/admin/auth-capture/#types) transactions have 19 characters.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `Amount`<br />             | `ebl:BasicAmountType`<br /&#x3E; &#x2A;(Required)* Amount to authorize.<br /> Character length and limitations: Value is typically a positive number that cannot exceed nine (9) digits in SOAP request/response for USD, CLP, or JPY or the [per transaction limit for the currency](/api/nvp-soap/currency-codes/). 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](/api/nvp-soap/currency-codes/).<br />                                                                                                                                                                                           |
| `TransactionEntity`<br />  | `ebl:TransactionEntityType`<br /&#x3E; &#x2A;(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.<br />                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `PaymentDetailsItem`<br /> | `ebl:PaymentDetailsItemType`<br /&#x3E; &#x2A;(Optional)* Details about each individual item included in the order.<br />                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `ShipToAddress`<br />      | [`ebl:AddressType`](#addresstype-fields)<br /&#x3E; &#x2A;(Optional)* Shipping address for this order.<br />                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `ItemTotal`<br />          | `cc:BasicAmountType`<br /&#x3E; &#x2A;(Optional)* Sum of cost of all items in this order.<br /> You must set the `currencyID` attribute to one of the three-character [currency codes](/api/nvp-soap/currency-codes/) for any of the supported PayPal currencies.<br /> Character length and limitations: Value is typically a positive number that cannot exceed nine (9) digits in SOAP request/response for USD, CLP, or JPY or the [per transaction limit for the currency](/api/nvp-soap/currency-codes/). 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](/api/nvp-soap/currency-codes/).<br /> |
| `ShippingTotal`<br />      | `cc:BasicAmountType`<br /&#x3E; &#x2A;(Optional)* Total shipping costs for this order.<br /> You must set the `currencyID` attribute to one of the three-character currency codes for any of the supported PayPal currencies.<br /> Character length and limitations: Value is typically a positive number that cannot exceed nine (9) digits in SOAP request/response for USD, CLP, or JPY or the [per transaction limit for the currency](/api/nvp-soap/currency-codes/). 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](/api/nvp-soap/currency-codes/).<br />                                     |
| `HandlingTotal`<br />      | `cc:BasicAmountType`<br /&#x3E; &#x2A;(Optional)* Total handling costs for this order.<br /> You must set the currencyID attribute to one of the three-character [currency codes](/api/nvp-soap/currency-codes/) for any of the supported PayPal currencies.<br /> Character length and limitations: Value is typically a positive number that cannot exceed nine (9) digits in SOAP request/response for USD, CLP, or JPY or the [per transaction limit for the currency](/api/nvp-soap/currency-codes/). 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](/api/nvp-soap/currency-codes/).<br />      |
| `TaxTotal`<br />           | `cc:BasicAmountType`<br /&#x3E; &#x2A;(Optional)* Sum of tax for all items in this order.<br /> Character length and limitations: Value is typically a positive number that cannot exceed nine (9) digits in SOAP request/response for USD, CLP, or JPY or the [per transaction limit for the currency](/api/nvp-soap/currency-codes/). 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](/api/nvp-soap/currency-codes/).<br />                                                                                                                                                                         |
| `InsuranceTotal`<br />     | `cc:BasicAmountType`<br /&#x3E; &#x2A;(Optional)* Total shipping insurance costs for this order.<br /> Character length and limitations: Value is typically a positive number that cannot exceed nine (9) digits in SOAP request/response for USD, CLP, or JPY or the [per transaction limit for the currency](/api/nvp-soap/currency-codes/). 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](/api/nvp-soap/currency-codes/).<br />                                                                                                                                                                  |
| `ShippingDiscount`<br />   | `cc:BasicAmountType`<br /&#x3E; &#x2A;(Optional)* Shipping discount for this order, specified as a negative number.<br /> 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](/api/nvp-soap/currency-codes/) for details.<br />                                                                                                                                                                                                                                                                                                                            |
| `OrderDescription`<br />   | `xs:string`<br /&#x3E; &#x2A;(Optional)* Description of items the customer is purchasing.<br /> Character length and limitations: 127 single-byte alphanumeric characters.<br />                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `Custom`<br />             | `xs:string`<br /&#x3E; &#x2A;(Optional)* A free-form field for your own use.<br /> Character length and limitations: 256 single-byte alphanumeric characters.<br />                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `IPAddress`<br />          | `xs:string`<br /&#x3E; &#x2A;(Optional)* IP address of the buyer.<br />                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `ShipToStore`<br />        | `xs:string`<br /> (Optional) Indicates if the item purchased will be shipped to a store location.<br />                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `MsgSubId`<br />           | `xs:string`<br /> (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.<br /> Character length and limitations: string of up to 38 single-byte characters.<br /> This field is available since version 92.0.<br />                                                                                                                                                                                                                                                                                                                                                                           |

#### AddressType Fields [#addresstype-fields]

| Field<br />             | Description<br />                                                                                                                                                                                                                                                                                                                                            |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `Name`<br />            | `xs:string`<br /> Person's name associated with this shipping address. It is required if using a shipping address.<br /> Character length and limitations: 128 double-byte characters<br />                                                                                                                                                                  |
| `Street1`<br />         | `xs:string`<br /> First street address. It is required if using a shipping address.<br /> Character length and limitations: 100 single-byte characters<br />                                                                                                                                                                                                 |
| `Street2`<br />         | `xs:string`<br /&#x3E; &#x2A;(Optional)* Second street address.<br /> Character length and limitations: 100 single-byte characters<br />                                                                                                                                                                                                                     |
| `CityName`<br />        | `xs:string`<br /> Name of city. It is required if using a shipping address.<br /> Character length and limitations: 40 single-byte characters<br />                                                                                                                                                                                                          |
| `StateOrProvince`<br /> | `xs:string`<br /> State or province.<br /> 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](/api/nvp-soap/state-codes/).<br /> Character length and limitations: 40 single-byte characters<br /> |
| `PostalCode`<br />      | `xs:string`<br /> 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.<br /> Character length and limitations: 20 single-byte characters<br />                                                                                                                         |
| `Country`<br />         | `ebl:CountryCodeType`<br /> Country code. It is required if using a shipping address.<br /> Character length and limitations: 2 single-byte characters<br />                                                                                                                                                                                                 |
| `Phone`<br />           | `xs:string`<br /&#x3E; &#x2A;(Optional)* Phone number.<br /> Character length and limitations: 20 single-byte characters<br />                                                                                                                                                                                                                               |

#### PaymentDetailsItemType Fields [#paymentdetailsitemtype-fields]

| Field                              | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Name`<br />                       | `xs:string`<br /&#x3E; &#x2A;(Optional)* Item name.<br /> Character length and limitations: 127 single-byte characters<br />                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `Number`<br />                     | `xs:string`<br /&#x3E; &#x2A;(Optional)* Item number.<br /> Character length and limitations: 127 single-byte characters<br />                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `Quantity`<br />                   | `xs:integer`<br /&#x3E; &#x2A;(Optional)* Item quantity.<br /> Character length and limitations: Any positive integer<br />                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `Tax`<br />                        | `cc:BasicAmountType`<br /&#x3E; &#x2A;(Optional)* Item sales tax.<br /> > **Note:** &#x2A;*Note:** You must set the `currencyID` attribute to one of the 3-character [currency codes](/api/nvp-soap/currency-codes/) for any of the supported PayPal currencies. Character length and limitations: Value is typically a positive number that cannot exceed nine (9) digits in SOAP request/response for USD, CLP, or JPY or the [per transaction limit for the currency](/api/nvp-soap/currency-codes/). 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](/api/nvp-soap/currency-codes/).<br /> |
| `Amount`<br />                     | `cc:BasicAmountType`<br /&#x3E; &#x2A;(Optional)* Cost of item.<br /> > **Note:** &#x2A;*Note:** You must set the `currencyID` attribute to one of the 3-character [currency codes](/api/nvp-soap/currency-codes/) for any of the supported PayPal currencies. Character length and limitations: Value is typically a positive number that cannot exceed nine (9) digits in SOAP request/response for USD, CLP, or JPY or the [per transaction limit for the currency](/api/nvp-soap/currency-codes/). 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](/api/nvp-soap/currency-codes/).<br />   |
| `EbayItemPaymentDetailsItem`<br /> | `ns:ebayItemPaymentDetailsItemType`<br /&#x3E; &#x2A;(Optional)* Information relating to an auction sale on eBay.<br />                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `PromoCode`<br />                  | `xs:string`<br /&#x3E; &#x2A;(Optional)* Promotional financing code for item. Part of the Merchant Services Promotion Financing feature.<br />                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `ProductCategory`<br />            | `ns:ProductCategoryType`<br /&#x3E; &#x2A;(Optional)*<br />                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `Description`<br />                | `xs:string`<br /&#x3E; &#x2A;(Optional)* Item description.<br /> Character length and limitations: 127 single-byte characters<br />                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `ItemWeight`<br />                 | `cc:MeasureType`<br /&#x3E; &#x2A;(Optional)* Information about the Item weight.<br />                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `ItemLength`<br />                 | `cc:MeasureType`<br /&#x3E; &#x2A;(Optional)* Information about the Item length.<br />                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `ItemWidth`<br />                  | `cc:MeasureType`<br /&#x3E; &#x2A;(Optional)* Information about the Item width.<br />                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `ItemHeight`<br />                 | `cc:MeasureType`<br /&#x3E; &#x2A;(Optional)* Information about the Item height.<br />                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `ItemURL`<br />                    | `xs:string`<br /&#x3E; &#x2A;(Optional)* URL for the item.<br /> Character length and limitations: no limit.<br />                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `EnhancedItemData`<br />           | `ed:EnhancedItemDataType`<br /&#x3E; &#x2A;(Optional)* Enhanced data for each item in the cart.<br />                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `ItemCategory`<br />               | `ns:ItemCategoryType`<br /&#x3E; &#x2A;(Optional)* Item category - physical or digital.<br />                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |

## DoAuthorization Response Message [#doauthorization-response-message]

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

### DoAuthorization Response Fields [#doauthorization-response-fields]

| Field                     | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `TransactionID`           | `xs:string`<br /&#x3E; &#x2A;(Optional)* Authorization identification number.<br /> Character length and limitations: 17 characters. [Orders](/api/nvp-soap/paypal-payments-standard/admin/auth-capture/#types) transactions have 19 characters.                                                                                                                                                                                                                                                                                                                                                                             |
| `Amount`<br />            | `ebl:BasicAmountType`<br /> Amount you specified in the request.<br /> Character length and limitations: Value is typically a positive number that cannot exceed nine (9) digits in SOAP request/response for USD, CLP, or JPY or the [per transaction limit for the currency](/api/nvp-soap/currency-codes/). 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](/api/nvp-soap/currency-codes/).<br /> |
| `AuthorizationInfo`<br /> | `ns:AuthorizationInfoType`<br /> Details on the Authorization transaction such as the payment status, pending reason (if applicable), and protection eligibility.<br />                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `MsgSubId`<br />          | `xs:string`<br /> (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.<br /> Character length and limitations: string of up to 38 single-byte characters.<br /> This field is available since version 92.0.<br />                                                                                                                                                                          |

### AuthorizationInfoType Fields [#authorizationinfotype-fields]

| Field                             | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `PaymentStatus`<br />             | `ebl:PaymentStatusCodeType`<br /> Status of the payment. Value is:<br /> `None` — No status.<br />`Canceled-Reversal` — A reversal has been canceled. For example, when you win a dispute, PayPal returns the funds for the reversal to you.<br />`Completed` — The payment has been completed, and the funds have been added successfully to your account balance.<br />`Denied` — You denied the payment. This happens only if the payment was previously pending because of possible reasons described for the `PendingReason` element.<br />`Expired` — The authorization period for this payment has been reached.<br />`Failed` — The payment has failed. This happens only if the payment was made from the buyer's bank account.<br />`In-Progress` — The transaction has not terminated. For example, an authorization may be awaiting completion.<br />`Partially-Refunded` — The payment has been partially refunded.<br />`Pending` — The payment is pending. See the `PendingReason` field for more information.<br />`Refunded` — You refunded the payment.<br />`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.<br />`Processed` — A payment has been accepted.<br />`Voided `— An authorization for this transaction has been voided.<br />                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `PendingReason`<br />             | `ebl:PendingStatusCodeType`<br /> Reason the payment is pending. Value is:<br /> `none` — No pending reason.<br />`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`.<br />`authorization` — The payment is pending because it has been authorized but not settled. You must capture the funds first.<br />`echeck` — The payment is pending because it was made by an eCheck that has not yet cleared.<br />`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`.<br />`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.<br />`order` — The payment is pending because it is part of an order that has been authorized but not settled.<br />`paymentreview` — The payment is pending while it is being reviewed by PayPal for risk.<br />`regulatoryreview` - 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.<br />`verify` — The payment is pending because you are not yet verified. You must verify your account before you can accept this payment.<br />`other` — The payment is pending for a reason other than those listed above. For more information, contact PayPal Customer Service.<br /> > **Note:** &#x2A;*Note:** `PendingReason` is returned in the response only if `PaymentStatus` is `Pending`. |
| `ProtectionEligibility`<br />     | `xs:string`<br /> Prior to version 64.4, the kind of seller protection in force for the transaction. Value is:<br /> `Eligible` — Merchant is protected by PayPal's Seller Protection Policy for Unauthorized Payment and Item Not Received.<br />`PartiallyEligible` — Merchant is protected by PayPal's Seller Protection Policy for Item Not Received.<br />`Ineligible` — Merchant is not protected under the Seller Protection Policy.<br />                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `ProtectionEligibilityType`<br /> | `xs:string`<br /> Since version 64.4, the type of seller protection in force for the transaction.<br /><br />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:** &#x2A;*Note:** If more than one of these values is returned in this field, they are returned in a comma-delimited string; for example, `ItemNotReceivedEligible,UnauthorizedPaymentEligible`.<br /> This field is available since version 64.4.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |

## Additional information [#additional-information]

* [API error codes](/api/nvp-soap/errors/)
* [Authorization and capture](/archive/paypal-payments-standard/admin/auth-capture/)