AddPaymentCard API Operation

Sets up payment cards as funding sources for PayPal accounts.

AddPaymentCard Request

The AddPaymentCard request supplies all the information the Adaptive Accounts service needs to add a payment card as a funding source to a PayPal account on behalf of its holder.

AddPaymentCard Request Fields

Field Description
accountId

xs:string
(Optional) Unique identification number of the PayPal account to which to add the payment card.

Note: You must pass either an accountId or an emailAddress in this request. You can't leave both fields out of the message.
billingAddress aa:AddressType
(Optional) Billing address of the payment card holder. See AddressType Fields for details.
cardNumber xs:string
(Required) The payment card number.
cardOwnerDateOfBirth xs:date
(Optional) Date of birth of the payment card holder.
cardType aa:CardTypeType
(Required) The type of payment card to add. Allowed values:
  • Visa
  • MasterCard
  • AmericanExpress
  • Discover
  • SwitchMaestro (deprecated, use UKMaestro instead)
  • UKMaestro
  • CarteAurore
  • CarteBleue
  • Cofinoga
  • 4etoiles
  • CarteAura
  • TarjetaAurora
  • JCB
  • Maestro
Note: Use the UKMaestro card type for International Maestro cards, as well as for UK-specific Maestro Cards.
cardVerificationNumber xs:string
The verification code of the payment card. This parameter is generally required for calls in which confirmationType is NONE. With the appropriate account review, this parameter can be optional.
confirmationType

aa:ConfirmationType
(Required) Defines the type of confirmation to perform after the payment card has been added.

Allowed values:

  • WEB - Return a redirect URL to use to send the account holder's browser to the PayPal confirm payment card addition flow.
  • NONE - Do not return a redirect URL. The payment card is added without explicit confirmation from the account holder.
Note: Before you can pass NONE for ConfirmationType, you must obtain advanced permissions.
createAccountKey

xs:string
(Required if confirmationType is NONE) Unique identifier of the account to which to add a payment card. Use in cases where the payment card is being added without the account holder's explicit confirmation. The value to pass is returned in the createAccountKey field of a CreateAccount response.

Note: A create account key response expires after 60 minutes. If you pass an expired key to an Adaptive Accounts API, an error is returned.
emailAddress

xs:string
(Optional) Email address that uniquely identifies the PayPal account to which to add the payment card.

Note: You must pass either an accountId or an emailAddress in this request. You can't leave both fields out of the message.
expirationDate aa:CardDateType
(Optional) Expiration date of the payment card. See CardDateType Fields for details. Required for Brazilian accounts.
issueNumber xs:string
(Optional) 2-digit issue number of the payment card (for Maestro cards only).
nameOnCard aa:NameType
(Required) Name (as it appears on the card) of the payment card holder. See NameType Fields for details.
requestEnvelope common:RequestEnvelope
(Required) Information common to all API operations, such as the language in which an error message is returned. See RequestEnvelope Fields for details.
startDate aa:CardDateType
(Optional) The start date for the payment card. See CardDateType Fields for details.
webOptions aa:WebOptionsType
(Optional) Structure in which to pass the URLs for the return and cancelation web flows. See WebOptionsType Fields for details.

AddressType Fields

Field Description
line1 xs:string
(Required) The street address.
line2 xs:string
(Optional) The second line of the address.
Note: This field is required for Brazilian addresses.
city xs:string
(Required) The city.
state xs:string
(Optional) The state code.
postalCode xs:string
(Optional) The zip or postal code.
countryCode xs:string
(Required) The country code. See Country Codes for allowed values.

NameType Fields

Field Description
salutation xs:string
(Optional) A salutation for the account or payment card holder.
firstName xs:string
(Required) First name of the account or payment card holder.
middleName xs:string
(Optional) Middle name of the account or payment card holder.
lastName xs:string
(Required) Last name of the account or payment card holder.
suffix xs:string
(Optional) A suffix for the account or payment card holder.

CardDateType Fields

Field Description
month xs:integer
(Optional) The month of expiration.
year xs:integer
(Required) The year of expiration.

WebOptionsType Fields

