PayPal Payments API
The PayPal Payments API lets businesses authorize, capture, refund, void, and reauthorize payments, supporting credit and debit cards as well as PayPal and Venmo wallets.
OpenAPI Specification
openapi: 3.0.3
info:
title: Paypal Payments
description: Call the Payments API to authorize payments, capture authorized payments, refund payments that have already been captured, and show payment information. Use the Payments API in conjunction with the <a href="/docs/api/orders/v2/">Orders API</a>. For more information, see the <a href="/docs/checkout/">PayPal Checkout Overview</a>.
version: '2.5'
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.
- name: Captures
description: Use the `/captures` resource to show details for and refund a captured payment.
- name: Refunds
description: Use the `/refunds` resource to show refund details.
externalDocs:
url: https://developer.paypal.com/docs/api/payments/v2/
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
"/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 <code>200 OK</code> 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 <code>amount</code> 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 <code>201 Created</code> 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
"/v2/payments/refunds/{refund_id}":
get:
summary: Paypal Show refund details
description: Shows details for a refund, by ID.
operationId: refunds.get
parameters:
- "$ref": "#/components/parameters/refund_id"
responses:
'200':
description: A successful request returns the HTTP <code>200 OK</code> status code and a JSON response body that shows refund details.
content:
application/json:
schema:
"$ref": "#/components/schemas/refund"
'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"
'500':
description: The request failed because an internal server error occurred.
default:
"$ref": "#/components/responses/default"
tags:
- Refunds
security:
- Oauth2:
- https://uri.paypal.com/services/payments/refund
components:
securitySchemes:
Oauth2:
type: oauth2
description: OAuth 2.0 authentication
flows:
clientCredentials:
tokenUrl: "/v1/oauth2/token"
scopes:
https://uri.paypal.com/services/payments/payment/authcapture: Permission to do non-real time payments like capture on authorization
https://uri.paypal.com/services/payments/refund: Permission to initiate a refund on a capture transaction
https://uri.paypal.com/services/payments/non-referenced-credit: Permission to initiate non referenced credit
https://uri.paypal.com/services/payments/realtimepayment: Permission to do any real time payment, with support for sale/authorize/order intents
https://uri.paypal.com/services/payments/reversepayment: Permission to do any reverse payment
responses:
default:
description: The default response.
content:
application/json:
schema:
"$ref": "#/components/schemas/error_default"
schemas:
'400':
properties:
details:
type: array
items:
anyOf:
- title: INVALID_PARAMETER_VALUE
properties:
issue:
type: string
enum:
- INVALID_PARAMETER_VALUE
description:
type: string
enum:
- The value of a field is invalid.
- 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.
'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.
'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.
'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.
'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.
'422':
properties:
details:
type: array
items:
anyOf:
- title: INVALID_CURRENCY_CODE
properties:
issue:
type: string
enum:
- INVALID_CURRENCY_CODE
description:
type: string
enum:
- Currency code is invalid or is not currently supported. Please refer https://developer.paypal.com/docs/api/reference/currency-codes/ for list of supported currency codes.
- title: CANNOT_BE_ZERO_OR_NEGATIVE
properties:
issue:
type: string
enum:
- CANNOT_BE_ZERO_OR_NEGATIVE
description:
type: string
enum:
- Must be greater than zero. If the currency supports decimals, only two decimal place precision is supported.
- title: DECIMAL_PRECISION
properties:
issue:
type: string
enum:
- DECIMAL_PRECISION
description:
type: string
enum:
- If the currency supports decimals, only two decimal place precision is supported.
- title: DECIMALS_NOT_SUPPORTED
properties:
issue:
type: string
enum:
- DECIMALS_NOT_SUPPORTED
description:
type: string
enum:
- Currency does not support decimals. Please refer to https://developer.paypal.com/docs/api/reference/currency-codes/ for more information.
- title: TRANSACTION_REFUSED
properties:
issue:
type: string
enum:
- TRANSACTION_REFUSED
description:
type: string
enum:
- PayPal's internal controls prevent authorization from being captured.
- title: AUTHORIZATION_VOIDED
properties:
issue:
type: string
enum:
- AUTHORIZATION_VOIDED
description:
type: string
enum:
- 'A voided authorization cannot be captured or reauthorized. '
- title: MAX_CAPTURE_COUNT_EXCEEDED
properties:
issue:
type: string
enum:
- MAX_CAPTURE_COUNT_EXCEEDED
description:
type: string
enum:
- Maxmimum number of allowable captures has been reached. No additional captures are possible for this authorization. Contact Customer Service or your account manager to change the number of captures for a given authorization.
- title: DUPLICATE_INVOICE_ID
properties:
issue:
type: string
enum:
- DUPLICATE_INVOICE_ID
description:
type: string
enum:
- Requested invoice_id has been previously captured. Possible duplicate transaction.
- title: AUTH_CAPTURE_CURRENCY_MISMATCH
properties:
issue:
type: string
enum:
- AUTH_CAPTURE_CURRENCY_MISMATCH
description:
type: string
enum:
- Currency of capture must be the same as currency of authorization.
- title: PAYER_CANNOT_PAY
properties:
issue:
type: string
enum:
- PAYER_CANNOT_PAY
description:
type: string
enum:
- Payer cannot pay for this transaction. Please contact the payer to find other ways to pay for this transaction.
- title: AUTHORIZATION_DENIED
properties:
issue:
type: string
enum:
- AUTHORIZATION_DENIED
description:
type: string
enum:
- An denied authorization cannot be captured.
- title: AUTHORIZATION_EXPIRED
properties:
issue:
type: string
enum:
- AUTHORIZATION_EXPIRED
description:
type: string
enum:
- An expired authorization cannot be captured.
- title: AUTHORIZATION_ALREADY_CAPTURED
properties:
issue:
type: string
enum:
- AUTHORIZATION_ALREADY_CAPTURED
description:
type: string
enum:
- Authorization has previously been captured.
- title: MAX_CAPTURE_AMOUNT_EXCEEDED
properties:
issue:
type: string
enum:
- MAX_CAPTURE_AMOUNT_EXCEEDED
description:
type: string
enum:
- Capture amount exceeds allowable limit. Please contact customer service or your account manager to request the change to your overage limit. The default overage limit is 115%, which allows the sum of all captures to be up to 115% of the order amount. The ability to over capture is subjected to regulatory approvals.
- title: TRANSACTION_REFUSED
properties:
issue:
type: string
enum:
- TRANSACTION_REFUSED
description:
type: string
enum:
- PayPal's internal controls prevent authorization from being captured.
- 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 c
# --- truncated at 32 KB (106 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/paypal/refs/heads/main/openapi/paypal-payments-openapi-original.yml