Orders (1)

API Version v1

Partners can use the Orders API to create, show details for, authorize, and capture payment for orders.

Orders API integration note: The PayPal Commerce Platform is a limited-release solution aimed at partners, crowd funding, and multi-party commerce platforms. To use Orders API for Partners, see Multiparty Payments. v1 of the API will be deprecated soon. A new version is available at Orders API v2.

Create order

post/v1/checkout/orders

Creates an order.

SecurityOauth2
Request
header Parameters
PayPal-Partner-Attribution-Id
string
Request Body schema: application/json
intent
string

The intent.

Enum: Description
SALE

A sale.

AUTHORIZE

An authorization.

required
Array of objects (Purchase Unit) non-empty

An array of purchase units. Each purchase unit establishes a contract between a customer and merchant.

object (Payment Details)

The payment details for the order.

object (Application Context)

Customizes the payer experience during the approval process for the payment with PayPal.

Note: The PayPal Commerce Platform might configure brand_name and shipping_preference during partner account setup, which overrides the request values.

required
object (Redirect URLs)

The redirect URLs. Required only for the PayPal payment method. The supported settings are return and cancel URLs.

object (Currency)

The currency and amount of the PayPal-computed total of amounts in all purchase units.

object (Metadata)

The name-and-value pairs that contain external data, such as user, user feedback, score, and so on.

Responses
200

A successful request returns the HTTP 200 OK status code and a JSON response body that includes the PayPal-generated order ID, an array of purchase unit objects, payment details, customer information, metadata, and order status.

Request samples 
curl -v -X POST https://api-m.sandbox.paypal.com/v1/checkout/orders \
 \
-d '{
  "application_context": {
    "locale": "en-US",
    "brand_name": "walmart",
    "landing_page": "billing",
    "user_action": "continue",
    "supplementary_data": [
      {
        "name": "risk_correlation_id",
        "value": "9N8554567F903282T"
      },
      {
        "name": "buyer_ipaddress",
        "value": "109.20.212.116"
      },
      {
        "name": "external_channel",
        "value": "WEB"
      }
    ]
  },
  "purchase_units": [
    {
      "reference_id": "store_mobile_world_order_1234",
      "description": "Mobile World Store order-1234",
      "amount": {
        "currency": "USD",
        "details": {
          "subtotal": "1.09",
          "shipping": "0.02",
          "tax": "0.33"
        },
        "total": "1.44"
      },
      "payee": {
        "email": "seller@example.com"
      },
      "items": [
        {
          "name": "NeoPhone",
          "sku": "sku03",
          "price": "0.54",
          "currency": "USD",
          "quantity": "1"
        },
        {
          "name": "Fitness Watch",
          "sku": "sku04",
          "price": "0.55",
          "currency": "USD",
          "quantity": "1"
        }
      ],
      "shipping_address": {
        "line1": "2211 N First Street",
        "line2": "Building 17",
        "city": "San Jose",
        "country_code": "US",
        "postal_code": "95131",
        "state": "CA",
        "phone": "(123) 456-7890"
      },
      "shipping_method": "United Postal Service",
      "partner_fee_details": {
        "receiver": {
          "email": "partner@example.com"
        },
        "amount": {
          "value": "0.01",
          "currency": "USD"
        }
      },
      "payment_linked_group": 1,
      "custom": "custom_value_2388",
      "invoice_number": "invoice_number_2388",
      "payment_descriptor": "Payment Mobile World"
    }
  ],
  "redirect_urls": {
    "return_url": "https://example.com/return",
    "cancel_url": "https://example.com/cancel"
  }
}'
Response samples
application/json
{
  • "id": "8RU61172JS455403V",
  • "gross_total_amount": {
    • "value": "1.44",
    • "currency": "USD"
    },
  • "application_context": {
    • "locale": "en-US",
    • "brand_name": "walmart",
    • "landing_page": "billing",
    • "user_action": "continue",
    • "supplementary_data": [
      • {
        • "name": "risk_correlation_id",
        • "value": "9N8554567F903282T"
        },
      • {
        • "name": "buyer_ipaddress",
        • "value": "109.20.212.116"
        },
      • {
        • "name": "external_channel",
        • "value": "WEB"
        }
      ]
    },
  • "purchase_units": [
    • {
      • "reference_id": "store_mobile_world_order_1234",
      • "description": "Mobile World Store order-1234",
      • "amount": {
        • "currency": "USD",
        • "details": {
          • "subtotal": "1.09",
          • "shipping": "0.02",
          • "tax": "0.33"
          },
        • "total": "1.44"
        },
      • "payee": {
        • "email": "seller@example.com"
        },
      • "items": [
        • {
          • "name": "NeoPhone",
          • "sku": "sku03",
          • "price": "0.54",
          • "currency": "USD",
          • "quantity": "1"
          },
        • {
          • "name": "Fitness Watch",
          • "sku": "sku04",
          • "price": "0.55",
          • "currency": "USD",
          • "quantity": "1"
          }
        ],
      • "shipping_address": {
        • "recipient_name": "John Doe",
        • "default_address": false,
        • "preferred_address": false,
        • "primary_address": false,
        • "disable_for_transaction": false,
        • "line1": "2211 N First Street",
        • "line2": "Building 17",
        • "city": "San Jose",
        • "country_code": "US",
        • "postal_code": "95131",
        • "state": "CA",
        • "phone": "(123) 456-7890"
        },
      • "shipping_method": "United Postal Service",
      • "partner_fee_details": {
        • "receiver": {
          • "email": "partner@example.com"
          },
        • "amount": {
          • "value": "0.01",
          • "currency": "USD"
          }
        },
      • "payment_linked_group": 1,
      • "custom": "custom_value_2388",
      • "invoice_number": "invoice_number_2388",
      • "payment_descriptor": "Payment Mobile World",
      • "status": "CAPTURED"
      }
    ],
  • "redirect_urls": {},
  • "create_time": "2017-04-26T21:18:49Z",
  • "links": [],
  • "status": "CREATED"
}

Show order details

get/v1/checkout/orders/{order_id}

Shows details for an order, by ID.

SecurityOauth2
Request
path Parameters
order_id
required
string

The ID of the order for which to show details.

Responses
200

A successful request returns the HTTP 200 OK status code and a JSON response body that shows order details.

Request samples 
curl -v -X GET https://api-m.sandbox.paypal.com/v1/checkout/orders/8SC68793353299025 \
-H 'Authorization: Bearer access_token6V7rbVwmlM1gFZKW_8QtzWXqpcwQ6T5vhEGYNJDAAdn3paCgRpdeMdVYmWzgbKSsECednupJ3Zx5Xd-g'
Response samples
application/json
{
  • "id": "8SC68793353299025",
  • "status": "CREATED",
  • "gross_total_amount": {
    • "value": "1.44",
    • "currency": "USD"
    },
  • "application_context": { },
  • "purchase_units": [
    • {
      • "reference_id": "store_mobile_world_order_1234",
      • "description": "Mobile World Store order-1234",
      • "amount": {
        • "currency": "USD",
        • "details": {
          • "subtotal": "1.09",
          • "shipping": "0.02",
          • "tax": "0.33"
          },
        • "total": "1.44"
        },
      • "payee": {
        • "email": "seller@example.com"
        },
      • "items": [
        • {
          • "name": "NeoPhone",
          • "sku": "sku03",
          • "price": "0.54",
          • "currency": "USD",
          • "quantity": "1"
          },
        • {
          • "name": "Fitness Watch",
          • "sku": "sku04",
          • "price": "0.55",
          • "currency": "USD",
          • "quantity": "1"
          }
        ],
      • "shipping_address": {
        • "line1": "2211 N First Street",
        • "line2": "Building 17",
        • "city": "San Jose",
        • "country_code": "US",
        • "postal_code": "95131",
        • "state": "CA",
        • "phone": "(123) 456-7890"
        },
      • "shipping_method": "United Postal Service",
      • "partner_fee_details": {
        • "receiver": {
          • "email": "partner@example.com"
          },
        • "amount": {
          • "value": "0.01",
          • "currency": "USD"
          }
        },
      • "payment_linked_group": 1,
      • "custom": "custom_value_2388",
      • "invoice_number": "invoice_number_2388",
      • "payment_descriptor": "Payment Mobile World",
      • "status": "NOT_PROCESSED"
      }
    ],
  • "redirect_urls": {},
  • "links": [],
  • "create_time": "2018-09-21T17:22:45Z"
}

