# RequestPermissions API Operation (/api/nvp-soap/request-permissions)



> **Note:** **Important:** The Adaptive Platform API is not available for new integrations. PayPal provides this documentation to support existing integrations. If you're starting an integration, [we recommend our latest solutions](/).

Requests permissions to execute API operations on a PayPal account holder's behalf.

## RequestPermissionsRequest Message [#requestpermissionsrequest-message]

<img src="https://www.paypalobjects.com/webstatic/en_US/developer/docs/api/RequestPermissionsRequest.gif" />

### RequestPermissions Request Fields [#requestpermissions-request-fields]

| Field<br />             | Description<br />                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `scope`<br />           | `xs:string`<br /&#x3E; &#x2A;(Required)* At least 1 of the following permission categories:`EXPRESS_CHECKOUT` - Express Checkout`DIRECT_PAYMENT` - Direct payment by debit or credit card`SETTLEMENT_CONSOLIDATION` - Settlement consolidation`SETTLEMENT_REPORTING` - Settlement reporting`AUTH_CAPTURE` - Payment authorization and capture`MOBILE_CHECKOUT` - Mobile checkout`BILLING_AGREEMENT` - Billing agreements`REFERENCE_TRANSACTION` - Reference transactions`AIR_TRAVEL` - Express Checkout for UTAP`MASS_PAY` - Mass pay`TRANSACTION_DETAILS` - Transaction details`TRANSACTION_SEARCH` - Transaction search`RECURRING_PAYMENTS` - Recurring payments`ACCOUNT_BALANCE` - Account balance`ENCRYPTED_WEBSITE_PAYMENTS` - Encrypted website payments`REFUND` - Refunds`NON_REFERENCED_CREDIT` - Non-referenced credit`BUTTON_MANAGER` - Button Manager`MANAGE_PENDING_TRANSACTION_STATUS` includes ManagePendingTransactionStatus`RECURRING_PAYMENT_REPORT` - Reporting for recurring payments`EXTENDED_PRO_PROCESSING_REPORT` - Extended Pro processing`EXCEPTION_PROCESSING_REPORT` - Exception processing`ACCOUNT_MANAGEMENT_PERMISSION` - Account Management Permission (MAM)`ACCESS_BASIC_PERSONAL_DATA` - User attributes`ACCESS_ADVANCED_PERSONAL_DATA` - User attributes`INVOICING` - Invoicing |
| `callback`<br />        | `xs:string`<br /&#x3E; &#x2A;(Required)* Your callback function that specifies actions to take after the account holder grants or denies the request.<br />                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `requestEnvelope`<br /> | `common:requestEnvelope`<br /&#x3E; &#x2A;(Required)* Information common to each API operation, such as the language in which an error message is returned.<br />                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |

### RequestEnvelope Fields [#requestenvelope-fields]

| Field<br />           | Description<br />                                                                                                                                                                                          |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `detailLevel`<br />   | `common:DetailLevelCode`<br /&#x3E; &#x2A;(Optional)* Level of detail required by the client application for components. Value is:`ReturnAll` — This value provides the maximum level of detail (default). |
| `errorLanguage`<br /> | `xs:string`<br /&#x3E; &#x2A;(Required)* RFC 3066 language in which error messages are returned; by default it is `en_US`, which is the only language currently supported.<br />                           |

## RequestPermissionsResponse Message [#requestpermissionsresponse-message]

<img src="https://www.paypalobjects.com/webstatic/en_US/developer/docs/api/RequestPermissionsResponse.gif" />

### RequestPermissions Response Fields [#requestpermissions-response-fields]

| Field<br />              | Description<br />                                                                                                                |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------- |
| `token`<br />            | `xs:string`<br /&#x3E; &#x2A;(Required)* A token from PayPal that enables the request to obtain permissions.<br />               |
| `responseEnvelope`<br /> | `common:ResponseEnvelope`<br /> Common response information, including a timestamp and the response acknowledgment status.<br /> |

### ResponseEnvelope Fields [#responseenvelope-fields]

