Create payment

Deprecation notice: The /v1/payments endpoint is deprecated. Use the /v2/payments endpoint instead. For details, see PayPal Checkout Basic Integration.

Creates a sale, an authorized payment to be captured later, or an order. To create a sale, authorization, or order, include the payment details in the JSON request body. Set the intent to sale, authorize, or order.

Note: TPP Clients (Third Party Providers in the context of PSD2 regulation) are restricted from using authorize and order intents.

Include payer, transaction details, and, for PayPal payments only, redirect URLs. The combination of the payment_method and funding_instrument determines the type of payment that is created. For more information, see Payments REST API.

Authorization

AuthorizationBearer <token>

Oauth 2.0 authentication

In: header

Scope: https://api.paypal.com/v1/payments/.*

Header Parameters

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

intentenumRequired

The payment intent. Value is:

sale. Makes an immediate payment.
authorize. [Authorizes a payment for capture later](/docs/integration/direct/payments/authorize-and-capture-payments/).
order. [Creates an order](/docs/integration/direct/payments/orders/).

Value in"sale" | "authorize" | "order"

payerobject<payer>Required

The source of the funds for this payment. Payment method is PayPal Wallet payment or bank direct debit.

payer properties

3 properties

payment_methodenumOptional

The payment method.

funding_instrumentsobject<funding_instrument>[]Optional

An array of a single funding instrument for the current payment. Valid only and required for the credit card payment method. The array must include either a `credit_card` or `credit_card_token` object. If the array contains more than one instrument, the payment is declined.

Items1 <= length <= 1

payer_infoobject<payer_info>Optional

The payer information.

payer_info properties

5 properties

emailstringOptional

The payer's email address. Maximum length is 127 characters.

Formatemail

birth_datestringOptional

