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
200

OK

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 once for 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"
    }
}
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.

Responses
204

A successful request returns the HTTP 204 No Content status code with no JSON response body.

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
invoice_id
string [ 1 .. 127 ] characters

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

The reason for the refund. Appears in both the payer's transaction history and the emails that the payer receives.

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_to_payer": "Defective product",
  • "seller_payable_breakdown": {
    • "gross_amount": {
      • "value": "10.99",
      • "currency_code": "USD"
      },
    • "paypal_fee": {
      • "value": "0",
      • "currency_code": "USD"
      },
    • "net_amount": {
      • "value": "10.99",
      • "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

Currency of capture must be the same as currency of authorization.
Verify the currency of the capture and try the request again.

AUTH_CURRENCY_MISMATCH

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

Authentication failed due to missing authorization header, or invalid authentication credentials.
Account validations failed for the user.

AUTHORIZATION_ALREADY_CAPTURED

Authorization has already been captured.
If final_capture is set to to true, additional captures are not possible against the authorization.

AUTHORIZATION_DENIED

A denied authorization cannot be captured.
You cannot capture a denied authorization.

AUTHORIZATION_EXPIRED

An expired authorization cannot be captured.
You cannot capture an expired authorization.

AUTHORIZATION_VOIDED

A voided authorization cannot be captured or reauthorized.
You cannot capture or reauthorize a voided authorization.

CANNOT_BE_NEGATIVE

Must be greater than or equal to 0.

CANNOT_BE_VOIDED

A reauthorization cannot be voided. Please void the original parent authorization.
You cannot void a reauthorized payment. You must void the original parent authorized payment.

CANNOT_BE_ZERO_OR_NEGATIVE

Must be greater than zero. If the currency supports decimals, only two decimal place precision is supported.
Specify a different value and try the request again.

CANNOT_REFUND_SELF

The payer and payee for the refund cannot be same.

CAPTURE_FULLY_REFUNDED

The capture has already been fully refunded.
You cannot capture additional refunds against this capture.

CARD_BILLING_ADDRESS_COUNTRY_NOT_SUPPORTED

Specified country is not currently supported for payment processing.

CARD_BRAND_NOT_SUPPORTED

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

CARD_EXPIRED

The card is expired.

CARD_ISSUER_COUNTRY_NOT_SUPPORTED

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.

CURRENCY_MISMATCH

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

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

CURRENCY_NOT_SUPPORTED_FOR_COUNTRY

Currency code not supported for card payments in your country.

DECIMAL_PRECISION

The value of the field should not be more than two decimal places.
If the currency supports decimals, only two decimal place precision is supported.

DECIMALS_NOT_SUPPORTED

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

DUPLICATE_INVOICE_ID

Requested invoice number has been previously captured. Possible duplicate transaction.
Payment for this invoice was already captured.

DUPLICATE_REFUND

Requested invoice_id has been previously refunded. Possible duplicate transaction.

INSTRUMENT_DECLINED

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

INTERNAL_SERVER_ERROR

An internal server error has occurred.
Try your request again later.

INVALID_ACCOUNT_STATUS

Account validations failed for the user.
The user account could not be validated.

INVALID_CARD_NUMBER

The card number is invalid.

INVALID_CURRENCY_CODE

Currency code should be a three-character ISO-4217 currency code.
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_INVOICE_ID

Specified invoice_id does not exist.
Please check the invoice_id and try again.

INVALID_PARAMETER_SYNTAX

The value of the field does not conform to the expected format.
Verify the specification for supported pattern and try the request again.

INVALID_PARAMETER_VALUE

The value of a field is invalid.
Verify the specification for the allowed values and try the request again.

INVALID_PAYEE_ACCOUNT

Payee account is invalid.
Verify the payee account information and try the request again.

INVALID_PLATFORM_FEES_AMOUNT

The platform_fees amount cannot be greater than the capture amount.
Verify the platform_fees amount and try the request again.

INVALID_RESOURCE_ID

Specified resource ID does not exist. Please check the resource ID and try again.
Verify the resource ID and try the request again.

INVALID_STRING_LENGTH

The value of a field is either too short or too long.
Verify the specification for the supported min and max values and try the request again.

INVALID_STRING_MAX_LENGTH

The value of a field is too long.
The parameter string is too long.

MAX_CAPTURE_AMOUNT_EXCEEDED

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.
Specify a different amount and try the request again. Alternately, contact Customer Support to increase your limits.

MAX_CAPTURE_COUNT_EXCEEDED

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.
You cannot make additional captures.

MAX_NUMBER_OF_REFUNDS_EXCEEDED

You have exceeded the number of refunds that can be processed per capture.
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

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

MAX_PAYER_AMOUNT_LIMIT_EXCEEDED

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

MAX_REFUND_LIMIT_EXCEEDED

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

A required field / parameter is missing.
Verify the specification for required fields and try the request again.

MULTIPLE_AUTHORIZATIONS_FOUND

Cannot void multiple authorizations.
Specified invoice_id is associated with more than one authorization.

NOT_AUTHORIZED

You do not have permission to access or perform operations on this resource.
To make API calls on behalf of a merchant, ensure that you have sufficient permissions to proceed with this transaction.

PARTIAL_REFUND_NOT_ALLOWED

You cannot do a refund for an amount less than the original capture amount.
Specify an amount equal to the capture amount or omit the amount object from the request. Then, try the request again.

PAYEE_ACCOUNT_LOCKED_OR_CLOSED

Transaction could not complete because payee account is locked or closed.
To get more information about the status of the account, call Customer Support.

PAYEE_ACCOUNT_RESTRICTED

Payee account is restricted.
To get more information about the status of the account, call Customer Support.

PAYEE_REFUND_AMOUNT_LIMIT_EXCEEDED

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

PAYER_ACCOUNT_LOCKED_OR_CLOSED

The payer account cannot be used for this transaction.
Contact the payer for an alternate payment method.

PAYER_ACCOUNT_RESTRICTED

Payer account is restricted.
To get more information about the status of the account, call Customer Support.

PAYER_CANNOT_PAY

Payer cannot pay for this transaction.
Please contact the payer to find other ways to pay for this transaction.

PAYER_REFUND_AMOUNT_LIMIT_EXCEEDED

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

PENDING_CAPTURE

Cannot initiate a refund as the capture is pending.
Capture is typically pending when the payer has funded the transaction by using an e-check or bank account.

PERMISSION_DENIED

You do not have permission to access or perform operations on this resource.
To make API calls on behalf of a merchant, ensure that you have sufficient permissions to proceed with this transaction.

PERMISSION_NOT_GRANTED

Payee of the authorization has not granted permission to perform capture on the authorization.
To make API calls on behalf of a merchant, ensure that you have sufficient permissions to capture the authorization.

PLATFORM_FEE_EXCEEDED

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

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.

PREVIOUS_REQUEST_IN_PROGRESS

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

Authorization has been previously captured and hence cannot be voided.
This authorized payment was already captured. You cannot capture it again.

PREVIOUSLY_VOIDED

Authorization has been previously voided and hence cannot be voided again.
This authorized payment was already voided. You cannot void it again.

RATE_LIMIT_REACHED

Too many requests. Blocked due to rate limiting. The rate limit was reached.

REAUTHORIZATION_NOT_SUPPORTED

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.

REFUND_AMOUNT_EXCEEDED

The refund amount must be less than or equal to the capture amount that has not yet been refunded.
Verify the refund amount and try the request again.

REFUND_AMOUNT_TOO_LOW

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

Refund must be in the same currency as the capture.
Verify the currency of the refund and try the request again.

REFUND_FAILED_BY_PAYMENT_SOURCE

Refund was refused by the payment source.
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

Refund cannot be processed due to insufficient funds.
Verify that either you have sufficient funds in your PayPal account or the bank account that is linked to your PayPal account is verified and has sufficient funds.

REFUND_FUNDS_NOT_AVAILABLE

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

REFUND_IS_RESTRICTED

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

Capture cannot be refunded.
You cannot refund this capture.

REFUND_NOT_PERMITTED_DUE_TO_CHARGEBACK

The requested action could not be performed, semantically incorrect, or failed business validation.
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

Refund was refused by the payment source.
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

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

REFUND_TIME_EXCEEDED_FOR_PAYMENT_SOURCE

Refund was refused by the payment source.
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

You are over the time limit to perform a refund on this capture.
The refund cannot be issued at this time.

REFUND_TRANSACTION_REFUSED

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

SHIPPING_ADDRESS_INVALID

Address field does not match the corresponding validation regex.

TRANSACTION_DISPUTED

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

PayPal's internal controls prevent authorization from being captured.
For more information about this transaction, contact customer support.

UPDATE_AUTHORIZATION_NOT_SUPPORTED

Update authorization is not allowed for this type of authorization.

Definitions

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"
}

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.

eci_indicator
string [ 1 .. 256 ] characters

ECI indicator, as defined by 3- Secure.

emv_data
string [ 1 .. 2000 ] characters

Encoded Apple Pay EMV Payment Structure used for payments in China.

pin
string [ 1 .. 2000 ] characters

Bank Key encrypted Apple Pay PIN.

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

authorization

The authorized payment transaction.

status
string

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.

EXPIRED

The authorized payment has expired.

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 <= 127 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 (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"
    },
  • "seller_protection": {
    • "status": "ELIGIBLE",
    • "dispute_categories": [
      • "string"
      ]
    },
  • "expiration_time": "string",
  • "create_time": "stringstringstringst",
  • "update_time": "stringstringstringst"
}

