openapi: 3.0.3
info:
title: Paypal Subscriptions Authorizations Payment-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: Payment-Tokens
description: Use the `/vault/payment-tokens` resource to create, retrieve, and delete a payment token that may optionally be associated with a customer.
paths:
/v3/vault/payment-tokens:
post:
description: Creates a Payment Token from the given payment source and adds it to the Vault of the associated customer.
summary: Paypal Create payment token for a given payment source
operationId: payment-tokens.create
responses:
'200':
description: Idempotent response for a successful creation of payment token.
content:
application/json:
schema:
$ref: '#/components/schemas/payment_token_response'
examples:
payment_token_response:
value:
id: 8kk8451t
customer:
id: customer_4029352050
payment_source:
card:
last_digits: '1111'
expiry: 2027-02
brand: VISA
name: John Doe
billing_address:
address_line_1: 2211 N First Street
address_line_2: 17.3.160
admin_area_2: San Jose
admin_area_1: CA
postal_code: '95131'
country_code: US
links:
- rel: self
href: https://api-m.paypal.com/v3/vault/payment-tokens/8kk8451t
method: GET
encType: application/json
- rel: delete
href: https://api-m.paypal.com/v3/vault/payment-tokens/8kk8451t
method: DELETE
encType: application/json
'201':
description: A successful creation of payment token.
content:
application/json:
schema:
$ref: '#/components/schemas/payment_token_response'
examples:
payment_token_response:
value:
id: 8kk8451t
customer:
id: customer_4029352050
payment_source:
card:
last_digits: '1111'
expiry: 2027-02
brand: VISA
name: John Doe
billing_address:
address_line_1: 2211 N First Street
address_line_2: 17.3.160
admin_area_2: San Jose
admin_area_1: CA
postal_code: '95131'
country_code: US
links:
- rel: self
href: https://api-m.paypal.com/v3/vault/payment-tokens/8kk8451t
method: GET
encType: application/json
- rel: delete
href: https://api-m.paypal.com/v3/vault/payment-tokens/8kk8451t
method: DELETE
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'
'404':
description: Request contains reference to resources that do 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/paypal_request_id'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/payment_token_request'
examples:
payment_token_request:
value:
payment_source:
token:
id: 5C991763VB2781612
type: BILLING_AGREEMENT
description: Payment Token creation with a financial instrument and an optional customer_id.
required: true
security:
- Oauth2:
- https://uri.paypal.com/services/vault/payment-tokens/readwrite
tags:
- Payment-Tokens
get:
description: Returns all payment tokens for a customer.
summary: Paypal List all payment tokens
operationId: customer.payment-tokens.get
responses:
'200':
description: Successful execution.
content:
application/json:
schema:
$ref: '#/components/schemas/customer_vault_payment_tokens_response'
examples:
customer_vault_payment_tokens_response:
value:
customer:
id: customer_4029352050
payment_tokens:
- id: 8kk8451t
customer:
id: customer_4029352050
payment_source:
card:
brand: VISA
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_2: San Jose
admin_area_1: CA
postal_code: '95131'
country_code: US
links:
- rel: self
href: https://api-m.paypal.com/v3/vault/payment-tokens/8kk8451t
method: GET
encType: application/json
- rel: delete
href: https://api-m.paypal.com/v3/vault/payment-tokens/8kk8451t
method: DELETE
encType: application/json
- id: fgh6561t
customer:
id: customer_4029352050
payment_source:
paypal:
description: Description for PayPal to be shown to PayPal payer
email_address: john.doe@example.com
account_id: VYYFH3WJ4JPJQ
shipping:
name:
full_name: John Doe
address:
address_line_1: 2211 N First Street
address_line_2: 17.3.160
admin_area_2: San Jose
admin_area_1: CA
postal_code: '95131'
country_code: US
usage_pattern: IMMEDIATE
usage_type: MERCHANT
customer_type: CONSUMER
name:
given_name: John
surname: Doe
address:
address_line_1: 2211 N First Street
address_line_2: 17.3.160
admin_area_2: San Jose
admin_area_1: CA
postal_code: '95131'
country_code: US
links:
- rel: self
href: https://api-m.paypal.com/v3/vault/payment-tokens/fgh6561t
method: GET
encType: application/json
- rel: delete
href: https://api-m.paypal.com/v3/vault/payment-tokens/fgh6561t
method: DELETE
encType: application/json
- id: hg654s1t
customer:
id: customer_4029352050
payment_source:
venmo:
description: Description for Venmo to be shown to Venmo payer
shipping:
name:
full_name: John Doe
address:
address_line_1: 2211 N First Street
address_line_2: 17.3.160
admin_area_2: San Jose
admin_area_1: CA
postal_code: '95131'
country_code: US
usage_pattern: IMMEDIATE
usage_type: MERCHANT
customer_type: CONSUMER
email_address: john.doe@example.com
user_name: johndoe
name:
given_name: John
surname: Doe
account_id: VYYFH3WJ4JPJQ
address:
address_line_1: PayPal
address_line_2: 2211 North 1st Street
admin_area_1: CA
admin_area_2: San Jose
postal_code: '96112'
country_code: US
links:
- rel: self
href: https://api-m.paypal.com/v3/vault/payment-tokens/hg654s1t
method: GET
encType: application/json
- rel: delete
href: https://api-m.paypal.com/v3/vault/payment-tokens/hg654s1t
method: DELETE
encType: application/json
links:
- rel: self
href: https://api-m.paypal.com/v3/vault/payment-tokens?customer_id=customer_4029352050&page=1&page_size=5&total_required=false
method: GET
encType: application/json
- rel: first
href: https://api-m.paypal.com/v3/vault/payment-tokens?customer_id=customer_4029352050&page=1&page_size=5&total_required=false
method: GET
encType: application/json
- rel: last
href: https://api-m.paypal.com/v3/vault/payment-tokens?customer_id=customer_4029352050&page=1&page_size=5&total_required=false
method: GET
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'
'500':
description: An internal server error has occurred.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
parameters:
- $ref: '#/components/parameters/customer_id'
- $ref: '#/components/parameters/page_size'
- $ref: '#/components/parameters/page'
- $ref: '#/components/parameters/total_required'
security:
- Oauth2:
- https://uri.paypal.com/services/vault/payment-tokens/readwrite
tags:
- Payment-Tokens
/v3/vault/payment-tokens/{id}:
get:
description: Returns a readable representation of vaulted payment source associated with the payment token id.
summary: Paypal Retrieve a payment token
operationId: payment-tokens.get
responses:
'200':
description: Successful execution.
content:
application/json:
schema:
$ref: '#/components/schemas/payment_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/readwrite
tags:
- Payment-Tokens
delete:
description: Delete the payment token associated with the payment token id.
summary: Paypal Delete payment token
operationId: payment-tokens.delete
responses:
'204':
description: The server has successfully executed the method, but there is no entity body to return.
'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'
'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/readwrite
tags:
- Payment-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
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}$
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
ach_debit_verification_status:
description: The ach debit verification status.
type: string
default: NOT_VERIFIED
minLength: 1
maxLength: 255
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])$
ach_debit_response: {}
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
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'
payment_token_response:
title: Payment Token Response
description: Full representation of a saved payment token.
type: object
properties:
id:
description: The PayPal-generated ID for the vault token.
$ref: '#/components/schemas/vault_id'
customer:
description: Customer in merchant's or partner's system of records.
$ref: '#/components/schemas/customer'
payment_source:
description: The vaulted payment method details.
type: object
properties:
card:
$ref: '#/components/schemas/card_response'
paypal:
$ref: '#/components/schemas/paypal_wallet_response'
venmo:
$ref: '#/components/schemas/venmo_response'
apple_pay:
$ref: '#/components/schemas/apple_pay_payment_token_response'
bank:
$ref: '#/components/schemas/bank_response'
links:
description: An array of related [HATEOAS links](/api/rest/responses/#hateoas).
readOnly: true
type: array
minItems: 1
maxItems: 32
items:
$ref: '#/components/schemas/link_description'
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_-]+$
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
instrument_id:
type: string
description: The identifier of the instrument.
minLength: 1
maxLength: 256
pattern: ^[A-Za-z0-9-_.+=]+$
metadata: {}
customer_vault_payment_tokens_response:
title: Vault of a customer
description: Collection of payment tokens saved for a given customer.
properties:
total_items:
type: integer
description: Total number of items.
minimum: 1
maximum: 50
total_pages:
type: integer
description: Total number of pages.
minimum: 1
maximum: 10
customer:
$ref: '#/components/schemas/customer'
payment_tokens:
type: array
minItems: 0
maxItems: 64
items:
description: Each token in this collection represents a payment token.
$ref: '#/components/schemas/payment_token_response'
links:
description: An array of related [HATEOAS links](/api/rest/responses/#hateoas).
readOnly: true
type: array
minItems: 1
maxItems: 32
items:
$ref: '#/components/schemas/link_description'
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.
s
# --- truncated at 32 KB (58 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/paypal/refs/heads/main/openapi/paypal-payment-tokens-api-openapi.yml