Payments (2)

API Version v2

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 Orders API. For more information, see the PayPal Checkout Overview.

Show details for authorized payment

get/v2/payments/authorizations/{authorization_id}

Shows details for an authorized payment, by ID.

SecurityOauth2
Request
path Parameters
authorization_id
required
string

The ID of the authorized payment for which to show details.

header Parameters
Authorization
required
string

To make REST API calls, include the bearer token in the Authorization header with the Bearer authentication scheme. The value is Bearer <Access-Token> or Basic <client_id>:<secret>.

Content-Type
required
string

Required for operations with a request body. The value is application/. Where the 'format' is 'json'.

Responses
201

Created

Request samples 
curl -v -X GET https://api-m.sandbox.paypal.com/v2/payments/authorizations/0VF52814937998046 \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer A21AAFs9YK9gWL6Vl6AqeoPtm-nf6JmtPOwAc8kfzHVdeigPEhrOJLCvbeIt3fJ4NKvyZo_iWic7sC3RIQrVUdu7igagcuMVQ'
Response samples
application/json
{}

Capture authorized payment

post/v2/payments/authorizations/{authorization_id}/capture

Captures an authorized payment, by ID.

SecurityOauth2
Request
path Parameters
authorization_id
required
string

The PayPal-generated ID for the authorized payment to capture.

header Parameters
PayPal-Request-Id
string

The server stores keys for 45 days.

Prefer
string
Default: return=minimal

The preferred server response upon successful completion of the request. Value is:

  • return=minimal. The server returns a minimal response to optimize communication between the API caller and the server. A minimal response includes the id, status and HATEOAS links.
  • return=representation. The server returns a complete resource representation, including the current state of the resource.

Authorization
required
string

To make REST API calls, include the bearer token in the Authorization header with the Bearer authentication scheme. The value is Bearer <Access-Token> or Basic <client_id>:<secret>.

Content-Type
required
string

Required for operations with a request body. The value is application/. Where the 'format' is 'json'.

Request Body schema: application/json
invoice_id
string [ 1 .. 127 ] characters ^.{1,127}$

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.

note_to_payer
string [ 1 .. 255 ] characters ^.{1,255}$

An informational note about this settlement. Appears in both the payer's transaction history and the emails that the payer receives.

final_capture
boolean
Default: false

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.

object (payment_instruction)

Any additional payment instructions to be consider during payment processing. This processing instruction is applicable for Capturing an order or Authorizing an Order.

soft_descriptor
string <= 22 characters

The payment descriptor on the payer's account statement.

object (Money)

The amount to capture. To capture a portion of the full authorized amount, specify an amount. If amount is not specified, the full authorized amount is captured. The amount must be a positive number and in the same currency as the authorization against which the payment is being captured.

Responses
201

A successful request returns the HTTP 201 Created status code and a JSON response body that shows captured payment details.

Request samples
application/json
{
  • "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"
}
Response samples
application/json
{}

Reauthorize authorized payment

post/v2/payments/authorizations/{authorization_id}/reauthorize

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.

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.

A reauthorized payment itself has a new honor period of three days.

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.

Supports only the amount request parameter.

Note: This request is currently not supported for Partner use cases.

SecurityOauth2
Request
path Parameters
authorization_id
required
string

The PayPal-generated ID for the authorized payment to reauthorize.

header Parameters
PayPal-Request-Id
string

The server stores keys for 45 days.

Prefer
string
Default: return=minimal

The preferred server response upon successful completion of the request. Value is:

  • return=minimal. The server returns a minimal response to optimize communication between the API caller and the server. A minimal response includes the id, status and HATEOAS links.
  • return=representation. The server returns a complete resource representation, including the current state of the resource.

Authorization
required
string

To make REST API calls, include the bearer token in the Authorization header with the Bearer authentication scheme. The value is Bearer <Access-Token> or Basic <client_id>:<secret>.

Content-Type
required
string

Required for operations with a request body. The value is application/. Where the 'format' is 'json'.

Request Body schema: application/json
object (Money)

The amount to reauthorize for an authorized payment.

Responses
201

A successful request returns the HTTP 201 Created status code and a JSON response body that shows the reauthorized payment details.

Request samples
application/json
{
  • "amount": {
    • "value": "10.99",
    • "currency_code": "USD"
    },
  • "invoice_id": "INVOICE-123",
  • "payment_instruction": {
    • "disbursement_mode": "INSTANT"
    },
  • "note_to_payer": "Payment For MAA Trip",
  • "soft_descriptor": "AI*MAATrip",
  • "supplementary_data": {
    • "airline": [
      • {
        • "ticket": {
          • "number": "045-2135145561",
          • "issue_date": "2018-01-19",
          • "issuing_carrier_code": "AI",
          • "travel_agency_name": "World Tours",
          • "travel_agency_code": "01"
          },
        • "passenger": {
          • "name": {
            • "full_name": "Trini George"
            },
          • "date_of_birth": "1981-05-31",
          • "country_code": "US"
          },
        • "flight_leg_details": [
          • {
            • "flight_number": 101,
            • "carrier_code": "AI",
            • "service_class": "J",
            • "departure_date": "2018-02-15",
            • "departure_time": "15:30",
            • "departure_airport": "SFO",
            • "arrival_airport": "DBX",
            • "stopover_code": "X",
            • "fare_basis_code": "SPRSVR"
            },
          • {
            • "flight_number": 102,
            • "carrier_code": "AI",
            • "service_class": "J",
            • "departure_date": "2018-02-15",
            • "departure_time": "19:05",
            • "departure_airport": "DBX",
            • "arrival_airport": "MAA",
            • "stopover_code": "O",
            • "fare_basis_code": "SPRSVR"
            }
          ]
        }
      ]
    }
}
Response samples
application/json
{}

Void authorized payment

post/v2/payments/authorizations/{authorization_id}/void

Voids, or cancels, an authorized payment, by ID. You cannot void an authorized payment that has been fully captured.

SecurityOauth2
Request
path Parameters
authorization_id
required
string

The PayPal-generated ID for the authorized payment to void.

header Parameters
Authorization
required
string

To make REST API calls, include the bearer token in the Authorization header with the Bearer authentication scheme. The value is Bearer <Access-Token> or Basic <client_id>:<secret>.

Content-Type
required
string

Required for operations with a request body. The value is application/. Where the 'format' is 'json'.

PayPal-Auth-Assertion
string

An API-caller-provided JSON Web Token (JWT) assertion that identifies the merchant. For details, see 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.

Prefer
string
Default: return=minimal