Cancel order

delete/v1/checkout/orders/{order_id}

Cancels an order, by ID, and deletes the order. To call this method, the order status must be CREATED or APPROVED.

SecurityOauth2
Request
path Parameters
order_id
required
string

The ID of the order to cancel.

Responses
204

A successful request returns the HTTP 204 No Content status code with no JSON response body. If the order is already paid, the order cannot be canceled and the request returns the HTTP 422 Unprocessable Entity status code with the message, This order is in progress.

Request samples 
curl -v -X DELETE https://api-m.sandbox.paypal.com/v1/checkout/orders/8SC68793353299025 \
-H 'Authorization: Bearer access_token6V7rbVwmlM1gFZKW_8QtzWXqpcwQ6T5vhEGYNJDAAdn3paCgRpdeMdVYmWzgbKSsECednupJ3Zx5Xd-g'

Pay for order

post/v1/checkout/orders/{order_id}/pay

Initiates a PayPal payment that a buyer has approved.

Note: For Partner use cases, use the disbursement_mode to indicate whether to disburse funds to the seller and partner accounts immediately or later. If you delay disbursement, you must call disburse funds to disburse funds to the merchant and partner.

SecurityOauth2
Request
path Parameters
order_id
required
string

The ID of the order for which to execute a payment.

header Parameters
PayPal-Partner-Attribution-Id
string
PayPal-Request-Id
string

The server stores keys forever.

Request Body schema: application/json
disbursement_mode
required
string

Indicates whether to disburse money instantly or later.

Enum: Description
INSTANT

Money is disbursed instantly.

DELAYED

Money will be disbursed later.

object (Payer)

The source of the funds for this payment. Either a PayPal account or a credit card.

Responses
200

A successful request returns the HTTP 200 OK status code and a JSON response body that shows order and payment details.

Request samples 
curl -v -X POST https://api-m.sandbox.paypal.com/v1/checkout/orders/8SC68793353299025/pay \
-H 'Authorization: Bearer access_token6V7rbVwmlM1gFZKW_8QtzWXqpcwQ6T5vhEGYNJDAAdn3paCgRpdeMdVYmWzgbKSsECednupJ3Zx5Xd-g' \
-d '{}'
Response samples
application/json
{
  • "order_id": "76T08342AW176740Y",
  • "status": "APPROVED",
  • "payer_info": {
    • "email": "buyer@example.com",
    • "first_name": "Robert",
    • "last_name": "Lesley",
    • "payer_id": "HPQAUP5WC3J8U",
    • "phone": "7028530329",
    • "country_code": "US",
    • "shipping_address": {
      • "recipient_name": "Robert Lesley",
      • "line1": "2211 N First Street",
      • "line2": "Building 17",
      • "city": "San Jose",
      • "country_code": "US",
      • "postal_code": "95131",
      • "state": "CA"
      }
    },
  • "create_time": "2018-09-21T17:33:18Z",
  • "update_time": "2018-09-21T17:33:18Z",
  • "links": []
}

Errors

ACCOUNT_CANNOT_BE_FETCHED

Message:
Account cannot be fetched.

Description:
The server cannot get the partner or seller account information. The account is either not available or incorrect. The API returns this error for seller accounts when you do not enable onboarding after buyers make purchases for the associated partner.

INTERNAL_SERVER_ERROR

Message:
An internal server error occurred.

Description:
A system or application error occurred. Although the client appears to provide a correct request, something unexpected occurred on the server. A 500 response indicates a server-side software defect or site outage.

INVALID_REQUEST

Message:
The request is not well-formed, is syntactically incorrect, or violates schema.

Description:
The server did not understand the request because the API could not convert the payload data to the underlying data type, the data was not in the expected data format, the required field was not available, or a simple data validation error occurred. See Validation errors.

NOT_AUTHORIZED

Message:
Authorization failed due to insufficient permissions.

Description:
The client is not authorized to access this resource although it might have valid credentials. For example, the client does not have the correct OAuth2 scope. Additionally, a business-level authorization error might have occurred. For example, the account holder does not have sufficient funds.

PAYMENT_NOT_APPROVED_FOR_EXECUTION

Message:
Payer has not approved payment.

Description:
The API created the order. However, the customer has not approved the payment.

RESOURCE_NOT_FOUND

Message:
The specified resource does not exist.

Description:
The server did not find anything that matches the request URI. Either the URI is incorrect or the resource is not available. For example, no data exists in the database at that key.

UNAUTHORIZED

Message:
Authentication failed due to invalid authentication credentials.

Description:
The request requires authentication and the caller did not provide valid authentication credentials. Note the difference between this error and the NOT_AUTHORIZED error. See Authentication errors.

VALIDATION_ERROR

Message:
Required field is missing.

Description:
The server did not understand the request because the API could not convert the payload data to the underlying data type, the data was not in the expected data format, the required field was not available, or a simple data validation error occurred. See Validation errors.

Definitions

Address

The billing address or shipping address for a payment.

line1
required
string

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

line2
string

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

city
string

The city name.

country_code
required
string <ppaas_common_country_code_v2> (country_code) = 2 characters ^([A-Z]{2}|C2)$

The two-character ISO 3166-1 code 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.

postal_code
string

The postal code, which is the zip code or equivalent. Typically required for countries with a postal code or an equivalent. See postal code.

state
string

The code for a US state or the equivalent for other countries. Required for transactions if the address is in one of these countries: Argentina, Brazil, Canada, India, Italy, Japan, Mexico, Thailand, or United States. Maximum length is 40 single-byte characters.

phone
string <phone>

The phone number, in E.123 format. Maximum length is 50 characters.

normalization_status
string

The address normalization status. Returned only for payers from Brazil.

Enum: "UNKNOWN" "UNNORMALIZED_USER_PREFERRED" "NORMALIZED" "UNNORMALIZED"
type
string

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

{
  • "line1": "string",
  • "line2": "string",
  • "city": "string",
  • "country_code": "st",
  • "postal_code": "string",
  • "state": "string",
  • "phone": "string",
  • "normalization_status": "UNKNOWN",
  • "type": "string"
}

Amount

The payment amount, with details.

currency
required
string

The three-character ISO-4217 currency code. PayPal does not support all currencies.

total
required
string

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.

object (Payment Amount Details)

The additional details about the payment amount.

{
  • "currency": "string",
  • "total": "string",
  • "details": {
    • "subtotal": "string",
    • "shipping": "string",
    • "tax": "string",
    • "handling_fee": "string",
    • "shipping_discount": "string",
    • "insurance": "string",
    • "gift_wrap": "string"
    }
}

Application Context

Customizes the payer experience during the approval process for the payment with PayPal.

Note: The PayPal Commerce Platform might configure brand_name and shipping_preference during partner account setup, which overrides the request values.

brand_name
string <= 127 characters

The label that overrides the business name in the PayPal account on the PayPal pages.

