Adaptive Payments / API Reference / SetPaymentOptions

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

payKey

xs:string

(Required) The pay key that identifies the payment for which you want to set payment options. This is the pay key returned in the PayResponse message.

displayOptions

ap:DisplayOptions

(Optional) Specifies display items in payment flows and emails.

initiatingEntitity

ap:InitiatingEntity

(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.

shippingAddressId

xs:string

(Optional) Sender's shipping address ID.

senderOptions

ap:SenderOptions

(Optional) Specifies information to be provided by the sender, and optionally can include the sender address.

receiverOptions

ap:ReceiverOptions

(Optional) Specifies information about each receiver.

requestEnvelope

common:requestEnvelope

(Required) Information common to each API operation, such as the language in which an error message is returned.

DisplayOptions Fields

Field

Description

emailHeaderImageUrl

xs:string

(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.

emailMarketingImageUrl

xs:string

(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.

headerImageUrl

xs:string

(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.

businessName

xs:string

(Optional) The business name to display. The name cannot exceed 128 characters.

InitiatingEntity Fields

Field

Description

institutionCustomer

ap:InstitutionCustomer

(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

countryCode

xs:string

(Required) The two-character country code of the home country of the end consumer

displayName

xs:string

(Required) The full name of the consumer as known by the institution.

Maximum length: 200 characters

email

xs:string

(Optional) The email address of the consumer as known by the institution.

Maximum length: 127 characters

firstName

xs:string

(Required) The first name of the consumer as known by the institution.

Maximum length: 64 characters

institutionCustomerId

xs:string

(Required) The unique identifier assigned to the consumer by the institution.

Maximum length: 64 characters

institutionId

xs:string

(Required) The unique identifier assigned to the institution.

Maximum length: 64 characters

lastName

xs:string

(Required) The last name of the consumer as known by the institution.

Maximum length: 64 characters

SenderOptions Fields

Field

Description

requireShippingAddressSelection

xs:boolean

(Optional) If true, require the sender to select a shipping address during the embedded payment flow; default is false.

referrerCode

xs:string

(Optional) A code that identifies the partner associated with this transaction.

Maximum length: 32 characters.

addressOverride

xs:boolean

(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 of this SetPaymentOptions API call). Only applicable for the embedded payment flow. True by default. 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.

shippingAddress

ap:ShippingAddressInfo

(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

description

xs:string

(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

customId

xs:string

(Optional) An external reference or identifier you want to associate with the payment.

Maximum length: 1000 characters

invoiceData

ap:InvoiceData

(Optional) Item information for the payment, which could appear on an invoice.

receiver

ap:ReceiverIdentifier

(Optional) Receiver ID associated with these options.

ShippingAddressInfo Fields

Field

Description

addresseeName

xs:string

(Optional) Person's name associated with this shipping address.

Maximum length: 128 characters

street1

xs:string

(Optional) First street address.

Maximum length: 128 characters

street2

xs:string

(Optional) Second street address.

Maximum length: 128 characters

city

xs:string

(Optional) Name of city.

Maximum length: 128 characters

state

xs:string

(Optional) State or province.

Maximum length: 128 characters

zip

xs:string

(Optional) U.S. ZIP code or other country-specific postal code.

Maximum length: 128 characters

country

xs:string

(Optional) Country code.

Maximum length: 128 characters

phone

ap:PhoneNumber

(Optional) Phone number.

PhoneNumber Fields

Field

Description

type

ap:PhoneType

(Optional) Specifies the type of phone number. Currently, only MOBILE is valid. Other Value is:

  • 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

Field

Description

item

ap:InvoiceItem

(Optional) Any number of items associated with the payment.

totalTax

xs:decimal

(Optional) Total tax associated with the payment.

totalShipping

xs:decimal

(Optional) Total shipping charge associated with the payment.

InvoiceItem Fields

Field

Description

name

xs:string

(Optional) Name of item.

identifier

xs:string

(Optional) External reference to item or item ID.

price

xs:decimal

(Optional) Total of item line.

itemPrice

xs:decimal

(Optional) Price of an individual item.

itemCount

xs:int

(Optional) Item quantity.

ReceiverIdentifier Fields

Field

Description

email

xs:string

(Optional) Receiver's email address.

Maximum length: 127 characters

accountId

xs:string

(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

phone

common:PhoneNumberType

(Optional) Receiver's phone number.

PhoneNumberType Fields

Field

Description

countryCode

xs:string

(Required) Telephone country code.

phoneNumber

xs:string

(Required) Telephone number.

extension

xs:string

(Optional) Telephone extension.

RequestEnvelope Fields

Field

Description

detailLevel

common:DetailLevelCode

(Optional) Level of detail required by the client application for components. Value is:

  • ReturnAll — This value provides the maximum level of detail (default).

errorLanguage

xs:string

(Required) RFC 3066 language in which error messages are returned; by default it is en_US, which is the only language currently supported.

SetPaymentOptionsResponse Message

ResponseEnvelope Fields

Field

Description

ack

common:AckCode

Acknowledgment code. Value is:

  • Success — The operation completed successfully.

  • Failure — The operation failed.

  • SuccessWithWarning — The operation completed successfully; however, there is a warning message.

  • FailureWithWarning — The operation failed with a warning message.

build

xs:string

Build number. It is used only by PayPal Merchant Technical Support.

correlationId

xs:string

Correlation identifier. It is a 13-character, alphanumeric string (for example, db87c705a910e) that is used only by PayPal Merchant Technical Support.

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

xs:datetime

Date on which the response was sent, for example:

2012-04-02T22:33:35.774-07:00

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

error

common:ErrorData

Detailed error information.

responseEnvelope

common:ResponseEnvelope

Common response information, including a timestamp and the response acknowledgment status.

ErrorData Fields

Field

Description

category

common:ErrorCategory

The location where the error occurred.

Value is:

  • System — The system encountered errors; try again

  • Application — The application encountered errors; try again

  • Request — The request was incorrect

domain

xs:string

The domain to which this service belongs.

errorId

xs:long

A 6-digit number that uniquely identifies a particular error.

exceptionID

This field is not used.

message

xs:string

A description of the error.

parameter

common:ErrorParameter

Represents contextual information about the error.

severity

common:ErrorSeverity

The severity of the error encountered.

Value is:

  • Error — Processing of the request was interrupted

  • Warning — Processing of the request was completed

subdomain

This field is not used.

ResponseEnvelope Fields

Field

Description

ack

common:AckCode

Acknowledgment code. Value is:

  • Success — The operation completed successfully.

  • Failure — The operation failed.

  • SuccessWithWarning — The operation completed successfully; however, there is a warning message.

  • FailureWithWarning — The operation failed with a warning message.

build

xs:string

Build number. It is used only by PayPal Merchant Technical Support.

correlationId

xs:string

Correlation identifier. It is a 13-character, alphanumeric string (for example, db87c705a910e) that is used only by PayPal Merchant Technical Support.

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

xs:datetime

Date on which the response was sent, for example:

2012-04-02T22:33:35.774-07:00

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

  • Invalid request parameter: payKey with value <value>

  • payKey <value> has already been used to make a payment

  • displayOptions has already been set and cannot be set multiple times

  • initiationEntity has already been set and cannot be set multiple times

  • Invalid Request Parameter: institutionId with value <value>

  • The instituion ID <value> is not activated

580022

  • Invalid request parameter: <value>

  • Invalid Request Parameter: institutionId with value <value>

  • The institution id <value> is not activated

  • The clientDetails parameter is missing

  • Invalid request parameter: payKey with value <value>

  • Invalid Phone Country Code <value>

  • Invalid Country Code <value> for Receiver

  • Invalid Receiver Phone Type <value> <value> <value>

  • Invalid Phone Format <value> <value>

  • Invalid Phone Number <value> <value>

  • Invalid Receiver Phone Number <value> <value>

  • Invalid Area or Exchange Code <value> <value>

  • <value> has already been set and cannot be set multiple times

  • Invalid request parameter: <value> with value <value>

  • Invalid request parameter: <value> <value> is invalid

  • Invalid request parameter: <value> <value> is duplicated

  • Invalid request parameter: <value> <value> cannot be negative or zero

Since 1.6.0
580027

  • Currently the system does not accept the currency <value>

  • Unsupported country code <value>

  • Currently the system does not accept the currency <value>

  • The parameter is not supported

Since 1.6.0
580028 The URL <value> is malformed