The preferred server response upon successful completion of the request. Value is:

  • return=minimal. The server returns a minimal response to optimize communication between the API caller and the server. A minimal response includes the id, status and HATEOAS links.
  • return=representation. The server returns a complete resource representation, including the current state of the resource.

Responses
204

A successful request returns the HTTP 204 No Content status code with no JSON response body. This response is returned when the Prefer header is set to return=minimal.

Request samples 
curl -v -X POST https://api-m.sandbox.paypal.com/v2/payments/authorizations/0VF52814937998046/void \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer A21AAFs9YK9gWL6Vl6AqeoPtm-nf6JmtPOwAc8kfzHVdeigPEhrOJLCvbeIt3fJ4NKvyZo_iWic7sC3RIQrVUdu7igagcuMVQ'

Show captured payment details

get/v2/payments/captures/{capture_id}

Shows details for a captured payment, by ID.

SecurityOauth2
Request
path Parameters
capture_id
required
string

The PayPal-generated ID for the captured payment for which to show details.

header Parameters
Authorization
required
string

To make REST API calls, include the bearer token in the Authorization header with the Bearer authentication scheme. The value is Bearer <Access-Token> or Basic <client_id>:<secret>.

Content-Type
required
string

Required for operations with a request body. The value is application/. Where the 'format' is 'json'.

Responses
200

A successful request returns the HTTP 200 OK status code and a JSON response body that shows captured payment details.

Request samples 
curl -v -X GET https://api-m.sandbox.paypal.com/v2/payments/captures/2GG279541U471931P \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer A21AAFs9YK9gWL6Vl6AqeoPtm-nf6JmtPOwAc8kfzHVdeigPEhrOJLCvbeIt3fJ4NKvyZo_iWic7sC3RIQrVUdu7igagcuMVQ'
Response samples
application/json
{
  • "id": "2GG279541U471931P",
  • "status": "COMPLETED",
  • "status_details": { },
  • "amount": {
    • "total": "10.99",
    • "currency": "USD"
    },
  • "final_capture": true,
  • "seller_protection": {
    • "status": "ELIGIBLE",
    • "dispute_categories": [
      • "ITEM_NOT_RECEIVED",
      • "UNAUTHORIZED_TRANSACTION"
      ]
    },
  • "seller_receivable_breakdown": {
    • "gross_amount": {
      • "total": "10.99",
      • "currency": "USD"
      },
    • "paypal_fee": {
      • "value": "0.33",
      • "currency": "USD"
      },
    • "net_amount": {
      • "value": "10.66",
      • "currency": "USD"
      },
    • "receivable_amount": {
      • "currency_code": "CNY",
      • "value": "59.26"
      },
    • "paypal_fee_in_receivable_currency": {
      • "currency_code": "CNY",
      • "value": "1.13"
      },
    • "exchange_rate": {
      • "source_currency": "USD",
      • "target_currency": "CNY",
      • "value": "5.9483297432325"
      }
    },
  • "invoice_id": "INVOICE-123",
  • "create_time": "2017-09-11T23:24:01Z",
  • "update_time": "2017-09-11T23:24:01Z",
  • "links": []
}

Refund captured payment

post/v2/payments/captures/{capture_id}/refund

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.

SecurityOauth2
Request
path Parameters
capture_id
required
string

The PayPal-generated ID for the captured payment to refund.

header Parameters
PayPal-Request-Id
string

The server stores keys for 45 days.

Prefer
string
Default: return=minimal

The preferred server response upon successful completion of the request. Value is:

  • return=minimal. The server returns a minimal response to optimize communication between the API caller and the server. A minimal response includes the id, status and HATEOAS links.
  • return=representation. The server returns a complete resource representation, including the current state of the resource.

Authorization
required
string

To make REST API calls, include the bearer token in the Authorization header with the Bearer authentication scheme. The value is Bearer <Access-Token> or Basic <client_id>:<secret>.

Content-Type
required
string

Required for operations with a request body. The value is application/. Where the 'format' is 'json'.

PayPal-Auth-Assertion
string

An API-caller-provided JSON Web Token (JWT) assertion that identifies the merchant. For details, see 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.

Request Body schema: application/json
custom_id
string [ 1 .. 127 ] characters ^.*$

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.

invoice_id
string [ 1 .. 127 ] characters ^.*$

The API caller-provided external invoice ID for this order. The pattern is defined by an external party and supports Unicode.

note_to_payer
string [ 1 .. 255 ] characters ^.*$

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.

object (Money)

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.

object (payment_instruction)

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.

Responses
201

A successful request returns the HTTP 201 Created status code and a JSON response body that shows refund details.

Request samples
application/json
{
  • "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"
          }
        }
      ]
    }
}
Response samples
application/json
{
  • "id": "1JU08902781691411",
  • "amount": {
    • "value": "10.00",
    • "currency_code": "USD"
    },
  • "status": "COMPLETED",
  • "note": "Defective product",
  • "seller_payable_breakdown": {
    • "gross_amount": {
      • "value": "10.00",
      • "currency_code": "USD"
      },
    • "paypal_fee": {
      • "value": "0",
      • "currency_code": "USD"
      },
    • "platform_fees": [
      • {
        • "amount": {
          • "currency_code": "USD",
          • "value": "1.00"
          }
        }
      ],
    • "net_amount": {
      • "value": "9.00",
      • "currency_code": "USD"
      },
    • "total_refunded_amount": {
      • "value": "10.00",
      • "currency_code": "USD"
      }
    },
  • "invoice_id": "INVOICE-123",
  • "create_time": "2022-04-23T23:24:19Z",
  • "update_time": "2022-04-23T23:24:19Z",
  • "links": []
}

Show refund details

get/v2/payments/refunds/{refund_id}

Shows details for a refund, by ID.

SecurityOauth2
Request
path Parameters
refund_id
required
string

The PayPal-generated ID for the refund for which to show details.

header Parameters
Authorization
required
string

To make REST API calls, include the bearer token in the Authorization header with the Bearer authentication scheme. The value is Bearer <Access-Token> or Basic <client_id>:<secret>.

Content-Type
required
string

Required for operations with a request body. The value is application/. Where the 'format' is 'json'.

Responses
200

A successful request returns the HTTP 200 OK status code and a JSON response body that shows refund details.