locale
string <ppaas_common_language_v3> (language) [ 2 .. 10 ] characters ^[a-z]{2}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}))...

The language tag 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, the optional ISO-15924 script tag, and the ISO-3166 alpha-2 country code.

shipping_preference
string

The shipping preferences.

Enum: Description
NO_SHIPPING

Redact shipping address fields from the PayPal pages. Recommended for digital goods.

GET_FROM_FILE

Use the buyer-selected shipping address.

SET_PROVIDED_ADDRESS

Use the merchant-provided address. Buyer cannot change the address on the PayPal pages. If the merchant does not pass an address, the buyer can choose the address on PayPal pages.

user_action
string

Defines whether to present the customer with a Continue or Pay Now checkout flow. To present buyers with the Pay Now checkout flow, set useraction=commit. Default is the Continue checkout flow.

Checkout flowChoose whenDescription
ContinueYou do not know the final payment amount when you initiate the checkout flow.The default flow. Redirects the customer to the PayPal payment page, which shows the Continue button. When the customer clicks Continue, the customer can change the payment amount.
Pay NowYou know the final payment amount when you initiate the checkout flow.Set user_action=commit. Redirects the customer to the PayPal payment page, which shows the Pay Now button. When the customer clicks Pay Now, the payment is processed immediately.

Array of objects (Name and Value Pair)

An array of name-and-value pairs that contain supplementary data required by PayPal for transaction processing.

{
  • "brand_name": "string",
  • "locale": "string",
  • "shipping_preference": "NO_SHIPPING",
  • "user_action": "string",
  • "supplementary_data": [
    • {
      • "name": "string",
      • "value": "string"
      }
    ]
}

Capture

A capture transaction.

id
string

The ID of the capture transaction.

status
string

The status of the capture transaction.

Enum: Description
PENDING

The purchase unit status is CAPTURED and the capture status is pending.

COMPLETED

The purchase unit status is CAPTURED and the payment was captured successfully.

REFUNDED

The purchase unit status is CAPTURED and the dispute decision was in the customer's favor. A full refund for the captured payment was made successfully to the customer.

PARTIALLY_REFUNDED

The purchase unit status is CAPTURED and the dispute decision was in the customer's favor. A partial refund for the captured payment was made successfully to the customer.

DENIED

The purchase unit status is CAPTURED and the capture was denied.

reason_code
string

A reason code that indicates the reason for the transaction state of PENDING or REVERSED.

Enum: Description
CHARGEBACK

The transaction state is PENDING or REVERSED due to a chargeback.

GUARANTEE

The transaction state is PENDING or REVERSED due to a guarantee.

BUYER_COMPLAINT

The transaction state is PENDING or REVERSED due to a buyer complaint.

REFUND

The transaction state is PENDING or REVERSED due to a refund.

UNCONFIRMED_SHIPPING_ADDRESS

The transaction state is PENDING or REVERSED due to an unconfirmed shipping address.

ECHECK

The transaction state is PENDING or REVERSED due to an e-check.

INTERNATIONAL_WITHDRAWAL

The transaction state is PENDING or REVERSED due to an international withdrawal.

RECEIVING_PREFERENCE_MANDATES_MANUAL_ACTION

The transaction state is PENDING or REVERSED due to a receiving preference that mandates manual action.

PAYMENT_REVIEW

The transaction state is PENDING or REVERSED due to a payment review.

REGULATORY_REVIEW

The transaction state is PENDING or REVERSED due to a regulatory review.

UNILATERAL

The transaction state is PENDING or REVERSED due to a unilateral reason.

VERIFICATION_REQUIRED

The transaction state is PENDING or REVERSED because verification is required.

DELAYED_DISBURSEMENT

The transaction state is PENDING or REVERSED due to a delayed disbursement.

Array of objects (Link Description)

An array of request-related HATEOAS links.

object (Amount)

The amount to capture. Default is the authorization amount. If that amount is the same as the authorized amount, the authorization state changes to CAPTURED. Otherwise, the authorization state changes to PARTIALLY_CAPTURED. To indicate that this capture is the final capture, set is_final_capture to true.

object (Currency)

The currency and amount of the transaction fee.

{
  • "id": "string",
  • "status": "PENDING",
  • "reason_code": "CHARGEBACK",
  • "links": [
    • {
      • "href": "string",
      • "rel": "string",
      • "method": "GET"
      }
    ],
  • "amount": {
    • "currency": "string",
    • "total": "string",
    • "details": {
      • "subtotal": "string",
      • "shipping": "string",
      • "tax": "string",
      • "handling_fee": "string",
      • "shipping_discount": "string",
      • "insurance": "string",
      • "gift_wrap": "string"
      }
    },
  • "transaction_fee": {
    • "currency": "string",
    • "value": "string"
    }
}

country_code

The two-character ISO 3166-1 code 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.

string <ppaas_common_country_code_v2> (country_code) = 2 characters ^([A-Z]{2}|C2)$

The two-character ISO 3166-1 code 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.

"st"

Credit Card

Deprecated. The credit card details. You can use this instrument to fund a payment. Use a payment card instead.

number
required
string

The credit card number. Value is numeric characters only with no spaces or punctuation. Must conform to the modulo and length required by each credit card type. Redacted in responses.

type
required
string

The credit card type. Value is visa, mastercard, discover, or amex. Do not use these lowercase values for display.

expire_month
required
integer

The expiration month with no leading zero. Value is from 1 to 12.

expire_year
required
integer

The four-digit expiration year.

cvv2
string

The three- to four-digit card validation code.

first_name
string

The card holder's first name.

last_name
string

The card holder's last name.

Array of objects (Link Description)

An array of request-related HATEOAS links.

object (Address)

The billing address or shipping address for a payment.

{
  • "number": "string",
  • "type": "string",
  • "expire_month": 0,
  • "expire_year": 0,
  • "cvv2": "string",
  • "first_name": "string",
  • "last_name": "string",
  • "links": [
    • {
      • "href": "string",
      • "rel": "string",
      • "method": "GET"
      }
    ],
  • "billing_address": {
    • "line1": "string",
    • "line2": "string",
    • "city": "string",
    • "country_code": "st",
    • "postal_code": "string",
    • "state": "string",
    • "phone": "string",
    • "normalization_status": "UNKNOWN",
    • "type": "string"
    }
}

Credit Card Token

The tokenized credit card details. You can use this instrument to fund a payment.

credit_card_id
required
string

The ID of credit card that is stored in the PayPal vault.

payer_id
string

A unique ID that you can assign and track when you store a credit card in the vault or use a vaulted credit card. This ID can help to avoid unintentional use or misuse of credit cards and can be any value, such as a UUID, user name, or email address. Required when you use a vaulted credit card and if a payer_id was originally provided when you vaulted the credit card.

last4
string

The last four digits of the stored credit card number.

type
string

The credit card type. Value is visa, mastercard, discover, or amex. Do not use these lowercase values for display.

expire_month
integer

The expiration month with no leading zero. Value is from 1 to 12.

expire_year
integer

The four-digit expiration year.

{
  • "credit_card_id": "string",
  • "payer_id": "string",
  • "last4": "string",
  • "type": "string",
  • "expire_month": 0,
  • "expire_year": 0
}

Currency

The currency and amount for a transaction.

currency
required
string

The three-character ISO-4217 currency code. PayPal does not support all currencies.

value
required
string

The amount. Includes the specified number of digits after decimal separator for the ISO-4217 currency code.

{
  • "currency": "string",
  • "value": "string"
}

currency_code

The three-character ISO-4217 currency code that identifies the currency.

string <ppaas_common_currency_code_v2> (currency_code) = 3 characters

