SetPaymentOptions API Operation
Important: Adaptive Payments is not available for new integrations. PayPal provides this documentation to support existing integrations.
Specifies settings for a payment. If you start a payment by specifying an actionType
of CREATE
in a Pay
API call, you can use the SetPaymentOptions
API to specify settings for the payment.
SetPaymentsOptionsRequest Message
SetPaymentOptionsRequest Fields
Field |
Description |
---|---|
|
(Required) The pay key that identifies the payment for which you want to set payment options. This is the pay key returned in the |
|
(Optional) Specifies display items in payment flows and emails. |
|
(Optional) The PayPal financial partner that is initiating the payment. A financial partner must be granted permission by PayPal before the financial partner can use PayPal APIs. |
|
(Optional) Sender's shipping address ID. |
|
(Optional) Specifies information to be provided by the sender, and optionally can include the sender address. |
|
(Optional) Specifies information about each receiver. |
|
(Required) Information common to each API operation, such as the language in which an error message is returned. |
DisplayOptions Fields
Field |
Description |
---|---|
|
(Optional) The URL of the image that displays in the in the header of customer emails. The URL cannot exceed 1,024 characters. The image dimensions are 43 pixels high x 240 pixels wide. |
|
(Optional) The URL of the image that displays in the in customer emails. The URL cannot exceed 1,024 characters. The image dimensions are 80 pixels high x 530 pixels wide. |
|
(Optional) The URL of an image that displays in the header of a payment page. If set, it overrides the header image URL specified in your account's Profile. The URL cannot exceed 1,024 characters. The image dimensions are 90 pixels high x 750 pixels wide. |
|
(Optional) The business name to display. The name cannot exceed 128 characters. |
InitiatingEntity Fields
Field |
Description |
---|---|
|
(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. |
Institution Customer Fields
Field |
Description |
---|---|
|
(Required) The two-character country code of the home country of the end consumer |
|
(Required) The full name of the consumer as known by the institution. Maximum length: 200 characters |
|
(Optional) The email address of the consumer as known by the institution. Maximum length: 127 characters |
|
(Required) The first name of the consumer as known by the institution. Maximum length: 64 characters |
|
(Required) The unique identifier assigned to the consumer by the institution. Maximum length: 64 characters |
|
(Required) The unique identifier assigned to the institution. Maximum length: 64 characters |
|
(Required) The last name of the consumer as known by the institution. Maximum length: 64 characters |
SenderOptions Fields
Field |
Description |
---|---|
|
(Optional) If |
|
(Optional) A code that identifies the partner associated with this transaction. Maximum length: 32 characters. |
|
(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 |
|
(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. |
ReceiverOptions Fields
Field |
Description |
---|---|
|
(Optional) A description you want to associate with the payment. This overrides the value of the memo in Pay API for each receiver. If this is not specified the value in the memo will be used. Maximum length: 1000 characters |
|
(Optional) An external reference or identifier you want to associate with the payment. Maximum length: 1000 characters |
|
(Optional) Item information for the payment, which could appear on an invoice. |
|
(Optional) Receiver ID associated with these options. |
ShippingAddressInfo Fields
Field |
Description |
---|---|
|
(Optional) Person's name associated with this shipping address. Maximum length: 128 characters |
|
(Optional) First street address. Maximum length: 128 characters |
|
(Optional) Second street address. Maximum length: 128 characters |
|
(Optional) Name of city. Maximum length: 128 characters |
|
(Optional) State or province. Maximum length: 128 characters |
|
(Optional) U.S. ZIP code or other country-specific postal code. Maximum length: 128 characters |
|
(Optional) Country code. Maximum length: 128 characters |
|
(Optional) Phone number. |
PhoneNumber Fields
Field |
Description |
---|---|
|
(Optional) Specifies the type of phone number. Currently, only
|
InvoiceData Fields
Field |
Description |
---|---|
|
(Optional) Any number of items associated with the payment. |
|
(Optional) Total tax associated with the payment. |
|
(Optional) Total shipping charge associated with the payment. |
InvoiceItem Fields
Field |
Description |
---|---|
|
(Optional) Name of item. |
|
(Optional) External reference to item or item ID. |
|
(Optional) Total of item line. |
|
(Optional) Price of an individual item. |
|
(Optional) Item quantity. |
ReceiverIdentifier Fields
Field |
Description |
---|---|
|
(Optional) Receiver's email address. Maximum length: 127 characters |
|
(Optional) Receiver's account ID value (which is the same as the Payer ID value used in the Express Checkout API). The account ID value is an encrypted PayPal account ID. This account ID value can be specified instead of a PayPal address. Maximum length: 13 single-byte alphanumeric characters |
|
(Optional) Receiver's phone number. |
PhoneNumberType Fields
Field |
Description |
---|---|
|
(Required) Telephone country code. |
|
(Required) Telephone number. |
|
(Optional) Telephone extension. |
RequestEnvelope Fields
Field |
Description |
---|---|
|
(Optional) Level of detail required by the client application for components. Value is:
|
|
(Required) RFC 3066 language in which error messages are returned; by default it is |
SetPaymentOptionsResponse Message
ResponseEnvelope Fields
Field |
Description |
---|---|
|
Acknowledgment code. Value is:
|
|
Build number. It is used only by PayPal Merchant Technical Support. |
|
Correlation identifier. It is a 13-character, alphanumeric string (for example, Note: You must log and store this data for every response you receive. PayPal Technical Support uses the information to assist with reported issues. |
|
Date on which the response was sent, for example: 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
The PPFaultMessage
returns ErrorData
and the ResponseEnvelope
information to your application if an error occurs.
FaultMessage Fields
Field |
Description |
---|---|
|
Detailed error information. |
|
Common response information, including a timestamp and the response acknowledgment status. |
ErrorData Fields
Field |
Description |
---|---|
|
The location where the error occurred. Value is:
|
|
The domain to which this service belongs. |
|
A 6-digit number that uniquely identifies a particular error. |
|
This field is not used. |
|
A description of the error. |
|
Represents contextual information about the error. |
|
The severity of the error encountered. Value is:
|
|
This field is not used. |
ResponseEnvelope Fields
Field |
Description |
---|---|
|
Acknowledgment code. Value is:
|
|
Build number. It is used only by PayPal Merchant Technical Support. |
|
Correlation identifier. It is a 13-character, alphanumeric string (for example, Note: You must log and store this data for every response you receive. PayPal Technical Support uses the information to assist with reported issues. |
|
Date on which the response was sent, for example: Note: You must log and store this data for every response you receive. PayPal Technical Support uses the information to assist with reported issues. |
SetPaymentOptions Examples Using NVP and CURL
These examples use NVP for the data binding and CURL to deliver the HTTP request to the PayPal sandbox endpoint. Line breaks are provided for ease of reading; each CURL command is a single line and each request and response is a string without line breaks or extra whitespace.
Specifying Invoice Data
This example shows how to set up purchase details for display on the payment review page, for user authorization. The details include the item description, item count, item price, total shipping, and total tax.
Note: The sample code below uses the
insecure
setting to work around the certificate for testing in a sandbox environment. For actual implementations, you must specify the location of the certificate.
Request
curl https://svcs.sandbox.paypal.com/AdaptivePayments/SetPaymentOptions \ -s \ --insecure \ -H "X-PAYPAL-SECURITY-USERID: api_username" \ -H "X-PAYPAL-SECURITY-PASSWORD: api_password" \ -H "X-PAYPAL-SECURITY-SIGNATURE: api_signature" \ -H "X-PAYPAL-REQUEST-DATA-FORMAT: NV" \ -H "X-PAYPAL-RESPONSE-DATA-FORMAT: NV" \ -H "X-PAYPAL-APPLICATION-ID: app_id" \ -d requestEnvelope.errorLanguage=en_US \ -d receiverOptions[0].receiver.email=test@test.com \ -d receiverOptions[0].invoiceData.item[0].name=ITEM1 \ -d receiverOptions[0].invoiceData.item[0].price=50.0 \ -d receiverOptions[0].invoiceData.item[0].itemCount=2 \ -d receiverOptions[0].invoiceData.item[0].itemPrice=25.0 \ -d receiverOptions[0].invoiceData.totalTax=25.0 \ -d receiverOptions[0].invoiceData.totalShipping=25.0 \ -d payKey=...
Specifying a Shipping Address
This example shows how to provide a shipping address for inclusion on the payment review page.
Note: The sample code below uses the
insecure
setting to work around the certificate for testing in a sandbox environment. For actual implementations, you must specify the location of the certificate.
Request
curl https://svcs.sandbox.paypal.com/AdaptivePayments/SetPaymentOptions \ -s \ --insecure \ -H "X-PAYPAL-SECURITY-USERID: api_username" \ -H "X-PAYPAL-SECURITY-PASSWORD: api_password" \ -H "X-PAYPAL-SECURITY-SIGNATURE: api_signature" \ -H "X-PAYPAL-REQUEST-DATA-FORMAT: NV" \ -H "X-PAYPAL-RESPONSE-DATA-FORMAT: NV" \ -H "X-PAYPAL-APPLICATION-ID: app_id" \ -d requestEnvelope.errorLanguage=en_US \ -d receiverList.receiver(0).email=test@test.com \ -d senderOptions.shippingAddress.addresseeName=John \ -d senderOptions.shippingAddress.city=San+Jose \ -d senderOptions.shippingAddress.country=US \ -d senderOptions.shippingAddress.phone.countryCode=91 \ -d senderOptions.shippingAddress.phone.phoneNumber=408123456 \ -d senderOptions.shippingAddress.phone.type=MOBILE \ -d senderOptions.shippingAddress.state=CA \ -d senderOptions.shippingAddress.street1=17+Magneson+St \ -d senderOptions.shippingAddress.street2=building+1 \ -d senderOptions.shippingAddress.zip=12345 \ -d payKey=...
SetPaymentOptions Errors
Code |
Message |
Additional Information |
---|---|---|
520002 | Internal error | |
520003 |
Authentication failed. API credentials are incorrect. |
Since 1.6.0 |
550001 |
User is not allowed to perform this action |
|
550001 |
This payment request must be authorized by the sender |
|
540031 |
You do not have permission to set these payment options |
|
540031 |
You do not have permission to set these payment options Operation is not permitted because the credentials do not match those of the initial operation |
Since 1.6.0 |
580001 | Invalid request: <value> |
Since 1.6.0 |
580022 |
|
|
580022 |
|
Since 1.6.0 |
580027 |
|
Since 1.6.0 |
580028 | The URL <value> is malformed |