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:
required
intent
string

The intent.

Enum Value 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 
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 
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 
Response samples 
application/json
{ }
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: 
required
disbursement_mode
required
string
Indicates whether to disburse money instantly or later.


 Enum Value 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 
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 Value 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 Value 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 Value 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 Value 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 Value 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 Value 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 Value 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 Value 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 Value 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 Value 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 Value 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 Value 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 Value 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 Value 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"
}