PayPal Vault Payment Tokens API
The PayPal Vault Payment Tokens API lets merchants securely store and reuse customer payment instruments as tokens for repeat billing and one-click checkout flows.
OpenAPI Specification
openapi: 3.0.3
info:
title: Paypal Payment Method Tokens
description: The Payment Method Tokens API saves payment methods so payers don't have to enter details for future transactions. Payers can check out faster or pay without being present after they agree to save a payment method.<br><br>The API associates a payment method with a temporary setup token. Pass the setup token to the API to exchange the setup token for a permanent token.<br><br>The permanent token represents a payment method that's saved to the vault. This token can be used repeatedly for checkout or recurring transactions such as subscriptions.
version: '3.1'
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.
- name: Setup-Tokens
description: Use the `/vault/setup-tokens` resource to create and retrieve temporary vault payment methods.
externalDocs:
url: https://developer.paypal.com/docs/api/vault/v3/
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: [email protected]
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: [email protected]
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
"/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:
securitySchemes:
Oauth2:
type: oauth2
description: Oauth 2.0 authentication
flows:
clientCredentials:
tokenUrl: "/v1/oauth2/token"
scopes:
https://uri.paypal.com/services/vault/payment-tokens/readwrite: Manage payment instruments
https://uri.paypal.com/services/vault/payment-tokens/read: Permission to only read from vault
https://uri.paypal.com/services/vault/customers/read: Permission to read customer information.
https://uri.paypal.com/services/vault/customers/readwrite: Permission to create/update customer information.
schemas:
error_details:
title: Error Details
type: object
description: The error details. Required for client-side `4XX` errors.
properties:
field:
type: string
description: The field that caused the error. If this field is in the body, set this value to the field's JSON pointer value. Required for client-side errors.
value:
type: string
description: The value of the field that caused the error.
location:
"$ref": "#/components/schemas/error_location"
issue:
type: string
description: The unique, fine-grained application-level error code.
description:
type: string
description: The human-readable description for an issue. The description can change over the lifetime of an API, so clients must not depend on this value.
required:
- issue
error_location:
type: string
description: The location of the field that caused the error. Value is `body`, `path`, or `query`.
enum:
- body
- path
- query
default: body
error_link_description:
title: Link Description
description: The request-related [HATEOAS link](/api/rest/responses/#hateoas-links) information.
type: object
required:
- href
- rel
properties:
href:
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.
type: string
minLength: 0
maxLength: 20000
pattern: "^.*$"
rel:
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).
type: string
minLength: 0
maxLength: 100
pattern: "^.*$"
method:
description: The HTTP method required to make the related call.
type: string
minLength: 3
maxLength: 6
pattern: "^[A-Z]*$"
enum:
- GET
- POST
- PUT
- DELETE
- PATCH
error_400:
type: object
title: Bad Request Error
description: Request is not well-formed, syntactically incorrect, or violates schema.
properties:
name:
type: string
enum:
- INVALID_REQUEST
message:
type: string
enum:
- Request is not well-formed, syntactically incorrect, or violates schema.
details:
type: array
items:
"$ref": "#/components/schemas/error_details"
debug_id:
type: string
description: The PayPal internal ID. Used for correlation purposes.
links:
description: An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).
type: array
minItems: 0
maxItems: 10000
items:
"$ref": "#/components/schemas/error_link_description"
error_401:
type: object
title: Unauthorized Error
description: Authentication failed due to missing Authorization header, or invalid authentication credentials.
properties:
name:
type: string
enum:
- AUTHENTICATION_FAILURE
message:
type: string
enum:
- Authentication failed due to missing authorization header, or invalid authentication credentials.
details:
type: array
items:
"$ref": "#/components/schemas/error_details"
debug_id:
type: string
description: The PayPal internal ID. Used for correlation purposes.
links:
description: An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).
type: array
minItems: 0
maxItems: 10000
items:
"$ref": "#/components/schemas/error_link_description"
error_403:
type: object
title: Not Authorized Error
description: 'The client is not authorized to access this resource, although it may have valid credentials. '
properties:
name:
type: string
enum:
- NOT_AUTHORIZED
message:
type: string
enum:
- Authorization failed due to insufficient permissions.
details:
type: array
items:
"$ref": "#/components/schemas/error_details"
debug_id:
type: string
description: The PayPal internal ID. Used for correlation purposes.
links:
description: An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).
type: array
minItems: 0
maxItems: 10000
items:
"$ref": "#/components/schemas/error_link_description"
error_404:
type: object
title: Not found Error
description: The server has not found anything matching the request URI. This either means that the URI is incorrect or the resource is not available.
properties:
name:
type: string
enum:
- RESOURCE_NOT_FOUND
message:
type: string
enum:
- The specified resource does not exist.
details:
type: array
items:
"$ref": "#/components/schemas/error_details"
debug_id:
type: string
description: The PayPal internal ID. Used for correlation purposes.
links:
description: An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).
type: array
minItems: 0
maxItems: 10000
items:
"$ref": "#/components/schemas/error_link_description"
error_409:
type: object
title: Resource Conflict Error
description: The server has detected a conflict while processing this request.
properties:
name:
type: string
enum:
- RESOURCE_CONFLICT
message:
type: string
enum:
- The server has detected a conflict while processing this request.
details:
type: array
items:
"$ref": "#/components/schemas/error_details"
debug_id:
type: string
description: The PayPal internal ID. Used for correlation purposes.
links:
description: An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).
type: array
minItems: 0
maxItems: 10000
items:
"$ref": "#/components/schemas/error_link_description"
error_415:
type: object
title: Unsupported Media Type Error
description: The server does not support the request payload's media type.
properties:
name:
type: string
enum:
- UNSUPPORTED_MEDIA_TYPE
message:
type: string
enum:
- The server does not support the request payload's media type.
details:
type: array
items:
"$ref": "#/components/schemas/error_details"
debug_id:
type: string
description: The PayPal internal ID. Used for correlation purposes.
links:
description: An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).
type: array
minItems: 0
maxItems: 10000
items:
"$ref": "#/components/schemas/error_link_description"
error_422:
type: object
title: Unprocessable Entity Error
description: The requested action cannot be performed and may require interaction with APIs or processes outside of the current request. This is distinct from a 500 response in that there are
# --- truncated at 32 KB (81 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/paypal/refs/heads/main/openapi/paypal-vault-payment-tokens-openapi-original.yml