openapi: 3.0.3 info: title: Paypal Subscriptions Authorizations Captures API description: You can use billing plans and subscriptions to create subscriptions that process recurring PayPal payments for physical or digital goods, or services. A plan includes pricing and billing cycle information that defines the amount and frequency of charge for a subscription. You can also define a fixed plan, such as a $5 basic plan or a volume- or graduated-based plan with pricing tiers based on the quantity purchased. For more information, see Subscriptions Overview. version: '1.6' 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: Captures description: Use the `/captures` resource to show details for and refund a captured payment. paths: /v2/payments/captures/{capture_id}: get: summary: Paypal Show captured payment details description: Shows details for a captured payment, by ID. operationId: captures.get parameters: - $ref: '#/components/parameters/capture_id' responses: '200': description: A successful request returns the HTTP 200 OK status code and a JSON response body that shows captured payment details. content: application/json: schema: $ref: '#/components/schemas/capture-2' '401': description: Authentication failed due to missing authorization header, or invalid authentication credentials. content: application/json: schema: $ref: '#/components/schemas/error_401' '403': description: The request failed because the caller has insufficient permissions. content: application/json: schema: allOf: - $ref: '#/components/schemas/error_403' - $ref: '#/components/schemas/403' '404': description: The request failed because the resource does not exist. content: application/json: schema: allOf: - $ref: '#/components/schemas/error_404' - $ref: '#/components/schemas/404' '500': description: The request failed because an internal server error occurred. default: $ref: '#/components/responses/default' tags: - Captures security: - Oauth2: - https://uri.paypal.com/services/payments/payment/authcapture /v2/payments/captures/{capture_id}/refund: post: summary: Paypal Refund captured payment description: Refunds a captured payment, by ID. For a full refund, include an empty payload in the JSON request body. For a partial refund, include an amount object in the JSON request body. operationId: captures.refund parameters: - $ref: '#/components/parameters/capture_id' - $ref: '#/components/parameters/paypal_request_id' - $ref: '#/components/parameters/prefer' - $ref: '#/components/parameters/paypal_auth_assertion' requestBody: content: application/json: schema: $ref: '#/components/schemas/refund_request' examples: refund_request: value: amount: value: '10.00' currency_code: USD invoice_id: INVOICE-123 note_to_payer: DefectiveProduct payment_instruction: platform_fees: - amount: currency_code: USD value: '1.00' responses: '201': description: A successful request returns the HTTP 201 Created status code and a JSON response body that shows refund details. content: application/json: schema: $ref: '#/components/schemas/refund' '400': description: The request failed because it is not well-formed or is syntactically incorrect or violates schema. content: application/json: schema: allOf: - $ref: '#/components/schemas/error_400' - $ref: '#/components/schemas/captures.refund-400' '401': description: Authentication failed due to missing authorization header, or invalid authentication credentials. content: application/json: schema: allOf: - $ref: '#/components/schemas/error_401' - $ref: '#/components/schemas/401' '403': description: The request failed because the caller has insufficient permissions. content: application/json: schema: allOf: - $ref: '#/components/schemas/error_403' - $ref: '#/components/schemas/403' '404': description: The request failed because the resource does not exist. content: application/json: schema: allOf: - $ref: '#/components/schemas/error_404' - $ref: '#/components/schemas/404' '409': description: The request failed because a previous call for the given resource is in progress. content: application/json: schema: allOf: - $ref: '#/components/schemas/error_409' - $ref: '#/components/schemas/409' '422': description: The request failed because it either is semantically incorrect or failed business validation. content: application/json: schema: allOf: - $ref: '#/components/schemas/error_422' - $ref: '#/components/schemas/captures.refund-422' '500': description: The request failed because an internal server error occurred. default: $ref: '#/components/responses/default' tags: - Captures security: - Oauth2: - https://uri.paypal.com/services/payments/refund components: schemas: 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' payment_instruction-2: type: object title: Payment Instruction description: Any additional payments instructions during refund payment processing. This object is only applicable to merchants that have been enabled for PayPal Commerce Platform for Marketplaces and Platforms capability. Please speak to your account manager if you want to use this capability. properties: platform_fees: type: array description: Specifies the amount that the API caller will contribute to the refund being processed. The amount needs to be lower than platform_fees amount originally captured or the amount that is remaining if multiple refunds have been processed. This field is only applicable to merchants that have been enabled for PayPal Commerce Platform for Marketplaces and Platforms capability. Please speak to your account manager if you want to use this capability. minItems: 0 maxItems: 1 items: $ref: '#/components/schemas/platform_fee' disbursement_mode: type: string title: Disbursement Mode description: The funds that are held on behalf of the merchant. default: INSTANT minLength: 1 maxLength: 16 pattern: ^[A-Z_]+$ enum: - INSTANT - DELAYED 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' supplementary_data: title: Supplementary Data type: object description: The supplementary data. properties: related_ids: description: Identifiers related to a specific resource. readOnly: true $ref: '#/components/schemas/related_ids' net_amount_breakdown_item: type: object title: Net Amount Breakdown Item description: The net amount. Returned when the currency of the refund is different from the currency of the PayPal account where the merchant holds their funds. properties: payable_amount: description: The net amount debited from the merchant's PayPal account. readOnly: true $ref: '#/components/schemas/money' converted_amount: description: The converted payable amount. readOnly: true $ref: '#/components/schemas/money' exchange_rate: description: The exchange rate that determines the amount that was debited from the merchant's PayPal account. readOnly: true $ref: '#/components/schemas/exchange_rate' '403': properties: details: type: array items: anyOf: - title: PERMISSION_DENIED properties: issue: type: string enum: - PERMISSION_DENIED description: type: string enum: - You do not have permission to access or perform operations on this resource. account_id: type: string title: PayPal Account Identifier description: The account identifier for a PayPal account. format: ppaas_payer_id_v3 minLength: 13 maxLength: 13 pattern: ^[2-9A-HJ-NP-Z]{13}$ link_description: type: object title: Link Description description: The request-related [HATEOAS link](/api/rest/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_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' capture: type: object title: Capture description: A captured payment. allOf: - $ref: '#/components/schemas/capture_status' - properties: id: description: The PayPal-generated ID for the captured payment. type: string readOnly: true amount: description: The amount for this captured payment. $ref: '#/components/schemas/money' readOnly: true invoice_id: description: The API caller-provided external invoice number for this order. Appears in both the payer's transaction history and the emails that the payer receives. type: string readOnly: true custom_id: type: string description: The API caller-provided external ID. Used to reconcile API caller-initiated transactions with PayPal transactions. Appears in transaction and settlement reports. maxLength: 127 network_transaction_reference: $ref: '#/components/schemas/network_transaction_reference' seller_protection: $ref: '#/components/schemas/seller_protection' readOnly: true final_capture: description: Indicates whether you can make additional captures against the authorized payment. Set to `true` if you do not intend to capture additional payments against the authorization. Set to `false` if you intend to capture additional payments against the authorization. type: boolean default: false readOnly: true seller_receivable_breakdown: $ref: '#/components/schemas/seller_receivable_breakdown' readOnly: true disbursement_mode: $ref: '#/components/schemas/disbursement_mode' links: description: An array of related [HATEOAS links](/docs/api/reference/api-responses/#hateoas-links). type: array readOnly: true items: $ref: '#/components/schemas/link_description' processor_response: description: An object that provides additional processor information for a direct credit card transaction. $ref: '#/components/schemas/processor_response' - $ref: '#/components/schemas/activity_timestamps' card_brand: type: string title: Card Brand description: The card network or brand. Applies to credit, debit, gift, and payment cards. minLength: 1 maxLength: 255 pattern: ^[A-Z_]+$ enum: - VISA - MASTERCARD - DISCOVER - AMEX - SOLO - JCB - STAR - DELTA - SWITCH - MAESTRO - CB_NATIONALE - CONFIGOGA - CONFIDIS - ELECTRON - CETELEM - CHINA_UNION_PAY 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' exchange_rate: description: The exchange rate that determines the amount to convert from one currency to another currency. type: object title: Exchange Rate properties: source_currency: description: The source currency from which to convert an amount. $ref: '#/components/schemas/currency_code' target_currency: description: The target currency to which to convert an amount. $ref: '#/components/schemas/currency_code' value: description: The target currency amount. Equivalent to one unit of the source currency. Formatted as integer or decimal value with one to 15 digits to the right of the decimal point. type: string readOnly: true 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_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 refund_request: title: Refund Request type: object description: Refunds a captured payment, by ID. For a full refund, include an empty request body. For a partial refund, include an amount object in the request body. properties: amount: description: The amount to refund. To refund a portion of the captured amount, specify an amount. If amount is not specified, an amount equal to captured amount - previous refunds is refunded. The amount must be a positive number and in the same currency as the one in which the payment was captured. $ref: '#/components/schemas/money' custom_id: type: string description: The API caller-provided external ID. Used to reconcile API caller-initiated transactions with PayPal transactions. Appears in transaction and settlement reports. The pattern is defined by an external party and supports Unicode. minLength: 1 maxLength: 127 pattern: ^.*$ invoice_id: type: string description: The API caller-provided external invoice ID for this order. The pattern is defined by an external party and supports Unicode. minLength: 1 maxLength: 127 pattern: ^.*$ note_to_payer: type: string description: The reason for the refund. Appears in both the payer's transaction history and the emails that the payer receives. The pattern is defined by an external party and supports Unicode. minLength: 1 maxLength: 255 pattern: ^.*$ payment_instruction: description: Any additional refund instructions to be set during refund payment processing. This object is only applicable to merchants that have been enabled for PayPal Commerce Platform for Marketplaces and Platforms capability. Please speak to your account manager if you want to use this capability. $ref: '#/components/schemas/payment_instruction-2' refund: type: object title: Refund description: The refund information. allOf: - $ref: '#/components/schemas/refund_status' - properties: id: description: The PayPal-generated ID for the refund. type: string readOnly: true amount: description: The amount that the payee refunded to the payer. $ref: '#/components/schemas/money' readOnly: true invoice_id: description: The API caller-provided external invoice number for this order. Appears in both the payer's transaction history and the emails that the payer receives. type: string readOnly: true custom_id: type: string description: The API caller-provided external ID. Used to reconcile API caller-initiated transactions with PayPal transactions. Appears in transaction and settlement reports. minLength: 1 maxLength: 127 pattern: ^[A-Za-z0-9-_.,]*$ acquirer_reference_number: type: string description: Reference ID issued for the card transaction. This ID can be used to track the transaction across processors, card brands and issuing banks. minLength: 1 maxLength: 36 pattern: ^[a-zA-Z0-9]+$ note_to_payer: description: The reason for the refund. Appears in both the payer's transaction history and the emails that the payer receives. type: string readOnly: true seller_payable_breakdown: description: The breakdown of the refund. type: object title: Merchant Payable Breakdown properties: gross_amount: description: The amount that the payee refunded to the payer. $ref: '#/components/schemas/money' readOnly: true paypal_fee: description: The PayPal fee that was refunded to the payer in the currency of the transaction. This fee might not match the PayPal fee that the payee paid when the payment was captured. $ref: '#/components/schemas/money' readOnly: true paypal_fee_in_receivable_currency: description: The PayPal fee that was refunded to the payer in the receivable currency. Returned only in cases when the receivable currency is different from transaction currency. Example 'CNY'. $ref: '#/components/schemas/money' readOnly: true net_amount: description: The net amount that the payee's account is debited in the transaction currency. The net amount is calculated as gross_amount minus paypal_fee minus platform_fees. $ref: '#/components/schemas/money' readOnly: true net_amount_in_receivable_currency: description: The net amount that the payee's account is debited in the receivable currency. Returned only in cases when the receivable currency is different from transaction currency. Example 'CNY'. $ref: '#/components/schemas/money' readOnly: true platform_fees: type: array description: An array of platform or partner fees, commissions, or brokerage fees for the refund. minItems: 0 maxItems: 1 items: $ref: '#/components/schemas/platform_fee' net_amount_breakdown: type: array description: An array of breakdown values for the net amount. Returned when the currency of the refund is different from the currency of the PayPal account where the payee holds their funds. items: $ref: '#/components/schemas/net_amount_breakdown_item' readOnly: true total_refunded_amount: description: The total amount refunded from the original capture to date. For example, if a payer makes a $100 purchase and was refunded $20 a week ago and was refunded $30 in this refund, the `gross_amount` is $30 for this refund and the `total_refunded_amount` is $50. $ref: '#/components/schemas/money' readOnly: true payer: description: The details associated with the merchant for this transaction. $ref: '#/components/schemas/payee_base' readOnly: true links: description: An array of related [HATEOAS links](/docs/api/reference/api-responses/#hateoas-links). type: array readOnly: true items: $ref: '#/components/schemas/link_description' - $ref: '#/components/schemas/activity_timestamps' processor_response: type: object title: Processor Response description: The processor response information for payment requests, such as direct credit card transactions. properties: avs_code: description: The address verification code for Visa, Discover, Mastercard, or American Express transactions. type: string readOnly: true enum: - A - B - C - D - E - F - G - I - M - N - P - R - S - U - W - X - Y - Z - 'Null' - '0' - '1' - '2' - '3' - '4' cvv_code: description: The card verification value code for for Visa, Discover, Mastercard, or American Express. type: string readOnly: true enum: - E - I - M - N - P - S - U - X - All others - '0' - '1' - '2' - '3' - '4' response_code: description: Processor response code for the non-PayPal payment processor errors. type: string readOnly: true enum: - '0000' - 00N7 - '0100' - 0390 - '0500' - 0580 - 0800 - 0880 - 0890 - 0960 - 0R00 - '1000' - 10BR - '1300' - '1310' - '1312' - '1317' - '1320' - '1330' - '1335' - '1340' - '1350' - '1352' - '1360' - '1370' - '1380' - '1382' - '1384' - '1390' - '1393' - '5100' - '5110' - '5120' - '5130' - '5135' - '5140' - '5150' - '5160' - '5170' - '5180' - '5190' - '5200' - '5210' - '5400' - '5500' - '5650' - '5700' - '5710' - '5800' - '5900' - '5910' - '5920' - '5930' - '5950' - '6300' - '7600' - '7700' - '7710' - '7800' - '7900' - '8000' - '8010' - '8020' - '8030' - '8100' - '8110' - '8220' - '9100' - '9500' - '9510' - '9520' - '9530' - '9540' - '9600' - PCNR - PCVV - PP06 - PPRN - PPAD - PPAB - PPAE - PPAG - PPAI - PPAR - PPAU - PPAV - PPAX - PPBG - PPC2 - PPCE - PPCO - PPCR - PPCT - PPCU - PPD3 - PPDC - PPDI - PPDV - PPDT - PPEF - PPEL - PPER - PPEX - PPFE - PPFI - PPFR - PPFV - PPGR - PPH1 - PPIF - PPII - PPIM - PPIT - PPLR - PPLS - PPMB - PPMC - PPMD - PPNC - PPNL - PPNM - PPNT - PPPH - PPPI - PPPM - PPQC - PPRE - PPRF - PPRR - PPS0 - PPS1 - PPS2 - PPS3 - PPS4 - PPS5 - PPS6 - PPSC - PPSD - PPSE - PPTE - PPTF - PPTI - PPTR - PPTT - PPTV - PPUA - PPUC - PPUE - PPUI - PPUP - PPUR - PPVC - PPVE - PPVT payment_advice_code: description: The declined payment transactions might have payment advice codes. The card networks, like Visa and Mastercard, return payment advice codes. type: string readOnly: true enum: - '01' - '02' - '03' - '21' related_ids: type: object title: Related Identifiers description: Identifiers related to a specific resource. properties: order_id: type: string description: Order ID related to the resource. minLength: 1 maxLength: 20 pattern: ^[A-Z0-9]+$ authorization_id: type: string description: Authorization ID related to the resource. minLength: 1 maxLength: 20 pattern: ^[A-Z0-9]+$ capture_id: type: string description: Capture ID related to the resource. minLength: 1 maxLength: 20 pattern: ^[A-Z0-9]+$ error_default: description: The default error response. oneOf: - $ref: '#/components/schemas/error_400' - $ref: '#/components/schemas/error_401' - $ref: '#/components/schemas/error_403' - $ref: '#/components/schemas/error_404' - $ref: '#/components/schemas/error_409' - $ref: '#/components/schemas/error_415' - $ref: '#/components/schemas/error_422' - $ref: '#/components/schemas/error_500' - $ref: '#/components/schemas/error_503' 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 money: type: object title: Money description: The currency and amount for a financial transaction, such as a balance or payment due. properties: currency_code: $ref: '#/components/schemas/currency_code' value: type: string description: The value, which might be:For the required number of decimal places for a currency code, see [Currency Codes](/api/rest/reference/currency-codes/). maxLength: 32 pattern: ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$ required: - currency_code - value capture_status_details: title: Capture Status Details description: The details of the captured payment status. type: object properties: reason: description: The reason why the captured payment status is `PENDING` or `DENIED`. type: string minLength: 1 maxLength: 64 pattern: ^[A-Z_]+$ enum: - BUYER_COMPLAINT - CHARGEBACK - ECHECK - INTERNATIONAL_WITHDRAWAL - OTHER - PENDING_REVIEW - RECEIVING_PREFERENCE_MANDATES_MANUAL_ACTION - REFUNDED - TRANSACTION_APPROVED_AWAITING_FUNDING - UNILATERAL - VERIFICATION_REQUIRED '401': properties: details: type: array items: anyOf: - title: INVALID_ACCOUNT_STATUS properties: issue: type: string enum: - INVALID_ACCOUNT_STATUS description: type: string enum: - Account validations failed for the user. '409': properties: details: type: array items: anyOf: - title: PREVIOUS_REQUEST_IN_PROGRESS properties: issue: type: string enum: - PREVIOUS_REQUEST_IN_PROGRESS description: type: string enum: - A previous request on this resource is currently in progress. Please wait for sometime and try again. It is best to space out the initial and the subsequent request(s) to avoid receiving this error. payee_base: type: object title: Merchant Base description: The details for the merchant who receives the funds and fulfills the order. The merchant is also known as the payee. properties: email_address: description: The email address of merchant. $ref: '#/components/schemas/email' merchant_id: description: The encrypted PayPal account ID of the merchant. $ref: '#/components/schemas/account_id' seller_receivable_breakdown: type: object title: Seller Receivable Breakdown description: The detailed breakdown of the capture activity. This is not available for transactions that are in pending state. properties: gross_amount: description: The amount for this captured payment in the currency of the transaction. $ref: '#/components/schemas/money' paypal_fee: description: The applicable fee for this captured payment in the currency of the transaction. $ref: '#/components/schemas/money' paypal_fee_in_receivable_currency: description: The applicable fee for this captured payment in the receivable currency. Returned only in cases the fee is charged in the receivable currency. Example 'CNY'. $ref: '#/components/schemas/money' net_amount: description: The net amount that the payee receives for this captured payment in their PayPal account. The net amount is computed as gross_amount minus the paypal_fee minus the platform_fees. $ref: '#/components/schemas/money' receivable_amount: description: The net amount that is credited to the payee's PayPal account. Returned only when the currency of the captured payment is different from the currency of the PayPal account where the payee wants to credit the funds. The amount is computed as net_amount times exchange_rate. $ref: '#/components/schemas/money' exchange_rate: description: The exchange rate that determines the amount that is credited to the payee's PayPal account. Returned when the currency of the captured payment is different from the currency of the PayPal account where the payee wants to credit the funds. $ref: '#/components/schemas/exchange_rate' platform_fees: type: array description: An array of platform or partner fees, commissions, or brokerage fees that associated with the captured payment. minItems: 0 maxItems: 1 items: $ref: '#/components/schemas/platform_fee' required: - gross_amount 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_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' currency_code: description: The [three-character ISO-4217 currency code](/api/rest/reference/currency-codes/) that identifies the currency. type: string format: ppaas_common_currency_code_v2 minLength: 3 maxLength: 3 network_transaction_reference: type: object title: Network Transaction Reference description: Reference values used by the card network to identify a transaction. properties: id: type: string minLength: 9 maxLength: 36 pattern: ^[a-zA-Z0-9-]+$ description: Transaction reference id returned by the scheme. For Visa and Amex, this is the "Tran id" field in response. For MasterCard, this is the "BankNet reference id" field in response. For Discover, this is the "NRID" field in response. The pattern we expect for this field from Visa/Amex/CB/Discover is numeric, Mastercard/BNPP is alphanumeric and Paysecure is alphanumeric with special character -. date: type: string minLength: 4 maxLength: 4 pattern: ^[0-9]+$ description: The date that the transaction was authorized by the scheme. This field may not be returned for all networks. MasterCard refers to this field as "BankNet reference date. network: description: Name of the card network through which the transaction was routed. $ref: '#/components/schemas/card_brand' acquirer_reference_number: type: string description: Reference ID issued for the card transaction. This ID can be used to track the transaction across processors, card brands and issuing banks. minLength: 1 maxLength: 36 pattern: ^[a-zA-Z0-9]+$ required: - id captures.refund-422: properties: details: type: array items: anyOf: - title: CANNOT_BE_ZERO_OR_NEGATIVE properties: issue: type: string enum: - CANNOT_BE_ZERO_OR_NEGATIVE description: type: string - title: DECIMAL_PRECISION properties: issue: type: string enum: - DECIMAL_PRECISION description: type: string - title: DECIMALS_NOT_SUPPORTED properties: issue: type: string enum: - DECIMALS_NOT_SUPPORTED description: type: string - title: INVALID_CURRENCY_CODE properties: issue: type: string enum: - INVALID_CURRENCY_CODE description: type: string - title: CURRENCY_MISMATCH properties: issue: type: string enum: - CURRENCY_MISMATCH description: type: string - title: CANNOT_BE_NEGATIVE properties: issue: type: string enum: - CANNOT_BE_NEGATIVE description: type: string - title: CAPTURE_FULLY_REFUNDED properties: issue: type: string enum: - CAPTURE_FULLY_REFUNDED description: type: string enum: - The capture has already been fully refunded - title: REFUND_CAPTURE_CURRENCY_MISMATCH properties: issue: type: string enum: - REFUND_CAPTURE_CURRENCY_MISMATCH description: type: string enum: - Refund must be in the same currency as the capture - title: REFUND_NOT_ALLOWED properties: issue: type: string enum: - REFUND_NOT_ALLOWED description: type: string enum: - Capture cannot be refunded. - title: REFUND_TIME_LIMIT_EXCEEDED properties: issue: type: string enum: - REFUND_TIME_LIMIT_EXCEEDED description: type: string enum: - You are over the time limit to perform a refund on this capture - title: REFUND_AMOUNT_EXCEEDED properties: issue: type: string enum: - REFUND_AMOUNT_EXCEEDED description: type: string enum: - The refund amount must be less than or equal to the capture amount that has not yet been refunded. - title: REFUND_AMOUNT_TOO_LOW properties: issue: type: string enum: - REFUND_AMOUNT_TOO_LOW description: type: string enum: - The amount after applying currency conversion is zero and hence the capture cannot be refunded. The currency conversion is required because the currency of the capture is different than the currency in which the amount was settled into the payee account. - title: REFUND_FAILED_INSUFFICIENT_FUNDS properties: issue: type: string enum: - REFUND_FAILED_INSUFFICIENT_FUNDS description: type: string enum: - Capture could not be refunded due to insufficient funds. Please check to see if you have sufficient funds in your PayPal account or if the bank account linked to your PayPal account is verified and has sufficient funds. - title: PARTIAL_REFUND_NOT_ALLOWED properties: issue: type: string enum: - PARTIAL_REFUND_NOT_ALLOWED description: type: string enum: - You cannot do a refund less than the original capture amount. - title: MAX_NUMBER_OF_REFUNDS_EXCEEDED properties: issue: type: string enum: - MAX_NUMBER_OF_REFUNDS_EXCEEDED description: type: string enum: - You have exceeded the maximum number of refund attempts for this capture. - title: PENDING_CAPTURE properties: issue: type: string enum: - PENDING_CAPTURE description: type: string enum: - Cannot initiate a refund as the capture is pending. Capture is typically pending when the payer has funded the transaction using e-check/bank funded. - title: DUPLICATE_INVOICE_ID properties: issue: type: string enum: - DUPLICATE_INVOICE_ID description: type: string enum: - Invoice ID was previously used to refund a capture. - title: PAYEE_ACCOUNT_LOCKED_OR_CLOSED properties: issue: type: string enum: - PAYEE_ACCOUNT_LOCKED_OR_CLOSED description: type: string enum: - Transaction could not complete because payee account is locked or closed. - title: PAYER_ACCOUNT_LOCKED_OR_CLOSED properties: issue: type: string enum: - PAYER_ACCOUNT_LOCKED_OR_CLOSED description: type: string enum: - The payer account cannot be used for this transaction. - title: PAYEE_ACCOUNT_RESTRICTED properties: issue: type: string enum: - PAYEE_ACCOUNT_RESTRICTED description: type: string enum: - Payee account is restricted. - title: REFUND_NOT_PERMITTED_DUE_TO_CHARGEBACK properties: issue: type: string enum: - REFUND_NOT_PERMITTED_DUE_TO_CHARGEBACK description: type: string enum: - Refunds are not allowed on this capture due to a chargeback on the card or bank. Please contact the payee to resolve the chargeback. - title: TRANSACTION_DISPUTED properties: issue: type: string enum: - TRANSACTION_DISPUTED description: type: string enum: - Partial refunds cannot be offered at this time because there is an open case on this transaction. Visit the PayPal Resolution Center to review this case. - title: PLATFORM_FEE_EXCEEDED properties: issue: type: string enum: - PLATFORM_FEE_EXCEEDED description: type: string enum: - Platform fee amount specified exceeds the amount that is available for refund. You can only refund up to the available platform fee amount. This error is also returned when no platform_fee was specified or was zero when the payment was captured. - title: REFUND_IS_RESTRICTED properties: issue: type: string enum: - REFUND_IS_RESTRICTED description: type: string enum: - This refund can only be processed by the API caller that had 'captured' the transaction. If you facilitate your transactions via a platform/partner, please initiate a refund through them. - title: PLATFORM_FEE_NOT_ENABLED properties: issue: type: string enum: - PLATFORM_FEE_NOT_ENABLED description: type: string enum: - The API Caller account is not setup to be able to process refunds with 'platform_fees'. Please contact your Account Manager. This feature is useful when you want to contribute a portion of the 'platform_fees' you had capture as part of the refund being processed. platform_fee: type: object title: Platform Fee description: The platform or partner fee, commission, or brokerage fee that is associated with the transaction. Not a separate or isolated transaction leg from the external perspective. The platform fee is limited in scope and is always associated with the original payment for the purchase unit. properties: amount: description: The fee for this transaction. $ref: '#/components/schemas/money' payee: description: The recipient of the fee for this transaction. If you omit this value, the default is the API caller. $ref: '#/components/schemas/payee_base' required: - amount 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' refund_status_details: title: Refund Status Details description: The details of the refund status. type: object properties: reason: description: The reason why the refund has the `PENDING` or `FAILED` status. type: string enum: - ECHECK captures.refund-400: properties: details: type: array items: anyOf: - title: MISSING_REQUIRED_PARAMETER properties: issue: type: string enum: - MISSING_REQUIRED_PARAMETER description: type: string - title: INVALID_PARAMETER_SYNTAX properties: issue: type: string enum: - INVALID_PARAMETER_SYNTAX description: type: string - title: INVALID_STRING_LENGTH properties: issue: type: string enum: - INVALID_STRING_LENGTH description: type: string seller_protection: type: object description: The level of protection offered as defined by [PayPal Seller Protection for Merchants](https://www.paypal.com/us/webapps/mpp/security/seller-protection). title: Seller Protection properties: status: type: string description: Indicates whether the transaction is eligible for seller protection. For information, see [PayPal Seller Protection for Merchants](https://www.paypal.com/us/webapps/mpp/security/seller-protection). readOnly: true enum: - ELIGIBLE - PARTIALLY_ELIGIBLE - NOT_ELIGIBLE dispute_categories: type: array description: An array of conditions that are covered for the transaction. items: type: string description: The condition that is covered for the transaction. enum: - ITEM_NOT_RECEIVED - UNAUTHORIZED_TRANSACTION readOnly: true refund_status: type: object description: The refund status. title: Refund Status properties: status: description: The status of the refund. type: string readOnly: true enum: - CANCELLED - FAILED - PENDING - COMPLETED status_details: description: The details of the refund status. readOnly: true $ref: '#/components/schemas/refund_status_details' '404': properties: details: type: array items: anyOf: - title: INVALID_RESOURCE_ID properties: issue: type: string enum: - INVALID_RESOURCE_ID description: type: string enum: - Specified resource ID does not exist. Please check the resource ID and try again. 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' email: type: string description: The internationalized email address.
Note: Up to 64 characters are allowed before and 255 characters are allowed after the @ sign. However, the generally accepted maximum length for an email address is 254 characters. The pattern verifies that an unquoted @ sign exists.
format: merchant_common_email_address_v2 maxLength: 254 minLength: 3 pattern: (?:[a-zA-Z0-9!#$%&'*+/=?^_`{|}~-]+(?:\.[a-zA-Z0-9!#$%&'*+/=?^_`{|}~-]+)*|(?:[\x01-\x08\x0b\x0c\x0e-\x1f\x21\x23-\x5b\x5d-\x7f]|\[\x01-\x09\x0b\x0c\x0e-\x7f])*")@(?:(?:[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?\.)+[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?|\[(?:(?:(2(5[0-5]|[0-4][0-9])|1[0-9][0-9]|[1-9]?[0-9]))\.){3}(?:(2(5[0-5]|[0-4][0-9])|1[0-9][0-9]|[1-9]?[0-9])|[a-zA-Z0-9-]*[a-zA-Z0-9]:(?:[\x01-\x08\x0b\x0c\x0e-\x1f\x21-\x5a\x53-\x7f]|\[\x01-\x09\x0b\x0c\x0e-\x7f])+)\]) activity_timestamps: type: object description: The date and time stamps that are common to authorized payment, captured payment, and refund transactions. title: Transaction Date and Time Stamps properties: create_time: description: The date and time when the transaction occurred, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). readOnly: true $ref: '#/components/schemas/date_time' update_time: description: The date and time when the transaction was last updated, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). readOnly: true $ref: '#/components/schemas/date_time' capture-2: type: object title: Capture description: A captured payment. allOf: - $ref: '#/components/schemas/capture' - properties: supplementary_data: description: An object that provides supplementary/additional data related to a payment transaction. readOnly: true $ref: '#/components/schemas/supplementary_data' payee: description: The details associated with the merchant for this transaction. $ref: '#/components/schemas/payee_base' readOnly: true 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 date_time: type: string description: The date and time, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). Seconds are required while fractional seconds are optional.
Note: The regular expression provides guidance but does not reject all invalid dates.
format: ppaas_date_time_v3 minLength: 20 maxLength: 64 pattern: ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])[T,t]([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)([.][0-9]+)?([Zz]|[+-][0-9]{2}:[0-9]{2})$ capture_status: type: object title: Capture Status description: The status of a captured payment. properties: status: description: The status of the captured payment. type: string readOnly: true enum: - COMPLETED - DECLINED - PARTIALLY_REFUNDED - PENDING - REFUNDED - FAILED status_details: description: The details of the captured payment status. readOnly: true $ref: '#/components/schemas/capture_status_details' parameters: capture_id: name: capture_id in: path description: The PayPal-generated ID for the captured payment to refund. required: true schema: type: string paypal_auth_assertion: name: PayPal-Auth-Assertion in: header description: An API-caller-provided JSON Web Token (JWT) assertion that identifies the merchant. For details, see [PayPal-Auth-Assertion](/docs/api/reference/api-requests/#paypal-auth-assertion).
Note:For three party transactions in which a partner is managing the API calls on behalf of a merchant, the partner must identify the merchant using either a PayPal-Auth-Assertion header or an access token with target_subject.
required: false schema: type: string prefer: name: Prefer in: header description: The preferred server response upon successful completion of the request. Value is: required: false schema: type: string default: return=minimal paypal_request_id: name: PayPal-Request-Id in: header description: The server stores keys for 45 days. required: false schema: type: string responses: default: description: The default response. content: application/json: schema: $ref: '#/components/schemas/error_default' securitySchemes: Oauth2: type: oauth2 description: Oauth 2.0 authentication flows: clientCredentials: tokenUrl: /v1/oauth2/token scopes: https://uri.paypal.com/services/subscriptions: Manage plan & subscription externalDocs: url: https://developer.paypal.com/docs/api/subscriptions/v1/