AddPaymentCard API Operation

API

Last updated: Aug 15th, 7:02am

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.

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 Merchant Technical Support.
`correlationId`	Correlation ID; used only by Merchant 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