# GetPaymentOptions API Operation (/archive/adaptive-payments/api/get-payment-options)



> **Note:** **Important:** Adaptive Payments 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](https://www.paypal.com/us/business/accept-payments).

Shows the options previously specified in the SetPaymentOptions API.

## GetPaymentOptionsRequest Message [#getpaymentoptionsrequest-message]

### GetPaymentOptionsRequest Fields [#getpaymentoptionsrequest-fields]

| Field<br />             | Description                                                                                                                                                                                |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `payKey`<br />          | `xs:string`<br /&#x3E; &#x2A;(Required)* The pay key that identifies the payment for which you want to get payment options. This is the pay key you used to set the payment options.<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:<br /> `ReturnAll` — This value provides the maximum level of detail (default).<br /> |
| `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 />                                        |

## GetPaymentOptionsResponse Message [#getpaymentoptionsresponse-message]

### GetPaymentOptionsResponse Fields [#getpaymentoptionsresponse-fields]

| Field<br />                | Description<br />                                                                                                                                                                             |
| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `payKey`<br />             | `xs:string`<br /> The pay key that identifies the payment for which you set payment options.<br />                                                                                            |
| `displayOptions`<br />     | `ap:DisplayOptions`<br /> Specifies display items in payment flows and emails.<br />                                                                                                          |
| `initiatingEntitity`<br /> | `ap:InitiatingEntity`<br /> The PayPal financial partner that is initiating the payment. Financial partners must first be set up in the Admin tool before they can use the PayPal APIs.<br /> |
| `shippingAddressId`<br />  | `xs:string`<br /> Sender's shipping address ID.<br />                                                                                                                                         |
| `senderOptions`<br />      | `ap:SenderOptions`<br /> Specifies information to be provided by the sender, and optionally can include the sender address.<br />                                                             |
| `receiverOptions`<br />    | `ap:ReceiverOptions`<br /> Specifies information about each receiver.<br />                                                                                                                   |
| `requestEnvelope`<br />    | `common:requestEnvelope`<br /> Information common to each API operation, such as the language in which an error message is returned.<br />                                                    |

### DisplayOptions Fields [#displayoptions-fields]

DisplayOptions fields allow the API caller to provide PayPal with a link to an image.

| Field<br />                    | Description<br />                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `emailHeaderImageUrl`<br />    | `xs:string`<br /> The URL of the image that displays in the in the header of customer emails. The image dimensions are 43 pixels high x 240 pixels wide.<br />                                                                                                                                                                                                                                                                                                                                                                                               |
| `emailMarketingImageUrl`<br /> | `xs:string`<br /> The URL of the image that displays in the in customer emails. The image dimensions are 80 pixels high x 530 pixels wide.<br />                                                                                                                                                                                                                                                                                                                                                                                                             |
| `headerImageUrl`<br />         | `xs:string`<br /> The URL of the image that displays in the header of a payment page. Use this to configure payment flows by passing a different image URL for different scenarios. If set, it overrides the header image URL specified in your account's Profile. The image dimensions are 90 pixels high x 750 pixels wide.<br />  > **Note:** &#x2A;*Note:** The `headerImageUrl` and `businessName` parameters are mutually exclusive; only one of these fields can be used. If you specify both, the image will take precedence over the business name. |
| `businessName`<br />           | `xs:string`<br /> The business name to display.<br />  > **Note:** &#x2A;*Note:** The `headerImageUrl` and `businessName` parameters are mutually exclusive; only one of these fields can be used. If you specify both, the image will take precedence over the business name.                                                                                                                                                                                                                                                                               |

### InitiatingEntity Fields [#initiatingentity-fields]

| Field<br />                 | Description<br />                                                                                                                                                                                                                                                                                                                        |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `institutionCustomer`<br /> | `ap:InstitutionCustomer`<br /&#x3E; &#x2A;(Optional)* Details about the party that initiated this payment. This payment is made by the API caller on behalf of the initiating party. The initiating party can be an institution or a customer of the institution. The initiating party must be set up by PayPal Merchant Services.<br /> |

### Institution Customer Fields [#institution-customer-fields]

| Field<br />                   | Description<br />                                                                                                                                     |
| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `countryCode`<br />           | `xs:string`<br /&#x3E; &#x2A;(Required)* The two-character country code of the home country of the end consumer<br />                                 |
| `displayName`<br />           | `xs:string`<br /&#x3E; &#x2A;(Required)* The full name of the consumer as known by the institution.<br /> Maximum length: 200 characters<br />        |
| `email`<br />                 | `xs:string`<br /&#x3E; &#x2A;(Optional)* The email address of the consumer as known by the institution.<br /> Maximum length: 127 characters<br />    |
| `firstName`<br />             | `xs:string`<br /&#x3E; &#x2A;(Required)* The first name of the consumer as known by the institution.<br /> Maximum length: 64 characters<br />        |
| `institutionCustomerId`<br /> | `xs:string`<br /&#x3E; &#x2A;(Required)* The unique identifier assigned to the consumer by the institution.<br /> Maximum length: 64 characters<br /> |
| `institutionId`<br />         | `xs:string`<br /&#x3E; &#x2A;(Required)* The unique identifier assigned to the institution.<br /> Maximum length: 64 characters<br />                 |
| `lastName`<br />              | `xs:string`<br /&#x3E; &#x2A;(Required)* The last name of the consumer as known by the institution.<br /> Maximum length: 64 characters<br />         |

### SenderOptions Fields [#senderoptions-fields]

| Field<br />                             | Description<br />                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `requireShippingAddressSelection`<br /> | `xs:boolean`<br /&#x3E; &#x2A;(Optional)* If `true`, require the sender to select a shipping address during the embedded payment flow; default is `false`.<br />                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `referrerCode`<br />                    | `xs:string`<br /&#x3E; &#x2A;(Optional)* A code that identifies the partner associated with this transaction.<br /> Maximum length: 32 characters.<br />                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `addressOverride`<br />                 | `xs:boolean`<br /&#x3E; &#x2A;(Optional)* Determines whether pages in the user interface will enable the user to override the specified shipping address (that is, the address specified in the `shippingAddress` container). True by default. Only applicable for the embedded payment flow. If `addressOverride` is `true`, the specified shipping address is displayed as first, followed by other addresses in the sender's profile, along with an option to add a new shipping address. The sender thus can override the specified shipping address (that is, the sender can override the address in this SetPaymentOptions API call). If `addressOverride` is `false`, the sender cannot change the address in this SetPaymentOptions API call. Note that if no address is specified in this SetPaymentOptions API call, the buyer's shipping addresses are presented for selection.<br /> |
| `shippingAddress`<br />                 | `ap:ShippingAddressInfo`<br /&#x3E; &#x2A;(Optional)* Container for the sender's shipping address. After you specify an address using this container, the address will be returned as part of a PaymentDetails API response.<br />                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |

### ReceiverOptions Fields [#receiveroptions-fields]

| Field<br />         | Description<br />                                                                                                                         |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `description`<br /> | `xs:string`<br /> A description you want to associate with the payment.<br /> Maximum length: 1000 characters<br />                       |
| `customId`<br />    | `xs:string`<br /> An external reference or identifier you want to associate with the payment.<br /> Maximum length: 1000 characters<br /> |
| `invoiceData`<br /> | `ap:InvoiceData`<br /> Item information for the payment, which could appear on an invoice.<br />                                          |
| `receiver`<br />    | `ap:ReceiverIdentifier`<br /> Receiver ID associated with these options.<br />                                                            |

### ShippingAddressInfo Fields [#shippingaddressinfo-fields]

| Field<br />           | Description<br />                                                                                                                        |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `addresseeName`<br /> | `xs:string`<br /&#x3E; &#x2A;(Optional)* Person's name associated with this shipping address.<br /> Maximum length: 128 characters<br /> |
| `street1`<br />       | `xs:string`<br /&#x3E; &#x2A;(Optional)* First street address.<br /> Maximum length: 128 characters<br />                                |
| `street2`<br />       | `xs:string`<br /&#x3E; &#x2A;(Optional)* Second street address.<br /> Maximum length: 128 characters<br />                               |
| `city`<br />          | `xs:string`<br /&#x3E; &#x2A;(Optional)* Name of city.<br /> Maximum length: 128 characters<br />                                        |
| `state`<br />         | `xs:string`<br /&#x3E; &#x2A;(Optional)* State or province.<br /> Maximum length: 128 characters<br />                                   |
| `zip`<br />           | `xs:string`<br /&#x3E; &#x2A;(Optional)* U.S. ZIP code or other country-specific postal code.<br /> Maximum length: 128 characters<br /> |
| `country`<br />       | `xs:string`<br /&#x3E; &#x2A;(Optional)* Country code.<br /> Maximum length: 128 characters<br />                                        |
| `phone`<br />         | `ap:PhoneNumber`<br /&#x3E; &#x2A;(Optional)* Phone number.<br />                                                                        |

### PhoneNumber Fields [#phonenumber-fields]

| Field<br />  | Description<br />                                                                                                                                                                                                                                                                                                                 |
| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type`<br /> | `ap:PhoneType`<br /&#x3E; &#x2A;(Optional)* Specifies the type of phone number. Currently, only `MOBILE` is valid. Other Value is:<br /> `NONE` — None of the other choices`HOME` — Home phone`WORK` — Work phone`BUSINESS` — Business phone`MOBILE` — Mobile phone`FAX_HOME` — Fax home phone`FAX_BUSINESS` — Fax business phone |

### InvoiceData Fields [#invoicedata-fields]

| Field<br />           | Description<br />                                                             |
| --------------------- | ----------------------------------------------------------------------------- |
| `item`<br />          | `ap:InvoiceItem`<br /> Any number of items associated with the payment.<br /> |
| `totalTax`<br />      | `xs:decimal`<br /> Total tax associated with the payment.<br />               |
| `totalShipping`<br /> | `xs:decimal`<br /> Total shipping charge associated with the payment.<br />   |

### InvoiceItem Fields [#invoiceitem-fields]

| Field<br />        | Description<br />                                              |
| ------------------ | -------------------------------------------------------------- |
| `name`<br />       | `xs:string`<br /> Name of item.<br />                          |
| `identifier`<br /> | `xs:string`<br /> External reference to item or item ID.<br /> |
| `price`<br />      | `xs:decimal`<br /> Price of item.<br />                        |
| `itemPrice`<br />  | `xs:decimal`<br /> Price of an individual item.<br />          |
| `itemCount`<br />  | `xs:int`<br /> Item quantity.<br />                            |

### ReceiverIdentifier Fields [#receiveridentifier-fields]

| Field<br />   | Description<br />                                                                      |
| ------------- | -------------------------------------------------------------------------------------- |
| `email`<br /> | `xs:string`<br /> Receiver's email address.<br /> Maximum length: 127 characters<br /> |
| `phone`<br /> | `common:PhoneNumberType`<br /> Receiver's phone number.<br />                          |

### PhoneNumberType Response Fields [#phonenumbertype-response-fields]

| Field<br />         | Description<br />                               |
| ------------------- | ----------------------------------------------- |
| `countryCode`<br /> | `xs:string`<br /> Telephone country code.<br /> |
| `phoneNumber`<br /> | `xs:string`<br /> Telephone number.<br />       |
| `extension`<br />   | `xs:string`<br /> Telephone extension.<br />    |

### ResponseEnvelope Fields [#responseenvelope-fields]

| Field<br />           | Description<br />                                                                                                                                                                                                                                                                                                                                           |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ack`<br />           | `common:AckCode`<br /> Acknowledgment code. Value is:<br /> `Success` — The operation completed successfully.<br />`Failure` — The operation failed.<br />`SuccessWithWarning` — The operation completed successfully; however, there is a warning message.<br />`FailureWithWarning `— The operation failed with a warning message.<br />                  |
| `build`<br />         | `xs:string`<br /> Build number. It is used only by PayPal Merchant Technical Support.<br />                                                                                                                                                                                                                                                                 |
| `correlationId`<br /> | `xs:string`<br /> Correlation identifier. It is a 13-character, alphanumeric string (for example, `db87c705a910e`) that is used only by PayPal 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 />     | `xs:datetime`<br /> Date on which the response was sent, for example:<br /> `2012-04-02T22:33:35.774-07:00`<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.

### 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:<br /> `System` — The system encountered errors; try again<br />`Application` — The application encountered errors; try again<br />`Request` — The request was incorrect<br /> |
| `domain`<br />      | `xs:string`<br /> The domain to which this service belongs.<br />                                                                                                                                                                                                 |
| `errorId`<br />     | `xs:long`<br /> A 6-digit number that uniquely identifies a particular error.<br />                                                                                                                                                                               |
| `exceptionID`<br /> | This field is not used.<br />                                                                                                                                                                                                                                     |
| `message`<br />     | `xs:string`<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:<br /> `Error` — Processing of the request was interrupted<br />`Warning` — Processing of the request was completed<br />                                                      |
| `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:<br /> `Success` — The operation completed successfully.<br />`Failure` — The operation failed.<br />`SuccessWithWarning` — The operation completed successfully; however, there is a warning message.<br />`FailureWithWarning `— The operation failed with a warning message.<br />                  |
| `build`<br />         | `xs:string`<br /> Build number. It is used only by PayPal Merchant Technical Support.<br />                                                                                                                                                                                                                                                                 |
| `correlationId`<br /> | `xs:string`<br /> Correlation identifier. It is a 13-character, alphanumeric string (for example, `db87c705a910e`) that is used only by PayPal 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 />     | `xs:datetime`<br /> Date on which the response was sent, for example:<br /> `2012-04-02T22:33:35.774-07:00`<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.                                                                |

## GetPaymentOptions Errors [#getpaymentoptions-errors]

| Code<br />   | Message<br />                                                                                                                                                      | Additional Information<br /> |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------- |
| 520002       | Internal error                                                                                                                                                     |                              |
| 520003<br /> | Authentication failed. API credentials are incorrect.<br />                                                                                                        | Since 1.6.0<br />            |
| 540031<br /> | You do not have permission to get these payment options<br />                                                                                                      |                              |
| 540031<br /> | You do not have permission to get these payment options<br /> Operation is not permitted because the credentials do not match those of the initial operation<br /> | Since 1.6.0<br />            |
| 550001<br /> | User is not allowed to perform this action<br />                                                                                                                   |                              |
| 580001       | Invalid request: \<value>                                                                                                                                          | Since 1.6.0<br />            |
| 580022<br /> | Invalid request parameter: payKey with value \<value><br />                                                                                                        |                              |