Request samples 
curl -v -X GET https://api-m.sandbox.paypal.com/v2/payments/refunds/1JU08902781691411 \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer A21AAFs9YK9gWL6Vl6AqeoPtm-nf6JmtPOwAc8kfzHVdeigPEhrOJLCvbeIt3fJ4NKvyZo_iWic7sC3RIQrVUdu7igagcuMVQ'
Response samples
application/json
{
  • "id": "1JU08902781691411",
  • "amount": {
    • "value": "10.99",
    • "currency_code": "USD"
    },
  • "status": "COMPLETED",
  • "note": "Defective product",
  • "seller_payable_breakdown": {
    • "gross_amount": {
      • "value": "10.99",
      • "currency_code": "USD"
      },
    • "paypal_fee": {
      • "value": "0.33",
      • "currency_code": "USD"
      },
    • "platform_fees": [
      • {
        • "amount": {
          • "currency_code": "USD",
          • "value": "1.00"
          },
        • "payee": {
          • "email_address": "fee@example.com"
          }
        }
      ],
    • "net_amount": {
      • "value": "9.66",
      • "currency_code": "USD"
      },
    • "total_refunded_amount": {
      • "value": "10.99",
      • "currency_code": "USD"
      }
    },
  • "invoice_id": "INVOICE-123",
  • "create_time": "2018-09-11T23:24:19Z",
  • "update_time": "2018-09-11T23:24:19Z",
  • "links": []
}

Errors

AUTH_CAPTURE_CURRENCY_MISMATCH

Message:
Currency of capture must be the same as currency of authorization.

Description:
Verify the currency of the capture and try the request again.

AUTH_CURRENCY_MISMATCH

Message:
The currency specified during reauthorization should be the same as the currency specified in the original authorization. Please check the currency of the authorization for which you are trying to reauthorize and try again.

AUTHENTICATION_FAILURE

Message:
Authentication failed due to missing authorization header, or invalid authentication credentials.

Description:
Account validations failed for the user.

AUTHORIZATION_ALREADY_CAPTURED

Message:
Authorization has already been captured.

Description:
If final_capture is set to to true, additional captures are not possible against the authorization.

AUTHORIZATION_AMOUNT_EXCEEDED

Description: Authorization amount specified exceeded allowable limit. Specify a different amount and try the request again. Alternately, contact Customer Support to increase your limits. Local regulations (e.g. in PSD2 countries) prohibit overages above the amount authorized by the payer.

AUTHORIZATION_DENIED

Message:
A denied authorization cannot be captured.

Description:
You cannot capture a denied authorization.

AUTHORIZATION_EXPIRED

Message:
An expired authorization cannot be captured.

Description:
You cannot capture an expired authorization.

AUTHORIZATION_VOIDED

Message:
A voided authorization cannot be captured or reauthorized.

Description:
You cannot capture or reauthorize a voided authorization.

CANNOT_BE_NEGATIVE

Description: Must be greater than or equal to 0.

CANNOT_BE_VOIDED

Message:
A reauthorization cannot be voided. Please void the original parent authorization.

Description:
You cannot void a reauthorized payment. You must void the original parent authorized payment.

CANNOT_BE_ZERO_OR_NEGATIVE

Message:
Must be greater than zero. If the currency supports decimals, only two decimal place precision is supported.

Description:
Specify a different value and try the request again.

CANNOT_REFUND_SELF

Description: The payer and payee for the refund cannot be same.

CAPTURE_FULLY_REFUNDED

Message:
The capture has already been fully refunded.

Description:
You cannot capture additional refunds against this capture.

CARD_BILLING_ADDRESS_COUNTRY_NOT_SUPPORTED

Description: Specified country is not currently supported for payment processing.

CARD_BRAND_NOT_SUPPORTED

Description: Refund cannot be issued to this card. The card brand card_brand is not supported. Please try again with another card.

CARD_EXPIRED

Description: The card is expired.

CARD_ISSUER_COUNTRY_NOT_SUPPORTED

Description: Card is issued by a financial institution for a country (e.g. Cuba, Iran, North Korea, Syria) that is not current supported for payment processing.

CARD_TYPE_NOT_SUPPORTED

Description: Processing of this card type is not supported. Use another type of card.

COMPLIANCE_VIOLATION

Description: Transaction is declined due to compliance violation.

CURRENCY_MISMATCH

Message:
All amounts specified should be in the same currency. Please ensure that the currency for the 'amount' and that of 'platform_fees.amount' is the same.

CURRENCY_NOT_SUPPORTED_FOR_CARD_BRAND

Description: Currency not supported for card specified. Card is card_brand. Only currency_code is supported for this brand of card.

CURRENCY_NOT_SUPPORTED_FOR_CARD_TYPE

Description: Currency code not supported for direct card payments using this card type. See Currency codes for list of supported currency codes.

CURRENCY_NOT_SUPPORTED_FOR_COUNTRY

Description: Currency code not supported for card payments in your country.

DECIMAL_PRECISION

Message:
The value of the field should not be more than two decimal places.

Description:
If the currency supports decimals, only two decimal place precision is supported.

DECIMALS_NOT_SUPPORTED

Message:
Currency does not support decimals.

Description:
Currency does not support decimals. Please refer to https://developer.paypal.com/docs/api/reference/currency-codes/ for more information.

DELAYED_DISBURSEMENT_NOT_SUPPORTED

Message:
The API Caller is not enabled to process transactions by specifying disbursement mode as delayed.

Description:
Verify the API caller is enabled to process transaction with delayed disbursement.

DUPLICATE_INVOICE_ID

Message:
Requested invoice number has been previously captured. Possible duplicate transaction.

Description:
Payment for this invoice was already captured.

DUPLICATE_REFUND

Description: Requested invoice_id has been previously refunded. Possible duplicate transaction.

DUPLICATE_TRANSACTION

Description: Duplicate invoice Id detected.

FX_RATE_CHANGE_DUE_TO_MARKET_EVENT

Description: The FX rate associated with the specified FX rate ID has been changed due to market events. Please refer to the provided new_fx_id link to retrieve a new FX rate ID and try the request again.

INSTRUMENT_DECLINED

Description: The instrument presented was either declined by the processor or bank, or it can't be used for this payment.

INTERNAL_SERVER_ERROR

Message:
An internal server error has occurred.

Description:
Try your request again later.

INVALID_ACCOUNT_STATUS

Message:
Account validations failed for the user.

Description:
The user account could not be validated.

INVALID_ARRAY_LENGTH

Message:
Request is not well-formed, syntactically incorrect, or violates schema.

Description:
The number of items in an array parameter is too small or too large.

INVALID_CARD_NUMBER

Description: The card number is invalid.

INVALID_COUNTRY_CODE

Message:
The requested action could not be performed, semantically incorrect, or failed business validation.