The three-character ISO-4217 currency code that identifies the currency.

"str"

Error

The error details.

name
required
string

The human-readable, unique name of the error.

message
required
string

The message that describes the error.

debug_id
required
string

The PayPal internal ID that is used for correlation purposes.

information_link
string

The information link, or URI, that shows detailed information about this error for the developer.

Array of objects (Error Details)

An array of additional details about the error.

Array of objects (Link Description)

An array of request-related HATEOAS links.

{
  • "name": "string",
  • "message": "string",
  • "debug_id": "string",
  • "information_link": "string",
  • "details": [
    • {
      • "field": "string",
      • "value": "string",
      • "location": "body",
      • "issue": "string",
      • "description": "string"
      }
    ],
  • "links": [
    • {
      • "href": "string",
      • "rel": "string",
      • "method": "GET"
      }
    ]
}

Error Details

The error details. Required for client-side 4XX errors.

field
string

The field that caused the error. If the field is in the body, set this value to the JSON pointer to that field. Required for client-side errors.

value
string

The value of the field that caused the error.

location
string
Default: "body"

The location of the field that caused the error. Value is body, path, or query.

issue
required
string

The unique and fine-grained application-level error code.

description
string

The human-readable description for an issue. The description MAY change over the lifetime of an API, so clients MUST NOT depend on this value.

{
  • "field": "string",
  • "value": "string",
  • "location": "body",
  • "issue": "string",
  • "description": "string"
}

Execute Order

An execute order request.

disbursement_mode
required
string

Indicates whether to disburse money instantly or later.

Enum: Description
INSTANT

Money is disbursed instantly.

DELAYED

Money will be disbursed later.

object (Payer)

The source of the funds for this payment. Either a PayPal account or a credit card.

{
  • "disbursement_mode": "INSTANT",
  • "payer": {
    • "payment_method": "credit_card",
    • "status": "VERIFIED",
    • "funding_instruments": [
      • {
        • "credit_card": {
          • "number": "string",
          • "type": "string",
          • "expire_month": 0,
          • "expire_year": 0,
          • "cvv2": "string",
          • "first_name": "string",
          • "last_name": "string",
          • "links": [
            • {
              • "href": "string",
              • "rel": "string",
              • "method": "GET"
              }
            ],
          • "billing_address": {
            • "line1": "string",
            • "line2": "string",
            • "city": "string",
            • "country_code": "st",
            • "postal_code": "string",
            • "state": "string",
            • "phone": "string",
            • "normalization_status": "UNKNOWN",
            • "type": "string"
            }
          },
        • "credit_card_token": {
          • "credit_card_id": "string",
          • "payer_id": "string",
          • "last4": "string",
          • "type": "string",
          • "expire_month": 0,
          • "expire_year": 0
          }
        }
      ],
    • "payer_info": {
      • "email": "user@example.com",
      • "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",
      • "country_code": "string",
      • "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"
        }
      }
    }
}

Funding Instrument

The funding instrument details. An instance of this schema is valid if and only if it validates against exactly one of these supported properties.

object (Credit Card)

Deprecated. The credit card details. You can use this instrument to fund a payment. Use a payment card instead.

object (Credit Card Token)

The tokenized credit card details. You can use this instrument to fund a payment.

{
  • "credit_card": {
    • "number": "string",
    • "type": "string",
    • "expire_month": 0,
    • "expire_year": 0,
    • "cvv2": "string",
    • "first_name": "string",
    • "last_name": "string",
    • "links": [
      • {
        • "href": "string",
        • "rel": "string",
        • "method": "GET"
        }
      ],
    • "billing_address": {
      • "line1": "string",
      • "line2": "string",
      • "city": "string",
      • "country_code": "st",
      • "postal_code": "string",
      • "state": "string",
      • "phone": "string",
      • "normalization_status": "UNKNOWN",
      • "type": "string"
      }
    },
  • "credit_card_token": {
    • "credit_card_id": "string",
    • "payer_id": "string",
    • "last4": "string",
    • "type": "string",
    • "expire_month": 0,
    • "expire_year": 0
    }
}

Installment Option

The installment option details.

term
required
integer

The number of installments.

required
object (Currency)

The currency and amount for a transaction.

object (Currency)

The currency and amount for a transaction.

discount_percentage
string <ppaas_common_percentage_v1> (Percentage) ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$

The percentage as a fixed-point, signed decimal value. Use for all interest rates. For example, specify an interest rate of 19.99% as 19.99. The allowed number formats are plain decimal numbers and whole numbers.

{
  • "term": 0,
  • "monthly_payment": {
    • "currency": "string",
    • "value": "string"
    },
  • "discount_amount": {
    • "currency": "string",
    • "value": "string"
    },
  • "discount_percentage": "string"
}

Item

The item details.

sku
string <= 127 characters

The stock keeping unit (SKU) for the item.

name
required
string

The item name. Maximum length is 127 characters.

description
string <= 127 characters

The item description. Supported only for the PayPal payment method.

quantity
required
string <= 10 characters ^[0-9]{0,10}$

The item quantity. Must be a whole number.

price
required
string <= 10 characters ^[0-9]{0,10}(\.[0-9]{0,2})?$

The item cost. Supports two decimal places.

currency
required
tax
string

The item tax. Supported only for the PayPal payment method.

url
string <uri>

The URL to item information. Available to the payer in the transaction history.

{
  • "sku": "string",
  • "name": "string",
  • "description": "string",
  • "quantity": "string",
  • "price": "string",
  • "currency": "string",
  • "tax": "string",
  • "url": "http://example.com"
}

language

The language tag 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, the optional ISO-15924 script tag, and the ISO-3166 alpha-2 country code.

string <ppaas_common_language_v3> (language) [ 2 .. 10 ] characters ^[a-z]{2}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}))...

The language tag 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, the optional ISO-15924 script tag, and the ISO-3166 alpha-2 country code.

"string"

Metadata

The name-and-value pairs that contain external data, such as user, user feedback, score, and so on.

Array of objects (Name and Value Pair)

An array of name-and-value pairs that contain data required by PayPal for transaction processing.

{
  • "supplementary_data": [
    • {
      • "name": "string",
      • "value": "string"
      }
    ]
}

Name and Value Pair

The name-and-value pair details.

name
required
string

The key for the name-and-value pair. You must correlate the value and name types.

value
required
string

The value for the name-and-value pair.

{
  • "name": "string",
  • "value": "string"
}

Order

An order.

id
string

The ID of the order.

intent
string

The intent.

Enum: Description
SALE

A sale.

AUTHORIZE

An authorization.

required
Array of objects (Purchase Unit) non-empty

An array of purchase units. Each purchase unit establishes a contract between a customer and merchant.

object (Payment Details)

The payment details for the order.

object (Application Context)

Customizes the payer experience during the approval process for the payment with PayPal.

Note: The PayPal Commerce Platform might configure brand_name and shipping_preference during partner account setup, which overrides the request values.

status
string

The status of the order. After the customer approves the order, the status is APPROVED. After the payment is made for the order and the order completes, the status is COMPLETED.

Enum: Description
CREATED

The POST /v1/checkout/orders call succeeded and the order was created.

APPROVED

The customer approved the order.

COMPLETED

The POST /v1/checkout/orders/{order_id}/pay call succeeded and the order was paid and is complete.

FAILED

The order failed.

required
object (Redirect URLs)

The redirect URLs. Required only for the PayPal payment method. The supported settings are return and cancel URLs.

create_time
string <date-time>

The date and time when the resource was created, in Internet date and time format.

update_time
string <date-time>

The date and time when the resource was last updated, in Internet date and time format.

Array of objects (Link Description)