Authorization

The authorized payment transaction.

status
string

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.

EXPIRED

The authorized payment has expired.

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 <= 127 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 (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 (Supplementary Data)

An object that provides supplementary/additional data related to a payment 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"
    },
  • "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"
      }
    }
}

authorization_status

The status fields for an authorized payment.

status
string

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.

EXPIRED

The authorized payment has expired.

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 [ 1 .. 24 ] characters ^[A-Z_]+$

The reason why the authorized status is PENDING.

Value: Description
PENDING_REVIEW

Authorization is pending manual review.

{
  • "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

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

"stringst"

capture

A captured payment.

status
string

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 <= 127 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 intend to capture additional payments against the authorization. Set to false if you intend to capture additional payments against the authorization.

disbursement_mode
string (disbursement_mode) [ 1 .. 16 ] characters ^[A-Z_]+$
Default: "INSTANT"

The funds that are held on behalf of the merchant.

Enum: Description
INSTANT

The funds are released to the merchant immediately.

DELAYED

The funds are held for a finite number of days. The actual duration depends on the region and type of integration. You can release the funds through a referenced payout. Otherwise, the funds disbursed automatically after the specified duration.

Array of objects (Link Description)

An array of related HATEOAS links.

object (Money)

The amount for this captured payment.

object (seller_protection)

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

object (Seller Receivable Breakdown)

The detailed breakdown of the capture activity. This is not available for transactions that are in pending state.

object (processor_response)

An object that provides additional processor information for a direct credit card transaction.

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": "COMPLETED",
  • "status_details": {
    • "reason": "BUYER_COMPLAINT"
    },
  • "id": "string",
  • "invoice_id": "string",
  • "custom_id": "string",
  • "final_capture": false,
  • "disbursement_mode": "INSTANT",
  • "links": [
    • {
      • "href": "string",
      • "rel": "string",
      • "method": "GET"
      }
    ],
  • "amount": {
    • "currency_code": "str",
    • "value": "string"
    },
  • "seller_protection": {
    • "status": "ELIGIBLE",
    • "dispute_categories": [
      • "string"
      ]
    },
  • "seller_receivable_breakdown": {
    • "platform_fees": [
      • {
        • "amount": {
          • "currency_code": "str",
          • "value": "string"
          },
        • "payee": {
          • "email_address": "string",
          • "merchant_id": "stringstrings"
          }
        }
      ],
    • "gross_amount": {
      • "currency_code": "str",
      • "value": "string"
      },
    • "paypal_fee": {
      • "currency_code": "str",
      • "value": "string"
      },
    • "paypal_fee_in_receivable_currency": {
      • "currency_code": "str",
      • "value": "string"
      },
    • "net_amount": {
      • "currency_code": "str",
      • "value": "string"
      },
    • "receivable_amount": {
      • "currency_code": "str",
      • "value": "string"
      },
    • "exchange_rate": {
      • "value": "string",
      • "source_currency": "str",
      • "target_currency": "str"
      }
    },
  • "processor_response": {
    • "avs_code": "A",
    • "cvv_code": "E",
    • "response_code": "0000",
    • "payment_advice_code": "01"
    },
  • "create_time": "stringstringstringst",
  • "update_time": "stringstringstringst"
}

Capture

A captured payment.

status
string

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 <= 127 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 intend to capture additional payments against the authorization. Set to false if you intend to capture additional payments against the authorization.

disbursement_mode
string (disbursement_mode) [ 1 .. 16 ] characters ^[A-Z_]+$
Default: "INSTANT"

The funds that are held on behalf of the merchant.

Enum: Description
INSTANT

The funds are released to the merchant immediately.

DELAYED

The funds are held for a finite number of days. The actual duration depends on the region and type of integration. You can release the funds through a referenced payout. Otherwise, the funds disbursed automatically after the specified duration.

Array of objects (Link Description)

An array of related HATEOAS links.

object (Money)

The amount for this captured payment.

object (seller_protection)

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

object (Seller Receivable Breakdown)

The detailed breakdown of the capture activity. This is not available for transactions that are in pending state.

object (processor_response)

An object that provides additional processor information for a direct credit card transaction.

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 (Supplementary Data)

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

{
  • "status": "COMPLETED",
  • "status_details": {
    • "reason": "BUYER_COMPLAINT"
    },
  • "id": "string",
  • "invoice_id": "string",
  • "custom_id": "string",
  • "final_capture": false,
  • "disbursement_mode": "INSTANT",
  • "links": [
    • {
      • "href": "string",
      • "rel": "string",
      • "method": "GET"
      }
    ],
  • "amount": {
    • "currency_code": "str",
    • "value": "string"
    },
  • "seller_protection": {
    • "status": "ELIGIBLE",
    • "dispute_categories": [
      • "string"
      ]
    },
  • "seller_receivable_breakdown": {
    • "platform_fees": [
      • {
        • "amount": {
          • "currency_code": "str",
          • "value": "string"
          },
        • "payee": {
          • "email_address": "string",
          • "merchant_id": "stringstrings"
          }
        }
      ],
    • "gross_amount": {
      • "currency_code": "str",
      • "value": "string"
      },
    • "paypal_fee": {
      • "currency_code": "str",
      • "value": "string"
      },
    • "paypal_fee_in_receivable_currency": {
      • "currency_code": "str",
      • "value": "string"
      },
    • "net_amount": {
      • "currency_code": "str",
      • "value": "string"
      },
    • "receivable_amount": {
      • "currency_code": "str",
      • "value": "string"
      },
    • "exchange_rate": {
      • "value": "string",
      • "source_currency": "str",
      • "target_currency": "str"
      }
    },
  • "processor_response": {
    • "avs_code": "A",
    • "cvv_code": "E",
    • "response_code": "0000",
    • "payment_advice_code": "01"
    },
  • "create_time": "stringstringstringst",
  • "update_time": "stringstringstringst",
  • "supplementary_data": {
    • "related_ids": {
      • "order_id": "string",
      • "authorization_id": "string",
      • "capture_id": "string"
      }
    }
}