Description:
Country code is invalid. Please refer to https://developer.paypal.com/docs/integration/direct/rest/country-codes/ for a list of supported country codes.

INVALID_CURRENCY_CODE

Message:
Currency code should be a three-character ISO-4217 currency code.

Description:
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.

INVALID_FX_RATE_ID

Description: The specified FX Rate ID is not valid.

INVALID_INVOICE_ID

Message:
Specified invoice_id does not exist.

Description:
Please check the invoice_id and try again.

INVALID_PARAMETER_SYNTAX

Message:
The value of the field does not conform to the expected format.

Description:
Verify the specification for supported pattern and try the request again.

INVALID_PARAMETER_VALUE

Message:
The value of a field is invalid.

Description:
Verify the specification for the allowed values and try the request again.

INVALID_PAYEE_ACCOUNT

Message:
Payee account is invalid.

Description:
Verify the payee account information and try the request again.

INVALID_PLATFORM_FEES_ACCOUNT

Message:
The specified platform_fees payee account is either invalid or account setup is incomplete. Please work with your PayPal Account Manager to enable this option for your account.

Description:
Verify the platform fee account set up is completed or correct account.

INVALID_PLATFORM_FEES_AMOUNT

Message:
The platform_fees amount cannot be greater than the capture amount.

Description:
Verify the platform_fees amount and try the request again.

INVALID_RESOURCE_ID

Message:
Specified resource ID does not exist. Please check the resource ID and try again.

Description:
Verify the resource ID and try the request again.

INVALID_SECURITY_CODE_LENGTH

Description: The security_code length is invalid for the specified card brand.

INVALID_STRING_LENGTH

Message:
The value of a field is either too short or too long.

Description:
Verify the specification for the supported min and max values and try the request again.

INVALID_STRING_MAX_LENGTH

Message:
The value of a field is too long.

Description:
The parameter string is too long.

MALFORMED_REQUEST_JSON

Message:
Request is not well-formed, syntactically incorrect, or violates schema.

Description: The request JSON is not well formed.

MAX_CAPTURE_AMOUNT_EXCEEDED

Message:
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. Local regulations (e.g. in PSD2 countries) prohibit overages above the amount authorized by the payer.

Description:
Specify a different amount and try the request again. Alternately, contact Customer Support to increase your limits.

MAX_CAPTURE_COUNT_EXCEEDED

Message:
Maximum number of allowable captures has been reached. No additional captures are possible for this authorization. Please contact customer service or your account manager to change the number of captures that be made for a given authorization.

Description:
You cannot make additional captures.

MAX_NUMBER_OF_REFUNDS_EXCEEDED

Message:
You have exceeded the number of refunds that can be processed per capture.

Description:
Please contact customer support or your account manager to review the number of refunds that can be processed per capture.

MAX_PAYEE_AMOUNT_LIMIT_EXCEEDED

Description: Refund amount exceeds the allowed cumulative limit that the payee can receive.

MAX_PAYER_AMOUNT_LIMIT_EXCEEDED

Description: Refund amount exceeds the allowed cumulative limit that the payer can refund.

MAX_REFUND_LIMIT_EXCEEDED

Description: Refund amount exceeds allowable limit. Specify a different amount and try the request again. Alternately, contact Customer Support to increase your limits.

MISSING_REQUIRED_PARAMETER

Message:
A required field / parameter is missing.

Description:
Verify the specification for required fields and try the request again.

MULTI_CURRENCY_CODE

Message:
The requested action could not be performed, semantically incorrect, or failed business validation.

Description:
Multiple differing values of currency_code are not supported. Entire request must have the same currency_code.

MULTIPLE_AUTHORIZATIONS_FOUND

Message:
Cannot void multiple authorizations.

Description:
Specified invoice_id is associated with more than one authorization.

NOT_AUTHORIZED

Message:
You do not have permission to access or perform operations on this resource.

Description:
To make API calls on behalf of a merchant, ensure that you have sufficient permissions to proceed with this transaction.

PARTIAL_REFUND_NOT_ALLOWED

Message:
You cannot do a refund for an amount less than the original capture amount.

Description:
Specify an amount equal to the capture amount or omit the amount object from the request. Then, try the request again.

PAYEE_ACCOUNT_INVALID

Message:
The requested action could not be performed, semantically incorrect, or failed business validation.

Description:
Payee account specified is invalid. Please check the payee.merchant_id specified and try again.

PAYEE_ACCOUNT_LOCKED_OR_CLOSED

Message:
Transaction could not complete because payee account is locked or closed.

Description:
To get more information about the status of the account, call Customer Support.

PAYEE_ACCOUNT_RESTRICTED

Message:
Payee account is restricted.

Description:
To get more information about the status of the account, call Customer Support.

PAYEE_FX_RATE_ID_CURRENCY_MISMATCH

Description: The specified FX Rate ID is for a currency that does not match with the currency of this request.

PAYEE_FX_RATE_ID_EXPIRED

Description: The specified FX Rate ID has expired.

PAYEE_NOT_CONSENTED

Description: Payee does not have appropriate consent to allow the API caller to process this type of transaction on their behalf. Your current setup requires the 'payee' to provide a consent before this transaction can be processed successfully.

PAYEE_REFUND_AMOUNT_LIMIT_EXCEEDED

Description: Refund amount exceeds per transaction limit that the payee can receive.

PAYER_ACCOUNT_LOCKED_OR_CLOSED

Message:
The payer account cannot be used for this transaction.

Description:
Contact the payer for an alternate payment method.

PAYER_ACCOUNT_RESTRICTED

Message:
Payer account is restricted.

Description:
To get more information about the status of the account, call Customer Support.

PAYER_CANNOT_PAY

Message:
Payer cannot pay for this transaction.

Description:
Please contact the payer to find other ways to pay for this transaction.

PAYER_REFUND_AMOUNT_LIMIT_EXCEEDED

Description: Refund amount exceeds per transaction limit that the payer can refund.

PENDING_CAPTURE

Message:
Cannot initiate a refund as the capture is pending.

Description:
Capture is typically pending when the payer has funded the transaction by using an e-check or bank account.

PERMISSION_DENIED

Message:
You do not have permission to access or perform operations on this resource.

Description:
To make API calls on behalf of a merchant, ensure that you have sufficient permissions to proceed with this transaction.

PERMISSION_NOT_GRANTED

Message:
Payee of the authorization has not granted permission to perform capture on the authorization.

Description:
To make API calls on behalf of a merchant, ensure that you have sufficient permissions to capture the authorization.