The birth date of the payer, in [Internet date format](https://tools.ietf.org/html/rfc3339#section-5.6). For example, `1990-04-12`.

Formatdate-time

tax_idstringOptional

The payer's tax ID. Supported for the PayPal payment method only.

Length0 <= length <= 14

tax_id_typeenumOptional

The payer's tax ID type. Supported for the PayPal payment method only.

Value in"BR_CPF" | "BR_CNPJ"

billing_addressobject<address>Optional

The payer's billing address.

address properties

8 properties

line1stringRequired

The first line of the address. For example, number, street, and so on.

Length0 <= length <= 300

line2stringOptional

The second line of the address. For example, suite or apartment number.

Length0 <= length <= 300

citystringOptional

The city name.

Length0 <= length <= 64

country_codestring<country_code>Required

The [two-character ISO 3166-1 code](/docs/api/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.

Match^([A-Z]{2}|C2)$Formatppaas_common_country_code_v2Length2 <= length <= 2

postal_codestringOptional

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).

statestringOptional

The [code](/docs/integration/direct/rest/state-codes/) for a US state or the equivalent for other countries. Required for transactions if the address is in one of these countries: [Argentina](/docs/integration/direct/rest/state-codes/#argentina), [Brazil](/docs/integration/direct/rest/state-codes/#brazil), [Canada](/docs/integration/direct/rest/state-codes/#canada), [China](/docs/integration/direct/rest/state-codes/#china), [India](/docs/integration/direct/rest/state-codes/#india), [Italy](/docs/integration/direct/rest/state-codes/#italy), [Japan](/docs/integration/direct/rest/state-codes/#japan), [Mexico](/docs/integration/direct/rest/state-codes/#mexico), [Thailand](/docs/integration/direct/rest/state-codes/#thailand), or [United States](/docs/integration/direct/rest/state-codes/#usa).

Length0 <= length <= 300

phonestringOptional

The phone number, in [E.123 format](https://www.itu.int/rec/T-REC-E.123-200102-I/en). Maximum length is 50 characters.

Formatphone

typestringOptional

The type of address. For example, `HOME_OR_WORK`, `GIFT`, and so on.

application_contextobject<application_context>Optional

Use the application context resource to customize payment flow experience for your buyers.

application_context properties

7 properties

brand_namestringOptional

A label that overrides the business name in the merchant's PayPal account on the PayPal checkout pages.

Length0 <= length <= 127

localestringOptional

The locale of pages that the PayPal payment experience displays. Please refer [here](/docs/api/reference/locale-codes/#localize-the-checkout-experience) for list of supported local codes. Defaulted to en_US if not provided or invalid.

landing_pagestringOptional

The type of landing page to show on the PayPal site for customer checkout. To use the non-PayPal account landing page, set to `Billing`. To use the PayPal account log in landing page, set to `Login`.

shipping_preferenceenumOptional

The shipping preference.

Default"GET_FROM_FILE"Value in"NO_SHIPPING" | "GET_FROM_FILE" | "SET_PROVIDED_ADDRESS"

user_actionstringOptional

The user action. Presents the customer with either the Continue or Pay Now checkout flow:

Flow	Action	Description
Pay Now	`user_action=commit`	After the customer is redirected to the PayPal payment page, shows the Pay Now button. Use this option when you know the final amount when checkout is initiated and you want to process the payment immediately when the customer clicks Pay Now.
Continue	`user_action=continue`	After the customer is redirected to the PayPal payment page, shows the Continue button. Use this option when you do not know the final amount when you initiate the checkout flow and you want to redirect the customer to the merchant page without processing the payment.

preferred_payment_sourceobject<payment_source>Optional

The preferred payment source for the payer. Currently supported only for PayPal Billing Agreements. If provided, checkout experience will have this payment source pre-selected for the payer.

payment_patternenum<payment_pattern>Optional

Provides context (e.g. frequency of payment (Single, Recurring) along with whether (Customer is Present, Not Present) for the payment being processed. For Card and PayPal Vaulted/Billing Agreement transactions, this helps specify the appropriate indicators to the networks (e.g. Mastercard, Visa) which ensures compliance as well as ensure a better auth-rate. For bank processing, indicates to clearing house whether the transaction is recurring or not depending on the option chosen.

Match^[A-Z_]+$Length3 <= length <= 255Value in"CUSTOMER_PRESENT_ONETIME_PURCHASE" | "CUSTOMER_NOT_PRESENT_RECURRING" | "CUSTOMER_PRESENT_RECURRING_FIRST" | "CUSTOMER_PRESENT_ONETIME_PURCHASE_VAULTED" | "CUSTOMER_NOT_PRESENT_ONETIME_PURCHASE_VAULTED" | "MAIL_ORDER_TELEPHONE_ORDER"

transactionsobject<transaction>[]Optional

An array of payment-related transactions. A transaction defines what the payment is for and who fulfills the payment. For update and execute payment calls, the **`transactions`** object accepts the **`amount`** object only.

transaction properties

10 properties

amountobject<amount>Optional

The amount to collect.

amount properties

3 properties

currencystringRequired

The [three-character ISO-4217 currency code](/docs/integration/direct/rest/currency-codes/). PayPal does not support all currencies.

totalstringRequired

The total amount charged to the payee by the payer. For refunds, represents the amount that the payee refunds to the original payer. Maximum length is 10 characters, which includes:

Seven digits before the decimal point.
The decimal point.
Two digits after the decimal point.
For currencies like `JPY` do not support decimals.

detailsobject<Payment Amount Details>Optional

The additional details about the payment amount.

Note: For an order authorization or capture, you cannot include the amount details object.

Payment Amount Details properties

7 properties

subtotalstringOptional

The subtotal amount for the items. If the request includes line items, this property is **required**. Maximum length is 10 characters, which includes:

Seven digits before the decimal point.
The decimal point.
Two digits after the decimal point.

Note: For an order authorization or capture, you cannot include the subtotal parameter.

shippingstringOptional

The shipping fee. Maximum length is 10 characters, which includes:

Seven digits before the decimal point.
The decimal point.
Two digits after the decimal point.

Note: For an order authorization or capture, you cannot include the shipping parameter.

taxstringOptional

The tax. Maximum length is 10 characters, which includes:

Seven digits before the decimal point.
The decimal point.
Two digits after the decimal point.

Note: For an order authorization or capture, you cannot include the tax parameter.

handling_feestringOptional

The handling fee. Maximum length is 10 characters, which includes:

Seven digits before the decimal point.
The decimal point.
Two digits after the decimal point.

Supported for the PayPal payment method only.

Note: For an order authorization or capture, you cannot include the handling_fee parameter.

shipping_discountstringOptional

The shipping fee discount. Maximum length is 10 characters, which includes:

Seven digits before the decimal point.
The decimal point.
Two digits after the decimal point.

Supported for the PayPal payment method only.

Note: For an order authorization or capture, you cannot include the shipping_discount parameter.

insurancestringOptional

The insurance fee. Maximum length is 10 characters, which includes:

Seven digits before the decimal point.
The decimal point.
Two digits after the decimal point.

Supported only for the PayPal payment method.

Note: For an order authorization or capture, you cannot include the insurance parameter.

gift_wrapstringOptional

The gift wrap fee. Maximum length is 10 characters, which includes:

Seven digits before the decimal point.
The decimal point.
Two digits after the decimal point.

Note: For an order authorization or capture, you cannot include the gift_wrap parameter.

payeeobject<payee>Optional

The payee who receives the funds and fulfills the order.

descriptionstringOptional

The purchase description.

Length0 <= length <= 127

note_to_payeestringOptional

The note to the recipient of the funds in this transaction.

Length0 <= length <= 255

customstringOptional

The free-form field for the client's use.

Length0 <= length <= 127

invoice_numberstringOptional

The invoice number to track this payment.

Length0 <= length <= 127

soft_descriptorstringOptional

The soft descriptor to use to charge this funding source. If greater than the maximum allowed length, the API truncates the string.

Length0 <= length <= 22

payment_optionsobject<Payment Options>Optional

The payment options for this transaction.

item_listobject<Item List>Optional

An array of items that are being purchased.

Item List properties

4 properties

itemsobject<item>[]Optional

An array of items that are being purchased.

shipping_addressobject<shipping_address>Optional

The shipping address details.

shipping_address properties

9 properties

line1stringRequired

The first line of the address. For example, number, street, and so on.

Length0 <= length <= 300

line2stringOptional

The second line of the address. For example, suite or apartment number.

Length0 <= length <= 300

citystringOptional

The city name.

Length0 <= length <= 64

country_codestring<country_code>Required

The [two-character ISO 3166-1 code](/docs/api/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.

Match^([A-Z]{2}|C2)$Formatppaas_common_country_code_v2Length2 <= length <= 2

postal_codestringOptional

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).

statestringOptional

Length0 <= length <= 300

phonestringOptional

The phone number, in [E.123 format](https://www.itu.int/rec/T-REC-E.123-200102-I/en). Maximum length is 50 characters.

Formatphone

typestringOptional

The type of address. For example, `HOME_OR_WORK`, `GIFT`, and so on.

recipient_namestringOptional

The name of the recipient at this address.

Length0 <= length <= 127

shipping_methodstringOptional

The shipping method used for this payment, such as USPS Parcel.

shipping_phone_numberstringOptional

The shipping phone number, in its canonical international format as defined by the [E.164](https://en.wikipedia.org/wiki/E.164) numbering plan. Enables merchants to share payer’s contact number with PayPal for the current payment. The final contact number for the payer who is associated with the transaction might be the same as or different from the `shipping_phone_number` based on the payer’s action on PayPal.

notify_urlstringOptional

The URL to send payment notifications.

FormaturiLength0 <= length <= 2048

experience_profile_idstringOptional

Deprecated. The PayPal-generated ID for the merchant's payment experience profile. For information, see [create web experience profile](/docs/api/payment-experience/v1/#web-profiles_create). Use application_context instead.

note_to_payerstringOptional

A free-form field that clients can use to send a note to the payer.

Length0 <= length <= 165

redirect_urlsobject<Redirect URLs>Optional

A set of redirect URLs that you provide for PayPal-based payments.

Response Body

`application/json`

curl -X POST "https://example.com/v1/payments/payment" \  -H "Content-Type: application/json" \  -d '{    "intent": "sale",    "payer": {      "payment_method": "paypal"    },    "transactions": [      {        "amount": {          "total": "30.11",          "currency": "USD",          "details": {            "subtotal": "30.00",            "tax": "0.07",            "shipping": "0.03",            "handling_fee": "1.00",            "shipping_discount": "-1.00",            "insurance": "0.01"          }        },        "description": "The payment transaction description.",        "custom": "EBAY_EMS_90048630024435",        "invoice_number": "48787589673",        "payment_options": {          "allowed_payment_method": "INSTANT_FUNDING_SOURCE"        },        "soft_descriptor": "ECHI5786786",        "item_list": {          "items": [            {              "name": "hat",              "description": "Brown hat.",              "quantity": "5",              "price": "3",              "tax": "0.01",              "sku": "1",              "currency": "USD"            },            {              "name": "handbag",              "description": "Black handbag.",              "quantity": "1",              "price": "15",              "tax": "0.02",              "sku": "product34",              "currency": "USD"            }          ],          "shipping_address": {            "recipient_name": "Brian Robinson",            "line1": "4th Floor",            "line2": "Unit #34",            "city": "San Jose",            "country_code": "US",            "postal_code": "95131",            "phone": "011862212345678",            "state": "CA"          }        }      }    ],    "note_to_payer": "Contact us for any questions on your order.",    "redirect_urls": {      "return_url": "https://example.com/return",      "cancel_url": "https://example.com/cancel"    }  }'

{  "id": "string",  "intent": "sale",  "payer": {    "payment_method": "credit_card",    "status": "VERIFIED",    "funding_instruments": [      {        "credit_card_token": {          "credit_card_id": "string",          "payer_id": "string",          "external_customer_id": "string",          "last4": "stri",          "type": "string",          "expire_month": 1,          "expire_year": "stri"        }      }    ],    "payer_info": {      "email": "[email protected]",      "salutation": "string",      "first_name": "string",      "middle_name": "string",      "last_name": "string",      "suffix": "string",      "payer_id": "string",      "birth_date": "2019-08-24T14:15:22Z",      "tax_id": "string",      "tax_id_type": "BR_CPF",      "billing_address": {        "line1": "string",        "line2": "string",        "city": "string",        "country_code": "st",        "postal_code": "string",        "state": "string",        "phone": "string",        "normalization_status": "UNKNOWN",        "type": "string"      },      "shipping_address": {        "line1": "string",        "line2": "string",        "city": "string",        "country_code": "st",        "postal_code": "string",        "state": "string",        "phone": "string",        "normalization_status": "UNKNOWN",        "type": "string",        "recipient_name": "string"      }    }  },  "application_context": {    "brand_name": "string",    "locale": "string",    "landing_page": "string",    "shipping_preference": "NO_SHIPPING",    "user_action": "string",    "preferred_payment_source": {      "token": {        "id": "string",        "type": "BILLING_AGREEMENT"      }    },    "payment_pattern": "CUSTOMER_PRESENT_ONETIME_PURCHASE"  },  "transactions": [    {      "amount": {        "currency": "string",        "total": "string",        "details": {          "subtotal": "string",          "shipping": "string",          "tax": "string",          "handling_fee": "string",          "shipping_discount": "string",          "insurance": "string",          "gift_wrap": "string"        }      },      "payee": {        "email": "[email protected]",        "merchant_id": "string"      },      "description": "string",      "note_to_payee": "string",      "custom": "string",      "invoice_number": "string",      "soft_descriptor": "string",      "payment_options": {        "allowed_payment_method": "UNRESTRICTED"      },      "item_list": {        "items": [          {            "sku": "string",            "name": "string",            "description": "string",            "quantity": "string",            "price": "string",            "currency": "str",            "tax": "string"          }        ],        "shipping_address": {          "line1": "string",          "line2": "string",          "city": "string",          "country_code": "st",          "postal_code": "string",          "state": "string",          "phone": "string",          "normalization_status": "UNKNOWN",          "type": "string",          "recipient_name": "string"        },        "shipping_method": "string",        "shipping_phone_number": "string"      },      "notify_url": "http://example.com",      "related_resources": [        {          "sale": {            "id": "string",            "amount": {              "currency": "string",              "total": "string",              "details": {                "subtotal": "string",                "shipping": "string",                "tax": "string",                "handling_fee": "string",                "shipping_discount": "string",                "insurance": "string",                "gift_wrap": "string"              }            },            "payment_mode": "INSTANT_TRANSFER",            "state": "completed",            "reason_code": "CHARGEBACK",            "protection_eligibility": "ELIGIBLE",            "protection_eligibility_type": "ITEM_NOT_RECEIVED_ELIGIBLE",            "clearing_time": "2019-08-24T14:15:22Z",            "payment_hold_status": "HELD",            "payment_hold_reasons": [              {                "payment_hold_reason": "PAYMENT_HOLD"              }            ],            "transaction_fee": {              "currency": "string",              "value": "string"            },            "receivable_amount": {              "currency": "string",              "value": "string"            },            "transaction_fee_in_receivable_currency": {              "currency": "string",              "value": "string"            },            "exchange_rate": "string",            "fmf_details": {              "filter_type": "ACCEPT",              "filter_id": "AVS_NO_MATCH",              "name": "string",              "description": "string"            },            "receipt_id": "string",            "parent_payment": "string",            "processor_response": {              "response_code": "stri",              "avs_code": "s",              "cvv_code": "s",              "advice_code": "01_NEW_ACCOUNT_INFORMATION",              "eci_submitted": "string",              "vpas": "string"            },            "billing_agreement_id": "string",            "create_time": "2019-08-24T14:15:22Z",            "update_time": "2019-08-24T14:15:22Z",            "links": [              {                "href": "string",                "rel": "string",                "method": "GET"              }            ]          },          "authorization": {            "id": "string",            "amount": {              "currency": "string",              "total": "string",              "details": {                "subtotal": "string",                "shipping": "string",                "tax": "string",                "handling_fee": "string",                "shipping_discount": "string",                "insurance": "string",                "gift_wrap": "string"              }            },            "payment_mode": "INSTANT_TRANSFER",            "state": "pending",            "reason_code": "AUTHORIZATION",            "pending_reason": "AUTHORIZATION",            "protection_eligibility": "ELIGIBLE",            "protection_eligibility_type": "ITEM_NOT_RECEIVED_ELIGIBLE",            "fmf_details": {              "filter_type": "ACCEPT",              "filter_id": "AVS_NO_MATCH",              "name": "string",              "description": "string"            },            "parent_payment": "string",            "processor_response": {              "response_code": "stri",              "avs_code": "s",              "cvv_code": "s",              "advice_code": "01_NEW_ACCOUNT_INFORMATION",              "eci_submitted": "string",              "vpas": "string"            },            "valid_until": "2019-08-24T14:15:22Z",            "create_time": "2019-08-24T14:15:22Z",            "update_time": "2019-08-24T14:15:22Z",            "receipt_id": "string",            "links": [              {                "href": "string",                "rel": "string",                "method": "GET"              }            ]          },          "order": {            "id": "string",            "amount": {              "currency": "string",              "total": "string",              "details": {                "subtotal": "string",                "shipping": "string",                "tax": "string",                "handling_fee": "string",                "shipping_discount": "string",                "insurance": "string",                "gift_wrap": "string"              }            },            "payment_mode": "INSTANT_TRANSFER",            "state": "PENDING",            "reason_code": "PAYER_SHIPPING_UNCONFIRMED",            "pending_reason": "payer_shipping_unconfirmed",            "protection_eligibility": "ELIGIBLE",            "protection_eligibility_type": "ITEM_NOT_RECEIVED_ELIGIBLE",            "parent_payment": "string",            "fmf_details": {              "filter_type": "ACCEPT",              "filter_id": "AVS_NO_MATCH",              "name": "string",              "description": "string"            },            "create_time": "2019-08-24T14:15:22Z",            "update_time": "2019-08-24T14:15:22Z",            "links": [              {                "href": "string",                "rel": "string",                "method": "GET"              }            ]          },          "capture": {            "id": "string",            "amount": {              "currency": "string",              "total": "string",              "details": {                "subtotal": "string",                "shipping": "string",                "tax": "string",                "handling_fee": "string",                "shipping_discount": "string",                "insurance": "string",                "gift_wrap": "string"              }            },            "is_final_capture": false,            "state": "pending",            "reason_code": "CHARGEBACK",            "parent_payment": "string",            "invoice_number": "string",            "transaction_fee": {              "currency": "string",              "value": "string"            },            "transaction_fee_in_receivable_currency": {              "currency": "string",              "value": "string"            },            "receivable_amount": {              "currency": "string",              "value": "string"            },            "exchange_rate": "string",            "note_to_payer": "string",            "create_time": "2019-08-24T14:15:22Z",            "update_time": "2019-08-24T14:15:22Z",            "links": [              {                "href": "string",                "rel": "string",                "method": "GET"              }            ]          },          "refund": {            "id": "string",            "amount": {              "currency": "string",              "total": "string",              "details": {                "subtotal": "string",                "shipping": "string",                "tax": "string",                "handling_fee": "string",                "shipping_discount": "string",                "insurance": "string",                "gift_wrap": "string"              }            },            "state": "pending",            "reason": "string",            "invoice_number": "string",            "sale_id": "string",            "capture_id": "string",            "parent_payment": "string",            "description": "string",            "create_time": "2019-08-24T14:15:22Z",            "update_time": "2019-08-24T14:15:22Z",            "links": [              {                "href": "string",                "rel": "string",                "method": "GET"              }            ]          }        }      ]    }  ],  "state": "created",  "experience_profile_id": "string",  "note_to_payer": "string",  "redirect_urls": {    "return_url": "http://example.com",    "cancel_url": "http://example.com"  },  "failure_reason": "UNABLE_TO_COMPLETE_TRANSACTION",  "create_time": "2019-08-24T14:15:22Z",  "update_time": "2019-08-24T14:15:22Z",  "links": [    {      "href": "string",      "rel": "string",      "method": "GET"    }  ]}

Header Parameters

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

intentenumRequired

The payment intent. Value is:

sale. Makes an immediate payment.
authorize. [Authorizes a payment for capture later](/docs/integration/direct/payments/authorize-and-capture-payments/).
order. [Creates an order](/docs/integration/direct/payments/orders/).

Value in"sale" | "authorize" | "order"

payerobject<payer>Required

The source of the funds for this payment. Payment method is PayPal Wallet payment or bank direct debit.

payer properties

3 properties

payment_methodenumOptional

The payment method.

funding_instrumentsobject<funding_instrument>[]Optional

Items1 <= length <= 1

payer_infoobject<payer_info>Optional

The payer information.

payer_info properties

5 properties

emailstringOptional

The payer's email address. Maximum length is 127 characters.

Formatemail

birth_datestringOptional

The birth date of the payer, in [Internet date format](https://tools.ietf.org/html/rfc3339#section-5.6). For example, `1990-04-12`.

Formatdate-time

tax_idstringOptional

The payer's tax ID. Supported for the PayPal payment method only.

Length0 <= length <= 14

tax_id_typeenumOptional

The payer's tax ID type. Supported for the PayPal payment method only.

Value in"BR_CPF" | "BR_CNPJ"

billing_addressobject<address>Optional

The payer's billing address.

address properties

8 properties

line1stringRequired

The first line of the address. For example, number, street, and so on.

Length0 <= length <= 300

line2stringOptional

The second line of the address. For example, suite or apartment number.

Length0 <= length <= 300

citystringOptional

The city name.

Length0 <= length <= 64

country_codestring<country_code>Required

The [two-character ISO 3166-1 code](/docs/api/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.

Match^([A-Z]{2}|C2)$Formatppaas_common_country_code_v2Length2 <= length <= 2

postal_codestringOptional

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).

statestringOptional

Length0 <= length <= 300

phonestringOptional

The phone number, in [E.123 format](https://www.itu.int/rec/T-REC-E.123-200102-I/en). Maximum length is 50 characters.

Formatphone

typestringOptional

The type of address. For example, `HOME_OR_WORK`, `GIFT`, and so on.

application_contextobject<application_context>Optional

Use the application context resource to customize payment flow experience for your buyers.

application_context properties

7 properties

brand_namestringOptional

A label that overrides the business name in the merchant's PayPal account on the PayPal checkout pages.

Length0 <= length <= 127

localestringOptional

landing_pagestringOptional

The type of landing page to show on the PayPal site for customer checkout. To use the non-PayPal account landing page, set to `Billing`. To use the PayPal account log in landing page, set to `Login`.

shipping_preferenceenumOptional

The shipping preference.

Default"GET_FROM_FILE"Value in"NO_SHIPPING" | "GET_FROM_FILE" | "SET_PROVIDED_ADDRESS"

user_actionstringOptional

The user action. Presents the customer with either the Continue or Pay Now checkout flow:

Flow	Action	Description
Pay Now	`user_action=commit`	After the customer is redirected to the PayPal payment page, shows the Pay Now button. Use this option when you know the final amount when checkout is initiated and you want to process the payment immediately when the customer clicks Pay Now.
Continue	`user_action=continue`	After the customer is redirected to the PayPal payment page, shows the Continue button. Use this option when you do not know the final amount when you initiate the checkout flow and you want to redirect the customer to the merchant page without processing the payment.

preferred_payment_sourceobject<payment_source>Optional

The preferred payment source for the payer. Currently supported only for PayPal Billing Agreements. If provided, checkout experience will have this payment source pre-selected for the payer.

payment_patternenum<payment_pattern>Optional

transactionsobject<transaction>[]Optional

transaction properties

10 properties

amountobject<amount>Optional

The amount to collect.

amount properties

3 properties

currencystringRequired

The [three-character ISO-4217 currency code](/docs/integration/direct/rest/currency-codes/). PayPal does not support all currencies.

totalstringRequired

The total amount charged to the payee by the payer. For refunds, represents the amount that the payee refunds to the original payer. Maximum length is 10 characters, which includes:

Seven digits before the decimal point.
The decimal point.
Two digits after the decimal point.
For currencies like `JPY` do not support decimals.

detailsobject<Payment Amount Details>Optional

The additional details about the payment amount.

Note: For an order authorization or capture, you cannot include the amount details object.

Payment Amount Details properties

7 properties

subtotalstringOptional

The subtotal amount for the items. If the request includes line items, this property is **required**. Maximum length is 10 characters, which includes:

Seven digits before the decimal point.
The decimal point.
Two digits after the decimal point.

Note: For an order authorization or capture, you cannot include the subtotal parameter.

shippingstringOptional

The shipping fee. Maximum length is 10 characters, which includes:

Seven digits before the decimal point.
The decimal point.
Two digits after the decimal point.

Note: For an order authorization or capture, you cannot include the shipping parameter.

taxstringOptional

The tax. Maximum length is 10 characters, which includes:

Seven digits before the decimal point.
The decimal point.
Two digits after the decimal point.

Note: For an order authorization or capture, you cannot include the tax parameter.

handling_feestringOptional

The handling fee. Maximum length is 10 characters, which includes:

Seven digits before the decimal point.
The decimal point.
Two digits after the decimal point.

Supported for the PayPal payment method only.

Note: For an order authorization or capture, you cannot include the handling_fee parameter.

shipping_discountstringOptional

The shipping fee discount. Maximum length is 10 characters, which includes:

Seven digits before the decimal point.
The decimal point.
Two digits after the decimal point.

Supported for the PayPal payment method only.

Note: For an order authorization or capture, you cannot include the shipping_discount parameter.

insurancestringOptional

The insurance fee. Maximum length is 10 characters, which includes:

Seven digits before the decimal point.
The decimal point.
Two digits after the decimal point.

Supported only for the PayPal payment method.

Note: For an order authorization or capture, you cannot include the insurance parameter.

gift_wrapstringOptional

The gift wrap fee. Maximum length is 10 characters, which includes:

Seven digits before the decimal point.
The decimal point.
Two digits after the decimal point.

Note: For an order authorization or capture, you cannot include the gift_wrap parameter.

payeeobject<payee>Optional

The payee who receives the funds and fulfills the order.

descriptionstringOptional

The purchase description.

Length0 <= length <= 127

note_to_payeestringOptional

The note to the recipient of the funds in this transaction.

Length0 <= length <= 255

customstringOptional

The free-form field for the client's use.

Length0 <= length <= 127

invoice_numberstringOptional

The invoice number to track this payment.

Length0 <= length <= 127

soft_descriptorstringOptional

The soft descriptor to use to charge this funding source. If greater than the maximum allowed length, the API truncates the string.

Length0 <= length <= 22

payment_optionsobject<Payment Options>Optional

The payment options for this transaction.

item_listobject<Item List>Optional

An array of items that are being purchased.

Item List properties

4 properties

itemsobject<item>[]Optional

An array of items that are being purchased.

shipping_addressobject<shipping_address>Optional

The shipping address details.

shipping_address properties

9 properties

line1stringRequired

The first line of the address. For example, number, street, and so on.

Length0 <= length <= 300

line2stringOptional

The second line of the address. For example, suite or apartment number.

Length0 <= length <= 300

citystringOptional

The city name.

Length0 <= length <= 64

country_codestring<country_code>Required

The [two-character ISO 3166-1 code](/docs/api/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.

Match^([A-Z]{2}|C2)$Formatppaas_common_country_code_v2Length2 <= length <= 2

postal_codestringOptional

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).

statestringOptional

Length0 <= length <= 300

phonestringOptional

The phone number, in [E.123 format](https://www.itu.int/rec/T-REC-E.123-200102-I/en). Maximum length is 50 characters.

Formatphone

typestringOptional

The type of address. For example, `HOME_OR_WORK`, `GIFT`, and so on.

recipient_namestringOptional

The name of the recipient at this address.

Length0 <= length <= 127

shipping_methodstringOptional

The shipping method used for this payment, such as USPS Parcel.

shipping_phone_numberstringOptional

notify_urlstringOptional

The URL to send payment notifications.

FormaturiLength0 <= length <= 2048

experience_profile_idstringOptional

note_to_payerstringOptional

A free-form field that clients can use to send a note to the payer.

Length0 <= length <= 165

redirect_urlsobject<Redirect URLs>Optional

A set of redirect URLs that you provide for PayPal-based payments.

curl -X POST "https://example.com/v1/payments/payment" \ -H "Content-Type: application/json" \ -d '{ "intent": "sale", "payer": { "payment_method": "paypal" }, "transactions": [ { "amount": { "total": "30.11", "currency": "USD", "details": { "subtotal": "30.00", "tax": "0.07", "shipping": "0.03", "handling_fee": "1.00", "shipping_discount": "-1.00", "insurance": "0.01" } }, "description": "The payment transaction description.", "custom": "EBAY_EMS_90048630024435", "invoice_number": "48787589673", "payment_options": { "allowed_payment_method": "INSTANT_FUNDING_SOURCE" }, "soft_descriptor": "ECHI5786786", "item_list": { "items": [ { "name": "hat", "description": "Brown hat.", "quantity": "5", "price": "3", "tax": "0.01", "sku": "1", "currency": "USD" }, { "name": "handbag", "description": "Black handbag.", "quantity": "1", "price": "15", "tax": "0.02", "sku": "product34", "currency": "USD" } ], "shipping_address": { "recipient_name": "Brian Robinson", "line1": "4th Floor", "line2": "Unit #34", "city": "San Jose", "country_code": "US", "postal_code": "95131", "phone": "011862212345678", "state": "CA" } } } ], "note_to_payer": "Contact us for any questions on your order.", "redirect_urls": { "return_url": "https://example.com/return", "cancel_url": "https://example.com/cancel" } }'

{ "id": "string", "intent": "sale", "payer": { "payment_method": "credit_card", "status": "VERIFIED", "funding_instruments": [ { "credit_card_token": { "credit_card_id": "string", "payer_id": "string", "external_customer_id": "string", "last4": "stri", "type": "string", "expire_month": 1, "expire_year": "stri" } } ], "payer_info": { "email": "[email protected]", "salutation": "string", "first_name": "string", "middle_name": "string", "last_name": "string", "suffix": "string", "payer_id": "string", "birth_date": "2019-08-24T14:15:22Z", "tax_id": "string", "tax_id_type": "BR_CPF", "billing_address": { "line1": "string", "line2": "string", "city": "string", "country_code": "st", "postal_code": "string", "state": "string", "phone": "string", "normalization_status": "UNKNOWN", "type": "string" }, "shipping_address": { "line1": "string", "line2": "string", "city": "string", "country_code": "st", "postal_code": "string", "state": "string", "phone": "string", "normalization_status": "UNKNOWN", "type": "string", "recipient_name": "string" } } }, "application_context": { "brand_name": "string", "locale": "string", "landing_page": "string", "shipping_preference": "NO_SHIPPING", "user_action": "string", "preferred_payment_source": { "token": { "id": "string", "type": "BILLING_AGREEMENT" } }, "payment_pattern": "CUSTOMER_PRESENT_ONETIME_PURCHASE" }, "transactions": [ { "amount": { "currency": "string", "total": "string", "details": { "subtotal": "string", "shipping": "string", "tax": "string", "handling_fee": "string", "shipping_discount": "string", "insurance": "string", "gift_wrap": "string" } }, "payee": { "email": "[email protected]", "merchant_id": "string" }, "description": "string", "note_to_payee": "string", "custom": "string", "invoice_number": "string", "soft_descriptor": "string", "payment_options": { "allowed_payment_method": "UNRESTRICTED" }, "item_list": { "items": [ { "sku": "string", "name": "string", "description": "string", "quantity": "string", "price": "string", "currency": "str", "tax": "string" } ], "shipping_address": { "line1": "string", "line2": "string", "city": "string", "country_code": "st", "postal_code": "string", "state": "string", "phone": "string", "normalization_status": "UNKNOWN", "type": "string", "recipient_name": "string" }, "shipping_method": "string", "shipping_phone_number": "string" }, "notify_url": "http://example.com", "related_resources": [ { "sale": { "id": "string", "amount": { "currency": "string", "total": "string", "details": { "subtotal": "string", "shipping": "string", "tax": "string", "handling_fee": "string", "shipping_discount": "string", "insurance": "string", "gift_wrap": "string" } }, "payment_mode": "INSTANT_TRANSFER", "state": "completed", "reason_code": "CHARGEBACK", "protection_eligibility": "ELIGIBLE", "protection_eligibility_type": "ITEM_NOT_RECEIVED_ELIGIBLE", "clearing_time": "2019-08-24T14:15:22Z", "payment_hold_status": "HELD", "payment_hold_reasons": [ { "payment_hold_reason": "PAYMENT_HOLD" } ], "transaction_fee": { "currency": "string", "value": "string" }, "receivable_amount": { "currency": "string", "value": "string" }, "transaction_fee_in_receivable_currency": { "currency": "string", "value": "string" }, "exchange_rate": "string", "fmf_details": { "filter_type": "ACCEPT", "filter_id": "AVS_NO_MATCH", "name": "string", "description": "string" }, "receipt_id": "string", "parent_payment": "string", "processor_response": { "response_code": "stri", "avs_code": "s", "cvv_code": "s", "advice_code": "01_NEW_ACCOUNT_INFORMATION", "eci_submitted": "string", "vpas": "string" }, "billing_agreement_id": "string", "create_time": "2019-08-24T14:15:22Z", "update_time": "2019-08-24T14:15:22Z", "links": [ { "href": "string", "rel": "string", "method": "GET" } ] }, "authorization": { "id": "string", "amount": { "currency": "string", "total": "string", "details": { "subtotal": "string", "shipping": "string", "tax": "string", "handling_fee": "string", "shipping_discount": "string", "insurance": "string", "gift_wrap": "string" } }, "payment_mode": "INSTANT_TRANSFER", "state": "pending", "reason_code": "AUTHORIZATION", "pending_reason": "AUTHORIZATION", "protection_eligibility": "ELIGIBLE", "protection_eligibility_type": "ITEM_NOT_RECEIVED_ELIGIBLE", "fmf_details": { "filter_type": "ACCEPT", "filter_id": "AVS_NO_MATCH", "name": "string", "description": "string" }, "parent_payment": "string", "processor_response": { "response_code": "stri", "avs_code": "s", "cvv_code": "s", "advice_code": "01_NEW_ACCOUNT_INFORMATION", "eci_submitted": "string", "vpas": "string" }, "valid_until": "2019-08-24T14:15:22Z", "create_time": "2019-08-24T14:15:22Z", "update_time": "2019-08-24T14:15:22Z", "receipt_id": "string", "links": [ { "href": "string", "rel": "string", "method": "GET" } ] }, "order": { "id": "string", "amount": { "currency": "string", "total": "string", "details": { "subtotal": "string", "shipping": "string", "tax": "string", "handling_fee": "string", "shipping_discount": "string", "insurance": "string", "gift_wrap": "string" } }, "payment_mode": "INSTANT_TRANSFER", "state": "PENDING", "reason_code": "PAYER_SHIPPING_UNCONFIRMED", "pending_reason": "payer_shipping_unconfirmed", "protection_eligibility": "ELIGIBLE", "protection_eligibility_type": "ITEM_NOT_RECEIVED_ELIGIBLE", "parent_payment": "string", "fmf_details": { "filter_type": "ACCEPT", "filter_id": "AVS_NO_MATCH", "name": "string", "description": "string" }, "create_time": "2019-08-24T14:15:22Z", "update_time": "2019-08-24T14:15:22Z", "links": [ { "href": "string", "rel": "string", "method": "GET" } ] }, "capture": { "id": "string", "amount": { "currency": "string", "total": "string", "details": { "subtotal": "string", "shipping": "string", "tax": "string", "handling_fee": "string", "shipping_discount": "string", "insurance": "string", "gift_wrap": "string" } }, "is_final_capture": false, "state": "pending", "reason_code": "CHARGEBACK", "parent_payment": "string", "invoice_number": "string", "transaction_fee": { "currency": "string", "value": "string" }, "transaction_fee_in_receivable_currency": { "currency": "string", "value": "string" }, "receivable_amount": { "currency": "string", "value": "string" }, "exchange_rate": "string", "note_to_payer": "string", "create_time": "2019-08-24T14:15:22Z", "update_time": "2019-08-24T14:15:22Z", "links": [ { "href": "string", "rel": "string", "method": "GET" } ] }, "refund": { "id": "string", "amount": { "currency": "string", "total": "string", "details": { "subtotal": "string", "shipping": "string", "tax": "string", "handling_fee": "string", "shipping_discount": "string", "insurance": "string", "gift_wrap": "string" } }, "state": "pending", "reason": "string", "invoice_number": "string", "sale_id": "string", "capture_id": "string", "parent_payment": "string", "description": "string", "create_time": "2019-08-24T14:15:22Z", "update_time": "2019-08-24T14:15:22Z", "links": [ { "href": "string", "rel": "string", "method": "GET" } ] } } ] } ], "state": "created", "experience_profile_id": "string", "note_to_payer": "string", "redirect_urls": { "return_url": "http://example.com", "cancel_url": "http://example.com" }, "failure_reason": "UNABLE_TO_COMPLETE_TRANSACTION", "create_time": "2019-08-24T14:15:22Z", "update_time": "2019-08-24T14:15:22Z", "links": [ { "href": "string", "rel": "string", "method": "GET" } ]}

payer properties

funding_instrument properties

credit_card_token properties

payer_info properties

address properties

application_context properties

payment_source properties

token properties

transaction properties

amount properties

Payment Amount Details properties

payee properties

Payment Options properties

Item List properties

item properties

shipping_address properties

Redirect URLs properties

201application/json

defaultapplication/json

On this page

On this page

On this page

If you accept cookies, we’ll use them to improve and customize your experience and enable our partners to show you personalized PayPal ads when you visit other sites. Manage cookies and learn more

Create payment

payer properties

funding_instrument properties

credit_card_token properties

payer_info properties

address properties

application_context properties

payment_source properties

token properties

transaction properties

amount properties

Payment Amount Details properties

payee properties

Payment Options properties

Item List properties

item properties

shipping_address properties

Redirect URLs properties

201application/json

defaultapplication/json

On this page

On this page

`application/json`

`application/json`

`application/json`

`application/json`