Capture Identifier

The capture identification-related fields. Includes the invoice ID, custom ID, note to payer, and soft descriptor.

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.

{
  • "invoice_id": "string",
  • "note_to_payer": "string"
}

Capture Request

Captures either a portion or the full authorized amount of an authorized payment.

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.

{
  • "invoice_id": "string",
  • "note_to_payer": "string",
  • "final_capture": "false",
  • "payment_instruction": {
    • "platform_fees": [
      • {
        • "amount": {
          • "currency_code": "str",
          • "value": "string"
          },
        • "payee": {
          • "email_address": "string",
          • "merchant_id": "stringstrings"
          }
        }
      ],
    • "payee_pricing_tier_id": "string",
    • "payee_receivable_fx_rate_id": "string",
    • "disbursement_mode": "INSTANT"
    },
  • "soft_descriptor": "string",
  • "amount": {
    • "currency_code": "str",
    • "value": "string"
    }
}

capture_status

The status of a captured payment.

status
string

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.

{
  • "status": "COMPLETED",
  • "status_details": {
    • "reason": "BUYER_COMPLAINT"
    }
}

capture_status_details

The details of the captured payment status.

reason
string [ 1 .. 64 ] characters ^[A-Z_]+$

The reason why the captured payment status is PENDING or DENIED.

Enum: Description
BUYER_COMPLAINT

The payer initiated a dispute for this captured payment with PayPal.

CHARGEBACK

The captured funds were reversed in response to the payer disputing this captured payment with the issuer of the financial instrument used to pay for this captured payment.

ECHECK

The payer paid by an eCheck that has not yet cleared.

INTERNATIONAL_WITHDRAWAL

Visit your online account. In your Account Overview, accept and deny this payment.

OTHER

No additional specific reason can be provided. For more information about this captured payment, visit your account online or contact PayPal.

PENDING_REVIEW

The captured payment is pending manual review.

RECEIVING_PREFERENCE_MANDATES_MANUAL_ACTION

The payee has not yet set up appropriate receiving preferences for their account. For more information about how to accept or deny this payment, visit your account online. This reason is typically offered in scenarios such as when the currency of the captured payment is different from the primary holding currency of the payee.

REFUNDED

The captured funds were refunded.

TRANSACTION_APPROVED_AWAITING_FUNDING

The payer must send the funds for this captured payment. This code generally appears for manual EFTs.

UNILATERAL

The payee does not have a PayPal account.

VERIFICATION_REQUIRED

The payee's PayPal account is not verified.

{
  • "reason": "BUYER_COMPLAINT"
}

card

The payment card to use to fund a payment. Can be a credit or debit card.

name
string [ 1 .. 300 ] characters ^.{1,300}$

The card holder's name as it appears on the card.

number
string [ 13 .. 19 ] characters ^[0-9]{13,19}$

The primary account number (PAN) for the payment card.

security_code
string [ 3 .. 4 ] characters ^[0-9]{3,4}$

The three- or four-digit security code of the card. Also known as the CVV, CVC, CVN, CVE, or CID. This parameter cannot be present in the request when payment_initiator=MERCHANT.

expiry
string (date_year_month) = 7 characters ^[0-9]{4}-(0[1-9]|1[0-2])$

The card expiration year and month, in Internet date format.

object (Portable Postal Address (Medium-Grained))

The billing address for this card. Supports only the address_line_1, address_line_2, admin_area_1, admin_area_2, postal_code, and country_code properties.

{
  • "name": "string",
  • "number": "stringstrings",
  • "security_code": "stri",
  • "expiry": "string",
  • "billing_address": {
    • "address_line_1": "string",
    • "address_line_2": "string",
    • "admin_area_2": "string",
    • "admin_area_1": "string",
    • "postal_code": "string",
    • "country_code": "st"
    }
}

card_brand

The card network or brand. Applies to credit, debit, gift, and payment cards.

string (card_brand) [ 1 .. 255 ] characters ^[A-Z_]+$

The card network or brand. Applies to credit, debit, gift, and payment cards.

Enum: Description
VISA

Visa card.

MASTERCARD

Mastecard card.

DISCOVER

Discover card.

AMEX

American Express card.

SOLO

Solo debit card.

JCB

Japan Credit Bureau card.

STAR

Military Star card.

DELTA

Delta Airlines card.

SWITCH

Switch credit card.

MAESTRO

Maestro credit card.

CB_NATIONALE

Carte Bancaire (CB) credit card.

CONFIGOGA

Configoga credit card.

CONFIDIS

Confidis credit card.

ELECTRON

Visa Electron credit card.

CETELEM

Cetelem credit card.

CHINA_UNION_PAY

China union pay credit card.

"VISA"

card_stored_credential

Provides additional details to process a payment using a card that has been stored or is intended to be stored (also referred to as stored_credential or card-on-file).
Parameter compatibility:

  • payment_type=ONE_TIME is compatible only with payment_initiator=CUSTOMER.
  • usage=FIRST is compatible only with payment_initiator=CUSTOMER.
  • previous_transaction_reference or previous_network_transaction_reference is compatible only with payment_initiator=MERCHANT.
  • Only one of the parameters - previous_transaction_reference and previous_network_transaction_reference - can be present in the request.

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

The person or party who initiated or triggered the payment.

Enum: Description
CUSTOMER

Payment is initiated with the active engagement of the customer. e.g. a customer checking out on a merchant website.

MERCHANT

Payment is initiated by merchant on behalf of the customer without the active engagement of customer. e.g. a merchant charging the monthly payment of a subscription to the customer.

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

Indicates the type of the stored payment_source payment.

Enum: Description
ONE_TIME

One Time payment such as online purchase or donation. (e.g. Checkout with one-click).

RECURRING

Payment which is part of a series of payments with fixed or variable amounts, following a fixed time interval. (e.g. Subscription payments).

UNSCHEDULED

Payment which is part of a series of payments that occur on a non-fixed schedule and/or have variable amounts. (e.g. Account Topup payments).

usage
string (stored_payment_source_usage_type) [ 1 .. 255 ] characters ^[0-9A-Z_]+$
Default: "DERIVED"

Indicates if this is a first or subsequent payment using a stored payment source (also referred to as stored credential or card on file).

Enum: Description
FIRST

Indicates the Initial/First payment with a payment_source that is intended to be stored upon successful processing of the payment.

SUBSEQUENT

Indicates a payment using a stored payment_source which has been successfully used previously for a payment.

DERIVED

Indicates that PayPal will derive the value of FIRST or SUBSEQUENT based on data available to PayPal.

object (network_transaction_reference)

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

{
  • "payment_initiator": "CUSTOMER",
  • "payment_type": "ONE_TIME",
  • "usage": "FIRST",
  • "previous_network_transaction_reference": {
    • "id": "stringstr",
    • "date": "stri",
    • "network": "VISA"
    }
}

card_type

Type of card. i.e Credit, Debit and so on.

string (card_type) [ 1 .. 255 ] characters ^[A-Z_]+$

Type of card. i.e Credit, Debit and so on.

Enum: Description
CREDIT

A credit card.

DEBIT

A debit card.

PREPAID

A Prepaid card.

STORE

A store card.

UNKNOWN

Card type cannot be determined.

"CREDIT"

country_code