PLATFORM_FEE_EXCEEDED

Message:
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.

PLATFORM_FEE_NOT_ENABLED

Message:
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_FEES_NOT_SUPPORTED

Message:
The API Caller is not enabled to process transactions by specifying 'platform_fees'. Please work with your PayPal Account Manager to enable this option for your account.

Description:
Verify the API caller is enabled to process the transaction with platform fees.

PREVIOUS_REQUEST_IN_PROGRESS

Message:
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.

Description:
This scenario only occurs when making multiple API requests on the same resource within a very short duration. To resolve this, API callers need to make subsequent requests with a delay.

PREVIOUSLY_CAPTURED

Message:
Authorization has been previously captured and hence cannot be voided.

Description:
This authorized payment was already captured. You cannot capture it again.

PREVIOUSLY_VOIDED

Message:
Authorization has been previously voided and hence cannot be voided again.

Description:
This authorized payment was already voided. You cannot void it again.

RATE_LIMIT_REACHED

Message:
Too many requests. Blocked due to rate limiting.

Description: The rate limit was reached.

REAUTHORIZATION_NOT_SUPPORTED

Message:
A reauthorize cannot be attempted on an authorization_id that is the result of a prior reauthorization or on an authorization made on an Order saved using the v2/orders/id/save API.

REAUTHORIZATION_TOO_SOON

Description: A reauthorization is only allowed once from Day 4 to Day 29 since the date of the original authorization.

REFUND_AMOUNT_EXCEEDED

Message:
The refund amount must be less than or equal to the capture amount that has not yet been refunded.

Description:
Verify the refund amount and try the request again.

REFUND_AMOUNT_TOO_LOW

Message:
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.

Description:
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.

REFUND_CAPTURE_CURRENCY_MISMATCH

Message:
Refund must be in the same currency as the capture.

Description:
Verify the currency of the refund and try the request again.

REFUND_FAILED_BY_PAYMENT_SOURCE

Message:
Refund was refused by the payment source.

Description:
We're unable to process refunds for the payer's selected payment source. Contact the payer directly to arrange a refund via alternative means.

REFUND_FAILED_INSUFFICIENT_FUNDS

Message:
Refund cannot be processed due to insufficient funds.

Description:
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.

REFUND_FUNDS_NOT_AVAILABLE

Description: There is no valid funding instrument linked to the account from which refund can be processed.

REFUND_IS_RESTRICTED

Message:
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.

REFUND_NOT_ALLOWED

Message:
Capture cannot be refunded.

Description:
You cannot refund this capture.

REFUND_NOT_PERMITTED_DUE_TO_CHARGEBACK

Message:
The requested action could not be performed, semantically incorrect, or failed business validation.

Description:
Refunds not allowed on this capture due to a chargeback on the card or bank. Please contact the payee to resolve the chargeback.

REFUND_NOT_SUPPORTED_FOR_PAYMENT_SOURCE

Message:
Refund was refused by the payment source.

Description:
Refunds are not supported for the payer's selected payment source. Contact the payer directly to arrange a refund via alternative means.

REFUND_REFUSED_BY_PROCESSOR

Description: The funding instrument linked to the account has been declined by either the processor or PayPal internal system.

REFUND_TIME_EXCEEDED_FOR_PAYMENT_SOURCE

Message:
Refund was refused by the payment source.

Description:
The time limit set by the payer's selected payment source to refund this transaction has expired. Contact the payer directly to arrange a refund via alternative means.

REFUND_TIME_LIMIT_EXCEEDED

Message:
You are over the time limit to perform a refund on this capture.

Description:
The refund cannot be issued at this time.

REFUND_TRANSACTION_REFUSED

Description: PayPal's internal controls or user account settings prevent refund from being processed.

SHIPPING_ADDRESS_INVALID

Message:
Address field does not match the corresponding validation regex.

SHIPPING_ADDRESS_NOT_ALLOWED_BY_RESIDENCE_COUNTRY

Message:
The provided shipping address is not allowed by buyer's residency country.

TRANSACTION_DISPUTED

Message:
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.

Description:
Refund for an amount less than the remaining transaction amount cannot be processed at this time because of an open dispute on the capture. Please visit the PayPal Resolution Center to view the details.

TRANSACTION_REFUSED

Message:
PayPal's internal controls prevent authorization from being captured.

Description:
For more information about this transaction, contact customer support.

UPDATE_AUTHORIZATION_NOT_SUPPORTED

Message:
Update authorization is not allowed for this type of authorization.

Definitions

3ds_card_brand

Card brand that the transaction was processed for authentication.

string (3ds_card_brand) [ 1 .. 255 ] characters ^[0-9A-Z_]+$

Card brand that the transaction was processed for authentication.

Enum: Description
AMERICAN_EXPRESS

Card Brand Amex.

DISCOVER

Card Brand DISCOVER.

JCB

Card Brand JCB.

MAESTRO

Card Brand MAESTRO.

MASTERCARD

Card Brand MASTERCARD.

SOLO

Card Brand SOLO.

VISA

Card Brand VISA.

ELECTRON

Card Brand ELECTRON.

ELO

Card Brand ELO.

"AMERICAN_EXPRESS"

activity_timestamps

The date and time stamps that are common to authorized payment, captured payment, and refund transactions.

create_time
string <ppaas_date_time_v3> (date_time) [ 20 .. 64 ] characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...

The date and time when the transaction occurred, in Internet date and time format.

update_time
string <ppaas_date_time_v3> (date_time) [ 20 .. 64 ] characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...

The date and time when the transaction was last updated, in Internet date and time format.

{
  • "create_time": "stringstringstringst",
  • "update_time": "stringstringstringst"
}

amount_breakdown

The breakdown of the amount. Breakdown provides details such as total item amount, total tax amount, shipping, handling, insurance, and discounts, if any.

object (Money)

The subtotal for all items. Required if the request includes purchase_units[].items[].unit_amount. Must equal the sum of (items[].unit_amount * items[].quantity) for all items. item_total.value can not be a negative number.

object (Money)

The shipping fee for all items within a given purchase_unit. shipping.value can not be a negative number.

object (Money)

The handling fee for all items within a given purchase_unit. handling.value can not be a negative number.

object (Money)

The total tax for all items. Required if the request includes purchase_units.items.tax. Must equal the sum of (items[].tax * items[].quantity) for all items. tax_total.value can not be a negative number.

object (Money)

The insurance fee for all items within a given purchase_unit. insurance.value can not be a negative number.

object (Money)

The shipping discount for all items within a given purchase_unit. shipping_discount.value can not be a negative number.