An array of request-related HATEOAS links. To complete the buyer approval, use the approval_url link with the GET method and do not use the link that shows the REDIRECT method.

object (Currency)

The currency and amount of the PayPal-computed total of amounts in all purchase units.

object (Metadata)

The name-and-value pairs that contain external data, such as user, user feedback, score, and so on.

{
  • "id": "string",
  • "intent": "SALE",
  • "purchase_units": [
    • {
      • "reference_id": "string",
      • "description": "string",
      • "custom": "string",
      • "invoice_number": "string",
      • "payment_descriptor": "string",
      • "items": [
        • {
          • "sku": "string",
          • "name": "string",
          • "description": "string",
          • "quantity": "string",
          • "price": "string",
          • "currency": "string",
          • "tax": "string",
          • "url": "http://example.com"
          }
        ],
      • "notify_url": "http://example.com",
      • "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",
      • "partner_fee_details": {
        • "receiver": {
          • "email": "user@example.com",
          • "merchant_id": "string",
          • "payee_display_metadata": {
            • "email": "user@example.com",
            • "display_phone": {
              • "country_code": "string",
              • "number": "string"
              },
            • "brand_name": "string"
            }
          },
        • "amount": {
          • "currency": "string",
          • "value": "string"
          }
        },
      • "payment_linked_group": 1,
      • "metadata": {
        • "supplementary_data": [
          • {
            • "name": "string",
            • "value": "string"
            }
          ]
        },
      • "payment_summary": {
        • "captures": [
          • {
            • "id": "string",
            • "status": "PENDING",
            • "reason_code": "CHARGEBACK",
            • "links": [
              • {
                • "href": null,
                • "rel": null,
                • "method": null
                }
              ],
            • "amount": {
              • "currency": "string",
              • "total": "string",
              • "details": {
                • "subtotal": null,
                • "shipping": null,
                • "tax": null,
                • "handling_fee": null,
                • "shipping_discount": null,
                • "insurance": null,
                • "gift_wrap": null
                }
              },
            • "transaction_fee": {
              • "currency": "string",
              • "value": "string"
              }
            }
          ],
        • "refunds": [
          • {
            • "id": "string",
            • "capture_id": "string",
            • "sale_id": "string",
            • "status": "PENDING",
            • "links": [
              • {
                • "href": null,
                • "rel": null,
                • "method": null
                }
              ],
            • "amount": {
              • "currency": "string",
              • "total": "string",
              • "details": {
                • "subtotal": null,
                • "shipping": null,
                • "tax": null,
                • "handling_fee": null,
                • "shipping_discount": null,
                • "insurance": null,
                • "gift_wrap": null
                }
              }
            }
          ],
        • "sales": [
          • {
            • "id": "string",
            • "status": "COMPLETED",
            • "reason_code": "CHARGEBACK",
            • "create_time": "2019-08-24T14:15:22Z",
            • "update_time": "2019-08-24T14:15:22Z",
            • "links": [
              • {
                • "href": null,
                • "rel": null,
                • "method": null
                }
              ],
            • "amount": {
              • "currency": "string",
              • "total": "string",
              • "details": {
                • "subtotal": null,
                • "shipping": null,
                • "tax": null,
                • "handling_fee": null,
                • "shipping_discount": null,
                • "insurance": null,
                • "gift_wrap": null
                }
              },
            • "transaction_fee": {
              • "currency": "string",
              • "value": "string"
              }
            }
          ],
        • "authorizations": [
          • {
            • "id": "string",
            • "status": "COMPLETED",
            • "reason_code": "CHARGEBACK",
            • "create_time": "2019-08-24T14:15:22Z",
            • "update_time": "2019-08-24T14:15:22Z",
            • "links": [
              • {
                • "href": null,
                • "rel": null,
                • "method": null
                }
              ],
            • "amount": {
              • "currency": "string",
              • "total": "string",
              • "details": {
                • "subtotal": null,
                • "shipping": null,
                • "tax": null,
                • "handling_fee": null,
                • "shipping_discount": null,
                • "insurance": null,
                • "gift_wrap": null
                }
              },
            • "transaction_fee": {
              • "currency": "string",
              • "value": "string"
              }
            }
          ]
        },
      • "status": "NOT_PROCESSED",
      • "reason_code": "PAYER_SHIPPING_UNCONFIRMED",
      • "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": "user@example.com",
        • "merchant_id": "string",
        • "payee_display_metadata": {
          • "email": "user@example.com",
          • "display_phone": {
            • "country_code": "string",
            • "number": "string"
            },
          • "brand_name": "string"
          }
        }
      }
    ],
  • "payment_details": {
    • "payment_id": "string",
    • "disbursement_mode": "INSTANT"
    },
  • "application_context": {
    • "brand_name": "string",
    • "locale": "string",
    • "shipping_preference": "NO_SHIPPING",
    • "user_action": "string",
    • "supplementary_data": [
      • {
        • "name": "string",
        • "value": "string"
        }
      ]
    },
  • "status": "CREATED",
  • "redirect_urls": {},
  • "create_time": "2019-08-24T14:15:22Z",
  • "update_time": "2019-08-24T14:15:22Z",
  • "links": [
    • {
      • "href": "string",
      • "rel": "string",
      • "method": "GET"
      }
    ],
  • "gross_total_amount": {
    • "currency": "string",
    • "value": "string"
    },
  • "metadata": {
    • "supplementary_data": [
      • {
        • "name": "string",
        • "value": "string"
        }
      ]
    }
}

Partner Fee Details

The partner fee that is collected for the original transaction.

required
object (Payee)

The partner who receives the partner fee.

required
object (Currency)

The amount and currency of the partner fee.

{
  • "receiver": {
    • "email": "user@example.com",
    • "merchant_id": "string",
    • "payee_display_metadata": {
      • "email": "user@example.com",
      • "display_phone": {
        • "country_code": "string",
        • "number": "string"
        },
      • "brand_name": "string"
      }
    },
  • "amount": {
    • "currency": "string",
    • "value": "string"
    }
}

Pay Order Response

A pay order response.

order_id
string

The ID of the order.

status
string

The status of the order.

Enum: Description
APPROVED

The order is approved.

CANCELED

The order is canceled.

COMPLETED

The order is completed.

CREATED

The order is created.

EXPIRED

The order is expired.

FAILED

The order FAILED.

IN_PROGRESS

The order is in progress.

PARTIALLY_COMPLETED

The order is partially completed.

SUBMITTED

The order was submitted.

intent
string

The intent.

Enum: Description
SALE

A sale.

AUTHORIZE

An authorization.

Array of objects (Purchase Unit) non-empty

An array of purchase units. Each purchase unit establishes a contract between a customer and merchant.

create_time
string <date-time>

The date and time when the resource was created, in Internet date and time format.

update_time
string <date-time>

The date and time when the resource was last updated, in Internet date and time format.

Array of objects (Link Description)

An array of request-related HATEOAS links.

object (Payer Information)

The payer information.