Field Description
cancelUrl xs:string
(Optional) The URL to which PayPal returns the account holder if he or she cancels confirmation of the payment card addition.
cancelUrlDescription xs:string
(Optional) A description of the cancelation URL.
returnUrl xs:string
(Optional) The URL to which PayPal returns the account holder once he or she completes confirmation of the payment card addition.
returnUrlDescription xs:string
(Optional) A description of the return URL.

RequestEnvelope Fields

Field Description
detailLevel common:DetailLevelCode
The level of detail required by the client application for component such as Item, Transaction. Possible values:
  • ReturnAll — This value provides the maximum level of detail (default)
errorLanguage xs:string
The RFC 3066 language in which error messages are returned; by default it is en_US, which is the only language currently supported

AddPaymentCard Response

The AddPaymentCard response returns the status of the AddPaymentCard request, along with data needed to carry out the type of confirmation specified in the request.

AddPaymentCard Response Fields

Field Definition
execStatus xs:string
Execution status of the request. Possible values:
  • FUNDING_SOURCE_ADDED
  • WEB_URL_VERIFICATION_NEEDED
fundingSourceKey xs:string
A key that uniquely identifies the funding source just added. Use this value in subsequent Adaptive Accounts API calls, such as the SetFundingSourceConfirmed API Operation. A funding source key is returned if NONE was passed in the confirmationType field of the request message.
redirectURL

xs:string
The URL to which to redirect the PayPal account holder when the AddPaymentCard web flow completes. If WEB was passed in the confirmationType field of the request message, then this URL points to the PayPal confirm payment card addition flow.

responseEnvelope common:ResponseEnvelope
Information common to all API responses, including a timestamp and the response acknowledgment status.

ResponseEnvelope Fields

Field Description
ack common:AckCode
Acknowledgment code. Possible values:
  • Success — Operation completed successfully
  • Failure — Operation failed
  • Warning — Warning
  • SuccessWithWarning — Operation completed successfully; however, there is a warning message
  • FailureWithWarning — Operation failed with a warning message
build Build number; used only by Developer Technical Support.
correlationId Correlation ID; used only by Developer Technical Support.
timestamp The date on which the response was sent. The time is not supported.

AddPaymentCard Errors

Variable Description
500000 Framework failure. Retry.
520002 Internal error
520003 Invalid credentials.
550001 User is not allowed to perform this action
560022 Invalid header.
560029 The required <name> header is missing from the HTTP request
580001 Invalid request:
  • Card is already added to some other account
  • Card is already added to the account specified in the request
  • Payment card unavailable
  • The payment card was refused
  • The payment card has expired
  • PayPal account specified in the request is locked
  • PayPal account specified in the request is closed
  • Operation is not supported: PA_Replaceable_Value
  • Invalid request: PA_Replaceable_Value
 
580022 Request parameter is invalid:
  • Invalid request parameter: billingAddress
  • Invalid request parameter: line1
  • Invalid request parameter: line2
  • Invalid request parameter: city
  • Invalid request parameter: state
  • Invalid request parameter: postalCode
  • Invalid request parameters: city, state, postalCode
  • Invalid request parameter: startDate
  • Invalid request parameter: cardType
  • Address for UPS cannot be a PO Box
  • Invalid request parameter: accountId
  • Invalid request parameter: cardOwnerDateOfBirth
  • Invalid request parameter: cardNumber
  • Invalid request parameter: expirationDate
  • Invalid request parameter: cardVerificationNumber
  • Expired createAccountKey
  • Invalid request parameter: PA_Replaceable_Value
  • Invalid request parameter: createAccountKey
  • Invalid request parameter: ipAddress
 
580023 The argument is inconsistent with the rest of the request
  • Country of billing address must match country of account holder address
  • Account associated with createAccountKey is different from the one provided in the request
580027 The parameter is not supported
  • Prohibited request parameter: PA_Replaceable_Value
  • The parameter is not supported
580029 Required parameter is missing in the request:
  • Missing required request parameter: firstName
  • Missing required request parameter: lastName
  • Missing required request parameter: line1
  • Missing required request parameter: city
  • Missing required request parameter: state
  • Missing required request parameter: postalCode
  • Missing required request parameter: countryCode
  • Missing required request parameter: billingAddress
  • Missing required request parameter: line2
  • Missing required request parameter: cardVerificationNumber
  • Missing required request parameter: createAccountKey
  • Missing required request parameter: PA_Replaceable_Value