openapi: 3.0.3
info:
title: Paypal Subscriptions Authorizations Setup-Tokens API
description: You can use billing plans and subscriptions to create subscriptions that process recurring PayPal payments for physical or digital goods, or services. A plan includes pricing and billing cycle information that defines the amount and frequency of charge for a subscription. You can also define a fixed plan, such as a $5 basic plan or a volume- or graduated-based plan with pricing tiers based on the quantity purchased. For more information, see <a href="/docs/subscriptions/">Subscriptions Overview</a>.
version: '1.6'
contact: {}
servers:
- url: https://api-m.sandbox.paypal.com
description: PayPal Sandbox Environment
- url: https://api-m.paypal.com
description: PayPal Live Environment
tags:
- name: Setup-Tokens
description: Use the `/vault/setup-tokens` resource to create and retrieve temporary vault payment methods.
paths:
/v3/vault/setup-tokens:
post:
description: Creates a Setup Token from the given payment source and adds it to the Vault of the associated customer.
summary: Paypal Create a setup token
operationId: setup-tokens.create
responses:
'200':
description: Idempotent response for a successful creation of setup token.
content:
application/json:
schema:
$ref: '#/components/schemas/setup_token_response'
examples:
setup_token_response:
value:
id: 5C991763VB2781612
customer:
id: customer_4029352050
status: APPROVED
payment_source:
card:
last_digits: '1111'
expiry: 2027-02
name: John Doe
billing_address:
address_line_1: 2211 N First Street
address_line_2: 17.3.160
admin_area_1: CA
admin_area_2: San Jose
postal_code: '95131'
country_code: US
links:
- rel: self
href: https://api-m.paypal.com/v3/vault/setup-tokens/5C991763VB2781612
method: GET
encType: application/json
- rel: confirm
href: https://api-m.paypal.com/v3/vault/payment-token
method: POST
encType: application/json
'201':
description: A successful creation of setup token.
content:
application/json:
schema:
$ref: '#/components/schemas/setup_token_response'
examples:
setup_token_response:
value:
id: 5C991763VB2781612
customer:
id: customer_4029352050
status: APPROVED
payment_source:
card:
last_digits: '1111'
expiry: 2027-02
name: John Doe
billing_address:
address_line_1: 2211 N First Street
address_line_2: 17.3.160
admin_area_1: CA
admin_area_2: San Jose
postal_code: '95131'
country_code: US
links:
- rel: self
href: https://api-m.paypal.com/v3/vault/setup-tokens/5C991763VB2781612
method: GET
encType: application/json
- rel: confirm
href: https://api-m.paypal.com/v3/vault/payment-token
method: POST
encType: application/json
'400':
description: Request is not well-formed, syntactically incorrect, or violates schema.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
'403':
description: Authorization failed due to insufficient permissions.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
'422':
description: The requested action could not be performed, semantically incorrect, or failed business validation.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
'500':
description: An internal server error has occurred.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
parameters:
- $ref: '#/components/parameters/paypal_request_id'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/setup_token_request'
examples:
setup_token_request:
value:
payment_source:
card:
number: '4111111111111111'
expiry: 2027-02
name: John Doe
billing_address:
address_line_1: 2211 N First Street
address_line_2: 17.3.160
admin_area_1: CA
admin_area_2: San Jose
postal_code: '95131'
country_code: US
experience_context:
brand_name: YourBrandName
locale: en-US
return_url: https://example.com/returnUrl
cancel_url: https://example.com/cancelUrl
description: Setup Token creation with a instrument type optional financial instrument details and customer_id.
required: true
security:
- Oauth2:
- https://uri.paypal.com/services/vault/payment-tokens/read
tags:
- Setup-Tokens
/v3/vault/setup-tokens/{id}:
get:
description: Returns a readable representation of temporarily vaulted payment source associated with the setup token id.
summary: Paypal Retrieve a setup token
operationId: setup-tokens.get
responses:
'200':
description: Found requested setup-token, returned a payment method associated with the token.
content:
application/json:
schema:
$ref: '#/components/schemas/setup_token_response'
'403':
description: Authorization failed due to insufficient permissions.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
'404':
description: The specified resource does not exist.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
'422':
description: The requested action could not be performed, semantically incorrect, or failed business validation.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
'500':
description: An internal server error has occurred.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
parameters:
- $ref: '#/components/parameters/id'
security:
- Oauth2:
- https://uri.paypal.com/services/vault/payment-tokens/read
tags:
- Setup-Tokens
components:
schemas:
language:
type: string
description: The [language tag](https://tools.ietf.org/html/bcp47#section-2) for the language in which to localize the error-related strings, such as messages, issues, and suggested actions. The tag is made up of the [ISO 639-2 language code](https://www.loc.gov/standards/iso639-2/php/code_list.php), the optional [ISO-15924 script tag](https://www.unicode.org/iso15924/codelists.html), and the [ISO-3166 alpha-2 country code](/api/rest/reference/country-codes/) or [M49 region code](https://unstats.un.org/unsd/methodology/m49/).
format: ppaas_common_language_v3
maxLength: 10
minLength: 2
pattern: ^[a-z]{2}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}|[0-9]{3}))?$
shipping_detail:
type: object
description: The shipping details.
title: Shipping Details
properties:
name:
description: The name of the person to whom to ship the items. Supports only the `full_name` property.
$ref: '#/components/schemas/name'
type:
description: The method by which the payer wants to get their items from the payee e.g shipping, in-person pickup. Either type or options but not both may be present.
type: string
minLength: 1
maxLength: 255
pattern: ^[0-9A-Z_]+$
enum:
- SHIPPING
- PICKUP_IN_PERSON
address:
description: The address of the person to whom to ship the items. Supports only the `address_line_1`, `address_line_2`, `admin_area_1`, `admin_area_2`, `postal_code`, and `country_code` properties.
$ref: '#/components/schemas/address_portable'
phone_type:
type: string
title: Phone Type
description: The phone type.
enum:
- FAX
- HOME
- MOBILE
- OTHER
- PAGER
paypal_wallet_request:
type: object
title: PayPal Wallet Request
description: A resource representing a request to vault PayPal Wallet.
allOf:
- $ref: '#/components/schemas/wallet_base'
- properties:
experience_context:
$ref: '#/components/schemas/experience_context'
link_description:
type: object
title: Link Description
description: The request-related [HATEOAS link](/api/rest/responses/#hateoas-links) information.
required:
- href
- rel
properties:
href:
type: string
description: The complete target URL. To make the related call, combine the method with this [URI Template-formatted](https://tools.ietf.org/html/rfc6570) link. For pre-processing, include the `$`, `(`, and `)` characters. The `href` is the key HATEOAS component that links a completed call with a subsequent call.
rel:
type: string
description: The [link relation type](https://tools.ietf.org/html/rfc5988#section-4), which serves as an ID for a link that unambiguously describes the semantics of the link. See [Link Relations](https://www.iana.org/assignments/link-relations/link-relations.xhtml).
method:
type: string
description: The HTTP method required to make the related call.
enum:
- GET
- POST
- PUT
- DELETE
- HEAD
- CONNECT
- OPTIONS
- PATCH
account_id:
type: string
title: PayPal Account Identifier
description: The account identifier for a PayPal account.
format: ppaas_payer_id_v3
minLength: 13
maxLength: 13
pattern: ^[2-9A-HJ-NP-Z]{13}$
date_no_time:
type: string
description: The stand-alone date, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). To represent special legal values, such as a date of birth, you should use dates with no associated time or time-zone data. Whenever possible, use the standard `date_time` type. This regular expression does not validate all dates. For example, February 31 is valid and nothing is known about leap years.
format: ppaas_date_notime_v2
minLength: 10
maxLength: 10
pattern: ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])$
customer:
type: object
title: Customer Request
description: Customer in merchant's or partner's system of records.
properties:
id:
description: The unique ID for a customer in merchant's or partner's system of records.
$ref: '#/components/schemas/merchant_partner_customer_id'
card_brand:
type: string
title: Card Brand
description: The card network or brand. Applies to credit, debit, gift, and payment cards.
minLength: 1
maxLength: 255
pattern: ^[A-Z_]+$
enum:
- VISA
- MASTERCARD
- DISCOVER
- AMEX
- SOLO
- JCB
- STAR
- DELTA
- SWITCH
- MAESTRO
- CB_NATIONALE
- CONFIGOGA
- CONFIDIS
- ELECTRON
- CETELEM
- CHINA_UNION_PAY
setup_token_request:
title: Setup Token
description: Setup Token Request where the `source` defines the type of instrument to be stored.
type: object
properties:
customer:
description: Customer in merchant's or partner's system of records.
$ref: '#/components/schemas/customer'
payment_source:
description: The payment method to vault with the instrument details.
properties:
card:
$ref: '#/components/schemas/card_request'
paypal:
$ref: '#/components/schemas/paypal_wallet_request'
venmo:
$ref: '#/components/schemas/venmo_request'
token:
$ref: '#/components/schemas/token_id_request'
metadata:
$ref: '#/components/schemas/metadata'
required:
- payment_source
card_request:
title: Card Request
description: A Resource representing a request to vault a Card.
allOf:
- $ref: '#/components/schemas/card'
- properties:
verification_method:
description: The API caller can opt in to verify the payment token through PayPal offered verification services (e.g. Smart Dollar Auth, 3DS).
$ref: '#/components/schemas/card_verification_method'
experience_context:
$ref: '#/components/schemas/experience_context'
merchant_partner_customer_id:
type: string
description: The unique ID for a customer generated by PayPal.
minLength: 1
maxLength: 22
pattern: ^[0-9a-zA-Z_-]+$
instrument_id:
type: string
description: The identifier of the instrument.
minLength: 1
maxLength: 256
pattern: ^[A-Za-z0-9-_.+=]+$
name:
type: object
title: Name
description: The name of the party.
properties:
prefix:
type: string
description: The prefix, or title, to the party's name.
maxLength: 140
given_name:
type: string
description: When the party is a person, the party's given, or first, name.
maxLength: 140
surname:
type: string
description: When the party is a person, the party's surname or family name. Also known as the last name. Required when the party is a person. Use also to store multiple surnames including the matronymic, or mother's, surname.
maxLength: 140
middle_name:
type: string
description: When the party is a person, the party's middle name. Use also to store multiple middle names including the patronymic, or father's, middle name.
maxLength: 140
suffix:
type: string
description: The suffix for the party's name.
maxLength: 140
alternate_full_name:
type: string
description: DEPRECATED. The party's alternate name. Can be a business name, nickname, or any other name that cannot be split into first, last name. Required when the party is a business.
maxLength: 300
full_name:
type: string
description: When the party is a person, the party's full name.
maxLength: 300
metadata: {}
phone:
type: object
title: Phone
description: The phone number, in its canonical international [E.164 numbering plan format](https://www.itu.int/rec/T-REC-E.164/en).
properties:
country_code:
type: string
description: The country calling code (CC), in its canonical international [E.164 numbering plan format](https://www.itu.int/rec/T-REC-E.164/en). The combined length of the CC and the national number must not be greater than 15 digits. The national number consists of a national destination code (NDC) and subscriber number (SN).
minLength: 1
maxLength: 3
pattern: ^[0-9]{1,3}?$
national_number:
type: string
description: The national number, in its canonical international [E.164 numbering plan format](https://www.itu.int/rec/T-REC-E.164/en). The combined length of the country calling code (CC) and the national number must not be greater than 15 digits. The national number consists of a national destination code (NDC) and subscriber number (SN).
minLength: 1
maxLength: 14
pattern: ^[0-9]{1,14}?$
extension_number:
type: string
description: The extension number.
minLength: 1
maxLength: 15
pattern: ^[0-9]{1,15}?$
required:
- country_code
- national_number
processor_response:
type: object
title: Processor Response
description: The processor information. Might be required for payment requests, such as direct credit card transactions.
properties:
avs_code:
description: The address verification code for Visa, Discover, Mastercard, or American Express transactions.
type: string
readOnly: true
enum:
- A
- B
- C
- D
- E
- F
- G
- I
- M
- N
- P
- R
- S
- U
- W
- X
- Y
- Z
- 'Null'
- '0'
- '1'
- '2'
- '3'
- '4'
cvv_code:
description: The card verification value code for for Visa, Discover, Mastercard, or American Express.
type: string
readOnly: true
enum:
- E
- I
- M
- N
- P
- S
- U
- X
- All others
- '0'
- '1'
- '2'
- '3'
- '4'
response_code:
description: Processor response code for the non-PayPal payment processor errors.
type: string
readOnly: true
enum:
- '0000'
- 00N7
- '0100'
- 0390
- '0500'
- 0580
- 0800
- 0880
- 0R00
- '1000'
- 10BR
- '1300'
- '1310'
- '1312'
- '1317'
- '1320'
- '1330'
- '1335'
- '1340'
- '1350'
- '1360'
- '1370'
- '1380'
- '1382'
- '1384'
- '1390'
- '1393'
- '5100'
- '5110'
- '5120'
- '5130'
- '5135'
- '5140'
- '5150'
- '5160'
- '5170'
- '5180'
- '5190'
- '5200'
- '5210'
- '5400'
- '5500'
- '5650'
- '5700'
- '5710'
- '5800'
- '5900'
- '5910'
- '5920'
- '5930'
- '6300'
- '7600'
- '7700'
- '7710'
- '7800'
- '7900'
- '8000'
- '8010'
- '8020'
- '8030'
- '8100'
- '8110'
- '8220'
- '9100'
- '9500'
- '9510'
- '9520'
- '9530'
- '9540'
- '9600'
- PCNR
- PCVV
- PPAD
- PPAE
- PPAG
- PPAI
- PPAR
- PPAU
- PPAV
- PPAX
- PPBG
- PPC2
- PPCE
- PPCO
- PPCR
- PPCT
- PPCU
- PPD3
- PPDC
- PPDI
- PPDV
- PPEF
- PPEL
- PPER
- PPEX
- PPFE
- PPFI
- PPFR
- PPFV
- PPGR
- PPH1
- PPIF
- PPII
- PPIM
- PPIT
- PPLR
- PPLS
- PPMB
- PPMC
- PPMD
- PPNC
- PPNL
- PPNT
- PPPH
- PPPI
- PPPM
- PPQC
- PPRE
- PPRF
- PPRR
- PPS0
- PPS1
- PPS2
- PPS3
- PPS4
- PPS5
- PPS6
- PPSC
- PPSD
- PPSE
- PPTE
- PPTF
- PPTI
- PPTR
- PPTT
- PPTV
- PPUA
- PPUC
- PPUE
- PPUI
- PPUP
- PPUR
- PPVC
- PPVE
- PPVT
payment_advice_code:
description: The declined payment transactions might have payment advice codes. The card networks, like Visa and Mastercard, return payment advice codes.
type: string
readOnly: true
enum:
- '01'
- '02'
- '03'
- '21'
experience_context:
type: object
title: Experience Context
description: Customizes the Vault creation flow experience for your customers.
properties:
brand_name:
type: string
description: The label that overrides the business name in the PayPal account on the PayPal site. The pattern is defined by an external party and supports Unicode.
minLength: 1
maxLength: 300
pattern: ^.*$
locale:
description: The BCP 47-formatted locale of pages that the PayPal vaulting experience shows. PayPal supports a five-character code. For example, `DA-DK`, `HE-IL`, `ID-ID`, `JA-JP`, `NO-NO`, `PT-BR`, `RU-RU`, `SV-SE`, `TH-TH`, `ZH-CN`, `ZH-HK`, or `ZH-TW`.
$ref: '#/components/schemas/language'
return_url:
type: string
format: uri
minLength: 1
maxLength: 4000
description: The URL where the customer is redirected after customer approves leaves the flow. It is a required field for contingency flows like PayPal wallet, 3DS.
cancel_url:
type: string
format: uri
minLength: 1
maxLength: 4000
description: The URL where the customer is redirected after customer cancels or leaves the flow. It is a required field for contingency flows like PayPal wallet, 3DS.
shipping_preference:
type: string
description: The shipping preference. This only applies to PayPal payment source.
default: GET_FROM_FILE
minLength: 1
maxLength: 255
pattern: ^[0-9A-Z_]+$
vault_instruction:
description: Vault Instruction on action to be performed after a successful payer approval.
$ref: '#/components/schemas/vault_instruction'
date_year_month:
type: string
description: The year and month, in ISO-8601 `YYYY-MM` date format. See [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6).
minLength: 7
maxLength: 7
pattern: ^[0-9]{4}-(0[1-9]|1[0-2])$
vault_id:
type: string
description: The PayPal-generated ID for the vault token.
minLength: 1
maxLength: 36
pattern: ^[0-9a-zA-Z_-]+$
ordinal:
type: integer
description: Ordinal number for sorting.
minimum: 1
maximum: 99
venmo_request:
type: object
title: Venmo Request
description: A resource representing a request to vault Venmo.
allOf:
- $ref: '#/components/schemas/wallet_base'
- properties:
experience_context:
$ref: '#/components/schemas/experience_context'
venmo_response:
title: Venmo Response
description: Full representation of a Venmo Payment Token.
type: object
allOf:
- $ref: '#/components/schemas/wallet_base'
- readOnly: true
$ref: '#/components/schemas/payer'
- properties:
user_name:
description: The Venmo username, as chosen by the user.
type: string
pattern: ^[-a-zA-Z0-9_]*$
minLength: 1
maxLength: 50
phone_with_type:
type: object
title: Phone With Type
description: The phone information.
properties:
phone_type:
$ref: '#/components/schemas/phone_type'
phone_number:
description: The phone number, in its canonical international [E.164 numbering plan format](https://www.itu.int/rec/T-REC-E.164/en). Supports only the `national_number` property.
$ref: '#/components/schemas/phone'
required:
- phone_number
3ds_result: {}
money:
type: object
title: Money
description: The currency and amount for a financial transaction, such as a balance or payment due.
properties:
currency_code:
$ref: '#/components/schemas/currency_code'
value:
type: string
description: The value, which might be:<ul><li>An integer for currencies like `JPY` that are not typically fractional.</li><li>A decimal fraction for currencies like `TND` that are subdivided into thousandths.</li></ul>For the required number of decimal places for a currency code, see [Currency Codes](/api/rest/reference/currency-codes/).
maxLength: 32
pattern: ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$
required:
- currency_code
- value
address_entity: {}
token_id_request:
type: object
title: Token Request
description: The Tokenized Payment Source representing a Request to Vault a Token.
properties:
id:
type: string
description: The PayPal-generated ID for the token.
minLength: 1
maxLength: 255
pattern: ^[0-9A-Z_-]+$
type:
type: string
description: The tokenization method that generated the ID.
minLength: 1
maxLength: 255
pattern: ^[0-9A-Z_-]+$
enum:
- BILLING_AGREEMENT
attributes:
description: The auxiliary details of the token.
$ref: '#/components/schemas/token_attributes'
required:
- id
- type
card_response:
type: object
title: Card Response
description: Full representation of a Card Payment Token.
properties:
name:
type: string
description: The card holder's name as it appears on the card.
minLength: 2
maxLength: 300
pattern: ^[A-Za-z ]+$
last_digits:
type: string
description: The last digits of the payment card.
pattern: '[0-9]{2,}'
minLength: 2
maxLength: 4
readOnly: true
brand:
description: The card brand or network. Typically used in the response.
readOnly: true
$ref: '#/components/schemas/card_brand'
expiry:
description: The card expiration year and month, in [Internet date format](https://tools.ietf.org/html/rfc3339#section-5.6).
$ref: '#/components/schemas/date_year_month'
billing_address:
description: The billing address for this card. Supports only the `address_line_1`, `address_line_2`, `admin_area_1`, `admin_area_2`, `postal_code`, and `country_code` properties.
$ref: '#/components/schemas/address_entity'
verification_status:
description: Card Verification status.
$ref: '#/components/schemas/card_verification_status'
verification:
$ref: '#/components/schemas/card_verification_details'
address_portable:
type: object
title: Portable Postal Address (Medium-Grained)
description: 'The portable international postal address. Maps to [AddressValidationMetadata](https://github.com/googlei18n/libaddressinput/wiki/AddressValidationMetadata) and HTML 5.1 [Autofilling form controls: the autocomplete attribute](https://www.w3.org/TR/html51/sec-forms.html#autofilling-form-controls-the-autocomplete-attribute).'
properties:
address_line_1:
type: string
description: The first line of the address. For example, number or street. For example, `173 Drury Lane`. Required for data entry and compliance and risk checks. Must contain the full address.
maxLength: 300
address_line_2:
type: string
description: The second line of the address. For example, suite or apartment number.
maxLength: 300
address_line_3:
type: string
description: The third line of the address, if needed. For example, a street complement for Brazil, direction text, such as `next to Walmart`, or a landmark in an Indian address.
maxLength: 100
admin_area_4:
type: string
description: The neighborhood, ward, or district. Smaller than `admin_area_level_3` or `sub_locality`. Value is:<ul><li>The postal sorting code for Guernsey and many French territories, such as French Guiana.</li><li>The fine-grained administrative levels in China.</li></ul>
maxLength: 100
admin_area_3:
type: string
description: A sub-locality, suburb, neighborhood, or district. Smaller than `admin_area_level_2`. Value is:<ul><li>Brazil. Suburb, bairro, or neighborhood.</li><li>India. Sub-locality or district. Street name information is not always available but a sub-locality or district can be a very small area.</li></ul>
maxLength: 100
admin_area_2:
type: string
description: A city, town, or village. Smaller than `admin_area_level_1`.
maxLength: 120
admin_area_1:
type: string
description: The highest level sub-division in a country, which is usually a province, state, or ISO-3166-2 subdivision. Format for postal delivery. For example, `CA` and not `California`. Value, by country, is:<ul><li>UK. A county.</li><li>US. A state.</li><li>Canada. A province.</li><li>Japan. A prefecture.</li><li>Switzerland. A kanton.</li></ul>
maxLength: 300
postal_code:
type: string
description: The postal code, which is the zip code or equivalent. Typically required for countries with a postal code or an equivalent. See [postal code](https://en.wikipedia.org/wiki/Postal_code).
maxLength: 60
country_code:
$ref: '#/components/schemas/country_code'
address_details:
type: object
title: Address Details
description: The non-portable additional address details that are sometimes needed for compliance, risk, or other scenarios where fine-grain address information might be needed. Not portable with common third party and open source. Redundant with core fields.<br/>For example, `address_portable.address_line_1` is usually a combination of `address_details.street_number`, `street_name`, and `street_type`.
properties:
street_number:
type: string
description: The street number.
maxLength: 100
street_name:
type: string
description: The street name. Just `Drury` in `Drury Lane`.
maxLength: 100
street_type:
type: string
description: The street type. For example, avenue, boulevard, road, or expressway.
maxLength: 100
delivery_service:
type: string
description: The delivery service. Post office box, bag number, or post office name.
maxLength: 100
building_name:
type: string
description: A named locations that represents the premise. Usually a building name or number or collection of buildings with a common name or number. For example, <code>Craven House</c
# --- truncated at 32 KB (48 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/paypal/refs/heads/main/openapi/paypal-setup-tokens-api-openapi.yml