{
  • "order_id": "string",
  • "status": "APPROVED",
  • "intent": "SALE",
  • "purchase_units": [
    • {
      • "reference_id": "string",
      • "description": "string",
      • "custom": "string",
      • "invoice_number": "string",
      • "payment_descriptor": "string",
      • "items": [
        • {
          • "sku": "string",
          • "name": "string",
          • "description": "string",
          • "quantity": "string",
          • "price": "string",
          • "currency": "string",
          • "tax": "string",
          • "url": "http://example.com"
          }
        ],
      • "notify_url": "http://example.com",
      • "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",
      • "partner_fee_details": {
        • "receiver": {
          • "email": "user@example.com",
          • "merchant_id": "string",
          • "payee_display_metadata": {
            • "email": "user@example.com",
            • "display_phone": {
              • "country_code": "string",
              • "number": "string"
              },
            • "brand_name": "string"
            }
          },
        • "amount": {
          • "currency": "string",
          • "value": "string"
          }
        },
      • "payment_linked_group": 1,
      • "metadata": {
        • "supplementary_data": [
          • {
            • "name": "string",
            • "value": "string"
            }
          ]
        },
      • "payment_summary": {
        • "captures": [
          • {
            • "id": "string",
            • "status": "PENDING",
            • "reason_code": "CHARGEBACK",
            • "links": [
              • {
                • "href": null,
                • "rel": null,
                • "method": null
                }
              ],
            • "amount": {
              • "currency": "string",
              • "total": "string",
              • "details": {
                • "subtotal": null,
                • "shipping": null,
                • "tax": null,
                • "handling_fee": null,
                • "shipping_discount": null,
                • "insurance": null,
                • "gift_wrap": null
                }
              },
            • "transaction_fee": {
              • "currency": "string",
              • "value": "string"
              }
            }
          ],
        • "refunds": [
          • {
            • "id": "string",
            • "capture_id": "string",
            • "sale_id": "string",
            • "status": "PENDING",
            • "links": [
              • {
                • "href": null,
                • "rel": null,
                • "method": null
                }
              ],
            • "amount": {
              • "currency": "string",
              • "total": "string",
              • "details": {
                • "subtotal": null,
                • "shipping": null,
                • "tax": null,
                • "handling_fee": null,
                • "shipping_discount": null,
                • "insurance": null,
                • "gift_wrap": null
                }
              }
            }
          ],
        • "sales": [
          • {
            • "id": "string",
            • "status": "COMPLETED",
            • "reason_code": "CHARGEBACK",
            • "create_time": "2019-08-24T14:15:22Z",
            • "update_time": "2019-08-24T14:15:22Z",
            • "links": [
              • {
                • "href": null,
                • "rel": null,
                • "method": null
                }
              ],
            • "amount": {
              • "currency": "string",
              • "total": "string",
              • "details": {
                • "subtotal": null,
                • "shipping": null,
                • "tax": null,
                • "handling_fee": null,
                • "shipping_discount": null,
                • "insurance": null,
                • "gift_wrap": null
                }
              },
            • "transaction_fee": {
              • "currency": "string",
              • "value": "string"
              }
            }
          ],
        • "authorizations": [
          • {
            • "id": "string",
            • "status": "COMPLETED",
            • "reason_code": "CHARGEBACK",
            • "create_time": "2019-08-24T14:15:22Z",
            • "update_time": "2019-08-24T14:15:22Z",
            • "links": [
              • {
                • "href": null,
                • "rel": null,
                • "method": null
                }
              ],
            • "amount": {
              • "currency": "string",
              • "total": "string",
              • "details": {
                • "subtotal": null,
                • "shipping": null,
                • "tax": null,
                • "handling_fee": null,
                • "shipping_discount": null,
                • "insurance": null,
                • "gift_wrap": null
                }
              },
            • "transaction_fee": {
              • "currency": "string",
              • "value": "string"
              }
            }
          ]
        },
      • "status": "NOT_PROCESSED",
      • "reason_code": "PAYER_SHIPPING_UNCONFIRMED",
      • "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": "user@example.com",
        • "merchant_id": "string",
        • "payee_display_metadata": {
          • "email": "user@example.com",
          • "display_phone": {
            • "country_code": "string",
            • "number": "string"
            },
          • "brand_name": "string"
          }
        }
      }
    ],
  • "create_time": "2019-08-24T14:15:22Z",
  • "update_time": "2019-08-24T14:15:22Z",
  • "links": [
    • {
      • "href": "string",
      • "rel": "string",
      • "method": "GET"
      }
    ],
  • "payer_info": {
    • "email": "user@example.com",
    • "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",
    • "country_code": "string",
    • "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"
      }
    }
}

Payee

The payee who receives the funds and fulfills the order.

email
string <email>

The email address associated with the payee's PayPal account. For an intent of authorize or order, the email address must be associated with a confirmed PayPal business account. For an intent of sale, the email can either:

  • Be associated with a confirmed PayPal personal or business account.
  • Not be associated with a PayPal account.

merchant_id
string

The encrypted PayPal account ID for the payee.

object (Payee Display Metadata)

The display-only metadata for the payee.

{
  • "email": "user@example.com",
  • "merchant_id": "string",
  • "payee_display_metadata": {
    • "email": "user@example.com",
    • "display_phone": {
      • "country_code": "string",
      • "number": "string"
      },
    • "brand_name": "string"
    }
}

Payee Display Metadata

The display-only metadata for the payee.

email
string <email>

The email address for the payer. Maximum length is 127 characters.

object (Display Phone)

The payee's phone number.

brand_name
string

The payer's business name.

{
  • "email": "user@example.com",
  • "display_phone": {
    • "country_code": "string",
    • "number": "string"
    },
  • "brand_name": "string"
}

Payer

The payer. The payer funds the payment.

payment_method
string

The payment method. Value is PayPal Wallet payment, bank direct debit, or direct credit card.

Enum: "credit_card" "paypal"
status
string

The status of payer's PayPal account.

Enum: "VERIFIED" "UNVERIFIED"
Array of objects (Funding Instrument)

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.

object (Payer Information)

The payer information.

{
  • "payment_method": "credit_card",
  • "status": "VERIFIED",
  • "funding_instruments": [
    • {
      • "credit_card": {
        • "number": "string",
        • "type": "string",
        • "expire_month": 0,
        • "expire_year": 0,
        • "cvv2": "string",
        • "first_name": "string",
        • "last_name": "string",
        • "links": [
          • {
            • "href": "string",
            • "rel": "string",
            • "method": "GET"
            }
          ],
        • "billing_address": {
          • "line1": "string",
          • "line2": "string",
          • "city": "string",
          • "country_code": "st",
          • "postal_code": "string",
          • "state": "string",
          • "phone": "string",
          • "normalization_status": "UNKNOWN",
          • "type": "string"
          }
        },
      • "credit_card_token": {
        • "credit_card_id": "string",
        • "payer_id": "string",
        • "last4": "string",
        • "type": "string",
        • "expire_month": 0,
        • "expire_year": 0
        }
      }
    ],
  • "payer_info": {
    • "email": "user@example.com",
    • "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",
    • "country_code": "string",
    • "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"
      }
    }
}

Payer Information

The payer information.

email
string <email>

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

salutation
string

The payer's salutation.

first_name
string

The payer's first name.

middle_name
string

The payer's middle name.

last_name
string

The payer's last name.

suffix
string

The payer's suffix.

payer_id
string

The PayPal-assigned encrypted payer ID.

birth_date
string <date-time>

The birth date of the payer, in Internet date format. For example, 1990-04-12.

tax_id
string <= 14 characters

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

tax_id_type
string

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

Enum: "BR_CPF" "BR_CNPJ"
country_code
object (Address)

The billing address or shipping address for a payment.

object (Shipping Address)

The shipping address details.

{
  • "email": "user@example.com",
  • "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",
  • "country_code": "string",
  • "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"
    }
}

Payment Details

The payment details for the order.

payment_id
string

The payment ID for the order.

disbursement_mode
string

Indicates whether to disburse the payment instantly or delay the payment.

Enum: Description
INSTANT

The payment is disbursed instantly.

DELAYED

The payment is delayed.

{
  • "payment_id": "string",
  • "disbursement_mode": "INSTANT"
}

Payment Summary

The payment summary.

Array of objects (Capture) non-empty

An array of captures for a purchase unit. A purchase unit can have zero or more captures.