object (Money)

The discount for all items within a given purchase_unit. discount.value can not be a negative number.

{
  • "item_total": {
    • "currency_code": "str",
    • "value": "string"
    },
  • "shipping": {
    • "currency_code": "str",
    • "value": "string"
    },
  • "handling": {
    • "currency_code": "str",
    • "value": "string"
    },
  • "tax_total": {
    • "currency_code": "str",
    • "value": "string"
    },
  • "insurance": {
    • "currency_code": "str",
    • "value": "string"
    },
  • "shipping_discount": {
    • "currency_code": "str",
    • "value": "string"
    },
  • "discount": {
    • "currency_code": "str",
    • "value": "string"
    }
}

amount_with_breakdown

The total order amount with an optional breakdown that provides details, such as the total item amount, total tax amount, shipping, handling, insurance, and discounts, if any.
If you specify amount.breakdown, the amount equals item_total plus tax_total plus shipping plus handling plus insurance minus shipping_discount minus discount.
The amount must be a positive number. For listed of supported currencies and decimal precision, see the PayPal REST APIs Currency Codes.

currency_code
required
string <ppaas_common_currency_code_v2> (currency_code) = 3 characters

The three-character ISO-4217 currency code that identifies the currency.

value
required
string <= 32 characters ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$

The value, which might be:

  • An integer for currencies like JPY that are not typically fractional.
  • A decimal fraction for currencies like TND that are subdivided into thousandths.
For the required number of decimal places for a currency code, see Currency Codes.

object (amount_breakdown)

The breakdown of the amount. Breakdown provides details such as total item amount, total tax amount, shipping, handling, insurance, and discounts, if any.

{
  • "currency_code": "str",
  • "value": "string",
  • "breakdown": {
    • "item_total": {
      • "currency_code": "str",
      • "value": "string"
      },
    • "shipping": {
      • "currency_code": "str",
      • "value": "string"
      },
    • "handling": {
      • "currency_code": "str",
      • "value": "string"
      },
    • "tax_total": {
      • "currency_code": "str",
      • "value": "string"
      },
    • "insurance": {
      • "currency_code": "str",
      • "value": "string"
      },
    • "shipping_discount": {
      • "currency_code": "str",
      • "value": "string"
      },
    • "discount": {
      • "currency_code": "str",
      • "value": "string"
      }
    }
}

apple_pay_attributes

Additional attributes associated with apple pay.

object (customer)

The details about a customer in PayPal's system of record.

object (v3_vault_instruction_base)

Base vaulting specification. The object can be extended for specific use cases within each payment_source that supports vaulting.

{
  • "customer": {
    • "id": "string",
    • "email_address": "string",
    • "phone": {
      • "phone_type": "FAX",
      • "phone_number": {
        • "national_number": "string"
        }
      }
    },
  • "vault": {
    • "store_in_vault": "ON_SUCCESS"
    }
}

apple_pay_decrypted_token_data

Information about the Payment data obtained by decrypting Apple Pay token.

device_manufacturer_id
string [ 1 .. 2000 ] characters ^.*$

Apple Pay Hex-encoded device manufacturer identifier. The pattern is defined by an external party and supports Unicode.

payment_data_type
string [ 1 .. 16 ] characters ^[0-9A-Z_]+$

Indicates the type of payment data passed, in case of Non China the payment data is 3DSECURE and for China it is EMV.

Enum: Description
3DSECURE

The card was authenticated using 3D Secure (3DS) authentication scheme. While using this value make sure to populate cryptogram and eci_indicator as part of payment data..

EMV

The card was authenticated using EMV method, which is applicable for China. While using this value make sure to pass emv_data and pin as part of payment data.

object (Money)

The transaction amount for the payment that the payer has approved on apple platform.

required
object (card)

Apple Pay tokenized credit card used to pay.

object (apple_pay_payment_data)

Apple Pay payment data object which contains the cryptogram, eci_indicator and other data.

{
  • "device_manufacturer_id": "string",
  • "payment_data_type": "3DSECURE",
  • "transaction_amount": {
    • "currency_code": "str",
    • "value": "string"
    },
  • "tokenized_card": {
    • "name": "string",
    • "number": "stringstrings",
    • "expiry": "string",
    • "card_type": "VISA",
    • "type": "CREDIT",
    • "brand": "VISA",
    • "billing_address": {
      • "address_line_1": "string",
      • "address_line_2": "string",
      • "admin_area_2": "string",
      • "admin_area_1": "string",
      • "postal_code": "string",
      • "country_code": "st"
      }
    },
  • "payment_data": {
    • "cryptogram": "string",
    • "eci_indicator": "string",
    • "emv_data": "string",
    • "pin": "string"
    }
}

apple_pay_payment_data

Information about the decrypted apple pay payment data for the token like cryptogram, eci indicator.

cryptogram
string [ 1 .. 2000 ] characters ^.*$

Online payment cryptogram, as defined by 3D Secure. The pattern is defined by an external party and supports Unicode.

eci_indicator
string [ 1 .. 256 ] characters ^.*$

ECI indicator, as defined by 3- Secure. The pattern is defined by an external party and supports Unicode.

emv_data
string [ 1 .. 2000 ] characters ^.*$

Encoded Apple Pay EMV Payment Structure used for payments in China. The pattern is defined by an external party and supports Unicode.

pin
string [ 1 .. 2000 ] characters ^.*$

Bank Key encrypted Apple Pay PIN. The pattern is defined by an external party and supports Unicode.

{
  • "cryptogram": "string",
  • "eci_indicator": "string",
  • "emv_data": "string",
  • "pin": "string"
}

assurance_details

Information about cardholder possession validation and cardholder identification and verifications (ID&V).

account_verified
boolean
Default: false

If true, indicates that Cardholder possession validation has been performed on returned payment credential.

card_holder_authenticated
boolean
Default: false

If true, indicates that identification and verifications (ID&V) was performed on the returned payment credential.If false, the same risk-based authentication can be performed as you would for card transactions. This risk-based authentication can include, but not limited to, step-up with 3D Secure protocol if applicable.

{
  • "account_verified": false,
  • "card_holder_authenticated": false
}

authentication_response

Results of Authentication such as 3D Secure.

liability_shift
string (liability_shift) [ 1 .. 255 ] characters ^[0-9A-Z_]+$

Liability shift indicator. The outcome of the issuer's authentication.

Enum: Description
NO

Liability is with the merchant.

POSSIBLE

Liability may shift to the card issuer.

UNKNOWN

The authentication system is not available.

