openapi: 3.0.3
info:
title: Paypal Subscriptions Authorizations 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 <a href="/docs/subscriptions/">Subscriptions Overview</a>.
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: Authorizations
description: Use the `/authorizations` resource to show details for, capture payment for, reauthorize, and void authorized payments.
paths:
/v2/payments/authorizations/{authorization_id}:
get:
summary: Paypal Show details for authorized payment
description: Shows details for an authorized payment, by ID.
operationId: authorizations.get
parameters:
- $ref: '#/components/parameters/authorization_id'
responses:
'200':
description: A successful request returns the HTTP <code>200 OK</code> status code and a JSON response body that shows authorization details.
content:
application/json:
schema:
$ref: '#/components/schemas/authorization-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:
- Authorizations
security:
- Oauth2:
- https://uri.paypal.com/services/payments/payment/authcapture
/v2/payments/authorizations/{authorization_id}/capture:
post:
summary: Paypal Capture authorized payment
description: Captures an authorized payment, by ID.
operationId: authorizations.capture
parameters:
- $ref: '#/components/parameters/authorization_id'
- $ref: '#/components/parameters/paypal_request_id'
- $ref: '#/components/parameters/prefer'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/capture_request'
examples:
capture_request:
value:
amount:
value: '10.99'
currency_code: USD
invoice_id: INVOICE-123
final_capture: true
note_to_payer: If the ordered color is not available, we will substitute with a different color free of charge.
soft_descriptor: Bob's Custom Sweaters
responses:
'201':
description: A successful request returns the HTTP <code>201 Created</code> status code and a JSON response body that shows captured payment details.
content:
application/json:
schema:
$ref: '#/components/schemas/capture-2'
'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/400'
'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'
'422':
description: The request failed because it is semantically incorrect or failed business validation.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/error_422'
- $ref: '#/components/schemas/422'
'500':
description: The request failed because an internal server error occurred.
default:
$ref: '#/components/responses/default'
tags:
- Authorizations
security:
- Oauth2:
- https://uri.paypal.com/services/payments/payment/authcapture
/v2/payments/authorizations/{authorization_id}/reauthorize:
post:
summary: Paypal Reauthorize authorized payment
description: Reauthorizes an authorized PayPal account payment, by ID. To ensure that funds are still available, reauthorize a payment after its initial three-day honor period expires. Within the 29-day authorization period, you can issue multiple re-authorizations after the honor period expires.<br/><br/>If 30 days have transpired since the date of the original authorization, you must create an authorized payment instead of reauthorizing the original authorized payment.<br/><br/>A reauthorized payment itself has a new honor period of three days.<br/><br/>You can reauthorize an authorized payment from 4 to 29 days after the 3-day honor period. The allowed amount depends on context and geography, for example in US it is up to 115% of the original authorized amount, not to exceed an increase of $75 USD.<br/><br/>Supports only the `amount` request parameter.<blockquote><strong>Note:</strong> This request is currently not supported for Partner use cases.</blockquote>
operationId: authorizations.reauthorize
parameters:
- $ref: '#/components/parameters/authorization_id'
- $ref: '#/components/parameters/paypal_request_id'
- $ref: '#/components/parameters/prefer'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/reauthorize_request'
examples:
reauthorize_request:
value:
amount:
value: '10.99'
currency_code: USD
responses:
'201':
description: A successful request returns the HTTP <code>201 Created</code> status code and a JSON response body that shows the reauthorized payment details.
content:
application/json:
schema:
$ref: '#/components/schemas/authorization-2'
'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/authorizations.reauthorize-400'
'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'
'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/authorizations.reauthorize-422'
'500':
description: The request failed because an internal server error occurred.
default:
$ref: '#/components/responses/default'
tags:
- Authorizations
security:
- Oauth2:
- https://uri.paypal.com/services/payments/payment/authcapture
/v2/payments/authorizations/{authorization_id}/void:
post:
summary: Paypal Void authorized payment
description: Voids, or cancels, an authorized payment, by ID. You cannot void an authorized payment that has been fully captured.
operationId: authorizations.void
parameters:
- $ref: '#/components/parameters/authorization_id'
- $ref: '#/components/parameters/paypal_auth_assertion'
- $ref: '#/components/parameters/prefer'
responses:
'200':
description: A successful request returns the HTTP <code>200 OK</code> status code and a JSON response body that shows authorization details. This response is returned when the Prefer header is set to return=representation.
content:
application/json:
schema:
$ref: '#/components/schemas/authorization-2'
'204':
description: A successful request returns the HTTP <code>204 No Content</code> status code with no JSON response body. This response is returned when the Prefer header is set to return=minimal.
'400':
description: The request failed because it is not well-formed or is syntactically incorrect or violates schema.
content:
application/json:
schema:
$ref: '#/components/schemas/error_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/authorizations.void-422'
'500':
description: The request failed because an internal server error occurred.
default:
$ref: '#/components/responses/default'
tags:
- Authorizations
security:
- Oauth2:
- https://uri.paypal.com/services/payments/payment/authcapture
components:
schemas:
reauthorize_request:
title: Reauthorize Request
type: object
description: Reauthorizes an authorized PayPal account payment, by ID. To ensure that funds are still available, reauthorize a payment after its initial three-day honor period expires. You can reauthorize a payment only once from days four to 29.<br/><br/>If 30 days have transpired since the date of the original authorization, you must create an authorized payment instead of reauthorizing the original authorized payment.<br/><br/>A reauthorized payment itself has a new honor period of three days.<br/><br/>You can reauthorize an authorized payment once. The allowed amount depends on context and geography, for example in US it is up to 115% of the original authorized amount, not to exceed an increase of $75 USD.<br/><br/>Supports only the `amount` request parameter.<blockquote><strong>Note:</strong> This request is currently not supported for Partner use cases.</blockquote>
properties:
amount:
description: The amount to reauthorize for an authorized payment.
$ref: '#/components/schemas/money'
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'
authorization-2:
type: object
title: Authorization
description: The authorized payment transaction.
allOf:
- $ref: '#/components/schemas/authorization'
- 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
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'
authorization_status_details:
title: Auhorization Status Details
description: The details of the authorized payment status.
type: object
properties:
reason:
description: The reason why the authorized status is `PENDING`.
type: string
minLength: 1
maxLength: 24
pattern: ^[A-Z_]+$
enum:
- PENDING_REVIEW
'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
payment_instruction:
type: object
title: Payment Instruction
description: Any additional payment instructions to be consider during payment processing. This processing instruction is applicable for Capturing an order or Authorizing an Order.
properties:
platform_fees:
type: array
description: An array of various fees, commissions, tips, or donations. This field is only applicable to merchants that been enabled for PayPal Commerce Platform for Marketplaces and Platforms capability.
minItems: 0
maxItems: 1
items:
$ref: '#/components/schemas/platform_fee'
disbursement_mode:
description: The funds that are held payee by the marketplace/platform. This field is only applicable to merchants that been enabled for PayPal Commerce Platform for Marketplaces and Platforms capability.
$ref: '#/components/schemas/disbursement_mode'
payee_pricing_tier_id:
type: string
description: This field is only enabled for selected merchants/partners to use and provides the ability to trigger a specific pricing rate/plan for a payment transaction. The list of eligible 'payee_pricing_tier_id' would be provided to you by your Account Manager. Specifying values other than the one provided to you by your account manager would result in an error.
minLength: 1
maxLength: 20
pattern: ^.*$
payee_receivable_fx_rate_id:
type: string
description: FX identifier generated returned by PayPal to be used for payment processing in order to honor FX rate (for eligible integrations) to be used when amount is settled/received into the payee account.
maxLength: 4000
minLength: 1
pattern: ^.*$
authorizations.reauthorize-400:
properties:
details:
type: array
items:
anyOf:
- title: MISSING_REQUIRED_PARAMETER
properties:
issue:
type: string
enum:
- MISSING_REQUIRED_PARAMETER
description:
type: string
enum:
- A required field / parameter is missing.
- title: INVALID_STRING_LENGTH
properties:
issue:
type: string
enum:
- INVALID_STRING_LENGTH
description:
type: string
enum:
- The value of a field is either too short or too long.
- title: INVALID_STRING_MAX_LENGTH
properties:
issue:
type: string
enum:
- INVALID_STRING_MAX_LENGTH
description:
type: string
enum:
- The value of a field is too long.
- title: INVALID_PARAMETER_SYNTAX
properties:
issue:
type: string
enum:
- INVALID_PARAMETER_SYNTAX
description:
type: string
enum:
- The value of a field does not conform to the expected format.
authorization_status:
type: object
title: Authorization Status
description: The status fields for an authorized payment.
properties:
status:
description: The status for the authorized payment.
type: string
readOnly: true
enum:
- CREATED
- CAPTURED
- DENIED
- PARTIALLY_CAPTURED
- VOIDED
- PENDING
status_details:
description: The details of the authorized order pending status.
readOnly: true
$ref: '#/components/schemas/authorization_status_details'
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'
authorization:
type: object
title: Authorization
description: The authorized payment transaction.
allOf:
- $ref: '#/components/schemas/authorization_status'
- properties:
id:
description: The PayPal-generated ID for the authorized payment.
type: string
readOnly: true
amount:
description: The amount for this authorized 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
expiration_time:
description: The date and time when the authorized payment expires, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6).
$ref: '#/components/schemas/date_time'
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'
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-relat
# --- truncated at 32 KB (75 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/paypal/refs/heads/main/openapi/paypal-authorizations-api-openapi.yml