{ "openapi": "3.0.3", "info": { "title": "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.

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.

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.4", "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." }, { "name": "tokens", "description": "Use the `/vault/tokens` resource to detokenize a vault token to retrieve details associated to the underlying payment source." }, { "name": "tokens-session", "description": "Use the `/vault/tokens/{id}/session` resource to read the token session cache and retrieve details associated to the underlying payment source." }, { "name": "customers", "description": "Use the `/vault/customers` resource to create, update, get and delete a customer." }, { "name": "payment-method-credentials", "description": "Use the `/vault/payment-method-credentials` resource to create payment method credentials" } ], "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": "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": "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": "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": "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": "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": "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": { "2": { "type": "object", "title": "Venmo Request", "description": "A resource representing a request to vault Venmo." }, "5": { "readOnly": true, "type": "object", "title": "Payer", "description": "The customer who approves and pays for the order. The customer is also known as the payer.", "format": "payer_v1" }, "7": { "title": "PayPal Wallet Response", "description": "Full representation of a PayPal Payment Token.", "type": "object" }, "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}$" }, "address": { "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).", "type": "object", "title": "Portable Postal Address (Medium-Grained)", "properties": { "address_line_1": { "type": "string", "description": "The first line of the address, such as number and street, for example, `173 Drury Lane`. Needed for data entry, and Compliance and Risk checks. This field needs to pass the full address.", "maxLength": 300 }, "address_line_2": { "type": "string", "description": "The second line of the address, for example, a suite or apartment number.", "maxLength": 300 }, "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. This data is formatted for postal delivery, for example, `CA` and not `California`. Value, by country, is:", "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" } }, "required": [ "country_code" ] }, "apple_pay_payment_token_response": { "type": "object", "title": "Apple Pay Response", "description": "A resource representing a response for Apple Pay.", "properties": { "card": { "$ref": "#/components/schemas/card" } } }, "authentication_result": { "type": "object", "title": "Authentication Response", "description": "Results of Authentication such as 3D Secure.", "properties": { "three_d_secure": { "$ref": "#/components/schemas/three_d_secure_authentication_response-2" } } }, "billing_address": { "type": "object", "title": "Address request details.", "description": "Address request details.", "properties": { "address_line_1": { "type": "string", "description": "The first line of the address, such as number and street, for example, `173 Drury Lane`. Needed for data entry, and Compliance and Risk checks. This field needs to pass the full address.", "maxLength": 300 }, "address_line_2": { "type": "string", "description": "The second line of the address, for example, a suite or apartment number.", "maxLength": 300 }, "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. This data is formatted for postal delivery, for example, `CA` and not `California`. Value, by country, is:", "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" }, "id": { "type": "string", "description": "The resource ID of the address.", "minLength": 1, "maxLength": 36, "pattern": "^[0-9A-Za-z-_]+$" } }, "required": [ "country_code" ] }, "billing_cycle": { "title": "Billing Cycle", "description": "The billing cycle providing details of the billing frequency, amount, duration and if the billing cycle is a free, discounted or regular billing cycle. The sequence of the billing cycle will be in the following order - free trial billing cycle(s), discounted trial billing cycle(s), regular billing cycle(s).", "type": "object", "properties": { "tenure_type": { "type": "string", "description": "The tenure type of the billing cycle identifies if the billing cycle is a trial(free or discounted) or regular billing cycle.", "minLength": 1, "maxLength": 24, "pattern": "^[A-Z_]+$", "x-enumDescriptions": [ { "value": "REGULAR", "description": "A regular billing cycle to identify recurring charges for the billing agreement." }, { "value": "TRIAL", "description": "A trial billing cycle to identify free or discounted charge for the billing agreement. Free trails will not have a price object in pricing scheme where as a discounted trial would have a discounted price compared to regular billing cycle." } ], "enum": [ "REGULAR", "TRIAL" ] }, "pricing_scheme": { "description": "The active pricing scheme for this billing cycle. A free trial billing cycle does not require a pricing scheme.", "$ref": "#/components/schemas/pricing_scheme" }, "frequency": { "description": "The frequency details for this billing cycle.", "$ref": "#/components/schemas/frequency" }, "total_cycles": { "type": "integer", "description": "The number of times this billing cycle gets executed. Trial billing cycles can only be executed a finite number of times (value between 1 and 999 for total_cycles). Regular billing cycles can be executed infinite times (value of 0 for total_cycles) or a finite number of times (value between 1 and 999 for total_cycles).", "minimum": 0, "maximum": 999, "default": 1, "format": "int32" }, "sequence": { "type": "integer", "description": "The order in which this cycle is to run among other billing cycles. For example, a trial billing cycle has a `sequence` of `1` while a regular billing cycle has a `sequence` of `2`, so that trial cycle runs before the regular cycle.", "minimum": 1, "maximum": 3, "default": 1, "format": "int32" }, "start_date": { "description": "The start date for the billing cycle, in YYYY-MM-DD. This field should be not be provided if the billing cycle starts at the time of checkout. When this field is not provided, the billing cycle amount will be included in any data validations confirming that the total provided by the merchant match the sum of individual items due at the time of checkout. Only one billing cycle (with sequence equal to 1) can have a no start date.", "$ref": "#/components/schemas/date_no_time" } }, "required": [ "tenure_type" ] }, "billing_cycle_list": { "type": "array", "description": "An array of billing cycles for trial billing and regular billing. A plan can have at most two trial cycles and only one regular cycle.", "minItems": 1, "maxItems": 3, "items": { "$ref": "#/components/schemas/billing_cycle" } }, "bin_details": { "type": "object", "title": "Bin Details", "description": "Bank Identification Number (BIN) details used to fund a payment.", "properties": { "bin": { "type": "string", "description": "The Bank Identification Number (BIN) signifies the number that is being used to identify the granular level details (except the PII information) of the card.", "pattern": "^[0-9]+$", "maxLength": 25, "minLength": 1 }, "issuing_bank": { "type": "string", "description": "The issuer of the card instrument.", "minLength": 1, "maxLength": 64 }, "bin_country_code": { "description": "The [two-character ISO-3166-1 country code](/docs/integration/direct/rest/country-codes/) of the bank.", "$ref": "#/components/schemas/country_code-2" }, "products": { "$ref": "#/components/schemas/products_list" } } }, "card": { "type": "object", "title": "Apple Pay Card", "description": "The payment card to be used to fund a payment. Can be a credit or debit card.", "properties": { "name": { "type": "string", "description": "The card holder's name as it appears on the card.", "maxLength": 300, "minLength": 1, "pattern": "^.{1,300}$" }, "last_digits": { "type": "string", "description": "The last digits of the payment card.", "pattern": "^[0-9]{2,4}$", "minLength": 2, "maxLength": 4, "readOnly": true }, "type": { "description": "The payment card type.", "$ref": "#/components/schemas/card_type" }, "brand": { "description": "The card brand or network. Typically used in the response.", "$ref": "#/components/schemas/card_brand" }, "billing_address": { "$ref": "#/components/schemas/card_billing_address" } } }, "card_billing_address": { "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).", "type": "object", "title": "Portable Postal Address (Medium-Grained)", "properties": { "address_line_1": { "type": "string", "description": "The first line of the address, such as number and street, for example, `173 Drury Lane`. Needed for data entry, and Compliance and Risk checks. This field needs to pass the full address.", "maxLength": 300 }, "address_line_2": { "type": "string", "description": "The second line of the address, for example, a suite or apartment number.", "maxLength": 300 }, "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. This data is formatted for postal delivery, for example, `CA` and not `California`. Value, by country, is:", "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" } }, "required": [ "country_code" ] }, "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_]+$", "x-enumDescriptions": [ { "value": "VISA", "description": "Visa card." }, { "value": "MASTERCARD", "description": "Mastecard card." }, { "value": "DISCOVER", "description": "Discover card." }, { "value": "AMEX", "description": "American Express card." }, { "value": "SOLO", "description": "Solo debit card." }, { "value": "JCB", "description": "Japan Credit Bureau card." }, { "value": "STAR", "description": "Military Star card." }, { "value": "DELTA", "description": "Delta Airlines card." }, { "value": "SWITCH", "description": "Switch credit card." }, { "value": "MAESTRO", "description": "Maestro credit card." }, { "value": "CB_NATIONALE", "description": "Carte Bancaire (CB) credit card." }, { "value": "CONFIGOGA", "description": "Configoga credit card." }, { "value": "CONFIDIS", "description": "Confidis credit card." }, { "value": "ELECTRON", "description": "Visa Electron credit card." }, { "value": "CETELEM", "description": "Cetelem credit card." }, { "value": "CHINA_UNION_PAY", "description": "China union pay credit card." }, { "value": "DINERS", "description": "The Diners Club International banking and payment services capability network owned by Discover Financial Services (DFS), one of the most recognized brands in US financial services." }, { "value": "ELO", "description": "The Brazilian Elo card payment network." }, { "value": "HIPER", "description": "The Hiper - Ingenico ePayment network." }, { "value": "HIPERCARD", "description": "The Brazilian Hipercard payment network that's widely accepted in the retail market." }, { "value": "RUPAY", "description": "The RuPay payment network." }, { "value": "GE", "description": "The GE Credit Union 3Point card payment network." }, { "value": "SYNCHRONY", "description": "The Synchrony Financial (SYF) payment network." }, { "value": "EFTPOS", "description": "The Electronic Fund Transfer At Point of Sale(EFTPOS) Debit card payment network." }, { "value": "UNKNOWN", "description": "UNKNOWN payment network." } ], "enum": [ "VISA", "MASTERCARD", "DISCOVER", "AMEX", "SOLO", "JCB", "STAR", "DELTA", "SWITCH", "MAESTRO", "CB_NATIONALE", "CONFIGOGA", "CONFIDIS", "ELECTRON", "CETELEM", "CHINA_UNION_PAY", "DINERS", "ELO", "HIPER", "HIPERCARD", "RUPAY", "GE", "SYNCHRONY", "EFTPOS", "UNKNOWN" ] }, "card_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." }, "vault_instruction": { "description": "Vault Instruction on action to be performed after a successful payer approval.", "$ref": "#/components/schemas/vault_instruction" } } }, "card_response": { "type": "object", "title": "Card Response", "description": "Full representation of a Card Payment Token including network token.", "allOf": [ { "$ref": "#/components/schemas/card_response_entity" }, { "properties": { "network_token": { "$ref": "#/components/schemas/network_token_entity" } } } ] }, "card_response_entity": { "type": "object", "title": "Card Response Entity", "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": { "$ref": "#/components/schemas/billing_address" }, "verification_status": { "description": "Card Verification status.", "$ref": "#/components/schemas/card_verification_status" }, "verification": { "$ref": "#/components/schemas/card_verification_details" }, "network_transaction_reference": { "$ref": "#/components/schemas/network_transaction_reference_response" }, "authentication_result": { "$ref": "#/components/schemas/authentication_result" }, "bin_details": { "description": "Bank Identification Number (BIN) details used to fund a payment.", "$ref": "#/components/schemas/bin_details" }, "type": { "description": "The payment card type.", "$ref": "#/components/schemas/card_type" } } }, "card_type": { "type": "string", "title": "Card Type", "description": "Type of card. i.e Credit, Debit and so on.", "minLength": 1, "maxLength": 255, "pattern": "^[A-Z_]+$", "x-enumDescriptions": [ { "value": "CREDIT", "description": "A credit card." }, { "value": "DEBIT", "description": "A debit card." }, { "value": "PREPAID", "description": "A Prepaid card." }, { "value": "STORE", "description": "A store card." }, { "value": "UNKNOWN", "description": "Card type cannot be determined." } ], "enum": [ "CREDIT", "DEBIT", "PREPAID", "STORE", "UNKNOWN" ] }, "card_verification_details": { "title": "Card Verification Details", "type": "object", "description": "Card Verification details including the authorization details and 3D SECURE details.", "properties": { "network_transaction_id": { "description": "DEPRECATED. This field is DEPRECATED. Please find the network transaction id data in the 'id' field under the 'network_transaction_reference' object instead of the 'verification' object.", "type": "string", "minLength": 1, "maxLength": 1024, "pattern": "^[a-zA-Z0-9-_@.:&+=*^'~#!$%()]+$", "deprecated": true }, "date": { "type": "string", "minLength": 4, "maxLength": 4, "pattern": "^[0-9]+$", "description": "DEPRECATED. This field is DEPRECATED. Please find the date data in the 'date' field under the 'network_transaction_reference' object instead of the 'verification' object.", "deprecated": true }, "network": { "description": "DEPRECATED. This field is DEPRECATED. Please find the network data in the 'network' field under the 'network_transaction_reference' object instead of the 'verification' object.", "$ref": "#/components/schemas/card_brand", "deprecated": true }, "time": { "description": "DEPRECATED. This field is DEPRECATED. Please find the time data in the 'time' field under the 'network_transaction_reference' object instead of the 'verification' object.", "readOnly": true, "$ref": "#/components/schemas/date_time", "deprecated": true }, "amount": { "description": "The amount used for card verification.", "$ref": "#/components/schemas/money" }, "processor_response": { "$ref": "#/components/schemas/processor_response" }, "three_d_secure": { "description": "DEPRECATED. This field is DEPRECATED. Please find the 3D secure authentication data in the 'three_d_secure' object under the 'authentication_result' object instead of the 'verification' object.", "deprecated": true } } }, "card_verification_method": { "title": "Card Verification Method", "type": "string", "description": "The verification method of the card.", "minLength": 1, "maxLength": 255, "pattern": "^[0-9A-Z_]+$", "x-enumDescriptions": [ { "value": "SCA_WHEN_REQUIRED", "description": "When an authorization or transaction is attempted this option will return a contingency and HATEOAS link only when local regulations require strong customer authentication, (e.g. 3DS in countries and use cases where it is mandated). The API caller should redirect the payer to the link so that they can authenticate themselves. In all cases, when an authorization is requested the AVS/CVV results will be returned in the response." }, { "value": "SCA_ALWAYS", "description": "Selecting this option will attempt to force a strong customer authentication for the authorization/transaction. In countries where SCA has been defined and implemented it will result in a contingency and HATEOAS link being returned. The API caller should redirect the payer to that link so that they can authenticate themselves against their issuing bank or other entity. As noted, the HATEOAS link is only available in all regions where strong authentication is supported, (e.g. in European countries where 3DS is live). Merchants can use this setting as an additional layer of security if they choose to. In all cases, when an authorization is requested the AVS/CVV results will be returned in the response." } ], "enum": [ "SCA_WHEN_REQUIRED", "SCA_ALWAYS" ] }, "card_verification_status": { "title": "Card Verification Status", "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^[0-9A-Z_]+$", "description": "Verification status of Card.", "x-enumDescriptions": [ { "value": "VERIFIED", "description": "Card has been verified " }, { "value": "FAILED", "description": "Card verification has failed " } ], "enum": [ "VERIFIED", "FAILED" ] }, "country_code": { "type": "string", "description": "The [2-character ISO 3166-1 code](/api/rest/reference/country-codes/) that identifies the country or region.
Note: The country code for Great Britain is GB and not UK as used in the top-level domain names for that country. Use the `C2` country code for China worldwide for comparable uncontrolled price (CUP) method, bank card, and cross-border transactions.
", "format": "ppaas_common_country_code_v2", "maxLength": 2, "minLength": 2, "pattern": "^([A-Z]{2}|C2)$" }, "country_code-2": { "type": "string", "description": "The [two-character ISO 3166-1 code](/api/rest/reference/country-codes/) that identifies the country or region.
Note: The country code for Great Britain is GB and not UK as used in the top-level domain names for that country. Use the `C2` country code for China worldwide for comparable uncontrolled price (CUP) method, bank card, and cross-border transactions.
", "format": "ppaas_common_country_code_v2", "maxLength": 2, "minLength": 2, "pattern": "^([A-Z]{2}|C2)$" }, "currency_code": { "description": "The [three-character ISO-4217 currency code](/api/rest/reference/currency-codes/) that identifies the currency.", "type": "string", "minLength": 3, "maxLength": 3, "x-security-classification": { "data_class": "class4", "data_category": "INTRINSIC" } }, "customer": { "description": "This object defines a customer in your system. Use it to manage customer profiles, save payment methods and contact details.", "type": "object", "title": "Customer Request", "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" }, "merchant_customer_id": { "type": "string", "description": "Merchants and partners may already have a data-store where their customer information is persisted. Use merchant_customer_id to associate the PayPal-generated customer.id to your representation of a customer.", "minLength": 1, "maxLength": 64, "pattern": "^[0-9a-zA-Z-_.^*$@#]+$" } } }, "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": { "$ref": "#/components/schemas/payment_token_response_list" }, "links": { "$ref": "#/components/schemas/link_description_list" } } }, "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])$" }, "date_time": { "type": "string", "description": "The date and time, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). Seconds are required while fractional seconds are optional.
Note: The regular expression provides guidance but does not reject all invalid dates.
", "format": "ppaas_date_time_v3", "minLength": 20, "maxLength": 64, "pattern": "^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])[T,t]([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)([.][0-9]+)?([Zz]|[+-][0-9]{2}:[0-9]{2})$" }, "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])$" }, "definitions-2": { "type": "object", "title": "Card Response", "description": "Full representation of a Card Payment Token including network token." }, "definitions-7": { "title": "Venmo Response", "description": "Full representation of a Venmo Payment Token.", "type": "object" }, "definitions-card": { "type": "object", "title": "Card Request", "description": "A Resource representing a request to vault a Card.", "properties": { "name": { "type": "string", "description": "The card holder's name as it appears on the card.", "maxLength": 300, "minLength": 1, "pattern": "^.{1,300}$" }, "number": { "type": "string", "description": "The primary account number (PAN) for the payment card.", "pattern": "^[0-9]{13,19}$", "minLength": 13, "maxLength": 19 }, "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" }, "security_code": { "type": "string", "description": "The three- or four-digit security code of the card. Also known as the CVV, CVC, CVN, CVE, or CID. This parameter cannot be present in the request when `payment_initiator=MERCHANT`.", "pattern": "^[0-9]{3,4}$", "minLength": 3, "maxLength": 4 }, "brand": { "description": "The card brand or network. Typically used in the response.", "$ref": "#/components/schemas/card_brand" }, "billing_address": { "$ref": "#/components/schemas/card_billing_address" }, "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/card_experience_context" }, "network_transaction_reference": { "$ref": "#/components/schemas/network_transaction_reference_request" } } }, "definitions-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": "^.*$" }, "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_]+$", "x-enumDescriptions": [ { "value": "GET_FROM_FILE", "description": "Use the payer-provided shipping address on the PayPal site." }, { "value": "NO_SHIPPING", "description": "Redact the shipping address from the PayPal site. Recommended for digital goods." }, { "value": "SET_PROVIDED_ADDRESS", "description": "Use the merchant/platform-provided address. The payer cannot change this address on the PayPal site. If the merchant does not pass an address, the customer can choose the address on the PayPal site." } ], "enum": [ "GET_FROM_FILE", "NO_SHIPPING", "SET_PROVIDED_ADDRESS" ] }, "vault_instruction": { "description": "Vault Instruction on action to be performed after a successful payer approval.", "$ref": "#/components/schemas/vault_instruction" } } }, "definitions-link_description_list": { "type": "array", "description": "An array of request-related [HATEOAS links](/api/rest/responses/#hateoas-links) that are either relevant to the issue by providing additional information or offering potential resolutions.", "readOnly": true, "minItems": 1, "maxItems": 4, "items": { "$ref": "#/components/schemas/link_description" } }, "definitions-payment_source": { "title": "Payment source request", "description": "The payment method to vault with the instrument details.", "type": "object", "properties": { "card": { "$ref": "#/components/schemas/payment_source_card" }, "token": { "$ref": "#/components/schemas/token_id_request" } } }, "email": { "type": "string", "description": "The internationalized email address.
Note: Up to 64 characters are allowed before and 255 characters are allowed after the @ sign. However, the generally accepted maximum length for an email address is 254 characters. The pattern verifies that an unquoted @ sign exists.
", "format": "merchant_common_email_address_v2", "maxLength": 254, "minLength": 3, "pattern": "(?:[a-zA-Z0-9!#$%&'*+/=?^_`{|}~-]+(?:\\.[a-zA-Z0-9!#$%&'*+/=?^_`{|}~-]+)*|(?:[\\x01-\\x08\\x0b\\x0c\\x0e-\\x1f\\x21\\x23-\\x5b\\x5d-\\x7f]|\\[\\x01-\\x09\\x0b\\x0c\\x0e-\\x7f])*\")@(?:(?:[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?\\.)+[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?|\\[(?:(?:(2(5[0-5]|[0-4][0-9])|1[0-9][0-9]|[1-9]?[0-9]))\\.){3}(?:(2(5[0-5]|[0-4][0-9])|1[0-9][0-9]|[1-9]?[0-9])|[a-zA-Z0-9-]*[a-zA-Z0-9]:(?:[\\x01-\\x08\\x0b\\x0c\\x0e-\\x1f\\x21-\\x5a\\x53-\\x7f]|\\[\\x01-\\x09\\x0b\\x0c\\x0e-\\x7f])+)\\])" }, "enrolled": { "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^[0-9A-Z_]+$", "description": "Status of Authentication eligibility.", "x-enumDescriptions": [ { "value": "Y", "description": "Yes. The bank is participating in 3-D Secure protocol and will return the ACSUrl." }, { "value": "N", "description": "No. The bank is not participating in 3-D Secure protocol." }, { "value": "U", "description": "Unavailable. The DS or ACS is not available for authentication at the time of the request." }, { "value": "B", "description": "Bypass. The merchant authentication rule is triggered to bypass authentication." } ], "enum": [ "Y", "N", "U", "B" ] }, "error": { "type": "object", "title": "Error", "description": "The error details.", "properties": { "name": { "type": "string", "description": "The human-readable, unique name of the error." }, "message": { "type": "string", "description": "The message that describes the error." }, "debug_id": { "type": "string", "description": "The PayPal internal ID. Used for correlation purposes." }, "details": { "$ref": "#/components/schemas/error_details_list" }, "links": { "$ref": "#/components/schemas/error_definitions-link_description_list" } }, "required": [ "name", "message", "debug_id" ] }, "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 no systemic problems limiting the API from performing the request.", "properties": { "name": { "type": "string", "enum": [ "UNPROCESSABLE_ENTITY" ] }, "message": { "type": "string", "enum": [ "The requested action could not be performed, semantically incorrect, or failed business validation." ] }, "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_429": { "type": "object", "title": "Too many requests", "description": "Too many requests. Blocked due to rate limiting.", "properties": { "name": { "type": "string", "enum": [ "RATE_LIMIT_REACHED" ] }, "message": { "type": "string", "enum": [ "Too many requests. Blocked due to rate limiting." ] }, "debug_id": { "type": "string", "description": "The PayPal internal ID. Used for correlation purposes." } } }, "error_500": { "type": "object", "title": "Internal Server Error", "description": "This is either a system or application error, and generally indicates that although the client appeared to provide a correct request, something unexpected has gone wrong on the server.", "properties": { "name": { "type": "string", "enum": [ "INTERNAL_SERVER_ERROR" ] }, "message": { "type": "string", "enum": [ "An internal server error occurred." ] }, "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" } } }, "example": { "name": "INTERNAL_SERVER_ERROR", "message": "An internal server error occurred.", "debug_id": "90957fca61718", "links": [ { "href": "https://developer.paypal.com/api/orders/v2/#error-INTERNAL_SERVER_ERROR", "rel": "information_link" } ] } }, "error_503": { "type": "object", "title": "Service Unavailable Error", "description": "The server is temporarily unable to handle the request, for example, because of planned maintenance or downtime.", "properties": { "name": { "type": "string", "enum": [ "SERVICE_UNAVAILABLE" ] }, "message": { "type": "string", "enum": [ "Service Unavailable." ] }, "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" } } }, "example": { "name": "SERVICE_UNAVAILABLE", "message": "Service Unavailable.", "debug_id": "90957fca61718", "information_link": "https://developer.paypal.com/docs/api/orders/v2/#error-SERVICE_UNAVAILABLE" } }, "error_default": { "description": "The default error response.", "oneOf": [ { "$ref": "#/components/schemas/error_400" }, { "$ref": "#/components/schemas/error_401" }, { "$ref": "#/components/schemas/error_403" }, { "$ref": "#/components/schemas/error_404" }, { "$ref": "#/components/schemas/error_409" }, { "$ref": "#/components/schemas/error_415" }, { "$ref": "#/components/schemas/error_422" }, { "$ref": "#/components/schemas/error_429" }, { "$ref": "#/components/schemas/error_500" }, { "$ref": "#/components/schemas/error_503" } ] }, "error_definitions-link_description_list": { "type": "array", "description": "An array of request-related [HATEOAS links](/api/rest/responses/#hateoas-links).", "readOnly": true, "items": { "$ref": "#/components/schemas/link_description" } }, "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_details-2": { "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": { "type": "string", "description": "The location of the field that caused the error. Value is `body`, `path`, or `query`.", "default": "body" }, "issue": { "type": "string", "description": "The unique, fine-grained application-level error code." }, "links": { "$ref": "#/components/schemas/definitions-link_description_list" }, "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_details_list": { "type": "array", "description": "An array of additional details about the error.", "items": { "$ref": "#/components/schemas/error_details-2" } }, "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_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" }, "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_]+$", "x-enumDescriptions": [ { "value": "GET_FROM_FILE", "description": "Use the payer-provided shipping address on the PayPal site." }, { "value": "NO_SHIPPING", "description": "Redact the shipping address from the PayPal site. Recommended for digital goods." }, { "value": "SET_PROVIDED_ADDRESS", "description": "Use the merchant/platform-provided address. The payer cannot change this address on the PayPal site. If the merchant does not pass an address, the customer can choose the address on the PayPal site." } ], "enum": [ "GET_FROM_FILE", "NO_SHIPPING", "SET_PROVIDED_ADDRESS" ] }, "vault_instruction": { "description": "Vault Instruction on action to be performed after a successful payer approval.", "$ref": "#/components/schemas/vault_instruction" } } }, "frequency": {}, "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}))?$" }, "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" ] } } }, "link_description_list": { "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_-]+$" }, "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: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" ] }, "name": { "description": "The name of the party.", "type": "object", "title": "Name", "properties": { "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 } } }, "network_token_entity": {}, "network_transaction_reference_entity": { "type": "object", "title": "Network Transaction Reference Entity", "description": "Previous network transaction reference including id and network.", "properties": { "id": { "type": "string", "minLength": 9, "maxLength": 36, "pattern": "^[a-zA-Z0-9-_@.:&+=*^'~#!$%()]+$", "description": "Transaction reference id returned by the scheme. For Visa and Amex, this is the \"Tran id\" field in response. For MasterCard, this is the \"BankNet reference id\" field in response. For Discover, this is the \"NRID\" field in response. The pattern we expect for this field from Visa/Amex/CB/Discover is numeric, Mastercard/BNPP is alphanumeric and Paysecure is alphanumeric with special character -." }, "date": { "type": "string", "minLength": 4, "maxLength": 4, "pattern": "^[0-9]+$", "description": "The date that the transaction was authorized by the scheme. This field may not be returned for all networks. MasterCard refers to this field as \"BankNet reference date." }, "network": { "description": "Name of the card network through which the transaction was routed.", "$ref": "#/components/schemas/card_brand" }, "time": { "description": "The date and time when the instrument was verified.", "readOnly": true, "$ref": "#/components/schemas/date_time" } }, "required": [ "id" ] }, "network_transaction_reference_request": {}, "network_transaction_reference_response": { "title": "Network Transaction Reference Response", "type": "object", "description": "Previous network transaction reference including id in response.", "allOf": [ { "$ref": "#/components/schemas/network_transaction_reference_entity" } ] }, "one_time_charges": { "title": "One-Time Charges Info", "description": "The one-time charge info at the time of checkout.", "type": "object", "properties": { "setup_fee": { "description": "The setup fee for the recurring plan.", "$ref": "#/components/schemas/money" }, "shipping_amount": { "description": "The shipping amount due at the time of checkout.", "$ref": "#/components/schemas/money" }, "taxes": { "description": "The taxes due at the time of checkout.", "$ref": "#/components/schemas/money" }, "product_price": { "description": "The product price for any one-time product purchased at the time of checkout.", "$ref": "#/components/schemas/money" }, "subtotal": { "description": "The subtotal at the time of checkout. This is calculated by using the formula x + y + z where x is first-recurring-charge, y is setup-fee and z is item-price.", "readOnly": true, "$ref": "#/components/schemas/money" }, "total_amount": { "description": "The total amount at the time of checkout. This is calculated by using the formula x + y + z where x is subtotal, y is shipping-amount and z is taxes.", "$ref": "#/components/schemas/money" } }, "required": [ "total_amount" ] }, "pares_status": { "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^[0-9A-Z_]+$", "description": "Transactions status result identifier. The outcome of the issuer's authentication.", "x-enumDescriptions": [ { "value": "Y", "description": "Successful authentication." }, { "value": "N", "description": "Failed authentication / account not verified / transaction denied." }, { "value": "U", "description": "Unable to complete authentication." }, { "value": "A", "description": "Successful attempts transaction." }, { "value": "C", "description": "Challenge required for authentication." }, { "value": "R", "description": "Authentication rejected (merchant must not submit for authorization)." }, { "value": "D", "description": "Challenge required; decoupled authentication confirmed." }, { "value": "I", "description": "Informational only; 3DS requestor challenge preference acknowledged." } ], "enum": [ "Y", "N", "U", "A", "C", "R", "D", "I" ] }, "payer_base": { "type": "object", "title": "Payer Base", "description": "The customer who approves and pays for the order. The customer is also known as the payer.", "properties": { "email_address": { "description": "The email address of the payer.", "$ref": "#/components/schemas/email" }, "payer_id": { "description": "The PayPal-assigned ID for the payer.", "readOnly": true, "$ref": "#/components/schemas/account_id" } } }, "payment_source": { "title": "Payment token response 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" } } }, "payment_source_card": { "type": "object", "title": "Card Request", "description": "A Resource representing a request to vault a Card.", "properties": { "name": { "type": "string", "description": "The card holder's name as it appears on the card.", "maxLength": 300, "minLength": 1, "pattern": "^.{1,300}$" }, "number": { "type": "string", "description": "The primary account number (PAN) for the payment card.", "pattern": "^[0-9]{13,19}$", "minLength": 13, "maxLength": 19 }, "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" }, "security_code": { "type": "string", "description": "The three- or four-digit security code of the card. Also known as the CVV, CVC, CVN, CVE, or CID. This parameter cannot be present in the request when `payment_initiator=MERCHANT`.", "pattern": "^[0-9]{3,4}$", "minLength": 3, "maxLength": 4 }, "brand": { "description": "The card brand or network. Typically used in the response.", "$ref": "#/components/schemas/card_brand" }, "billing_address": { "$ref": "#/components/schemas/payment_source_card_billing_address" }, "network_transaction_reference": { "$ref": "#/components/schemas/network_transaction_reference_request" } } }, "payment_source_card_billing_address": { "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).", "type": "object", "title": "Portable Postal Address (Medium-Grained)", "properties": { "address_line_1": { "type": "string", "description": "The first line of the address, such as number and street, for example, `173 Drury Lane`. Needed for data entry, and Compliance and Risk checks. This field needs to pass the full address.", "maxLength": 300 }, "address_line_2": { "type": "string", "description": "The second line of the address, for example, a suite or apartment number.", "maxLength": 300 }, "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. This data is formatted for postal delivery, for example, `CA` and not `California`. Value, by country, is:", "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" } }, "required": [ "country_code" ] }, "payment_token_request": { "title": "Payment Token Request", "description": "Payment Token Request where the `source` defines the type of instrument to be stored.", "type": "object", "properties": { "customer": { "$ref": "#/components/schemas/customer" }, "payment_source": { "$ref": "#/components/schemas/definitions-payment_source" } }, "required": [ "payment_source" ] }, "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": { "$ref": "#/components/schemas/payment_source" }, "links": { "$ref": "#/components/schemas/link_description_list" } } }, "payment_token_response_list": { "type": "array", "minItems": 0, "maxItems": 64, "items": { "$ref": "#/components/schemas/payment_token_response" } }, "payment_token_status": { "title": "Payment Token Status", "type": "string", "description": "The status of the payment token.", "minLength": 1, "maxLength": 255, "pattern": "^[0-9A-Z_]+$", "default": "CREATED", "x-enumDescriptions": [ { "value": "CREATED", "description": "A setup token is initialized with minimal information, more data must be added to the setup-token to be vaulted" }, { "value": "PAYER_ACTION_REQUIRED", "description": "A contingecy on payer approval is required before the payment method can be saved." }, { "value": "APPROVED", "description": "Setup token is ready to be vaulted. If a buyer approval contigency was returned, it is has been approved." }, { "value": "VAULTED", "description": "The payment token has been vaulted." }, { "value": "TOKENIZED", "description": "A vaulted payment method token has been tokenized for short term (one time) use." } ], "enum": [ "CREATED", "PAYER_ACTION_REQUIRED", "APPROVED", "VAULTED", "TOKENIZED" ] }, "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": { "billing_plan": { "$ref": "#/components/schemas/plan" }, "experience_context": { "$ref": "#/components/schemas/experience_context" } } } ] }, "paypal_wallet_response": { "allOf": [ { "description": "Resource consolidating common request and response attributes for vaulting a Digital Wallet.", "$ref": "#/components/schemas/wallet_base" }, { "description": "Resource consolidating common request and response attributes for vaulting a Digital Wallet." }, { "description": "Resource consolidating common request and response attributes for vaulting a Digital Wallet." }, { "$ref": "#/components/schemas/payer_base" }, { "properties": { "name": { "$ref": "#/components/schemas/name" }, "phone": { "description": "The phone number of the customer. Available only when you enable the **Contact Telephone Number** option in the **Profile & Settings** for the merchant's PayPal account. The `phone.phone_number` supports only `national_number`.", "$ref": "#/components/schemas/phone_with_type" }, "address": { "$ref": "#/components/schemas/address" } } }, { "$ref": "#/components/schemas/5" }, { "properties": { "account_id": { "readOnly": true, "description": "The account identifier for a PayPal account.", "$ref": "#/components/schemas/account_id" }, "phone_number": { "readOnly": true, "description": "The phone number, in its canonical international [E.164 numbering plan format](https://www.itu.int/rec/T-REC-E.164/en).", "$ref": "#/components/schemas/phone" } } }, { "$ref": "#/components/schemas/7" } ] }, "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" ] }, "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).", "type": "object", "title": "Phone", "properties": { "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}?$" } }, "required": [ "national_number" ] }, "phone_type": { "type": "string", "title": "Phone Type", "description": "The phone type.", "enum": [ "FAX", "HOME", "MOBILE", "OTHER", "PAGER" ] }, "phone_with_type": { "type": "object", "title": "Phone With Type", "description": "The phone information.", "properties": { "phone_type": { "$ref": "#/components/schemas/phone_type" }, "phone_number": { "$ref": "#/components/schemas/phone_number" } }, "required": [ "phone_number" ] }, "plan": { "title": "Plan", "description": "The merchant level Recurring Billing plan metadata for the Billing Agreement.", "type": "object", "properties": { "billing_cycles": { "$ref": "#/components/schemas/billing_cycle_list" }, "product": { "description": "Product details associated with any one-time product purchase.", "$ref": "#/components/schemas/product_override" }, "one_time_charges": { "description": "Price and currency for any one-time charges due at plan signup.", "$ref": "#/components/schemas/one_time_charges" }, "name": { "type": "string", "description": "Name of the recurring plan.", "minLength": 1, "maxLength": 127, "pattern": "^[A-Za-z0-9() +',.:-]+$" } }, "required": [ "billing_cycles", "one_time_charges" ] }, "pricing_scheme": { "title": "Pricing Scheme", "description": "The pricing scheme details.", "type": "object", "properties": { "price": { "description": "The price the customer will be charged based on the pricing model", "$ref": "#/components/schemas/money" }, "pricing_model": { "type": "string", "description": "The pricing model for the billing cycle.", "minLength": 1, "maxLength": 24, "pattern": "^[A-Z_]+$", "x-enumDescriptions": [ { "value": "FIXED", "description": "A fixed pricing scheme where the customer is charged a fixed amount." }, { "value": "VARIABLE", "description": "A variable pricing scheme where the customer is charged a variable amount." }, { "value": "AUTO_RELOAD", "description": "A auto-reload pricing scheme where the customer is charged a fixed amount for reload." } ], "enum": [ "FIXED", "VARIABLE", "AUTO_RELOAD" ] }, "reload_threshold_amount": { "description": "The threshold amount on which the reload charge would be triggered. This will be associated with the account-balance where if the account-balance goes below this amount then customer would incur reload charge.", "$ref": "#/components/schemas/money" } }, "required": [ "pricing_model" ] }, "processor_response": { "description": "The processor response information for payment requests, such as direct credit card transactions.", "type": "object", "title": "Processor Response", "properties": { "avs_code": { "description": "The address verification code for Visa, Discover, Mastercard, or American Express transactions.", "type": "string", "readOnly": true, "x-enumDescriptions": [ { "value": "A", "description": "For Visa, Mastercard, or Discover transactions, the address matches but the zip code does not match. For American Express transactions, the card holder address is correct." }, { "value": "B", "description": "For Visa, Mastercard, or Discover transactions, the address matches. International A." }, { "value": "C", "description": "For Visa, Mastercard, or Discover transactions, no values match. International N." }, { "value": "D", "description": "For Visa, Mastercard, or Discover transactions, the address and postal code match. International X." }, { "value": "E", "description": "For Visa, Mastercard, or Discover transactions, not allowed for Internet or phone transactions. For American Express card holder, the name is incorrect but the address and postal code match." }, { "value": "F", "description": "For Visa, Mastercard, or Discover transactions, the address and postal code match. UK-specific X. For American Express card holder, the name is incorrect but the address matches." }, { "value": "G", "description": "For Visa, Mastercard, or Discover transactions, global is unavailable. Nothing matches." }, { "value": "I", "description": "For Visa, Mastercard, or Discover transactions, international is unavailable. Not applicable." }, { "value": "M", "description": "For Visa, Mastercard, or Discover transactions, the address and postal code match. For American Express card holder, the name, address, and postal code match." }, { "value": "N", "description": "For Visa, Mastercard, or Discover transactions, nothing matches. For American Express card holder, the address and postal code are both incorrect." }, { "value": "P", "description": "For Visa, Mastercard, or Discover transactions, postal international Z. Postal code only." }, { "value": "R", "description": "For Visa, Mastercard, or Discover transactions, re-try the request. For American Express, the system is unavailable." }, { "value": "S", "description": "For Visa, Mastercard, Discover, or American Express, the service is not supported." }, { "value": "U", "description": "For Visa, Mastercard, or Discover transactions, the service is unavailable. For American Express, information is not available. For Maestro, the address is not checked or the acquirer had no response. The service is not available." }, { "value": "W", "description": "For Visa, Mastercard, or Discover transactions, whole ZIP code. For American Express, the card holder name, address, and postal code are all incorrect." }, { "value": "X", "description": "For Visa, Mastercard, or Discover transactions, exact match of the address and the nine-digit ZIP code. For American Express, the card holder name, address, and postal code are all incorrect." }, { "value": "Y", "description": "For Visa, Mastercard, or Discover transactions, the address and five-digit ZIP code match. For American Express, the card holder address and postal code are both correct." }, { "value": "Z", "description": "For Visa, Mastercard, or Discover transactions, the five-digit ZIP code matches but no address. For American Express, only the card holder postal code is correct." }, { "value": "Null", "description": "For Maestro, no AVS response was obtained." }, { "value": "0", "description": "For Maestro, all address information matches." }, { "value": "1", "description": "For Maestro, none of the address information matches." }, { "value": "2", "description": "For Maestro, part of the address information matches." }, { "value": "3", "description": "For Maestro, the merchant did not provide AVS information. It was not processed." }, { "value": "4", "description": "For Maestro, the address was not checked or the acquirer had no response. The service is not available." } ], "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, "x-enumDescriptions": [ { "value": "E", "description": "For Visa, Mastercard, Discover, or American Express, error - unrecognized or unknown response." }, { "value": "I", "description": "For Visa, Mastercard, Discover, or American Express, invalid or null." }, { "value": "M", "description": "For Visa, Mastercard, Discover, or American Express, the CVV2/CSC matches." }, { "value": "N", "description": "For Visa, Mastercard, Discover, or American Express, the CVV2/CSC does not match." }, { "value": "P", "description": "For Visa, Mastercard, Discover, or American Express, it was not processed." }, { "value": "S", "description": "For Visa, Mastercard, Discover, or American Express, the service is not supported." }, { "value": "U", "description": "For Visa, Mastercard, Discover, or American Express, unknown - the issuer is not certified." }, { "value": "X", "description": "For Visa, Mastercard, Discover, or American Express, no response. For Maestro, the service is not available." }, { "value": "All others", "description": "For Visa, Mastercard, Discover, or American Express, error." }, { "value": "0", "description": "For Maestro, the CVV2 matched." }, { "value": "1", "description": "For Maestro, the CVV2 did not match." }, { "value": "2", "description": "For Maestro, the merchant has not implemented CVV2 code handling." }, { "value": "3", "description": "For Maestro, the merchant has indicated that CVV2 is not present on card." }, { "value": "4", "description": "For Maestro, the service is not available." } ], "enum": [ "E", "I", "M", "N", "P", "S", "U", "X", "All others", "0", "1", "2", "3", "4" ] } } }, "product_override": {}, "products": { "type": "string", "description": "This value provides the category of the BIN.", "minLength": 1, "maxLength": 255 }, "products_list": { "type": "array", "description": "The type of card product assigned to the BIN by the issuer. These values are defined by the issuer and may change over time. Some examples include: PREPAID_GIFT, CONSUMER, CORPORATE.", "items": { "$ref": "#/components/schemas/products" }, "minItems": 1, "maxItems": 256 }, "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": { "$ref": "#/components/schemas/customer" }, "payment_source": { "description": "The payment method to vault with the instrument details.", "properties": { "card": { "$ref": "#/components/schemas/definitions-card" }, "paypal": { "$ref": "#/components/schemas/paypal_wallet_request" }, "venmo": { "$ref": "#/components/schemas/venmo_request" }, "token": { "$ref": "#/components/schemas/token_id_request" } } } }, "required": [ "payment_source" ] }, "setup_token_response": { "title": "Minimal Setup Token", "description": "Minimal representation of a cached setup token.", "type": "object", "properties": { "id": { "description": "The PayPal-generated ID for the vault token.", "$ref": "#/components/schemas/vault_id" }, "customer": { "$ref": "#/components/schemas/customer" }, "status": { "description": "The status of the payment token.", "$ref": "#/components/schemas/payment_token_status" }, "payment_source": { "description": "The setup payment method details.", "properties": { "card": { "allOf": [ { "$ref": "#/components/schemas/card_response_entity" }, { "properties": {} }, { "$ref": "#/components/schemas/definitions-2" } ] }, "paypal": { "$ref": "#/components/schemas/paypal_wallet_response" }, "venmo": { "$ref": "#/components/schemas/venmo_response" } } }, "links": { "$ref": "#/components/schemas/link_description_list" } } }, "shipping": { "description": "The shipping details.", "type": "object", "title": "Shipping Details", "properties": { "name": { "$ref": "#/components/schemas/shipping_name" }, "phone_number": { "$ref": "#/components/schemas/shipping_phone_number" }, "type": { "title": "Fullfillment Type", "description": "A classification for the method of purchase fulfillment (e.g shipping, in-store pickup, etc). Either `type` or `options` may be present, but not both.", "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^[0-9A-Z_]+$", "x-enumDescriptions": [ { "value": "SHIPPING", "description": "The payer intends to receive the items at a specified address.", "default": true }, { "value": "PICKUP_IN_PERSON", "description": "DEPRECATED. Please use \"PICKUP_FROM_PERSON\" instead." }, { "value": "PICKUP_IN_STORE", "description": "The payer intends to pick up the item(s) from the payee's physical store. Also termed as BOPIS, \"Buy Online, Pick-up in Store\". Seller protection is provided with this option." }, { "value": "PICKUP_FROM_PERSON", "description": "The payer intends to pick up the item(s) from the payee in person. Also termed as BOPIP, \"Buy Online, Pick-up in Person\". Seller protection is not available, since the payer is receiving the item from the payee in person, and can validate the item prior to payment." } ], "enum": [ "SHIPPING", "PICKUP_IN_PERSON", "PICKUP_IN_STORE", "PICKUP_FROM_PERSON" ] }, "address": { "$ref": "#/components/schemas/shipping_address" } } }, "shipping_address": { "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).", "type": "object", "title": "Portable Postal Address (Medium-Grained)", "properties": { "address_line_1": { "type": "string", "description": "The first line of the address, such as number and street, for example, `173 Drury Lane`. Needed for data entry, and Compliance and Risk checks. This field needs to pass the full address.", "maxLength": 300 }, "address_line_2": { "type": "string", "description": "The second line of the address, for example, a suite or apartment number.", "maxLength": 300 }, "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. This data is formatted for postal delivery, for example, `CA` and not `California`. Value, by country, is:", "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" } }, "required": [ "country_code" ] }, "shipping_name": { "description": "The name of the party.", "type": "object", "title": "Name", "properties": { "full_name": { "type": "string", "description": "When the party is a person, the party's full name.", "maxLength": 300 } } }, "shipping_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).", "type": "object", "title": "Phone", "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}?$" } }, "required": [ "country_code", "national_number" ] }, "three_d_secure_authentication_response": { "type": "object", "title": "Response of 3D Secure Authentication", "description": "Results of 3D Secure Authentication.", "properties": { "authentication_status": { "description": "The outcome of the issuer's authentication.", "$ref": "#/components/schemas/pares_status" }, "enrollment_status": { "description": "Status of authentication eligibility.", "$ref": "#/components/schemas/enrolled" } } }, "three_d_secure_authentication_response-2": { "type": "object", "title": "Three D Secure Authentication Response", "description": "Results of 3D Secure Authentication.", "allOf": [ { "$ref": "#/components/schemas/three_d_secure_authentication_response" }, { "properties": { "authentication_id": { "type": "string", "description": "The externally received 3ds authentication id, to be returned in card detokenization response.", "minLength": 1, "maxLength": 255, "pattern": "^[0-9a-zA-Z_-]+$" } } } ] }, "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-Za-z_-]+$" }, "type": { "type": "string", "description": "The tokenization method that generated the ID.", "minLength": 1, "maxLength": 255, "pattern": "^[0-9A-Z_-]+$", "x-enumDescriptions": [ { "value": "SETUP_TOKEN", "description": "The setup token, which is a temporary reference to payment source." } ], "enum": [ "SETUP_TOKEN" ] } }, "required": [ "id", "type" ] }, "vault_id": { "type": "string", "description": "The PayPal-generated ID for the vault token.", "minLength": 1, "maxLength": 36, "pattern": "^[0-9a-zA-Z_-]+$" }, "vault_instruction": { "title": "Vault Instruction", "type": "string", "description": "Vault Instruction on action to be performed after a successful payer approval.", "minLength": 1, "maxLength": 255, "pattern": "^[A-Z_]+$", "default": "ON_CREATE_PAYMENT_TOKENS", "x-enumDescriptions": [ { "value": "ON_CREATE_PAYMENT_TOKENS", "description": "Vault the payment method after API caller performs a successful POST on Payment Tokens." }, { "value": "ON_PAYER_APPROVAL", "description": "Vault the payment method on successful payer authentication and approval." } ], "enum": [ "ON_CREATE_PAYMENT_TOKENS", "ON_PAYER_APPROVAL" ] }, "venmo_request": { "allOf": [ { "$ref": "#/components/schemas/wallet_base" }, { "properties": { "experience_context": { "$ref": "#/components/schemas/definitions-experience_context" } } }, { "$ref": "#/components/schemas/2" } ] }, "venmo_response": { "allOf": [ { "description": "Resource consolidating common request and response attributes for vaulting a Digital Wallet.", "$ref": "#/components/schemas/wallet_base" }, { "description": "Resource consolidating common request and response attributes for vaulting a Digital Wallet." }, { "description": "Resource consolidating common request and response attributes for vaulting a Digital Wallet." }, { "$ref": "#/components/schemas/payer_base" }, { "properties": { "name": { "$ref": "#/components/schemas/name" }, "phone": { "description": "The phone number of the customer. Available only when you enable the **Contact Telephone Number** option in the **Profile & Settings** for the merchant's PayPal account. The `phone.phone_number` supports only `national_number`.", "$ref": "#/components/schemas/phone_with_type" }, "address": { "$ref": "#/components/schemas/address" } } }, { "$ref": "#/components/schemas/5" }, { "properties": { "user_name": { "description": "The Venmo username, as chosen by the user.", "type": "string", "pattern": "^[-a-zA-Z0-9_]*$", "minLength": 1, "maxLength": 50 } } }, { "$ref": "#/components/schemas/definitions-7" } ] }, "wallet_base": { "type": "object", "title": "Vaulted Digital Wallet Common Attributes", "description": "Resource consolidating common request and response attributes for vaulting a Digital Wallet.", "properties": { "description": { "type": "string", "description": "The description displayed to the consumer on the approval flow for a digital wallet, as well as on the merchant view of the payment token management experience. exp: PayPal.com.", "minLength": 1, "maxLength": 128, "pattern": "^.*$" }, "usage_pattern": { "type": "string", "description": "Expected business/charge model for the billing agreement.", "minLength": 1, "maxLength": 30, "pattern": "^[0-9A-Z_]+$", "x-enumDescriptions": [ { "value": "IMMEDIATE", "description": "On-demand instant payments – non-recurring, pre-paid, variable amount, variable frequency." }, { "value": "DEFERRED", "description": "Pay after use, non-recurring post-paid, variable amount, irregular frequency." }, { "value": "RECURRING_PREPAID", "description": "Pay upfront fixed or variable amount on a fixed date before the goods/service is delivered." }, { "value": "RECURRING_POSTPAID", "description": "Pay on a fixed date based on usage or consumption after the goods/service is delivered." }, { "value": "THRESHOLD_PREPAID", "description": "Charge payer when the set amount is reached or monthly billing cycle, whichever comes first, before the goods/service is delivered." }, { "value": "THRESHOLD_POSTPAID", "description": "Charge payer when the set amount is reached or monthly billing cycle, whichever comes first, after the goods/service is delivered." }, { "value": "UNSCHEDULED_POSTPAID", "description": "Merchant-managed installment plan when the amount to be paid and the billing frequency are fixed, but there is a defined number of payments with the payment due after the goods/services are delivered." }, { "value": "UNSCHEDULED_PREPAID", "description": "Unscheduled card on file plan where the merchant can bill buyer upfront based on an agreed logic, but amount due and frequency can vary. Inclusive of automatic reload plans." }, { "value": "SUBSCRIPTION_PREPAID", "description": "Subscription plan where the amount due and the billing frequency are fixed, and there is no defined duration with the payment due before the good/service is delivered." }, { "value": "SUBSCRIPTION_POSTPAID", "description": "Subscription plan where the amount due and the billing frequency are fixed, and there is no defined duration with the payment due after the goods/services are delivered." }, { "value": "INSTALLMENT_POSTPAID", "description": "Merchant-managed installment plan when the amount to be paid and the billing frequency are fixed, but there is a defined number of payments with the payment due after the goods/services are delivered." }, { "value": "INSTALLMENT_PREPAID", "description": "Merchant-managed installment plan when the amount to be paid and the billing frequency are fixed, but there is a defined number of payments with the payment due before the good/service is delivered." } ], "enum": [ "IMMEDIATE", "DEFERRED", "RECURRING_PREPAID", "RECURRING_POSTPAID", "THRESHOLD_PREPAID", "THRESHOLD_POSTPAID", "UNSCHEDULED_POSTPAID", "UNSCHEDULED_PREPAID", "SUBSCRIPTION_PREPAID", "SUBSCRIPTION_POSTPAID", "INSTALLMENT_POSTPAID", "INSTALLMENT_PREPAID" ] }, "shipping": { "$ref": "#/components/schemas/shipping" }, "permit_multiple_payment_tokens": { "type": "boolean", "description": "Create multiple payment tokens for the same payer, merchant/platform combination. Use this when the customer has not logged in at merchant/platform. The payment token thus generated, can then also be used to create the customer account at merchant/platform. Use this also when multiple payment tokens are required for the same payer, different customer at merchant/platform. This helps to identify customers distinctly even though they may share the same PayPal account. This only applies to PayPal payment source.", "default": false }, "usage_type": { "type": "string", "description": "The usage type associated with a digital wallet payment token.", "minLength": 1, "maxLength": 255, "pattern": "^[0-9A-Z_]+$", "x-enumDescriptions": [ { "value": "MERCHANT", "description": "The PayPal Payment Token will be used for future transaction directly with a merchant." }, { "value": "PLATFORM", "description": "The PayPal Payment Token will be used for future transaction on a platform. A platform is typically a marketplace or a channel that a payer can purchase goods and services from multiple merchants." } ], "enum": [ "MERCHANT", "PLATFORM" ] }, "customer_type": { "type": "string", "description": "The customer type associated with a digital wallet payment token. This is to indicate whether the customer acting on the merchant / platform is either a business or a consumer.", "minLength": 1, "maxLength": 255, "pattern": "^[0-9A-Z_]+$", "x-enumDescriptions": [ { "value": "CONSUMER", "description": "The customer vaulting the PayPal payment token is a consumer on the merchant / platform." }, { "value": "BUSINESS", "description": "The customer vaulting the PayPal payment token is a business on merchant / platform." } ], "enum": [ "CONSUMER", "BUSINESS" ] } } } }, "parameters": { "paypal_request_id": { "name": "PayPal-Request-Id", "description": "The server stores keys for 3 hours.", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 10000, "pattern": "^.*$" } }, "customer_id": { "name": "customer_id", "description": "A unique identifier representing a specific customer in merchant's/partner's system or records.", "in": "query", "required": true, "schema": { "type": "string", "minLength": 7, "maxLength": 36, "pattern": "^[0-9a-zA-Z_-]+$" } }, "page_size": { "name": "page_size", "description": "A non-negative, non-zero integer indicating the maximum number of results to return at one time.", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 5, "default": 5 } }, "page": { "name": "page", "description": "A non-negative, non-zero integer representing the page of the results.", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 10, "default": 1 } }, "total_required": { "name": "total_required", "description": "A boolean indicating total number of items (total_items) and pages (total_pages) are expected to be returned in the response.", "in": "query", "required": false, "schema": { "type": "boolean", "default": false } }, "id": { "name": "id", "description": "ID of the setup token.", "in": "path", "required": true, "schema": { "type": "string", "minLength": 7, "maxLength": 36, "pattern": "^[0-9a-zA-Z_-]+$" } } } } }