Deprecation notice: TheUse the Payments REST API to easily and securely accept online and mobile payments. The payments name space contains resource collections for payments, sales, refunds, authorizations, captures, and orders./v1/paymentsendpoint is deprecated. Use the/v2/paymentsendpoint instead. For details, see PayPal Checkout Basic Integration.
Important: The use of the PayPal REST /payments APIs to accept credit card payments is restricted. Instead, you can accept credit card payments with Braintree Direct.You can enable customers to make PayPal and credit card payments with only a few clicks, depending on the country. You can accept an immediate payment or authorize a payment and capture it later. You can show details for completed payments, refunds, and authorizations. You can make full or partial refunds. You also can void or re-authorize authorizations. For more information, see the Payments overview.",
"version": "1.12",
"contact": {}
},
"servers": [
{
"url": "https://api-m.sandbox.paypal.com",
"description": "PayPal API Sandbox"
}
],
"tags": [
{
"name": "payment",
"description": "Deprecation notice: TheUse the/v1/paymentsendpoint is deprecated. Use the/v2/paymentsendpoint instead. For details, see PayPal Checkout Basic Integration.
/payment resource to create a sale, an authorized payment, or an order. A sale is a direct credit card payment, stored credit card payment, or PayPal payment. An authorized payment places funds on hold to be captured later. An order is a purchase that a customer has approved but for which the funds are not placed on hold. You can also use this resource to execute approved PayPal payments and show details for, update, and list payments. For more information, see also ."
},
{
"name": "sale",
"description": "Deprecation notice: TheA sale is a completed payment. Use the/v1/paymentsendpoint is deprecated. Use the/v2/paymentsendpoint instead. For details, see PayPal Checkout Basic Integration.
/sale resource to show sale details and refund a sale. For more information, see also Refund payments."
},
{
"name": "authorization",
"description": "Deprecation notice: TheUse the/v1/paymentsendpoint is deprecated. Use the/v2/paymentsendpoint instead. For details, see PayPal Checkout Basic Integration.
/authorization resource and related sub-resources to show details for, capture, void, and reauthorize an authorization."
},
{
"name": "orders",
"description": "Deprecation notice: TheUse the/v1/paymentsendpoint is deprecated. Use the/v2/paymentsendpoint instead. For details, see PayPal Checkout Basic Integration.
/orders resource to authorize, capture, void, and show details for an order.Note: You cannot refund an order directly. Instead, you must refund a completed payment for an order. For integration information, see Orders and refund payment.For more information, see also Orders." }, { "name": "capture", "description": "
Deprecation notice: TheUse the/v1/paymentsendpoint is deprecated. Use the/v2/paymentsendpoint instead. For details, see PayPal Checkout Basic Integration.
/capture resource and sub-resources to show details for and refund captured payments."
},
{
"name": "refund",
"description": "Deprecation notice: TheUse the/v1/paymentsendpoint is deprecated. Use the/v2/paymentsendpoint instead. For details, see PayPal Checkout Basic Integration.
/refund resource to show details for a refund on direct and captured payments."
},
{
"name": "receipt",
"description": "Deprecation notice: TheUse the/v1/paymentsendpoint is deprecated. Use the/v2/paymentsendpoint instead. For details, see PayPal Checkout Basic Integration.
/receipt resource to show details for a payment receipt."
}
],
"externalDocs": {
"url": "https://developer.paypal.com/docs/api/payments/v1/"
},
"paths": {
"/v1/payments/payment": {
"post": {
"summary": "Create payment",
"description": "Deprecation notice: TheCreates a sale, an authorized payment to be captured later, or an order. To create a sale, authorization, or order, include the payment details in the JSON request body. Set the/v1/paymentsendpoint is deprecated. Use the/v2/paymentsendpoint instead. For details, see PayPal Checkout Basic Integration.
intent to sale, authorize, or order. Note: TPP Clients (Third Party Providers in the context of PSD2 regulation) are restricted from usingInclude payer, transaction details, and, for PayPal payments only, redirect URLs. The combination of theauthorizeandorderintents.
payment_method and funding_instrument determines the type of payment that is created. For more information, see Payments REST API.",
"operationId": "payment.create",
"responses": {
"201": {
"description": "A successful request returns the HTTP `201 Created` status code and a JSON response body that shows payment details.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/payment"
}
}
}
},
"default": {
"description": "The error details.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error"
}
}
}
}
},
"parameters": [
{
"$ref": "#/components/parameters/paypal_partner_attribution_id"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/payment"
},
"examples": {
"payment": {
"value": {
"intent": "sale",
"payer": {
"payment_method": "paypal"
},
"transactions": [
{
"amount": {
"total": "30.11",
"currency": "USD",
"details": {
"subtotal": "30.00",
"tax": "0.07",
"shipping": "0.03",
"handling_fee": "1.00",
"shipping_discount": "-1.00",
"insurance": "0.01"
}
},
"description": "The payment transaction description.",
"custom": "EBAY_EMS_90048630024435",
"invoice_number": "48787589673",
"payment_options": {
"allowed_payment_method": "INSTANT_FUNDING_SOURCE"
},
"soft_descriptor": "ECHI5786786",
"item_list": {
"items": [
{
"name": "hat",
"description": "Brown hat.",
"quantity": "5",
"price": "3",
"tax": "0.01",
"sku": "1",
"currency": "USD"
},
{
"name": "handbag",
"description": "Black handbag.",
"quantity": "1",
"price": "15",
"tax": "0.02",
"sku": "product34",
"currency": "USD"
}
],
"shipping_address": {
"recipient_name": "Brian Robinson",
"line1": "4th Floor",
"line2": "Unit #34",
"city": "San Jose",
"country_code": "US",
"postal_code": "95131",
"phone": "011862212345678",
"state": "CA"
}
}
}
],
"note_to_payer": "Contact us for any questions on your order.",
"redirect_urls": {
"return_url": "https://example.com/return",
"cancel_url": "https://example.com/cancel"
}
}
}
}
}
}
},
"security": [
{
"Oauth2": [
"https://api.paypal.com/v1/payments/.*"
]
},
{
"Oauth2": [
"https://uri.paypal.com/services/payments/payment"
]
},
{
"Oauth2": [
"https://uri.paypal.com/services/payments/realtimepayment"
]
},
{
"Oauth2": [
"https://uri.paypal.com/services/payments/paymentcard"
]
},
{
"Oauth2": [
"https://uri.paypal.com/services/payments/channelpartner"
]
}
],
"tags": [
"payment"
]
},
"get": {
"summary": "List payments",
"description": "Deprecation notice: TheLists payments that are completed. Payments that you just created with the create payment call do not appear in the list./v1/paymentsendpoint is deprecated. Use the/v2/paymentsendpoint instead. For details, see PayPal Checkout Basic Integration.
Deprecation notice: TheShows details for a payment, by ID, that has yet to complete. For example, shows details for a payment that was created, approved, or failed.", "operationId": "payment.get", "responses": { "200": { "description": "A successful request returns the HTTP `200 OK` status code and a JSON response body that shows payment details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/payment" } } } }, "default": { "description": "The error details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/payment_id" } ], "security": [ { "Oauth2": [ "https://api.paypal.com/v1/payments/.*" ] }, { "Oauth2": [ "https://uri.paypal.com/services/payments/payment" ] }, { "Oauth2": [ "https://uri.paypal.com/services/payments/realtimepayment" ] }, { "Oauth2": [ "https://uri.paypal.com/services/payments/payment/authcapture" ] } ], "tags": [ "payment" ] }, "patch": { "summary": "Partially update payment", "description": "/v1/paymentsendpoint is deprecated. Use the/v2/paymentsendpoint instead. For details, see PayPal Checkout Basic Integration.
Deprecation notice: ThePartially updates a payment, by ID. You can update the amount, shipping address, invoice ID, and custom data. You cannot update a payment after the payment executes./v1/paymentsendpoint is deprecated. Use the/v2/paymentsendpoint instead. For details, see PayPal Checkout Basic Integration.
Note: TPP Clients (Third Party Providers in the context of PSD2 regulation) are restricted from patching amount once authorized.", "operationId": "payment.update", "responses": { "200": { "description": "A successful request returns the HTTP `200 OK` status code and a JSON response body that shows payment details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/payment" } } } }, "default": { "description": "The error details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/payment_id" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/patch_request" }, "examples": { "patch_request": { "value": [ { "op": "replace", "path": "/transactions/0/amount", "value": { "total": "18.37", "currency": "EUR", "details": { "subtotal": "13.37", "shipping": "5.00" } } }, { "op": "add", "path": "/transactions/0/item_list/shipping_address", "value": { "recipient_name": "Anna Gruneberg", "line1": "Kathwarinenhof 1", "city": "Flensburg", "postal_code": "24939", "country_code": "DE" } } ] } } } } }, "security": [ { "Oauth2": [ "https://api.paypal.com/v1/payments/.*" ] }, { "Oauth2": [ "https://uri.paypal.com/services/payments/payment" ] }, { "Oauth2": [ "https://uri.paypal.com/services/payments/realtimepayment" ] }, { "Oauth2": [ "https://uri.paypal.com/services/payments/channelpartner" ] } ], "tags": [ "payment" ] } }, "/v1/payments/payment/{payment_id}/execute": { "post": { "summary": "Execute approved PayPal payment", "description": "
Deprecation notice: TheExecutes a PayPal payment that the customer has approved. You can optionally update one or more transactions when you execute the payment./v1/paymentsendpoint is deprecated. Use the/v2/paymentsendpoint instead. For details, see PayPal Checkout Basic Integration.
Important: This call works only after a customer has approved the payment. For more information, learn about PayPal payments.", "operationId": "payment.execute", "responses": { "200": { "description": "A successful request returns the HTTP `200 OK` status code and a JSON response body that shows details for the executed payment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/payment" } } } }, "default": { "description": "The error details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/paypal_request_id" }, { "$ref": "#/components/parameters/paypal_partner_attribution_id" }, { "$ref": "#/components/parameters/payment_id" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/payment_execution" }, "examples": { "payment_execution": { "value": { "payer_id": "CR87QHB7JTRSC" } } } } } }, "security": [ { "Oauth2": [ "https://api.paypal.com/v1/payments/.*" ] }, { "Oauth2": [ "https://uri.paypal.com/services/payments/payment" ] }, { "Oauth2": [ "https://uri.paypal.com/services/payments/realtimepayment" ] } ], "tags": [ "payment" ] } }, "/v1/payments/sale/{sale_id}": { "get": { "summary": "Show sale details", "description": "
Deprecation notice: TheShows details for a sale, by ID. Returns only sales that were created through the REST API.", "operationId": "sale.get", "responses": { "200": { "description": "A successful request returns the HTTP `200 OK` status code and a JSON response body that shows sale details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/sale" } } } }, "default": { "description": "The error details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/sale_id" } ], "security": [ { "Oauth2": [ "https://api.paypal.com/v1/payments/.*" ] }, { "Oauth2": [ "https://uri.paypal.com/services/payments/payment" ] }, { "Oauth2": [ "https://uri.paypal.com/services/payments/realtimepayment" ] }, { "Oauth2": [ "https://uri.paypal.com/services/payments/payment/authcapture" ] } ], "tags": [ "sale" ] } }, "/v1/payments/sale/{sale_id}/refund": { "post": { "summary": "Refund sale", "description": "/v1/paymentsendpoint is deprecated. Use the/v2/paymentsendpoint instead. For details, see PayPal Checkout Basic Integration.
Deprecation notice: TheRefunds a sale, by ID. For a full refund, do not include the/v1/paymentsendpoint is deprecated. Use the/v2/paymentsendpoint instead. For details, see PayPal Checkout Basic Integration.
amount object in the JSON request body. For a partial refund, include an amount object in the JSON request body.",
"operationId": "sale.refund",
"responses": {
"200": {
"description": "A successful idempotent request returns the HTTP `200 Created` status code and a JSON response body that shows details for the refunded sale.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/detailed_refund"
}
}
}
},
"201": {
"description": "A successful request returns the HTTP `201 Created` status code and a JSON response body that shows details for the refunded sale.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/detailed_refund"
}
}
}
},
"409": {
"description": "The request failed because a previous call for the given resource is in progress.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error"
}
}
}
},
"default": {
"description": "The error details.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error"
}
}
}
}
},
"parameters": [
{
"$ref": "#/components/parameters/paypal_request_id"
},
{
"$ref": "#/components/parameters/sale_id"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/refund_request"
},
"examples": {
"refund_request": {
"value": {
"amount": {
"total": "100.00",
"currency": "USD"
},
"invoice_number": "INV-7654321"
}
}
}
}
}
},
"security": [
{
"Oauth2": [
"https://api.paypal.com/v1/payments/.*"
]
},
{
"Oauth2": [
"https://uri.paypal.com/services/payments/payment"
]
},
{
"Oauth2": [
"https://uri.paypal.com/services/payments/refund"
]
},
{
"Oauth2": [
"https://uri.paypal.com/services/payments/unilateralrefund"
]
}
],
"tags": [
"sale"
]
}
},
"/v1/payments/authorization/{authorization_id}": {
"get": {
"summary": "Show authorization details",
"description": "Deprecation notice: TheShows details for an authorization, by ID.", "operationId": "authorization.get", "responses": { "200": { "description": "A successful request returns the HTTP `200 OK` status code and a JSON response body that shows authorization details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/authorization" } } } }, "default": { "description": "The error details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/authorization_id" } ], "security": [ { "Oauth2": [ "https://api.paypal.com/v1/payments/.*" ] }, { "Oauth2": [ "https://uri.paypal.com/services/payments/payment" ] }, { "Oauth2": [ "https://uri.paypal.com/services/payments/realtimepayment" ] }, { "Oauth2": [ "https://uri.paypal.com/services/payments/payment/authcapture" ] } ], "tags": [ "authorization" ] } }, "/v1/payments/authorization/{authorization_id}/capture": { "post": { "summary": "Capture authorization", "description": "/v1/paymentsendpoint is deprecated. Use the/v2/paymentsendpoint instead. For details, see PayPal Checkout Basic Integration.
Deprecation notice: TheCaptures and processes an authorization, by ID. The original payment call must specify an intent of/v1/paymentsendpoint is deprecated. Use the/v2/paymentsendpoint instead. For details, see PayPal Checkout Basic Integration.
authorize.",
"operationId": "authorization.capture",
"responses": {
"201": {
"description": "A successful request returns the HTTP `201 Created` status code and a JSON response body that shows details for the captured authorization.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/capture"
}
}
}
},
"default": {
"description": "The error details.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error"
}
}
}
}
},
"parameters": [
{
"$ref": "#/components/parameters/authorization_id"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/capture"
},
"examples": {
"capture": {
"value": {
"amount": {
"currency": "USD",
"total": "4.54"
},
"is_final_capture": true
}
}
}
}
}
},
"security": [
{
"Oauth2": [
"https://api.paypal.com/v1/payments/.*"
]
},
{
"Oauth2": [
"https://uri.paypal.com/services/payments/payment"
]
},
{
"Oauth2": [
"https://uri.paypal.com/services/payments/payment/authcapture"
]
}
],
"tags": [
"authorization"
]
}
},
"/v1/payments/authorization/{authorization_id}/void": {
"post": {
"summary": "Void authorization",
"description": "Deprecation notice: TheVoids, or cancels, an authorization, by ID. You cannot void a fully captured authorization.", "operationId": "authorization.void", "responses": { "200": { "description": "A successful request returns the HTTP `200 OK` status code and a JSON response body that shows details for the voided authorization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/authorization" } } } }, "409": { "description": "The request failed because a previous call for the given resource is in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } }, "default": { "description": "The error details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/paypal_request_id" }, { "$ref": "#/components/parameters/authorization_id" } ], "security": [ { "Oauth2": [ "https://api.paypal.com/v1/payments/.*" ] }, { "Oauth2": [ "https://uri.paypal.com/services/payments/payment" ] }, { "Oauth2": [ "https://uri.paypal.com/services/payments/payment/authcapture" ] } ], "tags": [ "authorization" ] } }, "/v1/payments/authorization/{authorization_id}/reauthorize": { "post": { "summary": "Re-authorize payment", "description": "/v1/paymentsendpoint is deprecated. Use the/v2/paymentsendpoint instead. For details, see PayPal Checkout Basic Integration.
Deprecation notice: TheRe-authorizes a PayPal account payment, by authorization ID. To ensure that funds are still available, re-authorize a payment after the initial three-day honor period. Supports only the/v1/paymentsendpoint is deprecated. Use the/v2/paymentsendpoint instead. For details, see PayPal Checkout Basic Integration.
amount request parameter. You can re-authorize a payment only once from four to 29 days after three-day honor period for the original authorization expires. If 30 days have passed from the original authorization, you must create a new authorization instead. A re-authorized payment itself has a new three-day honor period. You can re-authorize a transaction once for up to 115% of the originally authorized amount, not to exceed an increase of $75 USD.",
"operationId": "authorization.reauthorize",
"responses": {
"201": {
"description": "A successful request returns the HTTP `201 Created` status code and a JSON response body that shows details for the re-authorized authorization.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/authorization"
}
}
}
},
"default": {
"description": "The error details.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error"
}
}
}
}
},
"parameters": [
{
"$ref": "#/components/parameters/authorization_id"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/authorization"
}
}
}
},
"security": [
{
"Oauth2": [
"https://api.paypal.com/v1/payments/.*"
]
},
{
"Oauth2": [
"https://uri.paypal.com/services/payments/payment"
]
},
{
"Oauth2": [
"https://uri.paypal.com/services/payments/payment/authcapture"
]
}
],
"tags": [
"authorization"
]
}
},
"/v1/payments/orders/{order_id}": {
"get": {
"summary": "Show order details",
"description": "Deprecation notice: TheShows details for an order, by ID.", "operationId": "orders.get", "responses": { "200": { "description": "A successful request returns the HTTP `200 OK` status code and a JSON response body that shows details for the voided authorization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/order" } } } }, "default": { "description": "The error details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/order_id" } ], "security": [ { "Oauth2": [ "https://api.paypal.com/v1/payments/.*" ] }, { "Oauth2": [ "https://uri.paypal.com/services/payments/payment" ] }, { "Oauth2": [ "https://uri.paypal.com/services/payments/realtimepayment" ] }, { "Oauth2": [ "https://uri.paypal.com/services/payments/payment/authcapture" ] } ], "tags": [ "orders" ] } }, "/v1/payments/orders/{order_id}/capture": { "post": { "summary": "Capture order", "description": "/v1/paymentsendpoint is deprecated. Use the/v2/paymentsendpoint instead. For details, see PayPal Checkout Basic Integration.
Deprecation notice: TheCaptures a payment for an order, by ID. To use this call, the original payment call must specify an/v1/paymentsendpoint is deprecated. Use the/v2/paymentsendpoint instead. For details, see PayPal Checkout Basic Integration.
order intent. In the JSON request body, include the payment amount and indicate whether this capture is the final capture for the authorization.",
"operationId": "orders.capture",
"responses": {
"201": {
"description": "A successful request returns the HTTP `201 Created` status code and a JSON response body that shows details for the captured order.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/capture"
}
}
}
},
"default": {
"description": "The error details.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error"
}
}
}
}
},
"parameters": [
{
"$ref": "#/components/parameters/order_id"
}
],
"requestBody": {
"$ref": "#/components/requestBodies/capture"
},
"security": [
{
"Oauth2": [
"https://api.paypal.com/v1/payments/.*"
]
},
{
"Oauth2": [
"https://uri.paypal.com/services/payments/payment"
]
},
{
"Oauth2": [
"https://uri.paypal.com/services/payments/payment/authcapture"
]
}
],
"tags": [
"orders"
]
}
},
"/v1/payments/orders/{order_id}/do-void": {
"post": {
"summary": "Void order",
"description": "Deprecation notice: TheVoids, or cancels, an order, by ID. You can only void orders that are either in the/v1/paymentsendpoint is deprecated. Use the/v2/paymentsendpoint instead. For details, see PayPal Checkout Basic Integration.
PENDING or AUTHORIZED states or those in the CAPTURED state that are not fully captured.",
"operationId": "orders.void",
"responses": {
"200": {
"description": "A successful request returns the HTTP `200 OK` status code and a JSON response body that shows details for the voided order.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/order"
}
}
}
},
"default": {
"description": "The error details.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error"
}
}
}
}
},
"parameters": [
{
"$ref": "#/components/parameters/paypal_request_id"
},
{
"$ref": "#/components/parameters/order_id"
}
],
"security": [
{
"Oauth2": [
"https://api.paypal.com/v1/payments/.*"
]
},
{
"Oauth2": [
"https://uri.paypal.com/services/payments/payment"
]
},
{
"Oauth2": [
"https://uri.paypal.com/services/payments/payment/authcapture"
]
}
],
"tags": [
"orders"
]
}
},
"/v1/payments/orders/{order_id}/authorize": {
"post": {
"summary": "Authorize order",
"description": "Deprecation notice: TheAuthorizes an order, by ID. In the JSON request body, include an/v1/paymentsendpoint is deprecated. Use the/v2/paymentsendpoint instead. For details, see PayPal Checkout Basic Integration.
amount object.",
"operationId": "orders.authorize",
"responses": {
"201": {
"description": "A successful request returns the HTTP `201 Created` status code and a JSON response body that shows details for the authorized order.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/authorization"
}
}
}
},
"default": {
"description": "The error details.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error"
}
}
}
}
},
"parameters": [
{
"$ref": "#/components/parameters/order_id"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/order"
}
}
}
},
"security": [
{
"Oauth2": [
"https://api.paypal.com/v1/payments/.*"
]
},
{
"Oauth2": [
"https://uri.paypal.com/services/payments/payment"
]
},
{
"Oauth2": [
"https://uri.paypal.com/services/payments/payment/authcapture"
]
}
],
"tags": [
"orders"
]
}
},
"/v1/payments/capture/{capture_id}": {
"get": {
"summary": "Show captured payment details",
"description": "Deprecation notice: TheShows details for a captured payment, by ID.", "operationId": "capture.get", "responses": { "200": { "description": "A successful request returns the HTTP `200 OK` status code and a JSON response body that shows details for the captured payment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/capture" } } } }, "default": { "description": "The error details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/capture_id" } ], "security": [ { "Oauth2": [ "https://api.paypal.com/v1/payments/.*" ] }, { "Oauth2": [ "https://uri.paypal.com/services/payments/payment" ] }, { "Oauth2": [ "https://uri.paypal.com/services/payments/realtimepayment" ] }, { "Oauth2": [ "https://uri.paypal.com/services/payments/payment/authcapture" ] } ], "tags": [ "capture" ] } }, "/v1/payments/capture/{capture_id}/refund": { "post": { "summary": "Refund captured payment", "description": "/v1/paymentsendpoint is deprecated. Use the/v2/paymentsendpoint instead. For details, see PayPal Checkout Basic Integration.
Deprecation notice: TheRefunds a captured payment, by ID. In the JSON request body, include an/v1/paymentsendpoint is deprecated. Use the/v2/paymentsendpoint instead. For details, see PayPal Checkout Basic Integration.
amount object.",
"operationId": "capture.refund",
"responses": {
"200": {
"description": "A successful idempotent request returns the HTTP `200 OK` status code and a JSON response body that shows details for the captured payment.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/detailed_refund"
}
}
}
},
"201": {
"description": "A successful request returns the HTTP `201 OK` status code and a JSON response body that shows details for the captured payment.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/detailed_refund"
}
}
}
},
"409": {
"description": "The request failed because a previous call for the given resource is in progress.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error"
}
}
}
},
"default": {
"description": "The error details.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error"
}
}
}
}
},
"parameters": [
{
"$ref": "#/components/parameters/paypal_request_id"
},
{
"$ref": "#/components/parameters/capture_id"
}
],
"requestBody": {
"$ref": "#/components/requestBodies/refund_request"
},
"security": [
{
"Oauth2": [
"https://api.paypal.com/v1/payments/.*"
]
},
{
"Oauth2": [
"https://uri.paypal.com/services/payments/payment"
]
},
{
"Oauth2": [
"https://uri.paypal.com/services/payments/refund"
]
},
{
"Oauth2": [
"https://uri.paypal.com/services/payments/unilateralrefund"
]
}
],
"tags": [
"capture"
]
}
},
"/v1/payments/refund/{refund_id}": {
"get": {
"summary": "Show refund details",
"description": "Deprecation notice: TheShows details for a refund, by ID.", "operationId": "refund.get", "responses": { "200": { "description": "A successful request returns the HTTP `200 OK` status code and a JSON response body that shows refund details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/refund" } } } }, "default": { "description": "The error details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/refund_id" } ], "security": [ { "Oauth2": [ "https://api.paypal.com/v1/payments/.*" ] }, { "Oauth2": [ "https://uri.paypal.com/services/payments/payment" ] }, { "Oauth2": [ "https://uri.paypal.com/services/payments/refund" ] } ], "tags": [ "refund" ] } } }, "components": { "requestBodies": { "capture": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/capture" } } } }, "refund_request": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/refund_request" } } } } }, "securitySchemes": { "Oauth2": { "type": "oauth2", "description": "Oauth 2.0 authentication", "flows": { "clientCredentials": { "tokenUrl": "/api/oauth-proxy", "scopes": { "https://api.paypal.com/v1/payments/.*": "Deprecated. Legacy payment scope. It will be replaced with new scopes", "https://uri.paypal.com/services/payments/payment": "New special privileged scope available to do payment. This will be available to internal clients only", "https://uri.paypal.com/services/payments/realtimepayment": "Permission to do any real time payment, with support for sale/authorize/order intents", "https://uri.paypal.com/services/payments/payment/authcapture": "Permission to do non-real time payments like authorization on order or capture on authorization or an order ", "https://uri.paypal.com/services/payments/refund": "Permission to initiate a refund/reversal on a sale or capture transaction", "https://uri.paypal.com/services/payments/paymentcard": "Permission to do unbranded credit or debit card payments", "https://uri.paypal.com/services/payments/futurepayments": "Permission for future or pre-approved payment.", "https://uri.paypal.com/services/payments/channelpartner": "Permission to explicitly specify the receiver of a payment on request payload.", "https://uri.paypal.com/services/payments/unilateralrefund": "This scope enables partners/facilitators to perform unilateralrefund and also refund.", "https://uri.paypal.com/services/checkout/onetimepayment": "This scope enable buyer's checkout flow to load payment information." } } } } }, "schemas": { "error_details": { "title": "Error Details", "type": "object", "description": "The error details. Required for client-side `4XX` errors.", "properties": { "field": { "type": "string", "description": "The field that caused the error. If this field is in the body, set this value to the field's JSON pointer value. Required for client-side errors." }, "value": { "type": "string", "description": "The value of the field that caused the error." }, "location": { "$ref": "#/components/schemas/error_location" }, "issue": { "type": "string", "description": "The unique, fine-grained application-level error code." }, "description": { "type": "string", "description": "The human-readable description for an issue. The description can change over the lifetime of an API, so clients must not depend on this value." } }, "required": [ "issue" ] }, "error_location": { "type": "string", "description": "The location of the field that caused the error. Value is `body`, `path`, or `query`.", "enum": [ "body", "path", "query" ], "default": "body" }, "error_link_description": { "title": "Link Description", "description": "The request-related [HATEOAS link](/api/rest/responses/#hateoas-links) information.", "type": "object", "required": [ "href", "rel" ], "properties": { "href": { "description": "The complete target URL. To make the related call, combine the method with this [URI Template-formatted](https://tools.ietf.org/html/rfc6570) link. For pre-processing, include the `$`, `(`, and `)` characters. The `href` is the key HATEOAS component that links a completed call with a subsequent call.", "type": "string", "minLength": 0, "maxLength": 20000, "pattern": "^.*$" }, "rel": { "description": "The [link relation type](https://tools.ietf.org/html/rfc5988#section-4), which serves as an ID for a link that unambiguously describes the semantics of the link. See [Link Relations](https://www.iana.org/assignments/link-relations/link-relations.xhtml).", "type": "string", "minLength": 0, "maxLength": 100, "pattern": "^.*$" }, "method": { "description": "The HTTP method required to make the related call.", "type": "string", "minLength": 3, "maxLength": 6, "pattern": "^[A-Z]*$", "enum": [ "GET", "POST", "PUT", "DELETE", "PATCH" ] } } }, "error_400": { "type": "object", "title": "Bad Request Error", "description": "Request is not well-formed, syntactically incorrect, or violates schema.", "properties": { "name": { "type": "string", "enum": [ "INVALID_REQUEST" ] }, "message": { "type": "string", "enum": [ "Request is not well-formed, syntactically incorrect, or violates schema." ] }, "details": { "type": "array", "items": { "$ref": "#/components/schemas/error_details" } }, "debug_id": { "type": "string", "description": "The PayPal internal ID. Used for correlation purposes." }, "links": { "description": "An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).", "type": "array", "minItems": 0, "maxItems": 10000, "items": { "$ref": "#/components/schemas/error_link_description" } } } }, "error_401": { "type": "object", "title": "Unauthorized Error", "description": "Authentication failed due to missing Authorization header, or invalid authentication credentials.", "properties": { "name": { "type": "string", "enum": [ "AUTHENTICATION_FAILURE" ] }, "message": { "type": "string", "enum": [ "Authentication failed due to missing authorization header, or invalid authentication credentials." ] }, "details": { "type": "array", "items": { "$ref": "#/components/schemas/error_details" } }, "debug_id": { "type": "string", "description": "The PayPal internal ID. Used for correlation purposes." }, "links": { "description": "An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).", "type": "array", "minItems": 0, "maxItems": 10000, "items": { "$ref": "#/components/schemas/error_link_description" } } } }, "error_403": { "type": "object", "title": "Not Authorized Error", "description": "The client is not authorized to access this resource, although it may have valid credentials. ", "properties": { "name": { "type": "string", "enum": [ "NOT_AUTHORIZED" ] }, "message": { "type": "string", "enum": [ "Authorization failed due to insufficient permissions." ] }, "details": { "type": "array", "items": { "$ref": "#/components/schemas/error_details" } }, "debug_id": { "type": "string", "description": "The PayPal internal ID. Used for correlation purposes." }, "links": { "description": "An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).", "type": "array", "minItems": 0, "maxItems": 10000, "items": { "$ref": "#/components/schemas/error_link_description" } } } }, "error_404": { "type": "object", "title": "Not found Error", "description": "The server has not found anything matching the request URI. This either means that the URI is incorrect or the resource is not available.", "properties": { "name": { "type": "string", "enum": [ "RESOURCE_NOT_FOUND" ] }, "message": { "type": "string", "enum": [ "The specified resource does not exist." ] }, "details": { "type": "array", "items": { "$ref": "#/components/schemas/error_details" } }, "debug_id": { "type": "string", "description": "The PayPal internal ID. Used for correlation purposes." }, "links": { "description": "An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).", "type": "array", "minItems": 0, "maxItems": 10000, "items": { "$ref": "#/components/schemas/error_link_description" } } } }, "error_409": { "type": "object", "title": "Resource Conflict Error", "description": "The server has detected a conflict while processing this request.", "properties": { "name": { "type": "string", "enum": [ "RESOURCE_CONFLICT" ] }, "message": { "type": "string", "enum": [ "The server has detected a conflict while processing this request." ] }, "details": { "type": "array", "items": { "$ref": "#/components/schemas/error_details" } }, "debug_id": { "type": "string", "description": "The PayPal internal ID. Used for correlation purposes." }, "links": { "description": "An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).", "type": "array", "minItems": 0, "maxItems": 10000, "items": { "$ref": "#/components/schemas/error_link_description" } } } }, "error_415": { "type": "object", "title": "Unsupported Media Type Error", "description": "The server does not support the request payload's media type.", "properties": { "name": { "type": "string", "enum": [ "UNSUPPORTED_MEDIA_TYPE" ] }, "message": { "type": "string", "enum": [ "The server does not support the request payload's media type." ] }, "details": { "type": "array", "items": { "$ref": "#/components/schemas/error_details" } }, "debug_id": { "type": "string", "description": "The PayPal internal ID. Used for correlation purposes." }, "links": { "description": "An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).", "type": "array", "minItems": 0, "maxItems": 10000, "items": { "$ref": "#/components/schemas/error_link_description" } } } }, "error_422": { "type": "object", "title": "Unprocessable Entity Error", "description": "The requested action cannot be performed and may require interaction with APIs or processes outside of the current request. This is distinct from a 500 response in that there are no systemic problems limiting the API from performing the request.", "properties": { "name": { "type": "string", "enum": [ "UNPROCESSABLE_ENTITY" ] }, "message": { "type": "string", "enum": [ "The requested action could not be performed, semantically incorrect, or failed business validation." ] }, "details": { "type": "array", "items": { "$ref": "#/components/schemas/error_details" } }, "debug_id": { "type": "string", "description": "The PayPal internal ID. Used for correlation purposes." }, "links": { "description": "An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).", "type": "array", "minItems": 0, "maxItems": 10000, "items": { "$ref": "#/components/schemas/error_link_description" } } } }, "error_500": { "type": "object", "title": "Internal Server Error", "description": "This is either a system or application error, and generally indicates that although the client appeared to provide a correct request, something unexpected has gone wrong on the server.", "properties": { "name": { "type": "string", "enum": [ "INTERNAL_SERVER_ERROR" ] }, "message": { "type": "string", "enum": [ "An internal server error occurred." ] }, "debug_id": { "type": "string", "description": "The PayPal internal ID. Used for correlation purposes." }, "links": { "description": "An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).", "type": "array", "minItems": 0, "maxItems": 10000, "items": { "$ref": "#/components/schemas/error_link_description" } } }, "examples": [ { "name": "INTERNAL_SERVER_ERROR", "message": "An internal server error occurred.", "debug_id": "90957fca61718", "links": [ { "href": "https://developer.paypal.com/api/orders/v2/#error-INTERNAL_SERVER_ERROR", "rel": "information_link" } ] } ] }, "error_503": { "type": "object", "title": "Service Unavailable Error", "description": "The server is temporarily unable to handle the request, for example, because of planned maintenance or downtime.", "properties": { "name": { "type": "string", "enum": [ "SERVICE_UNAVAILABLE" ] }, "message": { "type": "string", "enum": [ "Service Unavailable." ] }, "debug_id": { "type": "string", "description": "The PayPal internal ID. Used for correlation purposes." }, "links": { "description": "An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).", "type": "array", "minItems": 0, "maxItems": 10000, "items": { "$ref": "#/components/schemas/error_link_description" } } }, "examples": [ { "name": "SERVICE_UNAVAILABLE", "message": "Service Unavailable.", "debug_id": "90957fca61718", "information_link": "https://developer.paypal.com/docs/api/orders/v2/#error-SERVICE_UNAVAILABLE" } ] }, "error_details-2": { "title": "Error Details", "type": "object", "description": "The error details. Required for client-side `4XX` errors.", "properties": { "field": { "type": "string", "description": "The field that caused the error. If this field is in the body, set this value to the field's JSON pointer value. Required for client-side errors." }, "value": { "type": "string", "description": "The value of the field that caused the error." }, "location": { "type": "string", "description": "The location of the field that caused the error. Value is `body`, `path`, or `query`.", "default": "body" }, "issue": { "type": "string", "description": "The unique, fine-grained application-level error code." }, "description": { "type": "string", "description": "The human-readable description for an issue. The description can change over the lifetime of an API, so clients must not depend on this value." } }, "required": [ "issue" ] }, "link_description": { "type": "object", "title": "Link Description", "description": "The request-related [HATEOAS link](/docs/api/reference/api-responses/#hateoas-links) information.", "required": [ "href", "rel" ], "properties": { "href": { "type": "string", "description": "The complete target URL. To make the related call, combine the method with this [URI Template-formatted](https://tools.ietf.org/html/rfc6570) 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": { "type": "string", "description": "The [link relation type](https://tools.ietf.org/html/rfc5988#section-4), which serves as an ID for a link that unambiguously describes the semantics of the link. See [Link Relations](https://www.iana.org/assignments/link-relations/link-relations.xhtml)." }, "method": { "type": "string", "description": "The HTTP method required to make the related call.", "enum": [ "GET", "POST", "PUT", "DELETE", "HEAD", "CONNECT", "OPTIONS", "PATCH" ] } } }, "error": { "type": "object", "title": "Error", "description": "The error details.", "properties": { "name": { "type": "string", "description": "The human-readable, unique name of the error." }, "message": { "type": "string", "description": "The message that describes the error." }, "debug_id": { "type": "string", "description": "The PayPal internal ID. Used for correlation purposes." }, "information_link": { "type": "string", "description": "The information link, or URI, that shows detailed information about this error for the developer.", "readOnly": true }, "details": { "type": "array", "description": "An array of additional details about the error.", "items": { "$ref": "#/components/schemas/error_details-2" } }, "links": { "type": "array", "description": "An array of request-related [HATEOAS links](/docs/api/reference/api-responses/#hateoas-links).", "readOnly": true, "items": { "$ref": "#/components/schemas/link_description", "readOnly": true } } }, "required": [ "name", "message", "debug_id" ] }, "credit_card_token": { "type": "object", "title": "Credit Card Token", "description": "The tokenized credit card details. You can use this instrument to fund a payment.", "properties": { "credit_card_id": { "type": "string", "description": "The ID of credit card that is stored in the PayPal vault.", "minLength": 1, "maxLength": 256 }, "payer_id": { "type": "string", "description": "Deprecated. 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. Use external_customer_id instead.", "minLength": 1, "maxLength": 256 }, "external_customer_id": { "type": "string", "description": "The externally-provided ID of the customer.", "minLength": 1, "maxLength": 256 }, "last4": { "type": "string", "readOnly": true, "description": "The last four digits of the stored credit card number.", "minLength": 4, "maxLength": 4 }, "type": { "type": "string", "readOnly": true, "description": "The credit card type. Value is `visa`, `mastercard`, `discover`, or `amex`. Do not use these lowercase values for display.", "minLength": 1, "maxLength": 256 }, "expire_month": { "type": "integer", "readOnly": true, "description": "The expiration month with no leading zero. Value is from `1` to `12`.", "minimum": 1, "maximum": 12 }, "expire_year": { "type": "string", "readOnly": true, "description": "The four-digit expiration year.", "pattern": "^[0-9]{4}$", "minLength": 4, "maxLength": 4 } }, "required": [ "credit_card_id" ] }, "funding_instrument": { "type": "object", "title": "Funding Instrument", "description": "The funding instrument details. An instance of this schema is valid if and only if it validates against exactly one of these supported properties.", "properties": { "credit_card_token": { "description": "The tokenized credit card details. You can use this instrument to fund a payment.", "$ref": "#/components/schemas/credit_card_token" } } }, "country_code": { "type": "string", "description": "The [two-character ISO 3166-1 code](/docs/api/reference/country-codes/) that identifies the country or region./v1/paymentsendpoint is deprecated. Use the/v2/paymentsendpoint instead. For details, see PayPal Checkout Basic Integration.
Note: The country code for Great Britain is", "format": "ppaas_common_country_code_v2", "maxLength": 2, "minLength": 2, "pattern": "^([A-Z]{2}|C2)$" }, "address": { "type": "object", "title": "Address", "description": "The billing address or shipping address for a payment.", "properties": { "line1": { "type": "string", "description": "The first line of the address. For example, number, street, and so on.", "maxLength": 300 }, "line2": { "type": "string", "description": "The second line of the address. For example, suite or apartment number.", "maxLength": 300 }, "city": { "type": "string", "description": "The city name.", "maxLength": 64 }, "country_code": { "$ref": "#/components/schemas/country_code" }, "postal_code": { "type": "string", "description": "The postal code, which is the zip code or equivalent. Typically required for countries with a postal code or an equivalent. See [postal code](https://en.wikipedia.org/wiki/Postal_code)." }, "state": { "type": "string", "description": "The [code](/docs/integration/direct/rest/state-codes/) for a US state or the equivalent for other countries. Required for transactions if the address is in one of these countries: [Argentina](/docs/integration/direct/rest/state-codes/#argentina), [Brazil](/docs/integration/direct/rest/state-codes/#brazil), [Canada](/docs/integration/direct/rest/state-codes/#canada), [China](/docs/integration/direct/rest/state-codes/#china), [India](/docs/integration/direct/rest/state-codes/#india), [Italy](/docs/integration/direct/rest/state-codes/#italy), [Japan](/docs/integration/direct/rest/state-codes/#japan), [Mexico](/docs/integration/direct/rest/state-codes/#mexico), [Thailand](/docs/integration/direct/rest/state-codes/#thailand), or [United States](/docs/integration/direct/rest/state-codes/#usa).", "maxLength": 300 }, "phone": { "type": "string", "format": "phone", "description": "The phone number, in [E.123 format](https://www.itu.int/rec/T-REC-E.123-200102-I/en). Maximum length is 50 characters." }, "normalization_status": { "type": "string", "description": "The address normalization status. Returned only for payers from Brazil.", "readOnly": true, "enum": [ "UNKNOWN", "UNNORMALIZED_USER_PREFERRED", "NORMALIZED", "UNNORMALIZED" ] }, "type": { "type": "string", "description": "The type of address. For example, `HOME_OR_WORK`, `GIFT`, and so on." } }, "required": [ "line1", "country_code" ] }, "shipping_address": { "title": "Shipping Address", "description": "The shipping address details.", "allOf": [ { "$ref": "#/components/schemas/address" }, { "properties": { "recipient_name": { "type": "string", "description": "The name of the recipient at this address.", "maxLength": 127 } } } ] }, "payer_info": { "type": "object", "title": "Payer Information", "description": "The payer information.", "properties": { "email": { "type": "string", "format": "email", "description": "The payer's email address. Maximum length is 127 characters." }, "salutation": { "type": "string", "description": "The payer's salutation.", "readOnly": true }, "first_name": { "type": "string", "description": "The payer's first name.", "readOnly": true }, "middle_name": { "type": "string", "description": "The payer's middle name.", "readOnly": true }, "last_name": { "type": "string", "description": "The payer's last name.", "readOnly": true }, "suffix": { "type": "string", "description": "The payer's suffix.", "readOnly": true }, "payer_id": { "type": "string", "description": "The PayPal-assigned encrypted payer ID.", "readOnly": true }, "birth_date": { "type": "string", "format": "date-time", "description": "The birth date of the payer, in [Internet date format](https://tools.ietf.org/html/rfc3339#section-5.6). For example, `1990-04-12`." }, "tax_id": { "type": "string", "description": "The payer's tax ID. Supported for the PayPal payment method only.", "maxLength": 14 }, "tax_id_type": { "type": "string", "description": "The payer's tax ID type. Supported for the PayPal payment method only.", "enum": [ "BR_CPF", "BR_CNPJ" ] }, "billing_address": { "$ref": "#/components/schemas/address", "description": "The payer's billing address." }, "shipping_address": { "$ref": "#/components/schemas/shipping_address", "description": "Deprecated. The shipping address. Use the shipping address for the purchase unit or at the root level of the checkout session.", "readOnly": true } } }, "payer": { "type": "object", "title": "Payer", "description": "The payer. The payer funds the payment.", "properties": { "payment_method": { "type": "string", "minLength": 4, "maxLength": 17, "description": "The payment method.", "enum": [ "credit_card", "paypal", "pay_upon_invoice", "carrier", "alternate_payment", "bank" ] }, "status": { "type": "string", "minLength": 8, "maxLength": 10, "description": "The status of payer's PayPal account.", "readOnly": true, "enum": [ "VERIFIED", "UNVERIFIED" ] }, "funding_instruments": { "type": "array", "description": "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.", "items": { "$ref": "#/components/schemas/funding_instrument" }, "minItems": 1, "maxItems": 1 }, "payer_info": { "$ref": "#/components/schemas/payer_info" } } }, "token": { "type": "object", "title": "Token", "description": "The tokenized payment source to fund a payment.", "properties": { "id": { "type": "string", "description": "The PayPal-generated ID for the token.", "minLength": 1, "maxLength": 255 }, "type": { "type": "string", "description": "The tokenization method that generated the ID.", "minLength": 1, "maxLength": 255, "pattern": "^[0-9A-Z_-]+$", "enum": [ "BILLING_AGREEMENT" ] } }, "required": [ "id", "type" ] }, "payment_source": { "type": "object", "title": "Payment Source", "description": "The payment source definition.", "properties": { "token": { "$ref": "#/components/schemas/token" } } }, "payment_pattern": { "type": "string", "description": "Provides context (e.g. frequency of payment (Single, Recurring) along with whether (Customer is Present, Not Present) for the payment being processed. For Card and PayPal Vaulted/Billing Agreement transactions, this helps specify the appropriate indicators to the networks (e.g. Mastercard, Visa) which ensures compliance as well as ensure a better auth-rate. For bank processing, indicates to clearing house whether the transaction is recurring or not depending on the option chosen.", "title": "Payment pattern", "minLength": 3, "maxLength": 255, "pattern": "^[A-Z_]+$", "enum": [ "CUSTOMER_PRESENT_ONETIME_PURCHASE", "CUSTOMER_NOT_PRESENT_RECURRING", "CUSTOMER_PRESENT_RECURRING_FIRST", "CUSTOMER_PRESENT_ONETIME_PURCHASE_VAULTED", "CUSTOMER_NOT_PRESENT_ONETIME_PURCHASE_VAULTED", "MAIL_ORDER_TELEPHONE_ORDER" ] }, "application_context": { "type": "object", "title": "Application Context", "description": "The application context. Set these properties to customize the payment flow experience for your customers.", "properties": { "brand_name": { "type": "string", "description": "A label that overrides the business name in the merchant's PayPal account on the PayPal checkout pages.", "maxLength": 127 }, "locale": { "type": "string", "description": "The locale of pages that the PayPal payment experience displays. Please refer [here](/docs/api/reference/locale-codes/#localize-the-checkout-experience) for list of supported local codes. Defaulted to en_US if not provided or invalid." }, "landing_page": { "type": "string", "description": "The type of landing page to show on the PayPal site for customer checkout. To use the non-PayPal account landing page, set to `Billing`. To use the PayPal account log in landing page, set to `Login`." }, "shipping_preference": { "type": "string", "description": "The shipping preference.", "default": "GET_FROM_FILE", "enum": [ "NO_SHIPPING", "GET_FROM_FILE", "SET_PROVIDED_ADDRESS" ] }, "user_action": { "type": "string", "description": "The user action. Presents the customer with either the Continue or Pay Now checkout flow:GBand notUKas 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.
| Flow | Action | Description |
|---|---|---|
| Pay Now | user_action=commit | After the customer is redirected to the PayPal payment page, shows the Pay Now button. Use this option when you know the final amount when checkout is initiated and you want to process the payment immediately when the customer clicks Pay Now. |
| Continue | user_action=continue | After the customer is redirected to the PayPal payment page, shows the Continue button. Use this option when you do not know the final amount when you initiate the checkout flow and you want to redirect the customer to the merchant page without processing the payment. |
Note: For an order authorization or capture, you cannot include the amount details object.",
"properties": {
"subtotal": {
"type": "string",
"description": "The subtotal amount for the items. If the request includes line items, this property is **required**. Maximum length is 10 characters, which includes:Note: For an order authorization or capture, you cannot include the subtotal parameter."
},
"shipping": {
"type": "string",
"description": "The shipping fee. Maximum length is 10 characters, which includes:Note: For an order authorization or capture, you cannot include the shipping parameter."
},
"tax": {
"type": "string",
"description": "The tax. Maximum length is 10 characters, which includes:Note: For an order authorization or capture, you cannot include the tax parameter."
},
"handling_fee": {
"type": "string",
"description": "The handling fee. Maximum length is 10 characters, which includes:Note: For an order authorization or capture, you cannot include the handling_fee parameter."
},
"shipping_discount": {
"type": "string",
"description": "The shipping fee discount. Maximum length is 10 characters, which includes:Note: For an order authorization or capture, you cannot include the shipping_discount parameter."
},
"insurance": {
"type": "string",
"description": "The insurance fee. Maximum length is 10 characters, which includes:Note: For an order authorization or capture, you cannot include the insurance parameter."
},
"gift_wrap": {
"type": "string",
"description": "The gift wrap fee. Maximum length is 10 characters, which includes:Note: For an order authorization or capture, you cannot include the gift_wrap parameter.",
"x-hidden": true
}
}
}
},
"required": [
"currency",
"total"
]
},
"payee": {
"type": "object",
"title": "Payee",
"description": "The payee who receives the funds and fulfills the order.",
"properties": {
"email": {
"type": "string",
"format": "email",
"description": "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:Note: For an order authorization, you cannot include amount details.",
"$ref": "#/components/schemas/amount"
},
"payment_mode": {
"type": "string",
"description": "The transaction payment mode.",
"readOnly": true,
"enum": [
"INSTANT_TRANSFER",
"MANUAL_BANK_TRANSFER",
"DELAYED_TRANSFER",
"ECHECK"
]
},
"state": {
"type": "string",
"description": "The state of the order transaction.",
"readOnly": true,
"enum": [
"PENDING",
"AUTHORIZED",
"CAPTURED",
"COMPLETED",
"VOIDED"
]
},
"reason_code": {
"type": "string",
"description": "The reason code that describes why the transaction state is pending or reversed. Supported only for PayPal payments.",
"readOnly": true,
"enum": [
"PAYER_SHIPPING_UNCONFIRMED",
"MULTI_CURRENCY",
"RISK_REVIEW",
"REGULATORY_REVIEW",
"VERIFICATION_REQUIRED",
"ORDER",
"OTHER"
]
},
"pending_reason": {
"type": "string",
"enum": [
"payer_shipping_unconfirmed",
"multi_currency",
"risk_review",
"regulatory_review",
"verification_required",
"order",
"other"
],
"description": "Deprecated. The reason code for the pending transaction state. Obsolete. Use `reason_code` instead.",
"readOnly": true
},
"protection_eligibility": {
"type": "string",
"description": "The level of seller protection in effect for the transaction.",
"readOnly": true,
"enum": [
"ELIGIBLE",
"PARTIALLY_ELIGIBLE",
"INELIGIBLE"
]
},
"protection_eligibility_type": {
"type": "string",
"description": "The kind of seller protection in effect for the transaction. Returned only when the `protection_eligibility` property is `ELIGIBLE` or `PARTIALLY_ELIGIBLE`. Supported only for PayPal payments.",
"readOnly": true,
"enum": [
"ITEM_NOT_RECEIVED_ELIGIBLE",
"UNAUTHORIZED_PAYMENT_ELIGIBLE",
"ITEM_NOT_RECEIVED_ELIGIBLE,UNAUTHORIZED_PAYMENT_ELIGIBLE"
]
},
"parent_payment": {
"type": "string",
"readOnly": true,
"description": "The ID of the payment on which this transaction is based."
},
"fmf_details": {
"$ref": "#/components/schemas/fmf_details"
},
"create_time": {
"type": "string",
"format": "date-time",
"description": "The date and time when the resource was created, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6).",
"readOnly": true
},
"update_time": {
"type": "string",
"format": "date-time",
"description": "The date and time when the resource was last updated, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6).",
"readOnly": true
},
"links": {
"type": "array",
"description": "An array of request-related [HATEOAS links](/docs/api/reference/api-responses/#hateoas-links).",
"readOnly": true,
"items": {
"$ref": "#/components/schemas/link_description"
}
}
},
"required": [
"amount"
]
},
"capture": {
"type": "object",
"title": "Capture",
"description": "The capture transaction details.",
"properties": {
"id": {
"type": "string",
"description": "The ID of the capture transaction.",
"readOnly": true
},
"amount": {
"description": "The amount to capture. If the amount matches the originally authorized amount, the state of the authorization changes to `captured`. Otherwise, the state changes to `partially_captured`.",
"$ref": "#/components/schemas/amount"
},
"is_final_capture": {
"type": "boolean",
"description": "Indicates whether to release all remaining held funds.",
"default": false
},
"state": {
"type": "string",
"description": "The state of the capture.",
"readOnly": true,
"enum": [
"pending",
"completed",
"refunded",
"partially_refunded",
"denied"
]
},
"reason_code": {
"type": "string",
"description": "The reason code that describes why the transaction state is pending or reversed.",
"readOnly": true,
"enum": [
"CHARGEBACK",
"GUARANTEE",
"BUYER_COMPLAINT",
"REFUND",
"UNCONFIRMED_SHIPPING_ADDRESS",
"ECHECK",
"INTERNATIONAL_WITHDRAWAL",
"RECEIVING_PREFERENCE_MANDATES_MANUAL_ACTION",
"PAYMENT_REVIEW",
"REGULATORY_REVIEW",
"UNILATERAL",
"VERIFICATION_REQUIRED",
"TRANSACTION_APPROVED_AWAITING_FUNDING",
"NONE"
]
},
"parent_payment": {
"type": "string",
"readOnly": true,
"description": "The ID of the payment on which this transaction is based."
},
"invoice_number": {
"type": "string",
"description": "The invoice number to track this payment.",
"maxLength": 127
},
"transaction_fee": {
"description": "The currency and amount of the transaction fee for this payment. Would not be returned for `pending` transactions where the funds have not been realized in the payee account.",
"readOnly": true,
"$ref": "#/components/schemas/currency"
},
"transaction_fee_in_receivable_currency": {
"description": "The currency and amount of the PayPal fee for this payment in the receivable currency. Returned only in cases the fee is charged in the receivable currency. Example `CNY`. Would not be returned for `pending` transactions where the funds have not been realized in the payee account.",
"readOnly": true,
"$ref": "#/components/schemas/currency"
},
"receivable_amount": {
"description": "The net amount and currency that the merchant receives for this transaction in the receivable currency.",
"$ref": "#/components/schemas/currency",
"readOnly": true
},
"exchange_rate": {
"type": "string",
"description": "The exchange rate applied for this transaction. Returned when there is a currency conversion from the transaction currency to the receivable currency.",
"readOnly": true
},
"note_to_payer": {
"type": "string",
"description": "A free-form field that clients can use to send a note to the payer.",
"maxLength": 255
},
"create_time": {
"type": "string",
"format": "date-time",
"description": "The date and time of the capture, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6).",
"readOnly": true
},
"update_time": {
"type": "string",
"format": "date-time",
"description": "The date and time when the resource was last updated, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6).",
"readOnly": true
},
"links": {
"type": "array",
"description": "An array of request-related [HATEOAS links](/docs/api/reference/api-responses/#hateoas-links).",
"readOnly": true,
"items": {
"$ref": "#/components/schemas/link_description"
}
}
}
},
"refund": {
"type": "object",
"title": "Refund",
"description": "The refund details.",
"properties": {
"id": {
"type": "string",
"readOnly": true,
"description": "The ID of the refund transaction. Maximum length is 17 characters."
},
"amount": {
"$ref": "#/components/schemas/amount",
"description": "The refund amount. Includes both the amount refunded to the payer and amount of the fee refunded to the payee."
},
"state": {
"type": "string",
"description": "The state of the refund.",
"readOnly": true,
"enum": [
"pending",
"completed",
"cancelled",
"failed"
]
},
"reason": {
"type": "string",
"description": "The reason that the transaction is being refunded."
},
"invoice_number": {
"type": "string",
"description": "The invoice or tracking ID number.",
"maxLength": 127
},
"sale_id": {
"type": "string",
"readOnly": true,
"description": "The ID of the sale transaction being refunded."
},
"capture_id": {
"type": "string",
"readOnly": true,
"description": "The ID of the sale transaction being refunded."
},
"parent_payment": {
"type": "string",
"readOnly": true,
"description": "The ID of the payment on which this transaction is based."
},
"description": {
"type": "string",
"description": "The refund description. Value must be single-byte alphanumeric characters."
},
"create_time": {
"type": "string",
"format": "date-time",
"description": "The date and time when the refund was created, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6).",
"readOnly": true
},
"update_time": {
"type": "string",
"format": "date-time",
"description": "The date and time when the resource was last updated, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6).",
"readOnly": true
},
"links": {
"type": "array",
"description": "An array of request-related [HATEOAS links](/docs/api/reference/api-responses/#hateoas-links).",
"readOnly": true,
"items": {
"$ref": "#/components/schemas/link_description"
}
}
}
},
"related_resources": {
"type": "object",
"title": "Related Resources",
"description": "The payment-related financial transactions, which include sales, authorizations, captures, and refunds. To show resource details, use the resource ID. For example, to [show details for a related authorization](/docs/api/payments/v1/#authorization_get), use the ID returned in the `authorization` object. You can also use the [HATEOAS links](/docs/api/hateoas-links/) for a resource to complete operations for that resource. For example, a `sale` object provides a `refund` link that enables you to refund the sale.",
"properties": {
"sale": {
"$ref": "#/components/schemas/sale"
},
"authorization": {
"$ref": "#/components/schemas/authorization"
},
"order": {
"$ref": "#/components/schemas/order"
},
"capture": {
"$ref": "#/components/schemas/capture"
},
"refund": {
"$ref": "#/components/schemas/refund"
}
}
},
"transaction": {
"type": "object",
"title": "Transaction",
"description": "An array of payment-related transactions. A transaction defines what the payment is for and who fulfills the payment.",
"properties": {
"amount": {
"$ref": "#/components/schemas/amount",
"description": "The amount to collect."
},
"payee": {
"$ref": "#/components/schemas/payee"
},
"description": {
"type": "string",
"description": "The purchase description.",
"maxLength": 127
},
"note_to_payee": {
"type": "string",
"description": "The note to the recipient of the funds in this transaction.",
"maxLength": 255
},
"custom": {
"type": "string",
"description": "The free-form field for the client's use.",
"maxLength": 127
},
"invoice_number": {
"type": "string",
"description": "The invoice number to track this payment.",
"maxLength": 127
},
"soft_descriptor": {
"type": "string",
"description": "The soft descriptor to use to charge this funding source. If greater than the maximum allowed length, the API truncates the string.",
"maxLength": 22
},
"payment_options": {
"type": "object",
"title": "Payment Options",
"description": "The payment options for this transaction.",
"properties": {
"allowed_payment_method": {
"type": "string",
"description": "The payment method for this transaction. This field does not apply to the credit card payment method.",
"default": "UNRESTRICTED",
"enum": [
"UNRESTRICTED",
"INSTANT_FUNDING_SOURCE",
"IMMEDIATE_PAY"
]
}
}
},
"item_list": {
"type": "object",
"title": "Item List",
"description": "An array of items that are being purchased.",
"properties": {
"items": {
"type": "array",
"description": "An array of items that are being purchased.",
"items": {
"$ref": "#/components/schemas/item"
}
},
"shipping_address": {
"$ref": "#/components/schemas/shipping_address"
},
"shipping_method": {
"type": "string",
"description": "The shipping method used for this payment, such as USPS Parcel."
},
"shipping_phone_number": {
"type": "string",
"description": "The shipping phone number, in its canonical international format as defined by the [E.164](https://en.wikipedia.org/wiki/E.164) numbering plan. Enables merchants to share payer’s contact number with PayPal for the current payment. The final contact number for the payer who is associated with the transaction might be the same as or different from the `shipping_phone_number` based on the payer’s action on PayPal."
}
}
},
"notify_url": {
"type": "string",
"format": "uri",
"description": "The URL to send payment notifications.",
"maxLength": 2048
},
"related_resources": {
"type": "array",
"description": "An array of payment-related transactions. A transaction defines what the payment is for and who fulfills the payment.",
"readOnly": true,
"items": {
"$ref": "#/components/schemas/related_resources"
}
}
}
},
"payment": {
"type": "object",
"title": "Payment",
"description": "The payment details.",
"properties": {
"id": {
"type": "string",
"description": "The ID of the payment.",
"readOnly": true
},
"intent": {
"type": "string",
"description": "The payment intent. Value is:sale. Makes an immediate payment.authorize. [Authorizes a payment for capture later](/docs/integration/direct/payments/authorize-and-capture-payments/).order. [Creates an order](/docs/integration/direct/payments/orders/).created. The transaction was successfully created.approved. The customer approved the transaction. The state changes from created to approved on generation of the sale_id for sale transactions, authorization_id for authorization transactions, or order_id for order transactions.failed. The transaction request failed.remove operation does not require a value."
},
"from": {
"type": "string",
"description": "The JSON Pointer to the target document location from which to move the value. Required for the move operation."
}
},
"required": [
"op"
]
},
"patch_request": {
"type": "array",
"title": "Patch Request",
"description": "An array of JSON patch objects to apply partial updates to resources.",
"items": {
"$ref": "#/components/schemas/patch"
}
},
"cart_base": {
"type": "object",
"title": "Cart Base",
"description": "The cart.",
"properties": {
"reference_id": {
"type": "string",
"description": "The merchant-provided ID for the purchase unit.",
"maxLength": 256
},
"amount": {
"$ref": "#/components/schemas/amount",
"description": "The amount to collect."
},
"payee": {
"$ref": "#/components/schemas/payee"
},
"description": {
"type": "string",
"description": "The purchase description.",
"maxLength": 127
},
"note_to_payee": {
"type": "string",
"description": "The note to the recipient of the funds in this transaction.",
"maxLength": 255
},
"custom": {
"type": "string",
"description": "The free-form field for the client's use.",
"maxLength": 127
},
"invoice_number": {
"type": "string",
"description": "The invoice number to track this payment.",
"maxLength": 127
},
"soft_descriptor": {
"type": "string",
"description": "The payment descriptor on account transactions on the customer's credit card statement, that PayPal sends to processors. The maximum length of the soft descriptor information that you can pass in the API field is 22 characters, in the following format:22 - len(PAYPAL * (8)) - len(Descriptor in Payment Receiving Preferences of Merchant account + 1)The PAYPAL prefix uses 8 characters.