object (three_d_secure_authentication_response)

Results of 3D Secure Authentication.

{
  • "liability_shift": "NO",
  • "three_d_secure": {
    • "authentication_status": "Y",
    • "enrollment_status": "Y"
    }
}

authentication_type

Indicates the type of authentication that was used to challenge the card holder.

string (authentication_type) [ 1 .. 255 ] characters ^[0-9A-Z_]+$

Indicates the type of authentication that was used to challenge the card holder.

Enum: Description
STATIC

Indicates fixed password.

DYNAMIC

Indicates one-time password. Could be single-step or multi-step.

OUT_OF_BAND

Indicates biometric over the phone.

DECOUPLED

Indicates decoupled authentication.

"STATIC"

authorization

The authorized payment transaction.

status
string (Authorization Status)

The status for the authorized payment.

Enum: Description
CREATED

The authorized payment is created. No captured payments have been made for this authorized payment.

CAPTURED

The authorized payment has one or more captures against it. The sum of these captured payments is greater than the amount of the original authorized payment.

DENIED

PayPal cannot authorize funds for this authorized payment.

PARTIALLY_CAPTURED

A captured payment was made for the authorized payment for an amount that is less than the amount of the original authorized payment.

VOIDED

The authorized payment was voided. No more captured payments can be made against this authorized payment.

PENDING

The created authorization is in pending state. For more information, see status.details.

object (authorization_status_details)

The details of the authorized order pending status.

id
string

The PayPal-generated ID for the authorized payment.

invoice_id
string

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.

custom_id
string <= 255 characters

The API caller-provided external ID. Used to reconcile API caller-initiated transactions with PayPal transactions. Appears in transaction and settlement reports.

Array of objects (Link Description)

An array of related HATEOAS links.

object (Money)

The amount for this authorized payment.

object (network_transaction_reference)

Reference values used by the card network to identify a transaction.

object (seller_protection)

The level of protection offered as defined by PayPal Seller Protection for Merchants.

expiration_time
string <ppaas_date_time_v3> (date_time) [ 20 .. 64 ] characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...

The date and time when the authorized payment expires, in Internet date and time format.

create_time
string <ppaas_date_time_v3> (date_time) [ 20 .. 64 ] characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...

The date and time when the transaction occurred, in Internet date and time format.

update_time
string <ppaas_date_time_v3> (date_time) [ 20 .. 64 ] characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...

The date and time when the transaction was last updated, in Internet date and time format.

{
  • "status": "CREATED",
  • "status_details": {
    • "reason": "PENDING_REVIEW"
    },
  • "id": "string",
  • "invoice_id": "string",
  • "custom_id": "string",
  • "links": [
    • {
      • "href": "string",
      • "rel": "string",
      • "method": "GET"
      }
    ],
  • "amount": {
    • "currency_code": "str",
    • "value": "string"
    },
  • "network_transaction_reference": {
    • "id": "stringstr",
    • "date": "stri",
    • "acquirer_reference_number": "string",
    • "network": "VISA"
    },
  • "seller_protection": {
    • "status": "ELIGIBLE",
    • "dispute_categories": [
      • "string"
      ]
    },
  • "expiration_time": "string",
  • "create_time": "stringstringstringst",
  • "update_time": "stringstringstringst"
}

Authorization

The authorized payment transaction.

status
string (Authorization Status)

The status for the authorized payment.

Enum: Description
CREATED

The authorized payment is created. No captured payments have been made for this authorized payment.

CAPTURED

The authorized payment has one or more captures against it. The sum of these captured payments is greater than the amount of the original authorized payment.

DENIED

PayPal cannot authorize funds for this authorized payment.

PARTIALLY_CAPTURED

A captured payment was made for the authorized payment for an amount that is less than the amount of the original authorized payment.

VOIDED

The authorized payment was voided. No more captured payments can be made against this authorized payment.

PENDING

The created authorization is in pending state. For more information, see status.details.

object (authorization_status_details)

The details of the authorized order pending status.

id
string

The PayPal-generated ID for the authorized payment.

invoice_id
string

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.

custom_id
string <= 255 characters

The API caller-provided external ID. Used to reconcile API caller-initiated transactions with PayPal transactions. Appears in transaction and settlement reports.

Array of objects (Link Description)

An array of related HATEOAS links.

object (Money)

The amount for this authorized payment.

object (network_transaction_reference)

Reference values used by the card network to identify a transaction.

object (seller_protection)

The level of protection offered as defined by PayPal Seller Protection for Merchants.

expiration_time
string <ppaas_date_time_v3> (date_time) [ 20 .. 64 ] characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...

The date and time when the authorized payment expires, in Internet date and time format.

create_time
string <ppaas_date_time_v3> (date_time) [ 20 .. 64 ] characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...

The date and time when the transaction occurred, in Internet date and time format.

update_time
string <ppaas_date_time_v3> (date_time) [ 20 .. 64 ] characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...

The date and time when the transaction was last updated, in Internet date and time format.

object (Payment Supplementary Data)

An object that provides supplementary/additional data related to a payment transaction.

object (payee_base)

The details associated with the merchant for this transaction.

{
  • "status": "CREATED",
  • "status_details": {
    • "reason": "PENDING_REVIEW"
    },
  • "id": "string",
  • "invoice_id": "string",
  • "custom_id": "string",
  • "links": [
    • {
      • "href": "string",
      • "rel": "string",
      • "method": "GET"
      }
    ],
  • "amount": {
    • "currency_code": "str",
    • "value": "string"
    },
  • "network_transaction_reference": {
    • "id": "stringstr",
    • "date": "stri",
    • "acquirer_reference_number": "string",
    • "network": "VISA"
    },
  • "seller_protection": {
    • "status": "ELIGIBLE",
    • "dispute_categories": [
      • "string"
      ]
    },
  • "expiration_time": "string",
  • "create_time": "stringstringstringst",
  • "update_time": "stringstringstringst",
  • "supplementary_data": {
    • "related_ids": {
      • "order_id": "string",
      • "authorization_id": "string",
      • "capture_id": "string"
      }
    },
  • "payee": {
    • "email_address": "string",
    • "merchant_id": "stringstrings"
    }
}

authorization_status

The status fields and status details for an authorized payment.

status
string (Authorization Status)

The status for the authorized payment.

Enum: Description
CREATED

The authorized payment is created. No captured payments have been made for this authorized payment.

CAPTURED

The authorized payment has one or more captures against it. The sum of these captured payments is greater than the amount of the original authorized payment.

DENIED

