{ "openapi": "3.0.3", "info": { "title": "Webhooks Management", "description": "The PayPal REST APIs use webhooks for event notification. Webhooks are HTTP callbacks that receive notification messages for events. After you configure a webhook listener for your app, you can create a webhook, which subscribes the webhook listener for your app to events. The notifications namespace contains resource collections for webhooks.", "version": "1.11", "contact": {} }, "servers": [ { "url": "https://api-m.sandbox.paypal.com", "description": "PayPal Sandbox Environment" }, { "url": "https://api-m.paypal.com", "description": "PayPal Live Environment" } ], "tags": [ { "name": "webhooks", "description": "Use the `/webhooks` resource to subscribe your webhook listener to events, list webhooks for an app, show details for, update, delete, and list event subscriptions for webhooks." }, { "name": "webhooks-lookup", "description": "Use the `/webhooks-lookup` resource to create, list, show details for, and delete webhook lookups." }, { "name": "verify-webhook-signature", "description": "Use the `/verify-webhook-signature` resource to verify a webhook signature." }, { "name": "webhooks-event-types", "description": "Use the `/webhooks-event-types` resource to list available events to which any webhook can subscribe." }, { "name": "webhooks-events", "description": "Use the `/webhooks-events` resource to list, show details for, and resend event notifications." }, { "name": "simulate-event", "description": "Use the `/simulate-event` resource to use a sample payload to simulate a webhook event. The events that this call generates only serve to validate the connection to the listener URL and to show how webhook events look.
Note: You can also use the Webhooks simulator to simulate webhook events.
" }, { "name": "publish-event-with-payload", "description": "Use the `/publish-event-with-payload` resource to publish an event with a specified payload." }, { "name": "publish-event-with-reference", "description": "Use the `/publish-event-with-reference` resource to publish an event with a specified reference." }, { "name": "webhook-event-delivery-status", "description": "Use the `/webhook-event-delivery-status` resource to show the webhook event send status." }, { "name": "webhooks-error-types", "description": "Use the `/error-types` resource to create and list available webhook error types." }, { "name": "webhooks-errors", "description": "Use the `/webhooks-errors` resource to create, list, show details for, and update webhook errors." }, { "name": "batch-resend", "description": "Use the `/batch-resend` resource to send out IPN/Webhooks in batches." } ], "externalDocs": { "url": "https://developer.paypal.com/docs/api/webhooks/v1/" }, "paths": { "/v1/notifications/webhooks": { "post": { "summary": "Create webhook", "description": "Subscribes your webhook listener to events.", "operationId": "webhooks.post", "responses": { "201": { "description": "A successful request returns the HTTP `201 Created` status code and a JSON response body with a [`webhook`](/docs/api/webhooks/v1/#definition-webhook) object that includes the webhook ID for later use.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/webhook" } } } }, "default": { "description": "The error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-2" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/webhook" }, "examples": { "webhook": { "value": { "url": "https://example.com/example_webhook", "event_types": [ { "name": "PAYMENT.AUTHORIZATION.CREATED" }, { "name": "PAYMENT.AUTHORIZATION.VOIDED" } ] } } } } } }, "security": [ { "Oauth2": ["https://uri.paypal.com/services/applications/webhooks"] } ], "tags": ["webhooks"] }, "get": { "summary": "List webhooks", "description": "Lists webhooks for an app.", "operationId": "webhooks.list", "responses": { "200": { "description": "A successful request returns the HTTP `200 OK` status code and a JSON response body that lists webhooks with webhook details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookList" } } } }, "default": { "description": "The error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-2" } } } } }, "parameters": [ { "$ref": "#/components/parameters/anchor_type" } ], "security": [ { "Oauth2": ["https://uri.paypal.com/services/applications/webhooks"] } ], "tags": ["webhooks"] } }, "/v1/notifications/webhooks/{webhook_id}": { "get": { "summary": "Show webhook details", "description": "Shows details for a webhook, by ID.", "operationId": "webhooks.get", "responses": { "200": { "description": "A successful request returns the HTTP `200 OK` status code and a JSON response body that shows webhook details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/webhook" } } } }, "default": { "description": "The error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-2" } } } } }, "parameters": [ { "$ref": "#/components/parameters/webhook_id" } ], "security": [ { "Oauth2": ["https://uri.paypal.com/services/applications/webhooks"] } ], "tags": ["webhooks"] }, "patch": { "summary": "Update webhook", "description": "Updates a webhook to replace webhook fields with new values. Supports only the `replace` operation. Pass a `json_patch` object with `replace` operation and `path`, which is `/url` for a URL or `/event_types` for events. The `value` is either the URL or a list of events.", "operationId": "webhooks.update", "responses": { "200": { "description": "A successful request returns the HTTP `200 OK` status code and a JSON response body that shows webhook details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/webhook" } } } }, "default": { "description": "The error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-2" } } } } }, "parameters": [ { "$ref": "#/components/parameters/webhook_id" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/patch_request" } } } }, "security": [ { "Oauth2": ["https://uri.paypal.com/services/applications/webhooks"] } ], "tags": ["webhooks"] }, "delete": { "summary": "Delete webhook", "description": "Deletes a webhook, by ID.", "operationId": "webhooks.delete", "responses": { "204": { "description": "A successful request returns the HTTP `204 No Content` status code with no JSON response body." }, "default": { "description": "The error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-2" } } } } }, "parameters": [ { "$ref": "#/components/parameters/webhook_id" } ], "security": [ { "Oauth2": ["https://uri.paypal.com/services/applications/webhooks"] } ], "tags": ["webhooks"] } }, "/v1/notifications/webhooks/{webhook_id}/event-types": { "get": { "summary": "List event subscriptions for webhook", "description": "Lists event subscriptions for a webhook, by ID.", "operationId": "event-types.list", "responses": { "200": { "description": "A successful request returns the HTTP `200 OK` status code and a JSON response body that lists event subscriptions for a webhook.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventTypeList" } } } }, "default": { "description": "The error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-2" } } } } }, "parameters": [ { "$ref": "#/components/parameters/webhook_id" } ], "security": [ { "Oauth2": ["https://uri.paypal.com/services/applications/webhooks"] } ], "tags": ["webhooks"] } }, "/v1/notifications/webhooks-lookup": { "post": { "summary": "Create webhook lookup", "description": "Creates a webhook lookup. A webhook lookup ties the API caller's REST API app to the subject account (or, if no subject is specified, to the API caller's account). If a webhook event is generated for an event that is tied to the account but not to a particular REST API app (for example, payments initiated with the NVP/SOAP APIs or through the user interface on PayPal.com), those webhook events will treated as if they were intended for the REST API app registered in the webhook lookup instead. Webhook events will then be delivered to any webhooks registered to that REST API app.", "operationId": "webhooks-lookup.post", "responses": { "201": { "description": "A successful request returns the HTTP `201 Created` status code and a JSON response body that shows webhook lookup details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/webhooks_lookup" } } } }, "default": { "description": "The error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-2" } } } } }, "security": [ { "Oauth2": ["https://uri.paypal.com/services/applications/webhooks"] } ], "tags": ["webhooks-lookup"] }, "get": { "summary": "List webhook lookups", "description": "Lists webhook lookups.", "operationId": "webhooks-lookup.list", "responses": { "200": { "description": "A successful request returns the HTTP `200 OK` status code and a JSON response body that lists webhook lookups with webhook lookup details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookLookupList" } } } }, "default": { "description": "The error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-2" } } } } }, "security": [ { "Oauth2": ["https://uri.paypal.com/services/applications/webhooks"] } ], "tags": ["webhooks-lookup"] } }, "/v1/notifications/webhooks-lookup/{webhook_lookup_id}": { "get": { "summary": "Show webhook lookup details", "description": "Shows details for a webhook lookup, by ID.", "operationId": "webhooks-lookup.get", "responses": { "200": { "description": "A successful request returns the HTTP `200 OK` status code and a JSON response body that shows webhook lookup details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/webhooks_lookup" } } } }, "default": { "description": "The error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-2" } } } } }, "parameters": [ { "$ref": "#/components/parameters/webhook_lookup_id" } ], "security": [ { "Oauth2": ["https://uri.paypal.com/services/applications/webhooks"] } ], "tags": ["webhooks-lookup"] }, "delete": { "summary": "Delete webhook lookup", "description": "Deletes a webhook lookup, by ID.", "operationId": "webhooks-lookup.delete", "responses": { "204": { "description": "A successful request returns the HTTP `204 No Content` status code with no JSON response body." }, "default": { "description": "The error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-2" } } } } }, "parameters": [ { "$ref": "#/components/parameters/webhook_lookup_id" } ], "security": [ { "Oauth2": ["https://uri.paypal.com/services/applications/webhooks"] } ], "tags": ["webhooks-lookup"] } }, "/v1/notifications/verify-webhook-signature": { "post": { "summary": "Verify webhook signature", "description": "Verifies a webhook signature.", "operationId": "verify-webhook-signature.post", "responses": { "200": { "description": "A successful request returns the HTTP `200 OK` status code and a JSON response body that shows the verification status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/verify_webhook_signature_response" } } } }, "default": { "description": "The error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-2" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/verify_webhook_signature" }, "examples": { "verify_webhook_signature": { "value": { "transmission_id": "69cd13f0-d67a-11e5-baa3-778b53f4ae55", "transmission_time": "2016-02-18T20:01:35Z", "cert_url": "cert_url", "auth_algo": "SHA256withRSA", "transmission_sig": "lmI95Jx3Y9nhR5SJWlHVIWpg4AgFk7n9bCHSRxbrd8A9zrhdu2rMyFrmz+Zjh3s3boXB07VXCXUZy/UFzUlnGJn0wDugt7FlSvdKeIJenLRemUxYCPVoEZzg9VFNqOa48gMkvF+XTpxBeUx/kWy6B5cp7GkT2+pOowfRK7OaynuxUoKW3JcMWw272VKjLTtTAShncla7tGF+55rxyt2KNZIIqxNMJ48RDZheGU5w1npu9dZHnPgTXB9iomeVRoD8O/jhRpnKsGrDschyNdkeh81BJJMH4Ctc6lnCCquoP/GzCzz33MMsNdid7vL/NIWaCsekQpW26FpWPi/tfj8nLA==", "webhook_id": "1JE4291016473214C", "webhook_event": { "id": "8PT597110X687430LKGECATA", "create_time": "2013-06-25T21:41:28Z", "resource_type": "authorization", "event_type": "PAYMENT.AUTHORIZATION.CREATED", "summary": "A payment authorization was created", "resource": { "id": "2DC87612EK520411B", "create_time": "2013-06-25T21:39:15Z", "update_time": "2013-06-25T21:39:17Z", "state": "authorized", "amount": { "total": "7.47", "currency": "USD", "details": { "subtotal": "7.47" } }, "parent_payment": "PAY-36246664YD343335CKHFA4AY", "valid_until": "2013-07-24T21:39:15Z", "links": [ { "href": "https://api-m.paypal.com/v1/payments/authorization/2DC87612EK520411B", "rel": "self", "method": "GET" }, { "href": "https://api-m.paypal.com/v1/payments/authorization/2DC87612EK520411B/capture", "rel": "capture", "method": "POST" }, { "href": "https://api-m.paypal.com/v1/payments/authorization/2DC87612EK520411B/void", "rel": "void", "method": "POST" }, { "href": "https://api-m.paypal.com/v1/payments/payment/PAY-36246664YD343335CKHFA4AY", "rel": "parent_payment", "method": "GET" } ] } } } } } } } }, "security": [ { "Oauth2": [ "https://uri.paypal.com/services/applications/webhooks", "https://uri.paypal.com/services/applications/verify-webhook-signature" ] } ], "tags": ["verify-webhook-signature"] } }, "/v1/notifications/webhooks-event-types": { "get": { "summary": "List available events", "description": "Lists available events to which any webhook can subscribe. For a list of supported events, see [Webhook event names](/docs/api/notifications/webhooks/event-names/).", "operationId": "webhooks-event-types.list", "responses": { "200": { "description": "A successful request returns the HTTP `200 OK` status code and a JSON response body that lists available events to which any webhook can subscribe.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventTypeList" } } } }, "default": { "description": "The error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-2" } } } } }, "tags": ["webhooks-event-types"] } }, "/v1/notifications/webhooks-events": { "get": { "summary": "List event notifications", "description": "Lists webhooks event notifications. Use query parameters to filter the response.", "operationId": "webhooks-events.list", "responses": { "200": { "description": "A successful request returns the HTTP `200 OK` status code and a JSON response body that lists webhooks event notifications.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventList" } } } }, "default": { "description": "The error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-2" } } } } }, "parameters": [ { "$ref": "#/components/parameters/page_size" }, { "$ref": "#/components/parameters/start_time" }, { "$ref": "#/components/parameters/end_time" }, { "$ref": "#/components/parameters/transaction_id" }, { "$ref": "#/components/parameters/event_type" } ], "security": [ { "Oauth2": ["https://uri.paypal.com/services/applications/webhooks"] } ], "tags": ["webhooks-events"] } }, "/v1/notifications/webhooks-events/{event_id}": { "get": { "summary": "Show event notification details", "description": "Shows details for a webhooks event notification, by ID.", "operationId": "webhooks-events.get", "responses": { "200": { "description": "A successful request returns the HTTP `200 OK` status code and a JSON response body that shows webhooks event notification details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/event" } } } }, "default": { "description": "The error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-2" } } } } }, "parameters": [ { "$ref": "#/components/parameters/event_id" } ], "security": [ { "Oauth2": ["https://uri.paypal.com/services/applications/webhooks"] } ], "tags": ["webhooks-events"] } }, "/v1/notifications/webhooks-events/{event_id}/resend": { "post": { "summary": "Resend event notification", "description": "Resends a webhook event notification, by ID. Any pending notifications are not resent.", "operationId": "webhooks-events.resend", "responses": { "202": { "description": "A successful request returns the HTTP `202 Accepted` status code and a JSON response body that shows webhook event notification details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/event" } } } }, "default": { "description": "The error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-2" } } } } }, "parameters": [ { "$ref": "#/components/parameters/event_id" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/event_resend" } } } }, "security": [ { "Oauth2": ["https://uri.paypal.com/services/applications/webhooks"] } ], "tags": ["webhooks-events"] } }, "/v1/notifications/simulate-event": { "post": { "summary": "Simulate webhook event", "description": "Simulates a webhook event. In the JSON request body, specify a sample payload.
You need to subscribe to the following webhook events for Pay upon Invoice:
EventTrigger
PAYMENT.CAPTURE.COMPLETEDA payment capture completes.
PAYMENT.CAPTURE.DENIEDA payment capture is denied.
CHECKOUT.PAYMENT-APPROVAL.REVERSEDPayPal reverses a payment capture.
", "operationId": "simulate-event.post", "responses": { "202": { "description": "A successful request returns the HTTP `202 Accepted` status code and a JSON response body that shows details for the mock event.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/event" } } } }, "default": { "description": "The error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-2" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/simulate_event" }, "examples": { "simulate_event": { "value": { "url": "https://example.com/example_webhook", "event_type": "PAYMENT.AUTHORIZATION.CREATED", "resource_version": "1.0" } } } } } }, "security": [ { "Oauth2": ["https://uri.paypal.com/services/applications/webhooks"] } ], "tags": ["simulate-event"] } } }, "components": { "securitySchemes": { "Oauth2": { "type": "oauth2", "description": "Oauth 2.0 authentication", "flows": { "clientCredentials": { "tokenUrl": "/v1/oauth2/token", "scopes": { "https://uri.paypal.com/services/applications/webhooks": "Access/update Webhooks.", "https://uri.paypal.com/services/applications/verify-webhook-signature": "Verify Webhook Signature" } } } } }, "schemas": { "EventList": { "type": "object", "title": "Event List", "description": "A list of webhooks events.", "properties": { "events": { "$ref": "#/components/schemas/event_list" }, "count": { "type": "integer", "description": "The number of items in each range of results. Note that the response might have fewer items than the requested `page_size` value." }, "links": { "$ref": "#/components/schemas/link_description_list" } } }, "EventTypeList": { "type": "object", "title": "Event Type List", "description": "A list of webhook events.", "properties": { "event_types": { "$ref": "#/components/schemas/event_type_list" } } }, "WebhookList": { "type": "object", "title": "Webhook List", "description": "A list of webhooks.", "properties": { "webhooks": { "$ref": "#/components/schemas/webhook_list" } } }, "WebhookLookupList": { "type": "object", "title": "Webhook Lookup List", "description": "A list of webhook lookups.", "properties": { "webhooks_lookups": { "$ref": "#/components/schemas/webhooks_lookup_list" } } }, "definitions-event_type_list": { "type": "array", "maxItems": 500, "description": "An array of events to which to subscribe your webhook. To subscribe to all events, including events as they are added, specify the asterisk wild card. To replace the `event_types` array, specify the asterisk wild card. To list all supported events, list available events.", "readOnly": false, "items": { "$ref": "#/components/schemas/event_type" } }, "definitions-link_description_list": { "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" } }, "error": {}, "error-2": { "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": { "$ref": "#/components/schemas/error_details_list" }, "links": { "$ref": "#/components/schemas/link_description_list" } }, "required": ["name", "message", "debug_id"] }, "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" } } }, "example": { "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" } } }, "example": { "name": "SERVICE_UNAVAILABLE", "message": "Service Unavailable.", "debug_id": "90957fca61718", "information_link": "https://developer.paypal.com/docs/api/orders/v2/#error-SERVICE_UNAVAILABLE" } }, "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_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"] }, "error_details_list": { "type": "array", "description": "An array of additional details about the error.", "items": { "$ref": "#/components/schemas/error_details-2" } }, "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_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_type": { "type": "object", "title": "Error Type", "description": "The type of webhook error that occurred.", "properties": { "id": { "type": "string", "description": "The ID for the webhook error type.", "readOnly": true }, "name": { "type": "string", "description": "The unique error type name.", "readOnly": false }, "description": { "type": "string", "description": "A human-readable description of the error type.", "readOnly": true } }, "required": ["name"] }, "event": { "type": "object", "title": "Event", "description": "A webhook event notification.", "properties": { "id": { "type": "string", "description": "The ID of the webhook event notification.", "readOnly": true }, "create_time": { "type": "string", "format": "date-time", "description": "The date and time when the webhook event notification was created, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6).", "readOnly": true }, "resource_type": { "type": "string", "description": "The name of the resource related to the webhook notification event.", "readOnly": true }, "event_version": { "$ref": "#/components/schemas/event_version" }, "event_type": { "type": "string", "description": "The event that triggered the webhook event notification.", "readOnly": true }, "summary": { "type": "string", "description": "A summary description for the event notification.", "readOnly": true }, "resource_version": { "$ref": "#/components/schemas/resource_version" }, "resource": { "$ref": "#/components/schemas/resource" }, "links": { "$ref": "#/components/schemas/link_description_list" } } }, "event_list": { "type": "array", "description": "An array of webhooks events.", "items": { "$ref": "#/components/schemas/event" } }, "event_resend": { "type": "object", "title": "Event Resend", "description": "Resends a webhook event notification, by ID.", "properties": { "webhook_ids": { "$ref": "#/components/schemas/webhook_ids_list" } } }, "event_type": { "type": "object", "title": "Event Type", "description": "An event type.", "properties": { "name": { "type": "string", "description": "The unique event name.
Note: To subscribe to all events, including events as they are added, specify an `*` as the value to represent a wildcard.
", "readOnly": false }, "description": { "type": "string", "description": "A human-readable description of the event.", "readOnly": true }, "status": { "type": "string", "description": "The status of a webhook event.", "readOnly": true }, "resource_versions": { "$ref": "#/components/schemas/resource_versions_list" } }, "required": ["name"] }, "event_type_list": { "type": "array", "description": "An array of webhook events.", "items": { "$ref": "#/components/schemas/event_type" } }, "event_version": { "type": "string", "title": "Event Version", "description": "The event version in the webhook notification.", "deprecated": true, "pattern": "^([0-9]+.[0-9]+)$" }, "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" ] } } }, "link_description_list": { "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" } }, "patch": { "type": "object", "title": "Patch", "description": "The JSON patch object to apply partial updates to resources.", "properties": { "op": { "type": "string", "description": "The operation.", "x-enumDescriptions": [ { "value": "add", "description": "Depending on the target location reference, completes one of these functions:The value parameter defines the value to add. For more information, see 4.1. add." }, { "value": "remove", "description": "Removes the value at the target location. For the operation to succeed, the target location must exist. For more information, see 4.2. remove." }, { "value": "replace", "description": "Replaces the value at the target location with a new value. The operation object must contain a value parameter that defines the replacement value. For the operation to succeed, the target location must exist. For more information, see 4.3. replace." }, { "value": "move", "description": "Removes the value at a specified location and adds it to the target location. The operation object must contain a from parameter, which is a string that contains a JSON pointer value that references the location in the target document from which to move the value. For the operation to succeed, the from location must exist. For more information, see 4.4. move." }, { "value": "copy", "description": "Copies the value at a specified location to the target location. The operation object must contain a from parameter, which is a string that contains a JSON pointer value that references the location in the target document from which to copy the value. For the operation to succeed, the from location must exist. For more information, see 4.5. copy." }, { "value": "test", "description": "Tests that a value at the target location is equal to a specified value. The operation object must contain a value parameter that defines the value to compare to the target location's value. For the operation to succeed, the target location must be equal to the value value. For test, equal indicates that the value at the target location and the value that value defines are of the same JSON type. The data type of the value determines how equality is defined:
TypeConsidered equal if both values
stringsContain the same number of Unicode characters and their code points are byte-by-byte equal.
numbersAre numerically equal.
arraysContain the same number of values, and each value is equal to the value at the corresponding position in the other array, by using these type-specific rules.
objectsContain the same number of parameters, and each parameter is equal to a parameter in the other object, by comparing their keys (as strings) and their values (by using these type-specific rules).
literals (false, true, and null)Are the same. The comparison is a logical comparison. For example, whitespace between the parameter values of an array is not significant. Also, ordering of the serialization of object parameters is not significant.
For more information, see 4.6. test." } ], "enum": ["add", "remove", "replace", "move", "copy", "test"] }, "path": { "type": "string", "description": "The JSON Pointer to the target document location at which to complete the operation." }, "value": { "type": [ "number", "integer", "string", "boolean", "null", "array", "object" ], "title": "Patch Value", "description": "The value to apply. The 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" } }, "resource": { "type": "object", "title": "Resource", "description": "The resource that triggered the webhook event notification.", "readOnly": true, "additionalProperties": true }, "resource_version": { "title": "Resource Version", "description": "The resource version in the webhook notification.", "type": "string", "pattern": "^([0-9]+.[0-9]+)$" }, "resource_versions": { "type": "string", "description": "The ID for an event type. For example, `1.0` or `2.0`." }, "resource_versions_list": { "type": "array", "description": "Identifier for the event type example: 1.0/2.0 etc.", "readOnly": true, "items": { "$ref": "#/components/schemas/resource_versions" } }, "simulate_event": { "type": "object", "title": "Simulate Event", "description": "Simulates a mock webhook event.", "properties": { "webhook_id": { "type": "string", "description": "The ID of the webhook. If omitted, the URL is required.", "readOnly": false, "pattern": "^[a-zA-Z0-9]+$", "maxLength": 50 }, "url": { "type": "string", "format": "uri", "description": "The URL for the webhook endpoint. If omitted, the webhook ID is required.", "readOnly": false, "maxLength": 2048 }, "event_type": { "type": "string", "description": "The event name. Specify one of the subscribed events. For each request, provide only one event.", "readOnly": false, "maxLength": 50, "pattern": "^[a-zA-Z0-9.]+$" }, "resource_version": { "type": "string", "description": "The identifier for event type ex: 1.0/2.0 etc.", "readOnly": false } }, "required": ["event_type"] }, "swagger_link_description": { "$ref": "#/components/schemas/link_description" }, "verify_webhook_signature": { "type": "object", "title": "Verify Webhook Signature", "description": "A verify webhook signature request.", "properties": { "auth_algo": { "type": "string", "maxLength": 100, "pattern": "^[a-zA-Z0-9]+$", "description": "The algorithm that PayPal uses to generate the signature and that you can use to verify the signature. Extract this value from the `PAYPAL-AUTH-ALGO` response header, which is received with the webhook notification." }, "cert_url": { "type": "string", "maxLength": 500, "format": "uri", "description": "The X.509 public key certificate. Download the certificate from this URL and use it to verify the signature. Extract this value from the `PAYPAL-CERT-URL` response header, which is received with the webhook notification." }, "transmission_id": { "type": "string", "maxLength": 50, "pattern": "^(?!\\d+$)\\w+\\S+", "description": "The ID of the HTTP transmission. Contained in the `PAYPAL-TRANSMISSION-ID` header of the notification message." }, "transmission_sig": { "type": "string", "maxLength": 500, "pattern": "^(?!\\d+$)\\w+\\S+", "description": "The PayPal-generated asymmetric signature. Appears in the `PAYPAL-TRANSMISSION-SIG` header of the notification message." }, "transmission_time": { "type": "string", "maxLength": 100, "format": "date-time", "description": "The date and time of the HTTP transmission, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). Appears in the `PAYPAL-TRANSMISSION-TIME` header of the notification message." }, "webhook_id": { "type": "string", "maxLength": 50, "pattern": "^[a-zA-Z0-9]+$", "description": "The ID of the webhook as configured in your Developer Portal account." }, "webhook_event": { "$ref": "#/components/schemas/event" } }, "required": [ "auth_algo", "cert_url", "transmission_id", "transmission_sig", "transmission_time", "webhook_id", "webhook_event" ] }, "verify_webhook_signature_response": { "type": "object", "title": "Verify Webhook Signature Response", "description": "The verify webhook signature response.", "properties": { "verification_status": { "type": "string", "description": "The status of the signature verification.", "enum": ["SUCCESS", "FAILURE"] } }, "required": ["verification_status"] }, "webhook": { "type": "object", "title": "Webhook", "description": "One or more webhook objects.", "properties": { "id": { "type": "string", "description": "The ID of the webhook.", "readOnly": true }, "url": { "type": "string", "format": "uri", "description": "The URL that is configured to listen on `localhost` for incoming `POST` notification messages that contain event information.", "readOnly": false, "maxLength": 2048 }, "event_types": { "$ref": "#/components/schemas/definitions-event_type_list" }, "links": { "$ref": "#/components/schemas/definitions-link_description_list" } }, "required": ["url", "event_types"] }, "webhook_ids": { "type": "string", "description": "The ID of the webhook event notification to resend." }, "webhook_ids_list": { "type": "array", "maxItems": 500, "description": "An array of webhook account IDs.", "items": { "$ref": "#/components/schemas/webhook_ids" } }, "webhook_list": { "type": "array", "description": "An array of webhooks.", "items": { "$ref": "#/components/schemas/webhook" } }, "webhooks_lookup": { "type": "object", "title": "Webhook Lookup", "description": "The webhook lookup details.", "properties": { "id": { "type": "string", "description": "The ID of the webhook lookup.", "readOnly": true }, "client_id": { "type": "string", "pattern": "^(?!\\d+$)\\w+\\S+", "maxLength": 128, "description": "The application client ID.", "readOnly": true }, "links": { "$ref": "#/components/schemas/definitions-link_description_list" } } }, "webhooks_lookup_list": { "type": "array", "description": "An array of webhook lookups.", "items": { "$ref": "#/components/schemas/webhooks_lookup" } } }, "parameters": { "anchor_type": { "name": "anchor_type", "in": "query", "description": "Filters the webhooks in the response by an `anchor_id` entity type.", "schema": { "type": "string", "enum": ["APPLICATION", "ACCOUNT"], "default": "APPLICATION" } }, "webhook_id": { "name": "webhook_id", "in": "path", "description": "The ID of the webhook for which to list subscriptions.", "required": true, "schema": { "type": "string" } }, "webhook_lookup_id": { "name": "webhook_lookup_id", "in": "path", "description": "The ID of the webhook lookup to delete.", "required": true, "schema": { "type": "string" } }, "page_size": { "name": "page_size", "in": "query", "description": "The number of webhook event notifications to return in the response.", "schema": { "type": "integer", "default": 10 } }, "start_time": { "name": "start_time", "in": "query", "description": "Filters the webhook event notifications in the response to those created on or after this date and time and on or before the `end_time` value. Both values are in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6) format. Example: `start_time=2013-03-06T11:00:00Z`.", "schema": { "type": "string" } }, "end_time": { "name": "end_time", "in": "query", "description": "Filters the webhook event notifications in the response to those created on or after the `start_time` and on or before this date and time. Both values are in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6) format. Example: `end_time=2013-03-06T11:00:00Z`.", "schema": { "type": "string" } }, "transaction_id": { "name": "transaction_id", "in": "query", "description": "Filters the response to a single transaction, by ID.", "schema": { "type": "string" } }, "event_type": { "name": "event_type", "in": "query", "description": "Filters the response to a single event.", "schema": { "type": "string" } }, "event_id": { "name": "event_id", "in": "path", "description": "The ID of the webhook event notification to resend.", "required": true, "schema": { "type": "string", "maxLength": 50, "pattern": "^[a-zA-Z0-9]+$" } } } } }