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.

operation/orders.create Create order

post/v1/checkout/orders

Try it

Creates an order.

SecurityOauth2

Request

header Parameters


PayPal-Partner-Attribution-Id	string

Request Body schema: application/jsonmultipart/relatedmultipart/form-datamultipart/mixedapplication/json required

| intent | string

The intent.

Enum Value	Description
SALE	A sale.
AUTHORIZE	An authorization.
purchase_units required	Array of objects (Purchase Unit) non-empty An array of purchase units. Each purchase unit establishes a contract between a customer and merchant.
payment_details	object (Payment Details) The payment details for the order.
application_context	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.
redirect_urls required	object (Redirect URLs) The redirect URLs. Required only for the PayPal payment method. The supported settings are return and cancel URLs.
gross_total_amount	object (Currency) The currency and amount of the PayPal-computed total of amounts in all purchase units.
metadata	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

application/jsonmultipart/relatedmultipart/form-datamultipart/mixedapplication/json

Copy

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

Sample 1 - 200 - Create Order with Application ContextSample 1 - 200 - Create Order with Application Context

Copy

Expand allCollapse all

`{"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": {"return_url": "https://example.com/return",

"cancel_url": "https://example.com/cancel"

"create_time": "2017-04-26T21:18:49Z",

"links": [{"href": "https://api-m.paypal.com/v1/checkout/orders/8RU61172JS455403V",

"rel": "self",

"method": "GET"

},

{"href": "https://api-m.paypal.com/webapps/hermes?token=8RU61172JS455403V",

"rel": "approval_url",

"method": "GET"

},

{"href": "https://api-m.paypal.com/v1/checkout/orders/8RU61172JS455403V",

"rel": "cancel",

"method": "DELETE"

}

],

"status": "CREATED"

operation/orders.get Show order details

get/v1/checkout/orders/{order_id}

Try it

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

Copy

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

Sample 1 - 200 - Show Order Details - 200 OK CreatedSample 1 - 200 - Show Order Details - 200 OK Created

Copy

Expand allCollapse all

`{"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": {"return_url": "https://example.com/return",

"cancel_url": "https://example.com/cancel"

"links": [{"href": "https://api-m.paypal.com/v1/checkout/orders/8SC68793353299025",

"rel": "self",

"method": "GET"

},

{"href": "https://www.paypal.com/checkoutnow?token=8SC68793353299025",

"rel": "approval_url",

"method": "POST"

}

],

"create_time": "2018-09-21T17:22:45Z"

operation/orders.cancel Cancel order

delete/v1/checkout/orders/{order_id}

Try it

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

Copy

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

Response samples

application/json

Sample 1 - 204 - Cancel Order - 204 No ContentSample 1 - 204 - Cancel Order - 204 No Content

Copy

{ }

operation/orders.pay Pay for order

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

Try it

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/jsonmultipart/relatedmultipart/form-datamultipart/mixedapplication/json 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.
payer	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

application/jsonmultipart/relatedmultipart/form-datamultipart/mixedapplication/json

Copy

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

Sample 1 - 200 - Pay Order - 200 OKSample 1 - 200 - Pay Order - 200 OK

Copy

Expand allCollapse all

`{"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"

}

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.

Copy

`{"line1": "string",

"line2": "string",

"city": "string",

"country_code": "st",

"postal_code": "string",

"state": "string",

"phone": "string",

"normalization_status": "UNKNOWN",

"type": "string"

schema/amount 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.
details	object (Payment Amount Details) The additional details about the payment amount.

Copy

Expand allCollapse all

`{"currency": "string",

"total": "string",

"details": {"subtotal": "string",

"shipping": "string",

"tax": "string",

"handling_fee": "string",

"shipping_discount": "string",

"insurance": "string",

"gift_wrap": "string"

}

schema/application_context 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}))...Show pattern
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 flow	Choose when	Description
Continue	You 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 Now	You 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.
supplementary_data	Array of objects (Name and Value Pair) An array of name-and-value pairs that contain supplementary data required by PayPal for transaction processing.

Copy

Expand allCollapse all

`{"brand_name": "string",

"locale": "string",

"shipping_preference": "NO_SHIPPING",

"user_action": "string",

"supplementary_data": [{"name": "string",

"value": "string"

}

]

schema/capture Capture

A capture transaction.

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.
links	Array of objects (Link Description) An array of request-related HATEOAS links.
amount	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`.
transaction_fee	object (Currency) The currency and amount of the transaction fee.

Copy

Expand allCollapse all

`{"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"

}

schema/country_code 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.

Copy

"st"

schema/credit_card 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.
links	Array of objects (Link Description) An array of request-related HATEOAS links.
billing_address	object (Address) The billing address or shipping address for a payment.

Copy

Expand allCollapse all

`{"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"

}

schema/credit_card_token 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.

Copy

`{"credit_card_id": "string",

"payer_id": "string",

"last4": "string",

"type": "string",

"expire_month": 0,

"expire_year": 0

schema/currency 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.

Copy

`{"currency": "string",

"value": "string"

schema/currency_code 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.

Copy

"str"

schema/error 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.
details	Array of objects (Error Details) An array of additional details about the error.
links	Array of objects (Link Description) An array of request-related HATEOAS links.

Copy

Expand allCollapse all

`{"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"

}

]

schema/error_details 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.

Copy

`{"field": "string",

"value": "string",

"location": "body",

"issue": "string",

"description": "string"

schema/pay_order_request 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.
payer	object (Payer) The source of the funds for this payment. Either a PayPal account or a credit card.

Copy

Expand allCollapse all

`{"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"

}

schema/funding_instrument 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.


credit_card	object (Credit Card) Deprecated. The credit card details. You can use this instrument to fund a payment. Use a payment card instead.
credit_card_token	object (Credit Card Token) The tokenized credit card details. You can use this instrument to fund a payment.

Copy

Expand allCollapse all

`{"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

}

schema/installment_option Installment Option

The installment option details.


term required	integer The number of installments.
monthly_payment required	object (Currency) The currency and amount for a transaction.
discount_amount	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.

Copy

Expand allCollapse all

`{"term": 0,

"monthly_payment": {"currency": "string",

"value": "string"

"discount_amount": {"currency": "string",

"value": "string"

"discount_percentage": "string"

schema/item 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	string The three-character ISO-4217 currency code.
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.

Copy

`{"sku": "string",

"name": "string",

"description": "string",

"quantity": "string",

"price": "string",

"currency": "string",

"tax": "string",

"url": "http://example.com"

schema/language 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}))...Show pattern

Copy

"string"

schema/link_description Link Description

The request-related HATEOAS link information.


href required	string The complete target URL. To make the related call, combine the method with this URI Template-formatted link. For pre-processing, include the `$`, `(`, and `)` characters. The `href` is the key HATEOAS component that links a completed call with a subsequent call.
rel required	string The link relation type, which serves as an ID for a link that unambiguously describes the semantics of the link. See Link Relations.
method	string The HTTP method required to make the related call. Enum:"GET""POST""PUT""DELETE""HEAD""CONNECT""OPTIONS""PATCH"

Copy

`{"href": "string",

"rel": "string",

"method": "GET"

schema/metadata Metadata

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


supplementary_data	Array of objects (Name and Value Pair) An array of name-and-value pairs that contain data required by PayPal for transaction processing.

Copy

Expand allCollapse all

`{"supplementary_data": [{"name": "string",

"value": "string"

}

]

schema/name_value_pair 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.

Copy

`{"name": "string",

"value": "string"

schema/order Order

An order.

The intent.

Enum Value	Description
SALE	A sale.
AUTHORIZE	An authorization.
purchase_units required	Array of objects (Purchase Unit) non-empty An array of purchase units. Each purchase unit establishes a contract between a customer and merchant.
payment_details	object (Payment Details) The payment details for the order.
application_context	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.
redirect_urls 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.
links	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.
gross_total_amount	object (Currency) The currency and amount of the PayPal-computed total of amounts in all purchase units.
metadata	object (Metadata) The name-and-value pairs that contain external data, such as user, user feedback, score, and so on.

Copy

Expand allCollapse all

`{"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": {"return_url": "http://example.com",

"cancel_url": "http://example.com"

"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"

}

]

}

schema/partner_fee_details Partner Fee Details

The partner fee that is collected for the original transaction.


receiver required	object (Payee) The partner who receives the partner fee.
amount required	object (Currency) The amount and currency of the partner fee.

Copy

Expand allCollapse all

`{"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"

}

schema/pay_order_response Pay Order Response

A pay order response.

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.
purchase_units	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.
links	Array of objects (Link Description) An array of request-related HATEOAS links.
payer_info	object (Payer Information) The payer information.

Copy

Expand allCollapse all

`{"order_id": "string",

"status": "APPROVED",

"intent": "SALE",

"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"

}

schema/payee 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.
payee_display_metadata	object (Payee Display Metadata) The display-only metadata for the payee.

Copy

Expand allCollapse all

`{"email": "user@example.com",

"merchant_id": "string",

"payee_display_metadata": {"email": "user@example.com",

"display_phone": {"country_code": "string",

"number": "string"

"brand_name": "string"

}

schema/payee_display_metadata Payee Display Metadata

The display-only metadata for the payee.


email	string<email> The email address for the payer. Maximum length is 127 characters.
display_phone	object (Display Phone) The payee's phone number.
brand_name	string The payer's business name.

Copy

Expand allCollapse all

`{"email": "user@example.com",

"display_phone": {"country_code": "string",

"number": "string"

"brand_name": "string"

schema/payer 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"
funding_instruments	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.
payer_info	object (Payer Information) The payer information.

Copy

Expand allCollapse all

`{"payment_method": "credit_card",

"status": "VERIFIED",

"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"

}

schema/payer_info 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	string The payer's two-character IS0-3166-1 country code.
billing_address	object (Address) The billing address or shipping address for a payment.
shipping_address	object (Shipping Address) The shipping address details.

Copy

Expand allCollapse all

`{"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"

}

schema/payment_details Payment Details

The payment details for the order.

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.

Copy

`{"payment_id": "string",

"disbursement_mode": "INSTANT"

schema/payment_summary Payment Summary

The payment summary.


captures	Array of objects (Capture) non-empty An array of captures for a purchase unit. A purchase unit can have zero or more captures.
refunds	Array of objects (Refund) non-empty An array of refunds for a purchase unit. A purchase unit can have zero or more refunds.
sales	Array of objects (Sale) non-empty An array of sales for a purchase unit. A purchase unit can have zero or more sales.
authorizations	Array of objects (Sale) non-empty An array of authorizations for a purchase unit. A purchase unit can have zero or more authorizations.

Copy

Expand allCollapse all

`{"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"

}

}

]

schema/percentage 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]+))$

Copy

"string"

schema/purchase_unit 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. | | items | 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. | | shipping_address | object (Shipping Address)
The shipping address details. | | shipping_method | string
The shipping method. For example, USPSParcel. | | partner_fee_details | 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. | | metadata | object (Metadata)
The name-and-value pairs that contain external data, such as user, user feedback, score, and so on. | | payment_summary | 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.
amount required	object (Amount) The amount to collect.
payee	object (Payee) The recipient of the funds for this transaction.

Copy

Expand allCollapse all

`{"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"

}

}

],

"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"

}

schema/refund Refund

A refund transaction.

The status of the refund.

Enum Value	Description
PENDING	The refund is pending.
COMPLETED	The refund completed.
FAILED	The refund failed.
links	Array of objects (Link Description) An array of request-related HATEOAS links.
amount	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.

Copy

Expand allCollapse all

`{"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"

}

schema/sale Sale

A sale transaction.

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.
links	Array of objects (Link Description) An array of request-related HATEOAS links.
amount	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.
transaction_fee	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.

Copy

Expand allCollapse all

`{"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"

}

schema/shipping_address 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.

Copy

`{"line1": "string",

"line2": "string",

"city": "string",

"country_code": "st",

"postal_code": "string",

"state": "string",

"phone": "string",

"normalization_status": "UNKNOWN",

"type": "string",

"recipient_name": "string"

Orders(1) ​

operation/orders.create Create order ​

header Parameters ​

Request Body schema: application/jsonmultipart/relatedmultipart/form-datamultipart/mixedapplication/json required ​

operation/orders.get Show order details ​

path Parameters ​

operation/orders.cancel Cancel order ​

path Parameters ​

operation/orders.pay Pay for order ​

path Parameters ​

header Parameters ​

Request Body schema: application/jsonmultipart/relatedmultipart/form-datamultipart/mixedapplication/json required ​

tag/Errors Errors ​

section/ACCOUNT_CANNOT_BE_FETCHED ACCOUNT_CANNOT_BE_FETCHED ​

section/INTERNAL_SERVER_ERROR INTERNAL_SERVER_ERROR ​

section/INVALID_REQUEST INVALID_REQUEST ​

section/NOT_AUTHORIZED NOT_AUTHORIZED ​

section/PAYMENT_NOT_APPROVED_FOR_EXECUTION PAYMENT_NOT_APPROVED_FOR_EXECUTION ​

section/RESOURCE_NOT_FOUND RESOURCE_NOT_FOUND ​

section/UNAUTHORIZED UNAUTHORIZED ​

section/VALIDATION_ERROR VALIDATION_ERROR ​

tag/Definitions Definitions ​

schema/address Address ​

schema/amount Amount ​

schema/application_context Application Context ​

schema/capture Capture ​

schema/country_code country_code ​

schema/credit_card Credit Card ​

schema/credit_card_token Credit Card Token ​

schema/currency Currency ​

schema/currency_code currency_code ​

schema/error Error ​

schema/error_details Error Details ​

schema/pay_order_request Execute Order ​

schema/funding_instrument Funding Instrument ​

schema/installment_option Installment Option ​

schema/item Item ​

schema/language language ​

schema/link_description Link Description ​

schema/metadata Metadata ​

schema/name_value_pair Name and Value Pair ​

schema/order Order ​

schema/partner_fee_details Partner Fee Details ​

schema/pay_order_response Pay Order Response ​

schema/payee Payee ​

schema/payee_display_metadata Payee Display Metadata ​

schema/payer Payer ​

schema/payer_info Payer Information ​

schema/payment_details Payment Details ​

schema/payment_summary Payment Summary ​

schema/percentage Percentage ​

schema/purchase_unit Purchase Unit ​

schema/refund Refund ​

schema/sale Sale ​

schema/shipping_address Shipping Address ​

Orders(1)

operation/orders.create Create order

header Parameters

Request Body schema: application/jsonmultipart/relatedmultipart/form-datamultipart/mixedapplication/json required

operation/orders.get Show order details

path Parameters

operation/orders.cancel Cancel order

path Parameters

operation/orders.pay Pay for order

path Parameters

header Parameters

Request Body schema: application/jsonmultipart/relatedmultipart/form-datamultipart/mixedapplication/json required

tag/Errors Errors

section/ACCOUNT_CANNOT_BE_FETCHED ACCOUNT_CANNOT_BE_FETCHED

section/INTERNAL_SERVER_ERROR INTERNAL_SERVER_ERROR

section/INVALID_REQUEST INVALID_REQUEST

section/NOT_AUTHORIZED NOT_AUTHORIZED

section/PAYMENT_NOT_APPROVED_FOR_EXECUTION PAYMENT_NOT_APPROVED_FOR_EXECUTION

section/RESOURCE_NOT_FOUND RESOURCE_NOT_FOUND

section/UNAUTHORIZED UNAUTHORIZED

section/VALIDATION_ERROR VALIDATION_ERROR

tag/Definitions Definitions

schema/address Address

schema/amount Amount

schema/application_context Application Context

schema/capture Capture

schema/country_code country_code

schema/credit_card Credit Card

schema/credit_card_token Credit Card Token

schema/currency Currency

schema/currency_code currency_code

schema/error Error

schema/error_details Error Details

schema/pay_order_request Execute Order

schema/funding_instrument Funding Instrument

schema/installment_option Installment Option

schema/item Item

schema/language language

schema/link_description Link Description

schema/metadata Metadata

schema/name_value_pair Name and Value Pair

schema/order Order

schema/partner_fee_details Partner Fee Details

schema/pay_order_response Pay Order Response

schema/payee Payee

schema/payee_display_metadata Payee Display Metadata

schema/payer Payer

schema/payer_info Payer Information

schema/payment_details Payment Details

schema/payment_summary Payment Summary

schema/percentage Percentage

schema/purchase_unit Purchase Unit

schema/refund Refund

schema/sale Sale

schema/shipping_address Shipping Address