PayPal cannot authorize funds for this authorized payment.

PARTIALLY_CAPTURED

A captured payment was made for the authorized payment for an amount that is less than the amount of the original authorized payment.

VOIDED

The authorized payment was voided. No more captured payments can be made against this authorized payment.

PENDING

The created authorization is in pending state. For more information, see status.details.

object (authorization_status_details)

The details of the authorized order pending status.

{
  • "status": "CREATED",
  • "status_details": {
    • "reason": "PENDING_REVIEW"
    }
}

authorization_status_details

The details of the authorized payment status.

reason
string (Authorization Incomplete Reason) [ 1 .. 64 ] characters ^[A-Z_]+$

The reason why the authorized status is PENDING.

Enum: Description
PENDING_REVIEW

Authorization is pending manual review.

DECLINED_BY_RISK_FRAUD_FILTERS

Risk Filter set by the payee failed for the transaction.

{
  • "reason": "PENDING_REVIEW"
}

BIC

The business identification code (BIC). In payments systems, a BIC is used to identify a specific business, most commonly a bank.

string (BIC) [ 8 .. 11 ] characters ^[A-Z-a-z0-9]{4}[A-Z-a-z]{2}[A-Z-a-z0-9]{2}([...

The business identification code (BIC). In payments systems, a BIC is used to identify a specific business, most commonly a bank.

"stringst"

billing_agreement_id

The PayPal billing agreement ID. References an approved recurring payment for goods or services.

string (billing_agreement_id) [ 2 .. 128 ] characters ^[a-zA-Z0-9-]+$

The PayPal billing agreement ID. References an approved recurring payment for goods or services.

"string"

bin_details

Bank Identification Number (BIN) details used to fund a payment.

bin
string [ 1 .. 25 ] characters ^[0-9]+$

The Bank Identification Number (BIN) signifies the number that is being used to identify the granular level details (except the PII information) of the card.

issuing_bank
string [ 1 .. 64 ] characters

The issuer of the card instrument.

products
Array of strings [ 1 .. 256 ] items

The type of card product assigned to the BIN by the issuer. These values are defined by the issuer and may change over time. Some examples include: PREPAID_GIFT, CONSUMER, CORPORATE.

bin_country_code
string <ppaas_common_country_code_v2> (country_code) = 2 characters ^([A-Z]{2}|C2)$
{
  • "bin": "string",
  • "issuing_bank": "string",
  • "products": [
    • "string"
    ],
  • "bin_country_code": "string"
}

blik_experience_context

Customizes the payer experience during the approval process for the BLIK payment.

brand_name
string [ 1 .. 127 ] characters ^.*$

The label that overrides the business name in the PayPal account on the PayPal site. The pattern is defined by an external party and supports Unicode.

shipping_preference
string [ 1 .. 24 ] characters ^[A-Z_]+$
Default: "GET_FROM_FILE"

The location from which the shipping address is derived.

Enum: Description
GET_FROM_FILE

Get the customer-provided shipping address on the PayPal site.

NO_SHIPPING

Redacts the shipping address from the PayPal site. Recommended for digital goods.

SET_PROVIDED_ADDRESS

Get the merchant-provided address. The customer cannot change this address on the PayPal site. If merchant does not pass an address, customer can choose the address on PayPal pages.

locale
string <ppaas_common_language_v3> (language) [ 2 .. 10 ] characters ^[a-z]{2}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}|[...

The BCP 47-formatted locale of pages that the PayPal payment experience shows. PayPal supports a five-character code. For example, da-DK, he-IL, id-ID, ja-JP, no-NO, pt-BR, ru-RU, sv-SE, th-TH, zh-CN, zh-HK, or zh-TW.

return_url
string <uri> (url)

The URL where the customer is redirected after the customer approves the payment.

cancel_url
string <uri> (url)

The URL where the customer is redirected after the customer cancels the payment.

consumer_user_agent
string [ 1 .. 256 ] characters ^.*$

The payer's User Agent. For example, Mozilla/5.0 (Macintosh; Intel Mac OS X x.y; rv:42.0).

consumer_ip
string <ppaas_ip_address_v1> (IP Address) [ 7 .. 39 ] characters ^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[...

The IP address of the consumer. It could be either IPv4 or IPv6.

{
  • "brand_name": "string",
  • "shipping_preference": "GET_FROM_FILE",
  • "locale": "string",
  • "return_url": "string",
  • "cancel_url": "string",
  • "consumer_user_agent": "string",
  • "consumer_ip": "string"
}

blik_level_0

Information used to pay using BLIK level_0 flow.

auth_code
required
string = 6 characters ^[0-9]{6}$

The 6-digit code used to authenticate a consumer within BLIK.

{
  • "auth_code": "string"
}

blik_one_click

Information used to pay using BLIK one-click flow.

auth_code
string = 6 characters ^[0-9]{6}$

The 6-digit code used to authenticate a consumer within BLIK.

consumer_reference
required
string [ 3 .. 64 ] characters ^[ -~]{3,64}$

The merchant generated, unique reference serving as a primary identifier for accounts connected between Blik and a merchant.

alias_label
string [ 8 .. 35 ] characters ^[ -~]{8,35}$

A bank defined identifier used as a display name to allow the payer to differentiate between multiple registered bank accounts.

alias_key
string [ 1 .. 19 ] characters ^[0-9]+$

A Blik-defined identifier for a specific Blik-enabled bank account that is associated with a given merchant. Used only in conjunction with a Consumer Reference.

{
  • "auth_code": "string",
  • "consumer_reference": "string",
  • "alias_label": "stringst",
  • "alias_key": "string"
}

capture

A captured payment.

status
string (Capture Status)

The status of the captured payment.

Enum: Description
COMPLETED

The funds for this captured payment were credited to the payee's PayPal account.

DECLINED

The funds could not be captured.

PARTIALLY_REFUNDED

An amount less than this captured payment's amount was partially refunded to the payer.

PENDING

The funds for this captured payment was not yet credited to the payee's PayPal account. For more information, see status.details.

REFUNDED

An amount greater than or equal to this captured payment's amount was refunded to the payer.

FAILED

There was an error while capturing payment.

object (capture_status_details)

The details of the captured payment status.

id
string

The PayPal-generated ID for the captured payment.

invoice_id
string

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.

custom_id
string <= 255 characters

The API caller-provided external ID. Used to reconcile API caller-initiated transactions with PayPal transactions. Appears in transaction and settlement reports.

final_capture
boolean
Default: false

Indicates whether you can make additional captures against the authorized payment. Set to true if you do not inten