The two-character ISO 3166-1 code that identifies the country or region.

Note: The country code for Great Britain is GB and not UK as used in the top-level domain names for that country. Use the C2 country code for China worldwide for comparable uncontrolled price (CUP) method, bank card, and cross-border transactions.

string <ppaas_common_country_code_v2> (country_code) = 2 characters ^([A-Z]{2}|C2)$

The two-character ISO 3166-1 code that identifies the country or region.

Note: The country code for Great Britain is GB and not UK as used in the top-level domain names for that country. Use the C2 country code for China worldwide for comparable uncontrolled price (CUP) method, bank card, and cross-border transactions.

"st"

country_code_v4

The 2-character ISO 3166-1 code that identifies the country or region.

Note: The country code for Great Britain is GB and not UK as used in the top-level domain names for that country. Use the C2 country code for China worldwide for comparable uncontrolled price (CUP) method, bank card, and cross-border transactions.

string <ppaas_common_country_code_v2> (country_code_v4) = 2 characters ^([A-Z]{2}|C2)$

The 2-character ISO 3166-1 code that identifies the country or region.

Note: The country code for Great Britain is GB and not UK as used in the top-level domain names for that country. Use the C2 country code for China worldwide for comparable uncontrolled price (CUP) method, bank card, and cross-border transactions.

"st"

cryptocurrency_symbol

The cryptocurrency symbol or code ticker options. Assigned by liquidity providers and exchanges.

string (cryptocurrency_symbol) [ 1 .. 10 ] characters ^[0-9A-Za-z]{1,10}$

The cryptocurrency symbol or code ticker options. Assigned by liquidity providers and exchanges.

Enum: Description
BTC

The ticker symbol for Bitcoin. https://en.wikipedia.org/wiki/Bitcoin.

ETH

The ticker symbol for Ethereum. https://en.wikipedia.org/wiki/Ethereum.

BCH

The ticker symbol for Bitcoin Cash. https://en.wikipedia.org/wiki/Bitcoin_Cash.

LTC

The ticker symbol for Litecoin. https://en.wikipedia.org/wiki/Litecoin.

"BTC"

currency_code

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

string <ppaas_common_currency_code_v2> (currency_code) = 3 characters

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

"str"

currency_code_v4

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

string <ppaas_common_currency_code_v2> (currency_code_v4) = 3 characters

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

"str"

date_time

The date and time, in Internet date and time format. Seconds are required while fractional seconds are optional.

Note: The regular expression provides guidance but does not reject all invalid dates.

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, in Internet date and time format. Seconds are required while fractional seconds are optional.

Note: The regular expression provides guidance but does not reject all invalid dates.

"stringstringstringst"

date_year_month

The year and month, in ISO-8601 YYYY-MM date format. See Internet date and time format.

string (date_year_month) = 7 characters ^[0-9]{4}-(0[1-9]|1[0-2])$

The year and month, in ISO-8601 YYYY-MM date format. See Internet date and time format.

"strings"

disbursement_mode

The funds that are held on behalf of the merchant.

string (disbursement_mode) [ 1 .. 16 ] characters ^[A-Z_]+$
Default: "INSTANT"

The funds that are held on behalf of the merchant.

Enum: Description
INSTANT

The funds are released to the merchant immediately.

DELAYED

The funds are held for a finite number of days. The actual duration depends on the region and type of integration. You can release the funds through a referenced payout. Otherwise, the funds disbursed automatically after the specified duration.

"INSTANT"

email

The internationalized email address.

Note: Up to 64 characters are allowed before and 255 characters are allowed after the @ sign. However, the generally accepted maximum length for an email address is 254 characters. The pattern verifies that an unquoted @ sign exists.