| Field<br />           | Description<br />                                                                                                                                                                                                                                                                                                               |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ack`<br />           | `common:AckCode`<br /> Acknowledgment code. Value is:`Success` — The operation completed successfully.`Failure` — The operation failed.`Warning` — Warning.`SuccessWithWarning` — The operation completed successfully; however, there is a warning message.`FailureWithWarning` — The operation failed with a warning message. |
| `build`<br />         | Build number; it is used only by Merchant Technical Support.<br />                                                                                                                                                                                                                                                              |
| `correlationId`<br /> | Correlation ID; it is used only by Merchant Technical Support.<br />  > **Note:** &#x2A;*Note:** You must log and store this data for every response you receive. PayPal Technical Support uses the information to assist with reported issues.                                                                                 |
| `timestamp`<br />     | Date on which the response was sent. The time is currently not supported.<br />  > **Note:** &#x2A;*Note:** You must log and store this data for every response you receive. PayPal Technical Support uses the information to assist with reported issues.                                                                      |

## PPFault Message [#ppfault-message]

The `PPFaultMessage` returns `ErrorData` and the `ResponseEnvelope` information to your application if an error occurs.

<img src="https://www.paypalobjects.com/webstatic/en_US/developer/docs/api/FaultMessage.gif" />

<img src="https://www.paypalobjects.com/webstatic/en_US/developer/docs/api/ErrorData.gif" />

### FaultMessage Fields [#faultmessage-fields]

| Field<br />              | Description<br />                                                                                                                |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------- |
| `error`<br />            | `common:ErrorData`<br /> Detailed error information.<br />                                                                       |
| `responseEnvelope`<br /> | `common:ResponseEnvelope`<br /> Common response information, including a timestamp and the response acknowledgment status.<br /> |

### ErrorData Fields [#errordata-fields]

| Field<br />         | Description<br />                                                                                                                                                                                                                        |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `category`<br />    | `common:ErrorCategory`<br /> The location where the error occurred.<br /> Value is:`System` — The system encountered errors; try again`Application` — The application encountered errors; try again`Request` — The request was incorrect |
| `domain`<br />      | The domain to which this service belongs.<br />                                                                                                                                                                                          |
| `errorId`<br />     | A number that uniquely identifies a particular error.<br />                                                                                                                                                                              |
| `exceptionID`<br /> | This field is not used.<br />                                                                                                                                                                                                            |
| `message`<br />     | A description of the error.<br />                                                                                                                                                                                                        |
| `parameter`<br />   | `common:ErrorParameter`<br /> Represents contextual information about the error.<br />                                                                                                                                                   |
| `severity`<br />    | `common:ErrorSeverity`<br /> The severity of the error encountered.<br /> Value is:`Error` — Processing of the request was interrupted`Warning` — Processing of the request was completed                                                |
| `subdomain`<br />   | This field is not used.<br />                                                                                                                                                                                                            |

### ResponseEnvelope Fields [#responseenvelope-fields-1]

| Field<br />           | Description<br />                                                                                                                                                                                                                                                                                                               |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ack`<br />           | `common:AckCode`<br /> Acknowledgment code. Value is:`Success` — The operation completed successfully.`Failure` — The operation failed.`Warning` — Warning.`SuccessWithWarning` — The operation completed successfully; however, there is a warning message.`FailureWithWarning` — The operation failed with a warning message. |
| `build`<br />         | Build number; it is used only by Merchant Technical Support.<br />                                                                                                                                                                                                                                                              |
| `correlationId`<br /> | Correlation ID; it is used only by Merchant Technical Support.<br />  > **Note:** &#x2A;*Note:** You must log and store this data for every response you receive. PayPal Technical Support uses the information to assist with reported issues.                                                                                 |
| `timestamp`<br />     | Date on which the response was sent. The time is currently not supported.<br />  > **Note:** &#x2A;*Note:** You must log and store this data for every response you receive. PayPal Technical Support uses the information to assist with reported issues.                                                                      |

## RequestPermission Errors [#requestpermission-errors]

| Code<br />   | Message<br />                                                                                        | Additional Information<br /> |
| ------------ | ---------------------------------------------------------------------------------------------------- | ---------------------------- |
| 520002<br /> | Internal error<br />                                                                                 |                              |
| 550001<br /> | User is not allowed to perform this action<br />                                                     |                              |
| 560022<br /> | Invalid API Caller Account<br />                                                                     |                              |
| 580022<br /> | Transaction refused because of an invalid argument. See additional error messages for details.<br /> |                              |
| 580028<br /> | Invalid Redirect URL<br />                                                                           |                              |