Array of objects (Refund) non-empty

An array of refunds for a purchase unit. A purchase unit can have zero or more refunds.

Array of objects (Sale) non-empty

An array of sales for a purchase unit. A purchase unit can have zero or more sales.

Array of objects (Sale) non-empty

An array of authorizations for a purchase unit. A purchase unit can have zero or more authorizations.

{
  • "captures": [
    • {
      • "id": "string",
      • "status": "PENDING",
      • "reason_code": "CHARGEBACK",
      • "links": [
        • {
          • "href": "string",
          • "rel": "string",
          • "method": "GET"
          }
        ],
      • "amount": {
        • "currency": "string",
        • "total": "string",
        • "details": {
          • "subtotal": "string",
          • "shipping": "string",
          • "tax": "string",
          • "handling_fee": "string",
          • "shipping_discount": "string",
          • "insurance": "string",
          • "gift_wrap": "string"
          }
        },
      • "transaction_fee": {
        • "currency": "string",
        • "value": "string"
        }
      }
    ],
  • "refunds": [
    • {
      • "id": "string",
      • "capture_id": "string",
      • "sale_id": "string",
      • "status": "PENDING",
      • "links": [
        • {
          • "href": "string",
          • "rel": "string",
          • "method": "GET"
          }
        ],
      • "amount": {
        • "currency": "string",
        • "total": "string",
        • "details": {
          • "subtotal": "string",
          • "shipping": "string",
          • "tax": "string",
          • "handling_fee": "string",
          • "shipping_discount": "string",
          • "insurance": "string",
          • "gift_wrap": "string"
          }
        }
      }
    ],
  • "sales": [
    • {
      • "id": "string",
      • "status": "COMPLETED",
      • "reason_code": "CHARGEBACK",
      • "create_time": "2019-08-24T14:15:22Z",
      • "update_time": "2019-08-24T14:15:22Z",
      • "links": [
        • {
          • "href": "string",
          • "rel": "string",
          • "method": "GET"
          }
        ],
      • "amount": {
        • "currency": "string",
        • "total": "string",
        • "details": {
          • "subtotal": "string",
          • "shipping": "string",
          • "tax": "string",
          • "handling_fee": "string",
          • "shipping_discount": "string",
          • "insurance": "string",
          • "gift_wrap": "string"
          }
        },
      • "transaction_fee": {
        • "currency": "string",
        • "value": "string"
        }
      }
    ],
  • "authorizations": [
    • {
      • "id": "string",
      • "status": "COMPLETED",
      • "reason_code": "CHARGEBACK",
      • "create_time": "2019-08-24T14:15:22Z",
      • "update_time": "2019-08-24T14:15:22Z",
      • "links": [
        • {
          • "href": "string",
          • "rel": "string",
          • "method": "GET"
          }
        ],
      • "amount": {
        • "currency": "string",
        • "total": "string",
        • "details": {
          • "subtotal": "string",
          • "shipping": "string",
          • "tax": "string",
          • "handling_fee": "string",
          • "shipping_discount": "string",
          • "insurance": "string",
          • "gift_wrap": "string"
          }
        },
      • "transaction_fee": {
        • "currency": "string",
        • "value": "string"
        }
      }
    ]
}

Percentage

The percentage as a fixed-point, signed decimal value. Use for all interest rates. For example, specify an interest rate of 19.99% as 19.99. The allowed number formats are plain decimal numbers and whole numbers.

string <ppaas_common_percentage_v1> (Percentage) ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$

The percentage as a fixed-point, signed decimal value. Use for all interest rates. For example, specify an interest rate of 19.99% as 19.99. The allowed number formats are plain decimal numbers and whole numbers.

"string"

Purchase Unit

A purchase unit. Establishes a contract between the payer and payee.

reference_id
required
string <= 256 characters

The merchant ID for the purchase unit.

description
string <= 127 characters

The purchase description.

custom
string <= 127 characters

The client-provided external ID. Used to reconcile client transactions with PayPal transactions. Returned in transaction and settlement reports. Only supported for the PayPal payment method.

invoice_number
string <= 256 characters

The API caller-provided external invoice ID for this order.. Only supported for the PayPal payment method.

payment_descriptor
string <= 22 characters

The payment descriptor on the buyer credit card statement of account activity.

Array of objects (Item)

An array of items that the customer is purchasing from the merchant.

notify_url
string <uri> <= 2048 characters

The payment notifications URL.

object (Shipping Address)

The shipping address details.

shipping_method
string

The shipping method. For example, USPSParcel.

object (Partner Fee Details)

The partner fee that is collected for the original transaction.

payment_linked_group
integer [ 1 .. 100 ]

An ID that groups multiple linked purchase units. The purchase transactions are linked only for the payment and not for refund. A refund is processed only for the specific transaction within the same linked group.

object (Metadata)

The name-and-value pairs that contain external data, such as user, user feedback, score, and so on.

object (Payment Summary)

The payment summary.

status
string

The transaction state.

Enum: Description
NOT_PROCESSED

The transaction was not processed.

PENDING

The transaction is pending.

VOIDED

The transaction was declined and voided.

AUTHORIZED

Payment for the transaction was not authorized.

CAPTURED

Payment for the transaction was captured or is pending capture.

reason_code
string

The reason code for a transaction status of PENDING or REVERSED. Eventually, this field will replace pending_reason. Supported only for the PayPal payment method.

Enum: Description
PAYER_SHIPPING_UNCONFIRMED

The transaction state is PENDING or REVERSED due to an unconfirmed payer shipping address.

MULTI_CURRENCY

The transaction state is PENDING or REVERSED because it is a multi-currency transaction.

RISK_REVIEW

The transaction state is PENDING or REVERSED due to a risk review.

REGULATORY_REVIEW

The transaction state is PENDING or REVERSED due to a regulatory review.

VERIFICATION_REQUIRED

The transaction state is PENDING or REVERSED because verification is required.

ORDER

The transaction state is PENDING or REVERSED because the transaction is an order.

OTHER

The transaction state is PENDING or REVERSED due to another reason.

DECLINED_BY_POLICY

The transaction state is PENDING or REVERSED because it was declined by a policy.

required
object (Amount)

The amount to collect.

object (Payee)

The recipient of the funds for this transaction.

