On this page
No Headings
Last updated: June 12, 2026
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.
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.
| 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:
Note: Use the UKMaestro card type for International Maestro cards, as well as for UK-specific Maestro Cards. |
cardVerificationNumber | xs:stringThe 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:
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. |
| 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. |
| 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. |
| Field | Description |
|---|---|
month | xs:integer(Optional) The month of expiration. |
year | xs:integer(Required) The year of expiration. |
| 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. |
| Field | Description |
|---|---|
detailLevel | common:DetailLevelCodeThe level of detail required by the client application for component such as Item, Transaction. Possible values:
|
errorLanguage | xs:stringThe RFC 3066 language in which error messages are returned; by default it is en_US, which is the only language currently supported |
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.
| Field | Definition |
|---|---|
execStatus | xs:stringExecution status of the request. Possible values:
|
fundingSourceKey | xs:stringA 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:stringThe 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:ResponseEnvelopeInformation common to all API responses, including a timestamp and the response acknowledgment status. |
| Field | Description |
|---|---|
ack | common:AckCodeAcknowledgment code. Possible values:
|
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. |
| 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:
|
| 580022 | Request parameter is invalid:
|
| 580023 | The argument is inconsistent with the rest of the request
|
| 580027 | The parameter is not supported
|
| 580029 | Required parameter is missing in the request:
|