On this page
No Headings
email_addressstringmerchant_common_email_address_v2(?:[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])+)\])The email address of the payer.
payer_idstringppaas_payer_id_v3^[2-9A-HJ-NP-Z]{13}$The PayPal-assigned ID for the payer.
nameobjectThe name of the party.
given_namestringWhen the party is a person, the party's given, or first, name.
surnamestringWhen 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.
shipping_addressobjectThe shipping details.
nameobjectThe name of the party.
full_namestringWhen the party is a person, the party's full name.
email_addressstringppaas_common_email_address_v2^(?:[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])?|\[(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-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])+)\])$The email address of the recipient of the shipped items, which may belong to either the payer, or an alternate contact, for delivery.
phone_numberobjectThe phone number, in its canonical international E.164 numbering plan format.
country_coderequiredstring^[0-9]{1,3}?$The country calling code (CC), in its canonical international E.164 numbering plan format. 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).
national_numberrequiredstring^[0-9]{1,14}?$The national number, in its canonical international E.164 numbering plan format. 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).
typestring"SHIPPING", "PICKUP_IN_PERSON", "PICKUP_IN_STORE", "PICKUP_FROM_PERSON"^[0-9A-Z_]+$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.
optionsarrayAn array of shipping options that the payee or merchant offers to the payer to ship or pick up their items.
itemsobjectThe options that the payee or merchant offers to the payer to ship or pick up their items.
idrequiredstringA unique ID that identifies a payer-selected shipping option.
labelrequiredstringA description that the payer sees, which helps them choose an appropriate shipping option. For example, Free Shipping, USPS Priority Shipping, Expédition prioritaire USPS, or USPS yōuxiān fā huò. Localize this description to the payer's locale.
typestring"SHIPPING", "PICKUP", "PICKUP_IN_STORE", "PICKUP_FROM_PERSON"A classification for the method of purchase fulfillment.
amountobjectThe shipping cost for the selected option.
currency_coderequiredstringThe three-character ISO-4217 currency code that identifies the currency.
valuerequiredstring^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$The value, which might be:
JPY that are not typically fractional.TND that are subdivided into thousandths.selectedrequiredbooleanIf the API request sets selected = true, it represents the shipping option that the payee or merchant expects to be pre-selected for the payer when they first view the shipping.options in the PayPal Checkout experience. As part of the response if a shipping.option contains selected=true, it represents the shipping option that the payer selected during the course of checkout with PayPal. Only one shipping.option can be set to selected=true.
addressobjectThe portable international postal address. Maps to AddressValidationMetadata and HTML 5.1 Autofilling form controls: the autocomplete attribute.
address_line_1stringThe 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.
address_line_2stringThe second line of the address, for example, a suite or apartment number.
admin_area_2stringA city, town, or village. Smaller than admin_area_level_1.
admin_area_1stringThe 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:
postal_codestringThe postal code, which is the ZIP code or equivalent. Typically required for countries with a postal code or an equivalent. See postal code.
country_coderequiredstringppaas_common_country_code_v2^([A-Z]{2}|C2)$The 2-character ISO 3166-1 code that identifies the country or region.
Note: The country code for Great Britain isGBand notUKas used in the top-level domain names for that country. Use theC2country code for China worldwide for comparable uncontrolled price (CUP) method, bank card, and cross-border transactions.
payment_sourceobjectThe payment source used to fund the payment.
cardobjectThe payment card to use to fund a payment. Card can be a credit or debit card.
The payment card used to fund the payment. Card can be a credit or debit card.
namestringThe card holder's name as it appears on the card.
last_digitsstring[0-9]{2,}The last digits of the payment card.
brandstring"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"^[A-Z_]+$The card brand or network. Typically used in the response.
available_networksarrayArray of brands or networks associated with the card.
itemsstring"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"^[A-Z_]+$The card network or brand. Applies to credit, debit, gift, and payment cards.
typestring"CREDIT", "DEBIT", "PREPAID", "STORE", "UNKNOWN"^[A-Z_]+$The payment card type.
authentication_resultobjectResults of Authentication such as 3D Secure.
liability_shiftstring"NO", "POSSIBLE", "UNKNOWN"^[0-9A-Z_]+$Liability shift indicator. The outcome of the issuer's authentication.
three_d_secureobjectResults of 3D Secure Authentication.
authentication_statusstring"Y", "N", "U", "A", "C", "R", "D", "I"^[0-9A-Z_]+$The outcome of the issuer's authentication.
enrollment_statusstring"Y", "N", "U", "B"^[0-9A-Z_]+$Status of authentication eligibility.
attributesobjectAdditional attributes associated with the use of this card.
vaultobjectThe details about a saved Card payment source.
idstringThe PayPal-generated ID for the saved payment source.
statusstring"VAULTED", "CREATED", "APPROVED"^[0-9A-Z_]+$The vault status.
linksarrayAn array of request-related HATEOAS links.
itemsobjectThe request-related HATEOAS link information.
hrefrequiredstringThe complete target URL. To make the related call, combine the method with this URI Template-formatted link. For pre-processing, include the $, (, and ) characters. The href is the key HATEOAS component that links a completed call with a subsequent call.
relrequiredstringThe link relation type, which serves as an ID for a link that unambiguously describes the semantics of the link. See Link Relations.
methodstring"GET", "POST", "PUT", "DELETE", "HEAD", "CONNECT", "OPTIONS", "PATCH"The HTTP method required to make the related call.
customerobjectThe details about a customer in PayPal's system of record.
idstring^[0-9a-zA-Z_-]+$The unique ID for a customer generated by PayPal.
email_addressstringmerchant_common_email_address_v2(?:[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])+)\])Email address of the buyer as provided to the merchant or on file with the merchant. Email Address is required if you are processing the transaction using PayPal Guest Processing which is offered to select partners and merchants. For all other use cases we do not expect partners/merchant to send email_address of their customer.
phoneobjectThe phone number of the buyer as provided to the merchant or on file with the merchant. The phone.phone_number supports only national_number.
phone_typestring"FAX", "HOME", "MOBILE", "OTHER", "PAGER"The phone type.
phone_numberrequiredobjectThe phone number, in its canonical international E.164 numbering plan format.
national_numberrequiredstring^[0-9]{1,14}?$The national number, in its canonical international E.164 numbering plan format. 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).
merchant_customer_idstring^[0-9a-zA-Z-_.^*$@#]+$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.
from_requestobjectRepresentation of card details as received in the request.
expirystring^[0-9]{4}-(0[1-9]|1[0-2])$The card expiration year and month, in Internet date format.
last_digitsstring[0-9]{2,}The last digits of the payment card.
expirystring^[0-9]{4}-(0[1-9]|1[0-2])$The card expiration year and month, in Internet date format.
bin_detailsobjectBank Identification Number (BIN) details used to fund a payment.
binstring^[0-9]+$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.
issuing_bankstringThe issuer of the card instrument.
bin_country_codestringppaas_common_country_code_v2^([A-Z]{2}|C2)$The two-character ISO-3166-1 country code of the bank.
productsarrayThe 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.
itemsstringThis value provides the category of the BIN.
stored_credentialobjectProvides additional details to process a payment using a card that has been stored or is intended to be stored (also referred to as stored_credential or card-on-file).
Parameter compatibility:
payment_type=ONE_TIME is compatible only with payment_initiator=CUSTOMER.usage=FIRST is compatible only with payment_initiator=CUSTOMER.previous_transaction_reference or previous_network_transaction_reference is compatible only with payment_initiator=MERCHANT.previous_transaction_reference and previous_network_transaction_reference - can be present in the request.payment_initiatorrequiredstring"CUSTOMER", "MERCHANT"^[0-9A-Z_]+$The person or party who initiated or triggered the payment.
payment_typerequiredstring"ONE_TIME", "RECURRING", "UNSCHEDULED"^[0-9A-Z_]+$Indicates the type of the stored payment_source payment.
usagestring"FIRST", "SUBSEQUENT", "DERIVED"^[0-9A-Z_]+$"DERIVED"Indicates if this is a first or subsequent payment using a stored payment source (also referred to as stored credential or card on file).
previous_network_transaction_referenceobjectReference values used by the card network to identify a transaction.
idrequiredstring^[a-zA-Z0-9-_@.:&+=*^'~#!$%()]+$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 -.
datestring^[0-9]+$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.
networkstring"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"^[A-Z_]+$Name of the card network through which the transaction was routed.
acquirer_reference_numberstring^[a-zA-Z0-9]+$Reference ID issued for the card transaction. This ID can be used to track the transaction across processors, card brands and issuing banks.
billing_addressobjectThe portable international postal address. Maps to AddressValidationMetadata and HTML 5.1 Autofilling form controls: the autocomplete attribute.
address_line_1stringThe 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.
address_line_2stringThe second line of the address, for example, a suite or apartment number.
admin_area_2stringA city, town, or village. Smaller than admin_area_level_1.
admin_area_1stringThe 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:
postal_codestringThe postal code, which is the ZIP code or equivalent. Typically required for countries with a postal code or an equivalent. See postal code.
country_coderequiredstringppaas_common_country_code_v2^([A-Z]{2}|C2)$The 2-character ISO 3166-1 code that identifies the country or region.
Note: The country code for Great Britain isGBand notUKas used in the top-level domain names for that country. Use theC2country code for China worldwide for comparable uncontrolled price (CUP) method, bank card, and cross-border transactions.
currency_codestringCurrency code of the given instrument