string <merchant_common_email_address_v2> (email) <= 254 characters (?:[a-zA-Z0-9!#$%&'*+/=?^_`{|}~-]+(?:\.[a-zA-...

The internationalized email address.

Note: Up to 64 characters are allowed before and 255 characters are allowed after the @ sign. However, the generally accepted maximum length for an email address is 254 characters. The pattern verifies that an unquoted @ sign exists.

"string"

email_address

The internationalized email address.

Note: Up to 64 characters are allowed before and 255 characters are allowed after the @ sign. However, the generally accepted maximum length for an email address is 254 characters. The pattern verifies that an unquoted @ sign exists.

string <ppaas_common_email_address_v2> (email_address) [ 3 .. 254 ] characters ^.+@[^"\-].+$

The internationalized email address.

Note: Up to 64 characters are allowed before and 255 characters are allowed after the @ sign. However, the generally accepted maximum length for an email address is 254 characters. The pattern verifies that an unquoted @ sign exists.

"string"

Error

The error details.

name
required
string

The human-readable, unique name of the error.

message
required
string

The message that describes the error.

debug_id
required
string

The PayPal internal ID. Used for correlation purposes.

information_link
string

The information link, or URI, that shows detailed information about this error for the developer.

Array of objects (Error Details)

An array of additional details about the error.

Array of objects (Link Description)

An array of request-related HATEOAS links.

{
  • "name": "string",
  • "message": "string",
  • "debug_id": "string",
  • "information_link": "string",
  • "details": [
    • {
      • "field": "string",
      • "value": "string",
      • "location": "body",
      • "issue": "string",
      • "description": "string"
      }
    ],
  • "links": [
    • {
      • "href": "string",
      • "rel": "string",
      • "method": "GET"
      }
    ]
}

Error Details

The error details. Required for client-side 4XX errors.

field
string

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
string

The value of the field that caused the error.

location
string
Default: "body"

The location of the field that caused the error. Value is body, path, or query.

issue
required
string

The unique, fine-grained application-level error code.

description
string

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.

{
  • "field": "string",
  • "value": "string",
  • "location": "body",
  • "issue": "string",
  • "description": "string"
}

exchange_rate

The exchange rate that determines the amount to convert from one currency to another currency.

value
string

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.

source_currency
string <ppaas_common_currency_code_v2> (currency_code) = 3 characters

The source currency from which to convert an amount.

target_currency
string <ppaas_common_currency_code_v2> (currency_code) = 3 characters

The target currency to which to convert an amount.

{
  • "value": "string",
  • "source_currency": "str",
  • "target_currency": "str"
}

experience_context_base

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

brand_name
string [ 1 .. 127 ] characters

The label that overrides the business name in the PayPal account on the PayPal site.

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.

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

instrument_id

The identifier of the instrument.

string (instrument_id) [ 1 .. 256 ] characters ^[A-Za-z0-9-_.+=]+$

The identifier of the instrument.

"string"

language

The language tag for the language in which to localize the error-related strings, such as messages, issues, and suggested actions. The tag is made up of the ISO 639-2 language code, the optional ISO-15924 script tag, and the ISO-3166 alpha-2 country code or M49 region code.

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

The language tag for the language in which to localize the error-related strings, such as messages, issues, and suggested actions. The tag is made up of the ISO 639-2 language code, the optional ISO-15924 script tag, and the ISO-3166 alpha-2 country code or M49 region code.

"string"

Money

The currency and amount for a financial transaction, such as a balance or payment due.

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

The 3-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.

{
  • "currency_code": "str",
  • "value": "string"
}

Money

The currency and amount for a financial transaction, such as a balance or payment due.

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.

{
  • "currency_code": "str",
  • "value": "string"
}

name

The full name representation like Mr J Smith.

string (name) [ 3 .. 300 ] characters

The full name representation like Mr J Smith.

"string"

net_amount_breakdown

The net amount. Returned when the currency of the refund is different from the currency of the PayPal account where the merchant holds their funds.

object (Money)

The net amount debited from the merchant's PayPal account.

object (Money)

The converted payable amount.

object (exchange_rate)

The exchange rate that determines the amount that was debited from the merchant's PayPal account.

{
  • "payable_amount": {
    • "currency_code": "str",
    • "value": "string"
    },
  • "converted_amount": {
    • "currency_code": "str",
    • "value": "string"
    },
  • "exchange_rate": {
    • "value": "string",
    • "source_currency": "str",
    • "target_currency": "str"
    }
}

network_transaction_reference

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

id
required
string [ 9 .. 15 ] characters ^[a-zA-Z0-9]+$

Transaction reference id returned by the scheme. For Visa and Amex, this is the "Tran id" field in response. For MasterCard, this is the "BankNet reference id" field in response. For Discover, this is the "NRID" field in response.

date
string = 4 characters ^[0-9]+$

The date that the transaction was authorized by the scheme. For MasterCard, this is the "BankNet reference date" field in response.

network
required
string (card_brand) [ 1 .. 255 ] characters ^[A-Z_]+$

Name of the card network through which the transaction was routed.

Enum: Description
VISA

Visa card.

MASTERCARD

Mastecard card.

DISCOVER

Discover card.

AMEX

American Express card.

SOLO

Solo debit card.

JCB

Japan Credit Bureau card.

STAR

Military Star card.

DELTA

Delta Airlines card.

SWITCH

Switch credit card.

MAESTRO

Maestro credit card.

CB_NATIONALE

Carte Bancaire (CB) credit card.

CONFIGOGA

Configoga credit card.

CONFIDIS

Confidis credit card.

ELECTRON

Visa Electron credit card.

CETELEM

Cetelem credit card.

CHINA_UNION_PAY

China union pay credit card.

{
  • "id": "stringstr",
  • "date": "stri",
  • "network": "VISA"
}

Patch

The JSON patch object to apply partial updates to resources.

op
required
string

The operation.

Enum: Description
add

Depending on the target location reference, completes one of these functions:

  • The target location is an array index. Inserts a new value into the array at the specified index.
  • The target location is an object parameter that does not already exist. Adds a new parameter to the object.
  • The target location is an object parameter that does exist. Replaces that parameter's value.
The value parameter defines the value to add. For more information, see 4.1. add.

remove

Removes the value at the target location. For the operation to succeed, the target location must exist. For more information, see 4.2. remove.

replace

Replaces the value at the target location with a new value. The operation object must contain a value parameter that defines the replacement value. For the operation to succeed, the target location must exist. For more information, see 4.3. replace.

move

Removes the value at a specified location and adds it to the target location. The operation object must contain a from parameter, which is a string that contains a JSON pointer value that references the location in the target document from which to move the value. For the operation to succeed, the from location must exist. For more information, see 4.4. move.

copy

Copies the value at a specified location to the target location. The operation object must contain a from parameter, which is a string that contains a JSON pointer value that references the location in the target document from which to copy the value. For the operation to succeed, the from location must exist. For more information, see 4.5. copy.

test

Tests that a value at the target location is equal to a specified value. The operation object must contain a value parameter that defines the value to compare to the target location's value. For the operation to succeed, the target location must be equal to the value value. For test, equal indicates that the value at the target location and the value that value defines are of the same JSON type. The data type of the value determines how equality is defined:

TypeConsidered equal if both values
stringsContain the same number of Unicode characters and their code points are byte-by-byte equal.
numbersAre numerically equal.
arraysContain the same number of values, and each value is equal to the value at the corresponding position in the other array, by using these type-specific rules.
objectsContain the same number of parameters, and each parameter is equal to a parameter in the other object, by comparing their keys (as strings) and their values (by using these type-specific rules).
literals (false, true, and null)Are the same. The comparison is a logical comparison. For example, whitespace between the parameter values of an array is not significant. Also, ordering of the serialization of object parameters is not significant.
For more information, see 4.6. test.

path
string

The JSON Pointer to the target document location at which to complete the operation.

value
object (Patch Value)

The value to apply. The remove operation does not require a value.

from
string

The JSON Pointer to the target document location from which to move the value. Required for the move operation.

{
  • "op": "add",
  • "path": "string",
  • "value": { },
  • "from": "string"
}

payee_base

The details for the merchant who receives the funds and fulfills the order. The merchant is also known as the payee.

email_address
string <merchant_common_email_address_v2> (email) <= 254 characters (?:[a-zA-Z0-9!#$%&'*+/=?^_`{|}~-]+(?:\.[a-zA-...

The email address of merchant.

merchant_id
string <ppaas_payer_id_v3> (PayPal Account Identifier) = 13 characters ^[2-9A-HJ-NP-Z]{13}$

The encrypted PayPal account ID of the merchant.

{
  • "email_address": "string",
  • "merchant_id": "stringstrings"
}

payment_initiator

The person or party who initiated or triggered the payment.

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

The person or party who initiated or triggered the payment.

Enum: Description
CUSTOMER

Payment is initiated with the active engagement of the customer. e.g. a customer checking out on a merchant website.

MERCHANT

Payment is initiated by merchant on behalf of the customer without the active engagement of customer. e.g. a merchant charging the monthly payment of a subscription to the customer.

"CUSTOMER"

payment_instruction

Any additional payments instructions during refund payment processing. This object is only applicable to merchants that have been enabled for PayPal Commerce Platform for Marketplaces and Platforms capability. Please speak to your account manager if you want to use this capability.

Array of objects (platform_fee) [ 0 .. 1 ] items

Specifies the amount that the API caller will contribute to the refund being processed. The amount needs to be lower than platform_fees amount originally captured or the amount that is remaining if multiple refunds have been processed. This field is only applicable to merchants that have been enabled for PayPal Commerce Platform for Marketplaces and Platforms capability. Please speak to your account manager if you want to use this capability.

{
  • "platform_fees": [
    • {
      • "amount": {
        • "currency_code": "str",
        • "value": "string"
        },
      • "payee": {
        • "email_address": "string",
        • "merchant_id": "stringstrings"
        }
      }
    ]
}

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.

Array of objects (platform_fee) [ 0 .. 1 ] items

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.

payee_pricing_tier_id
string [ 1 .. 20 ] characters

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.

payee_receivable_fx_rate_id
string [ 1 .. 4000 ] characters

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.

disbursement_mode
string (disbursement_mode) [ 1 .. 16 ] characters ^[A-Z_]+$
Default: "INSTANT"

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.

Enum: Description
INSTANT

The funds are released to the merchant immediately.

DELAYED

The funds are held for a finite number of days. The actual duration depends on the region and type of integration. You can release the funds through a referenced payout. Otherwise, the funds disbursed automatically after the specified duration.

{
  • "platform_fees": [
    • {
      • "amount": {
        • "currency_code": "str",
        • "value": "string"
        },
      • "payee": {
        • "email_address": "string",
        • "merchant_id": "stringstrings"
        }
      }
    ],
  • "payee_pricing_tier_id": "string",
  • "payee_receivable_fx_rate_id": "string",
  • "disbursement_mode": "INSTANT"
}

PayPal Account Identifier

The account identifier for a PayPal account.

string <ppaas_payer_id_v3> (PayPal Account Identifier) = 13 characters ^[2-9A-HJ-NP-Z]{13}$

The account identifier for a PayPal account.

"stringstrings"

platform_fee

The platform or partner fee, commission, or brokerage fee that is associated with the transaction. Not a separate or isolated transaction leg from the external perspective. The platform fee is limited in scope and is always associated with the original payment for the purchase unit.

required
object (Money)

The fee for this transaction.

object (payee_base)

The recipient of the fee for this transaction. If you omit this value, the default is the API caller.

{
  • "amount": {
    • "currency_code": "str",
    • "value": "string"
    },
  • "payee": {
    • "email_address": "string",
    • "merchant_id": "stringstrings"
    }
}

Point of sale

The API caller-provided information about the store.

store_id
string [ 1 .. 50 ] characters ^[A-Za-z0-9-]{1,50}$

The API caller-provided external store identification number.

terminal_id
string [ 1 .. 50 ] characters ^[A-Za-z0-9-]{1,50}$

The API caller-provided external terminal identification number.

{
  • "store_id": "string",
  • "terminal_id": "string"
}

Portable Postal Address (Medium-Grained)

The portable international postal address. Maps to AddressValidationMetadata and HTML 5.1 Autofilling form controls: the autocomplete attribute.

address_line_1
string <= 300 characters

The first line of the address. For example, number or street. For example, 173 Drury Lane. Required for data entry and compliance and risk checks. Must contain the full address.

address_line_2
string <= 300 characters

The second line of the address. For example, suite or apartment number.

admin_area_2
string <= 120 characters

A city, town, or village. Smaller than admin_area_level_1.

admin_area_1
string <= 300 characters

The highest level sub-division in a country, which is usually a province, state, or ISO-3166-2 subdivision. Format for postal delivery. For example, CA and not California. Value, by country, is:

  • UK. A county.
  • US. A state.
  • Canada. A province.
  • Japan. A prefecture.
  • Switzerland. A kanton.

postal_code
string <= 60 characters

The postal code, which is the zip code or equivalent. Typically required for countries with a postal code or an equivalent. See postal code.

country_code
required
string <ppaas_common_country_code_v2> (country_code) = 2 characters ^([A-Z]{2}|C2)$

The two-character ISO 3166-1 code that identifies the country or region.

Note: The country code for Great Britain is GB and not UK as used in the top-level domain names for that country. Use the C2 country code for China worldwide for comparable uncontrolled price (CUP) method, bank card, and cross-border transactions.

{
  • "address_line_1": "string",
  • "address_line_2": "string",
  • "admin_area_2": "string",
  • "admin_area_1": "string",
  • "postal_code": "string",
  • "country_code": "st"
}

processor_response

The processor information. Might be required for payment requests, such as direct credit card transactions.

avs_code
string

The address verification code for Visa, Discover, Mastercard, or American Express transactions.

Enum: Description
0

For Maestro, all address information matches.

1

For Maestro, none of the address information matches.

2

For Maestro, part of the address information matches.

3

For Maestro, the merchant did not provide AVS information. It was not processed.

4

For Maestro, the address was not checked or the acquirer had no response. The service is not available.

A

For Visa, Mastercard, or Discover transactions, the address matches but the zip code does not match. For American Express transactions, the card holder address is correct.

B

For Visa, Mastercard, or Discover transactions, the address matches. International A.

C

For Visa, Mastercard, or Discover transactions, no values match. International N.

D

For Visa, Mastercard, or Discover transactions, the address and postal code match. International X.

E

For Visa, Mastercard, or Discover transactions, not allowed for Internet or phone transactions. For American Express card holder, the name is incorrect but the address and postal code match.

F

For Visa, Mastercard, or Discover transactions, the address and postal code match. UK-specific X. For American Express card holder, the name is incorrect but the address matches.

G

For Visa, Mastercard, or Discover transactions, global is unavailable. Nothing matches.

I

For Visa, Mastercard, or Discover transactions, international is unavailable. Not applicable.

M

For Visa, Mastercard, or Discover transactions, the address and postal code match. For American Express card holder, the name, address, and postal code match.

N

For Visa, Mastercard, or Discover transactions, nothing matches. For American Express card holder, the address and postal code are both incorrect.

P

For Visa, Mastercard, or Discover transactions, postal international Z. Postal code only.

R

For Visa, Mastercard, or Discover transactions, re-try the request. For American Express, the system is unavailable.

S

For Visa, Mastercard, Discover, or American Express, the service is not supported.

U

For Visa, Mastercard, or Discover transactions, the service is unavailable. For American Express, information is not available. For Maestro, the address is not checked or the acquirer had no response. The service is not available.

W

For Visa, Mastercard, or Discover transactions, whole ZIP code. For American Express, the card holder name, address, and postal code are all incorrect.

X

For Visa, Mastercard, or Discover transactions, exact match of the address and the nine-digit ZIP code. For American Express, the card holder name, address, and postal code are all incorrect.

Y

For Visa, Mastercard, or Discover transactions, the address and five-digit ZIP code match. For American Express, the card holder address and postal code are both correct.

Z

For Visa, Mastercard, or Discover transactions, the five-digit ZIP code matches but no address. For American Express, only the card holder postal code is correct.

Null

For Maestro, no AVS response was obtained.

cvv_code
string

The card verification value code for for Visa, Discover, Mastercard, or American Express.

Enum: Description
0

For Maestro, the CVV2 matched.

1

For Maestro, the CVV2 did not match.

2

For Maestro, the merchant has not implemented CVV2 code handling.

3

For Maestro, the merchant has indicated that CVV2 is not present on card.

4

For Maestro, the service is not available.

E

For Visa, Mastercard, Discover, or American Express, error - unrecognized or unknown response.

I

For Visa, Mastercard, Discover, or American Express, invalid or null.

M

For Visa, Mastercard, Discover, or American Express, the CVV2/CSC matches.

N

For Visa, Mastercard, Discover, or American Express, the CVV2/CSC does not match.

P

For Visa, Mastercard, Discover, or American Express, it was not processed.

S

For Visa, Mastercard, Discover, or American Express, the service is not supported.

U

For Visa, Mastercard, Discover, or American Express, unknown - the issuer is not certified.

X

For Visa, Mastercard, Discover, or American Express, no response. For Maestro, the service is not available.

All others

For Visa, Mastercard, Discover, or American Express, error.

response_code
string

Processor response code for the non-PayPal payment processor errors.

Enum: Description
1000

PARTIAL_AUTHORIZATION.

1300

INVALID_DATA_FORMAT.

1310

INVALID_AMOUNT.

1312

INVALID_TRANSACTION_CARD_ISSUER_ACQUIRER.

1317

INVALID_CAPTURE_DATE.

1320

INVALID_CURRENCY_CODE.

1330

INVALID_ACCOUNT.

1335

INVALID_ACCOUNT_RECURRING.

1340

INVALID_TERMINAL.

1350

INVALID_MERCHANT.

1360

BAD_PROCESSING_CODE.

1370

INVALID_MCC.

1380

INVALID_EXPIRATION.

1382

INVALID_CARD_VERIFICATION_VALUE.

1384

INVALID_LIFE_CYCLE_OF_TRANSACTION.

1390

INVALID_ORDER.

1393

TRANSACTION_CANNOT_BE_COMPLETED.

5100

GENERIC_DECLINE.

5110

CVV2_FAILURE.

5120

INSUFFICIENT_FUNDS.

5130

INVALID_PIN.

5135

DECLINED_PIN_TRY_EXCEEDED.

5140

CARD_CLOSED.

5150

PICKUP_CARD_SPECIAL_CONDITIONS. Try using another card. Do not retry the same card.

5160

UNAUTHORIZED_USER.

5170

AVS_FAILURE.

5180

INVALID_OR_RESTRICTED_CARD. Try using another card. Do not retry the same card.

5190

SOFT_AVS.

5200

DUPLICATE_TRANSACTION.

5210

INVALID_TRANSACTION.

5400

EXPIRED_CARD.

5500

INCORRECT_PIN_REENTER.

5650

DECLINED_SCA_REQUIRED.

5700

TRANSACTION_NOT_PERMITTED. Outside of scope of accepted business.

5710

TX_ATTEMPTS_EXCEED_LIMIT.

5800

REVERSAL_REJECTED.

5900

INVALID_ISSUE.

5910

ISSUER_NOT_AVAILABLE_NOT_RETRIABLE.

5920

ISSUER_NOT_AVAILABLE_RETRIABLE.

5930

CARD_NOT_ACTIVATED.

6300

ACCOUNT_NOT_ON_FILE.

7600

APPROVED_NON_CAPTURE.

7700

ERROR_3DS.

7710

AUTHENTICATION_FAILED.

7800

BIN_ERROR.

7900

PIN_ERROR.

8000

PROCESSOR_SYSTEM_ERROR.

8010

HOST_KEY_ERROR.

8020

CONFIGURATION_ERROR.

8030

UNSUPPORTED_OPERATION.

8100

FATAL_COMMUNICATION_ERROR.

8110

RETRIABLE_COMMUNICATION_ERROR.

8220

SYSTEM_UNAVAILABLE.

9100

DECLINED_PLEASE_RETRY. Retry.

9500

SUSPECTED_FRAUD. Try using another card. Do not retry the same card.

9510

SECURITY_VIOLATION.

9520

LOST_OR_STOLEN. Try using another card. Do not retry the same card.

9530

HOLD_CALL_CENTER. The merchant must call the number on the back of the card. POS scenario.

9540

REFUSED_CARD.

9600

UNRECOGNIZED_RESPONSE_CODE.

0000

APPROVED.

00N7

CVV2_FAILURE_POSSIBLE_RETRY_WITH_CVV.

0100

REFERRAL.

0390

ACCOUNT_NOT_FOUND.

0500

DO_NOT_HONOR.

0580

UNAUTHORIZED_TRANSACTION.

0800

BAD_RESPONSE_REVERSAL_REQUIRED.

0880

CRYPTOGRAPHIC_FAILURE.

0R00

CANCELLED_PAYMENT.

10BR

ISSUER_REJECTED.

PCNR

CONTINGENCIES_NOT_RESOLVED.

PCVV

CVV_FAILURE.

PPAD

BILLING_ADDRESS.

PPAE

AMEX_DISABLED.

PPAG

ADULT_GAMING_UNSUPPORTED.

PPAI

AMOUNT_INCOMPATIBLE.

PPAR

AUTH_RESULT.

PPAU

MCC_CODE.

PPAV

ARC_AVS.

PPAX

AMOUNT_EXCEEDED.

PPBG

BAD_GAMING.

PPC2

ARC_CVV.

PPCE

CE_REGISTRATION_INCOMPLETE.

PPCO

COUNTRY.

PPCR

CREDIT_ERROR.

PPCT

CARD_TYPE_UNSUPPORTED.

PPCU

CURRENCY_USED_INVALID.

PPD3

SECURE_ERROR_3DS.

PPDC

DCC_UNSUPPORTED.

PPDI

DINERS_REJECT.

PPDV

AUTH_MESSAGE.

PPEF

EXPIRED_FUNDING_INSTRUMENT.

PPEL

EXCEEDS_FREQUENCY_LIMIT.

PPER

INTERNAL_SYSTEM_ERROR.

PPEX

EXPIRY_DATE.

PPFE

FUNDING_SOURCE_ALREADY_EXISTS.

PPFI

INVALID_FUNDING_INSTRUMENT.

PPFR

RESTRICTED_FUNDING_INSTRUMENT.

PPFV

FIELD_VALIDATION_FAILED.

PPGR

GAMING_REFUND_ERROR.

PPH1

H1_ERROR.

PPIF

IDEMPOTENCY_FAILURE.

PPII

INVALID_INPUT_FAILURE.

PPIM

ID_MISMATCH.

PPIT

INVALID_TRACE_ID.

PPLR

LATE_REVERSAL.

PPLS

LARGE_STATUS_CODE.

PPMB

MISSING_BUSINESS_RULE_OR_DATA.

PPMC

BLOCKED_Mastercard.

PPMD

PPMD.

PPNC

NOT_SUPPORTED_NRC.

PPNL

EXCEEDS_NETWORK_FREQUENCY_LIMIT.

PPNT

NETWORK_ERROR.

PPPH

NO_PHONE_FOR_DCC_TRANSACTION.

PPPI

INVALID_PRODUCT.

PPPM

INVALID_PAYMENT_METHOD.

PPQC

QUASI_CASH_UNSUPPORTED.

PPRE

UNSUPPORT_REFUND_ON_PENDING_BC.

PPRF

INVALID_PARENT_TRANSACTION_STATUS.

PPRR

MERCHANT_NOT_REGISTERED.

PPS0

BANKAUTH_ROW_MISMATCH.

PPS1

BANKAUTH_ROW_SETTLED.

PPS2

BANKAUTH_ROW_VOIDED.

PPS3

BANKAUTH_EXPIRED.

PPS4

CURRENCY_MISMATCH.

PPS5

CREDITCARD_MISMATCH.

PPS6

AMOUNT_MISMATCH.

PPSC

ARC_SCORE.

PPSD

STATUS_DESCRIPTION.

PPSE

AMEX_DENIED.

PPTE

VERIFICATION_TOKEN_EXPIRED.

PPTF

INVALID_TRACE_REFERENCE.

PPTI

INVALID_TRANSACTION_ID.

PPTR

VERIFICATION_TOKEN_REVOKED.

PPTT

TRANSACTION_TYPE_UNSUPPORTED.

PPTV

INVALID_VERIFICATION_TOKEN.

PPUA

USER_NOT_AUTHORIZED.

PPUC

CURRENCY_CODE_UNSUPPORTED.

PPUE

UNSUPPORT_ENTITY.

PPUI

UNSUPPORT_INSTALLMENT.

PPUP

UNSUPPORT_POS_FLAG.

PPUR

UNSUPPORTED_REVERSAL.

PPVC

VALIDATE_CURRENCY.

PPVE

VALIDATION_ERROR.

PPVT

VIRTUAL_TERMINAL_UNSUPPORTED.

payment_advice_code
string

The declined payment transactions might have payment advice codes. The card networks, like Visa and Mastercard, return payment advice codes.

Enum: Description
21

For Mastercard, the card holder has been unsuccessful at canceling recurring payment through merchant. Stop recurring payment requests. For Visa, all recurring payments were canceled for the card number requested. Stop recurring payment requests.

01

For Mastercard, expired card account upgrade or portfolio sale conversion. Obtain new account information before next billing cycle.

02

For Mastercard, over credit limit or insufficient funds. Retry the transaction 72 hours later. For Visa, the card holder wants to stop only one specific payment in the recurring payment relationship. The merchant must NOT resubmit the same transaction. The merchant can continue the billing process in the subsequent billing period.

03

For Mastercard, account closed as fraudulent. Obtain another type of payment from customer due to account being closed or fraud. Possible reason: Account closed as fraudulent. For Visa, the card holder wants to stop all recurring payment transactions for a specific merchant. Stop recurring payment requests.

{
  • "avs_code": "A",
  • "cvv_code": "E",
  • "response_code": "0000",
  • "payment_advice_code": "01"
}

Reauthorize Request

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.

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 once for 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.

object (Money)

The amount to reauthorize for an authorized payment.

{
  • "amount": {
    • "currency_code": "str",
    • "value": "string"
    }
}

refund

The refund information.

status
string

The status of the refund.

Enum: Description
CANCELLED

The refund was cancelled.

FAILED

The refund could not be processed.

PENDING

The refund is pending. For more information, see status_details.reason.

COMPLETED

The funds for this transaction were debited to the customer's account.

object (refund_status_details)

The details of the refund status.

id
string

The PayPal-generated ID for the refund.

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.

note_to_payer
string

The reason for the refund. Appears in both the payer's transaction history and the emails that the payer receives.

object (Merchant Payable Breakdown)

The breakdown of the refund.

Array of objects (Link Description)

An array of related HATEOAS links.

object (Money)

The amount that the payee refunded to the payer.

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": "CANCELLED",
  • "status_details": {
    • "reason": "ECHECK"
    },
  • "id": "string",
  • "invoice_id": "string",
  • "note_to_payer": "string",
  • "seller_payable_breakdown": {
    • "platform_fees": [
      • {
        • "amount": {
          • "currency_code": "str",
          • "value": "string"
          },
        • "payee": {
          • "email_address": "string",
          • "merchant_id": "stringstrings"
          }
        }
      ],
    • "net_amount_breakdown": [
      • {
        • "payable_amount": {
          • "currency_code": "str",
          • "value": "string"
          },
        • "converted_amount": {
          • "currency_code": "str",
          • "value": "string"
          },
        • "exchange_rate": {
          • "value": "string",
          • "source_currency": "str",
          • "target_currency": "str"
          }
        }
      ],
    • "gross_amount": {
      • "currency_code": "str",
      • "value": "string"
      },
    • "paypal_fee": {
      • "currency_code": "str",
      • "value": "string"
      },
    • "paypal_fee_in_receivable_currency": {
      • "currency_code": "str",
      • "value": "string"
      },
    • "net_amount": {
      • "currency_code": "str",
      • "value": "string"
      },
    • "net_amount_in_receivable_currency": {
      • "currency_code": "str",
      • "value": "string"
      },
    • "total_refunded_amount": {
      • "currency_code": "str",
      • "value": "string"
      }
    },
  • "links": [
    • {
      • "href": "string",
      • "rel": "string",
      • "method": "GET"
      }
    ],
  • "amount": {
    • "currency_code": "str",
    • "value": "string"
    },
  • "create_time": "stringstringstringst",
  • "update_time": "stringstringstringst"
}

Refund Request

Refunds a captured payment, by ID. For a full refund, include an empty request body. For a partial refund, include an amount object in the request body.

invoice_id
string [ 1 .. 127 ] characters

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

The reason for the refund. Appears in both the payer's transaction history and the emails that the payer receives.

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.

{
  • "invoice_id": "string",
  • "note_to_payer": "string",
  • "amount": {
    • "currency_code": "str",
    • "value": "string"
    },
  • "payment_instruction": {
    • "platform_fees": [
      • {
        • "amount": {
          • "currency_code": "str",
          • "value": "string"
          },
        • "payee": {
          • "email_address": "string",
          • "merchant_id": "stringstrings"
          }
        }
      ],
    • "payee_pricing_tier_id": "string",
    • "payee_receivable_fx_rate_id": "string",
    • "disbursement_mode": "INSTANT"
    }
}

refund_status

The refund status.

status
string

The status of the refund.

Enum: Description
CANCELLED

The refund was cancelled.

FAILED

The refund could not be processed.

PENDING

The refund is pending. For more information, see status_details.reason.

COMPLETED

The funds for this transaction were debited to the customer's account.

object (refund_status_details)

The details of the refund status.

{
  • "status": "CANCELLED",
  • "status_details": {
    • "reason": "ECHECK"
    }
}

refund_status_details

The details of the refund status.

reason
string

The reason why the refund has the PENDING or FAILED status.

Value: Description
ECHECK

The customer's account is funded through an eCheck, which has not yet cleared.

{
  • "reason": "ECHECK"
}

Seller Receivable Breakdown

The detailed breakdown of the capture activity. This is not available for transactions that are in pending state.

Array of objects (platform_fee) [ 0 .. 1 ] items

An array of platform or partner fees, commissions, or brokerage fees that associated with the captured payment.

required
object (Money)

The amount for this captured payment in the currency of the transaction.

object (Money)

The applicable fee for this captured payment in the currency of the transaction.

object (Money)

The applicable fee for this captured payment in the receivable currency. Returned only in cases the fee is charged in the receivable currency. Example 'CNY'.

object (Money)

The net amount that the payee receives for this captured payment in their PayPal account. The net amount is computed as gross_amount minus the paypal_fee minus the platform_fees.

object (Money)

The net amount that is credited to the payee's PayPal account. Returned only when the currency of the captured payment is different from the currency of the PayPal account where the payee wants to credit the funds. The amount is computed as net_amount times exchange_rate.

object (exchange_rate)

The exchange rate that determines the amount that is credited to the payee's PayPal account. Returned when the currency of the captured payment is different from the currency of the PayPal account where the payee wants to credit the funds.

{
  • "platform_fees": [
    • {
      • "amount": {
        • "currency_code": "str",
        • "value": "string"
        },
      • "payee": {
        • "email_address": "string",
        • "merchant_id": "stringstrings"
        }
      }
    ],
  • "gross_amount": {
    • "currency_code": "str",
    • "value": "string"
    },
  • "paypal_fee": {
    • "currency_code": "str",
    • "value": "string"
    },
  • "paypal_fee_in_receivable_currency": {
    • "currency_code": "str",
    • "value": "string"
    },
  • "net_amount": {
    • "currency_code": "str",
    • "value": "string"
    },
  • "receivable_amount": {
    • "currency_code": "str",
    • "value": "string"
    },
  • "exchange_rate": {
    • "value": "string",
    • "source_currency": "str",
    • "target_currency": "str"
    }
}

seller_protection

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

status
string

Indicates whether the transaction is eligible for seller protection. For information, see PayPal Seller Protection for Merchants.

Enum: Description
ELIGIBLE

Your PayPal balance remains intact if the customer claims that they did not receive an item or the account holder claims that they did not authorize the payment.

PARTIALLY_ELIGIBLE

Your PayPal balance remains intact if the customer claims that they did not receive an item.

NOT_ELIGIBLE

This transaction is not eligible for seller protection.

dispute_categories
Array of strings

An array of conditions that are covered for the transaction.

{
  • "status": "ELIGIBLE",
  • "dispute_categories": [
    • "string"
    ]
}

stored_payment_source_payment_type

Indicates the type of the stored payment_source payment.

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

Indicates the type of the stored payment_source payment.

Enum: Description
ONE_TIME

One Time payment such as online purchase or donation. (e.g. Checkout with one-click).

RECURRING

Payment which is part of a series of payments with fixed or variable amounts, following a fixed time interval. (e.g. Subscription payments).

UNSCHEDULED

Payment which is part of a series of payments that occur on a non-fixed schedule and/or have variable amounts. (e.g. Account Topup payments).

"ONE_TIME"

stored_payment_source_usage_type

Indicates if this is a first or subsequent payment using a stored payment source (also referred to as stored credential or card on file).

string (stored_payment_source_usage_type) [ 1 .. 255 ] characters ^[0-9A-Z_]+$
Default: "DERIVED"

Indicates if this is a first or subsequent payment using a stored payment source (also referred to as stored credential or card on file).

Enum: Description
FIRST

Indicates the Initial/First payment with a payment_source that is intended to be stored upon successful processing of the payment.

SUBSEQUENT

Indicates a payment using a stored payment_source which has been successfully used previously for a payment.

DERIVED

Indicates that PayPal will derive the value of FIRST or SUBSEQUENT based on data available to PayPal.

"FIRST"

Supplementary Data

The supplementary data.