{
  • "reference_id": "string",
  • "description": "string",
  • "custom": "string",
  • "invoice_number": "string",
  • "payment_descriptor": "string",
  • "items": [
    • {
      • "sku": "string",
      • "name": "string",
      • "description": "string",
      • "quantity": "string",
      • "price": "string",
      • "currency": "string",
      • "tax": "string",
      • "url": "http://example.com"
      }
    ],
  • "notify_url": "http://example.com",
  • "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",
  • "partner_fee_details": {
    • "receiver": {
      • "email": "user@example.com",
      • "merchant_id": "string",
      • "payee_display_metadata": {
        • "email": "user@example.com",
        • "display_phone": {
          • "country_code": "string",
          • "number": "string"
          },
        • "brand_name": "string"
        }
      },
    • "amount": {
      • "currency": "string",
      • "value": "string"
      }
    },
  • "payment_linked_group": 1,
  • "metadata": {
    • "supplementary_data": [
      • {
        • "name": "string",
        • "value": "string"
        }
      ]
    },
  • "payment_summary": {
    • "captures": [
      • {
        • "id": "string",
        • "status": "PENDING",
        • "reason_code": "CHARGEBACK",
        • "links": [
          • {
            • "href": "string",
            • "rel": "string",
            • "method": "GET"
            }
          ],
        • "amount": {
          • "currency": "string",
          • "total": "string",
          • "details": {
            • "subtotal": "string",
            • "shipping": "string",
            • "tax": "string",
            • "handling_fee": "string",
            • "shipping_discount": "string",
            • "insurance": "string",
            • "gift_wrap": "string"
            }
          },
        • "transaction_fee": {
          • "currency": "string",
          • "value": "string"
          }
        }
      ],
    • "refunds": [
      • {
        • "id": "string",
        • "capture_id": "string",
        • "sale_id": "string",
        • "status": "PENDING",
        • "links": [
          • {
            • "href": "string",
            • "rel": "string",
            • "method": "GET"
            }
          ],
        • "amount": {
          • "currency": "string",
          • "total": "string",
          • "details": {
            • "subtotal": "string",
            • "shipping": "string",
            • "tax": "string",
            • "handling_fee": "string",
            • "shipping_discount": "string",
            • "insurance": "string",
            • "gift_wrap": "string"
            }
          }
        }
      ],
    • "sales": [
      • {
        • "id": "string",
        • "status": "COMPLETED",
        • "reason_code": "CHARGEBACK",
        • "create_time": "2019-08-24T14:15:22Z",
        • "update_time": "2019-08-24T14:15:22Z",
        • "links": [
          • {
            • "href": "string",
            • "rel": "string",
            • "method": "GET"
            }
          ],
        • "amount": {
          • "currency": "string",
          • "total": "string",
          • "details": {
            • "subtotal": "string",
            • "shipping": "string",
            • "tax": "string",
            • "handling_fee": "string",
            • "shipping_discount": "string",
            • "insurance": "string",
            • "gift_wrap": "string"
            }
          },
        • "transaction_fee": {
          • "currency": "string",
          • "value": "string"
          }
        }
      ],
    • "authorizations": [
      • {
        • "id": "string",
        • "status": "COMPLETED",
        • "reason_code": "CHARGEBACK",
        • "create_time": "2019-08-24T14:15:22Z",
        • "update_time": "2019-08-24T14:15:22Z",
        • "links": [
          • {
            • "href": "string",
            • "rel": "string",
            • "method": "GET"
            }
          ],
        • "amount": {
          • "currency": "string",
          • "total": "string",
          • "details": {
            • "subtotal": "string",
            • "shipping": "string",
            • "tax": "string",
            • "handling_fee": "string",
            • "shipping_discount": "string",
            • "insurance": "string",
            • "gift_wrap": "string"
            }
          },
        • "transaction_fee": {
          • "currency": "string",
          • "value": "string"
          }
        }
      ]
    },
  • "status": "NOT_PROCESSED",
  • "reason_code": "PAYER_SHIPPING_UNCONFIRMED",
  • "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": "user@example.com",
    • "merchant_id": "string",
    • "payee_display_metadata": {
      • "email": "user@example.com",
      • "display_phone": {
        • "country_code": "string",
        • "number": "string"
        },
      • "brand_name": "string"
      }
    }
}

Refund

A refund transaction.

id
string

The ID of the refund transaction. Maximum length is 17 characters.

capture_id
string

The ID of the sale transaction to refund.

sale_id
string

The ID of the sale transaction to refund.

status
string

The status of the refund.

Enum: Description
PENDING

The refund is pending.

COMPLETED

The refund completed.

FAILED

The refund failed.

Array of objects (Link Description)

An array of request-related HATEOAS links.

object (Amount)

The amount that is refunded to the payer and the amount that is refunded to the payee. Maximum length is 10 characters, which includes:

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

{
  • "id": "string",
  • "capture_id": "string",
  • "sale_id": "string",
  • "status": "PENDING",
  • "links": [
    • {
      • "href": "string",
      • "rel": "string",
      • "method": "GET"
      }
    ],
  • "amount": {
    • "currency": "string",
    • "total": "string",
    • "details": {
      • "subtotal": "string",
      • "shipping": "string",
      • "tax": "string",
      • "handling_fee": "string",
      • "shipping_discount": "string",
      • "insurance": "string",
      • "gift_wrap": "string"
      }
    }
}

Sale

A sale transaction.

id
string

The ID of the sale transaction.

status
string

The status of the sale transaction.

Enum: Description
COMPLETED

The sale completed.

PARTIALLY_REFUNDED

The sale was partially refunded.

PENDING

The sale is pending.

REFUNDED

The sale was refunded.

DENIED

The sale was denied.

reason_code
string

A reason code that indicates the reason for the transaction state of PENDING or REVERSED.

Enum: Description
CHARGEBACK

The transaction state is REVERSED due to a chargeback.

GUARANTEE

The transaction state is REVERSED due to a guarantee.

BUYER_COMPLAINT

The transaction state is REVERSED due to a buyer complaint.

REFUND

The transaction state is REVERSED due to a refund.

UNCONFIRMED_SHIPPING_ADDRESS

The transaction state is PENDING or REVERSED due to an unconfirmed shipping address.

ECHECK

The transaction state is PENDING due to an e-check.

INTERNATIONAL_WITHDRAWAL

The transaction state is PENDING due to an international withdrawal.

RECEIVING_PREFERENCE_MANDATES_MANUAL_ACTION

The transaction state is PENDING due to a receiving preference that mandates manual action.

PAYMENT_REVIEW

The transaction state is PENDING due to a payment review.

REGULATORY_REVIEW

The transaction state is PENDING due to a regulatory review.

UNILATERAL

The transaction state is PENDING due to a unilateral reason.

VERIFICATION_REQUIRED

The transaction state is PENDING because verification is required.

DELAYED_DISBURSEMENT

The transaction state is PENDING due to a delayed disbursement.

create_time
string <date-time>

The date and time when the resource was created, in Internet date and time format.

update_time
string <date-time>

The date and time when the resource was last updated, in Internet date and time format.

Array of objects (Link Description)

An array of request-related HATEOAS links.

object (Amount)

The amount to collect. Maximum length is 10 characters, which includes:

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

object (Currency)

The currency and amount of the transaction fee. Maximum length is 10 characters, which includes:

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

{
  • "id": "string",
  • "status": "COMPLETED",
  • "reason_code": "CHARGEBACK",
  • "create_time": "2019-08-24T14:15:22Z",
  • "update_time": "2019-08-24T14:15:22Z",
  • "links": [
    • {
      • "href": "string",
      • "rel": "string",
      • "method": "GET"
      }
    ],
  • "amount": {
    • "currency": "string",
    • "total": "string",
    • "details": {
      • "subtotal": "string",
      • "shipping": "string",
      • "tax": "string",
      • "handling_fee": "string",
      • "shipping_discount": "string",
      • "insurance": "string",
      • "gift_wrap": "string"
      }
    },
  • "transaction_fee": {
    • "currency": "string",
    • "value": "string"
    }
}

Shipping Address

The shipping address details.

line1
required
string

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

line2
string

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

city
string

The city name.

country_code
required
string <ppaas_common_country_code_v2> (country_code) = 2 characters ^([A-Z]{2}|C2)$

The two-character ISO 3166-1 code 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.

postal_code
string

The postal code, which is the zip code or equivalent. Typically required for countries with a postal code or an equivalent. See postal code.

state
string

The code for a US state or the equivalent for other countries. Required for transactions if the address is in one of these countries: Argentina, Brazil, Canada, India, Italy, Japan, Mexico, Thailand, or United States. Maximum length is 40 single-byte characters.

phone
string <phone>

The phone number, in E.123 format. Maximum length is 50 characters.

normalization_status
string

The address normalization status. Returned only for payers from Brazil.

Enum: "UNKNOWN" "UNNORMALIZED_USER_PREFERRED" "NORMALIZED" "UNNORMALIZED"
type
string

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

recipient_name
string <= 127 characters

The name of the recipient at this 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"
}