Payments (1)

API Version v1
Deprecation notice: The /v1/payments endpoint is deprecated. Use the /v2/payments endpoint instead. For details, see PayPal Checkout Basic Integration.
Use the Payments REST API to easily and securely accept online and mobile payments. The payments name space contains resource collections for payments, sales, refunds, authorizations, captures, and orders.
Important: The use of the PayPal REST /payments APIs to accept credit card payments is restricted. Instead, you can accept credit card payments with Braintree Direct.
You can enable customers to make PayPal and credit card payments with only a few clicks, depending on the country. You can accept an immediate payment or authorize a payment and capture it later. You can show details for completed payments, refunds, and authorizations. You can make full or partial refunds. You also can void or re-authorize authorizations. For more information, see the Payments overview.

Create payment

post/v1/payments/payment
Deprecation notice: The /v1/payments endpoint is deprecated. Use the /v2/payments endpoint instead. For details, see PayPal Checkout Basic Integration.
Creates a sale, an authorized payment to be captured later, or an order. To create a sale, authorization, or order, include the payment details in the JSON request body. Set the intent to sale, authorize, or order.
Note: TPP Clients (Third Party Providers in the context of PSD2 regulation) are restricted from using authorize and order intents.
Include payer, transaction details, and, for PayPal payments only, redirect URLs. The combination of the payment_method and funding_instrument determines the type of payment that is created. For more information, see Payments REST API.
SecurityOauth2
Request
header Parameters
PayPal-Partner-Attribution-Id
string <= 32 characters
Request Body schema: application/json
intent
required
string

The payment intent. Value is:

Enum: "sale" "authorize" "order"
Array of objects (Transaction)

An array of payment-related transactions. A transaction defines what the payment is for and who fulfills the payment. For update and execute payment calls, the transactions object accepts the amount object only.

experience_profile_id
string

Deprecated. The PayPal-generated ID for the merchant's payment experience profile. For information, see create web experience profile. Use application_context instead.

note_to_payer
string <= 165 characters

A free-form field that clients can use to send a note to the payer.

object (Redirect URLs)

A set of redirect URLs that you provide for PayPal-based payments.

required
object (Payer)

The source of the funds for this payment. Payment method is PayPal Wallet payment or bank direct debit.

object (Application Context)

Use the application context resource to customize payment flow experience for your buyers.

Responses
201

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

Request samples
application/json
{
  • "intent": "sale",
  • "payer": {
    • "payment_method": "paypal"
    },
  • "transactions": [
    • {
      • "amount": {
        • "total": "30.11",
        • "currency": "USD",
        • "details": {
          • "subtotal": "30.00",
          • "tax": "0.07",
          • "shipping": "0.03",
          • "handling_fee": "1.00",
          • "shipping_discount": "-1.00",
          • "insurance": "0.01"
          }
        },
      • "description": "The payment transaction description.",
      • "custom": "EBAY_EMS_90048630024435",
      • "invoice_number": "48787589673",
      • "payment_options": {
        • "allowed_payment_method": "INSTANT_FUNDING_SOURCE"
        },
      • "soft_descriptor": "ECHI5786786",
      • "item_list": {
        • "items": [
          • {
            • "name": "hat",
            • "description": "Brown hat.",
            • "quantity": "5",
            • "price": "3",
            • "tax": "0.01",
            • "sku": "1",
            • "currency": "USD"
            },
          • {
            • "name": "handbag",
            • "description": "Black handbag.",
            • "quantity": "1",
            • "price": "15",
            • "tax": "0.02",
            • "sku": "product34",
            • "currency": "USD"
            }
          ],
        • "shipping_address": {
          • "recipient_name": "Brian Robinson",
          • "line1": "4th Floor",
          • "line2": "Unit #34",
          • "city": "San Jose",
          • "country_code": "US",
          • "postal_code": "95131",
          • "phone": "011862212345678",
          • "state": "CA"
          }
        }
      }
    ],
  • "note_to_payer": "Contact us for any questions on your order.",
  • "redirect_urls": {}
}
Response samples
application/json
{
  • "id": "PAY-1B56960729604235TKQQIYVY",
  • "create_time": "2017-09-22T20:53:43Z",
  • "update_time": "2017-09-22T20:53:44Z",
  • "state": "CREATED",
  • "intent": "sale",
  • "payer": {
    • "payment_method": "paypal"
    },
  • "transactions": [
    • {
      • "amount": {
        • "total": "30.11",
        • "currency": "USD",
        • "details": {
          • "subtotal": "30.00",
          • "tax": "0.07",
          • "shipping": "0.03",
          • "handling_fee": "1.00",
          • "insurance": "0.01",
          • "shipping_discount": "-1.00"
          }
        },
      • "description": "The payment transaction description.",
      • "custom": "EBAY_EMS_90048630024435",
      • "invoice_number": "48787589673",
      • "item_list": {
        • "items": [
          • {
            • "name": "hat",
            • "sku": "1",
            • "price": "3.00",
            • "currency": "USD",
            • "quantity": "5",
            • "description": "Brown hat.",
            • "tax": "0.01"
            },
          • {
            • "name": "handbag",
            • "sku": "product34",
            • "price": "15.00",
            • "currency": "USD",
            • "quantity": "1",
            • "description": "Black handbag.",
            • "tax": "0.02"
            }
          ],
        • "shipping_address": {
          • "recipient_name": "Brian Robinson",
          • "line1": "4th Floor",
          • "line2": "Unit #34",
          • "city": "San Jose",
          • "state": "CA",
          • "phone": "011862212345678",
          • "postal_code": "95131",
          • "country_code": "US"
          }
        }
      }
    ],
  • "links": []
}

List payments

get/v1/payments/payment
Deprecation notice: The /v1/payments endpoint is deprecated. Use the /v2/payments endpoint instead. For details, see PayPal Checkout Basic Integration.
Lists payments that are completed. Payments that you just created with the create payment call do not appear in the list.

The list shows the payments that are made to the merchant who makes the call. To filter the payments that appear in the response, you can specify one or more optional query and pagination parameters. See Filtering and pagination.
SecurityOauth2
Request
query Parameters
count
integer <= 20
Default: 10

The number of items to list in the response.

start_id
string

The ID of the starting resource in the response. When results are paged, you can use the next_id value as the start_id to continue with the next set of results.

start_index
integer

The start index of the payments to list. Typically, you use the start_index to jump to a specific position in the resource history based on its cart. For example, to start at the second item in a list of results, specify ?start_index=2.

start_time
string

The start date and time for the range to show in the response, in Internet date and time format. For example, start_time=2016-03-06T11:00:00Z.

end_time
string

The end date and time for the range to show in the response, in Internet date and time format. For example, end_time=2016-03-06T11:00:00Z.

payee_id
string

Filters the payments in the response by a PayPal-assigned merchant ID that identifies the payee.

sort_by
string

Sorts the payments in the response by a create time.

Value: "create_time"
sort_order
string

Sorts the payments in the response in descending order.

Value: "desc"
Responses
200

A successful request returns the HTTP 200 OK status code and a JSON response body that lists payments with payment details.

Request samples 
curl -v -X GET https://api-m.sandbox.paypal.com/v1/payments/payment?count=10&start_index=0&sort_by=create_time&sort_order=desc \
-H 'X-PAYPAL-SECURITY-CONTEXT: {"actor":{"account_number":"1659371090107732880","party_id":"1659371090107732880","auth_claims":["CLIENT_ID_SECRET"],"auth_state":"ANONYMOUS","client_id":"zf3..4BQ0T9aw-ngFr9dmOUZMwuKocrqe72Zx9D-Lf4"},"auth_token":"A015QQVR4S3u79k.UvhQ-AP4EhQikqOogdx-wIbvcvZ7Qaw","auth_token_type":"ACCESS_TOKEN","last_validated":1393560555,"scopes":["https://api-m.sandbox.paypal.com/v1/payments/.*","https://api-m.sandbox.paypal.com/v1/vault/credit-card/.*","openid","https://uri.paypal.com/services/payments/futurepayments","https://api-m.sandbox.paypal.com/v1/vault/credit-card","https://api-m.sandbox.paypal.com/v1/payments/.*"]}'
Response samples
application/json
{
  • "payments": [
    • {
      • "id": "PAY-0US81985GW1191216KOY7OXA",
      • "create_time": "2017-06-30T23:48:44Z",
      • "update_time": "2017-06-30T23:49:27Z",
      • "state": "APPROVED",
      • "intent": "order",
      • "payer": {
        • "payment_method": "paypal"
        },
      • "transactions": [
        • {
          • "amount": {
            • "total": "41.15",
            • "currency": "USD",
            • "details": {
              • "subtotal": "30.00",
              • "tax": "1.15",
              • "shipping": "10.00"
              }
            },
          • "description": "The payment transaction description.",
          • "item_list": {
            • "items": [
              • {
                • "name": "hat",
                • "sku": "1",
                • "price": "3.00",
                • "currency": "USD",
                • "quantity": "5"
                },
              • {
                • "name": "handbag",
                • "sku": "product34",
                • "price": "15.00",
                • "currency": "USD",
                • "quantity": "1"
                }
              ],
            • "shipping_address": {
              • "recipient_name": "John Doe",
              • "line1": "4th Floor, One Lagoon Drive",
              • "line2": "Unit #34",
              • "city": "Redwood City",
              • "state": "CA",
              • "phone": "4084217591",
              • "postal_code": "94065",
              • "country_code": "US"
              }
            },
          • "related_resources": []
          }
        ],
      • "links": []
      },
    • {
      • "id": "PAY-53485002LD6169910KOZQ25I",
      • "create_time": "2017-07-01T19:35:17Z",
      • "update_time": "2017-07-01T19:36:05Z",
      • "state": "APPROVED",
      • "intent": "order",
      • "payer": {
        • "payment_method": "paypal"
        },
      • "transactions": [
        • {
          • "amount": {
            • "total": "33.00",
            • "currency": "USD",
            • "details": {
              • "subtotal": "21.00",
              • "tax": "2.00",
              • "shipping": "10.00"
              }
            },
          • "description": "The payment transaction description.",
          • "item_list": {
            • "items": [
              • {
                • "name": "hat",
                • "sku": "1",
                • "price": "3.00",
                • "currency": "USD",
                • "quantity": "2"
                },
              • {
                • "name": "handbag",
                • "sku": "product34",
                • "price": "15.00",
                • "currency": "USD",
                • "quantity": "1"
                }
              ],
            • "shipping_address": {
              • "recipient_name": "Hannah Lu",
              • "line1": "1602 Crane ct",
              • "line2": "",
              • "city": "San Jose",
              • "state": "CA",
              • "phone": "4084217591",
              • "postal_code": "95052",
              • "country_code": "US"
              }
            },
          • "related_resources": []
          }
        ],
      • "links": []
      },
    • {}
    ],
  • "count": 3,
  • "next_id": "PAY-9X4935091L753623RKOZTRHI"
}

Show payment details

get/v1/payments/payment/{payment_id}
Deprecation notice: The /v1/payments endpoint is deprecated. Use the /v2/payments endpoint instead. For details, see PayPal Checkout Basic Integration.
Shows details for a payment, by ID, that has yet to complete. For example, shows details for a payment that was created, approved, or failed.
SecurityOauth2
Request
path Parameters
payment_id
required
string

The ID of the payment for which to show details.

Responses
200

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

Request samples 
curl -v -X GET https://api-m.sandbox.paypal.com/v1/payments/payment/PAY-0US81985GW1191216KOY7OXA \
-H 'X-PAYPAL-SECURITY-CONTEXT: {"actor":{"account_number":"1659371090107732880","party_id":"1659371090107732880","auth_claims":["CLIENT_ID_SECRET"],"auth_state":"ANONYMOUS","client_id":"zf3..4BQ0T9aw-ngFr9dmOUZMwuKocrqe72Zx9D-Lf4"},"auth_token":"A015QQVR4S3u79k.UvhQ-AP4EhQikqOogdx-wIbvcvZ7Qaw","auth_token_type":"ACCESS_TOKEN","last_validated":1393560555,"scopes":["https://api-m.sandbox.paypal.com/v1/payments/.*","https://api-m.sandbox.paypal.com/v1/vault/credit-card/.*","openid","https://uri.paypal.com/services/payments/futurepayments","https://api-m.sandbox.paypal.com/v1/vault/credit-card","https://api-m.sandbox.paypal.com/v1/payments/.*"]}'
Response samples
application/json
{
  • "id": "PAY-0US81985GW1191216KOY7OXA",
  • "create_time": "2017-06-30T23:48:44Z",
  • "update_time": "2017-06-30T23:49:27Z",
  • "state": "APPROVED",
  • "intent": "order",
  • "payer": {
    • "payment_method": "paypal"
    },
  • "transactions": [
    • {
      • "amount": {
        • "total": "41.15",
        • "currency": "USD",
        • "details": {
          • "subtotal": "30.00",
          • "tax": "1.15",
          • "shipping": "10.00"
          }
        },
      • "description": "The payment transaction description.",
      • "item_list": {
        • "items": [
          • {
            • "name": "hat",
            • "sku": "1",
            • "price": "3.00",
            • "currency": "USD",
            • "quantity": "5"
            },
          • {
            • "name": "handbag",
            • "sku": "product34",
            • "price": "15.00",
            • "currency": "USD",
            • "quantity": "1"
            }
          ],
        • "shipping_address": {
          • "recipient_name": "John Doe",
          • "line1": "4th Floor, One Lagoon Drive",
          • "line2": "Unit #34",
          • "city": "Redwood City",
          • "state": "CA",
          • "phone": "4084217591",
          • "postal_code": "94065",
          • "country_code": "US"
          }
        },
      • "related_resources": []
      }
    ],
  • "links": []
}

Partially update payment

patch/v1/payments/payment/{payment_id}
Deprecation notice: The /v1/payments endpoint is deprecated. Use the /v2/payments endpoint instead. For details, see PayPal Checkout Basic Integration.
Partially updates a payment, by ID. You can update the amount, shipping address, invoice ID, and custom data. You cannot update a payment after the payment executes.
Note: TPP Clients (Third Party Providers in the context of PSD2 regulation) are restricted from patching amount once authorized.
SecurityOauth2
Request
path Parameters
payment_id
required
string

The ID of the payment to update.

Request Body schema: application/json
Array
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.

Responses
200

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

Request samples
application/json
[
  • {
    • "op": "replace",
    • "path": "/transactions/0/amount",
    • "value": {
      • "total": "18.37",
      • "currency": "EUR",
      • "details": {
        • "subtotal": "13.37",
        • "shipping": "5.00"
        }
      }
    },
  • {
    • "op": "add",
    • "path": "/transactions/0/item_list/shipping_address",
    • "value": {
      • "recipient_name": "Anna Gruneberg",
      • "line1": "Kathwarinenhof 1",
      • "city": "Flensburg",
      • "postal_code": "24939",
      • "country_code": "DE"
      }
    }
]
Response samples
application/json
{
  • "id": "PAY-5YK922393D847794YKER7MUI",
  • "intent": "authorize",
  • "create_time": "2017-04-24T14:26:59.059Z",
  • "payer": {
    • "payer_info": {
      • "country_code": "DE",
      • "email": "payer@example.com",
      • "first_name": "Gruneberg",
      • "last_name": "Anna",
      • "payer_id": "8J4VWY56VUXQ6",
      • "phone": "605-521-1234"
      },
    • "payment_method": "paypal",
    • "status": "VERIFIED"
    },
  • "state": "APPROVED",
  • "transactions": [
    • {
      • "amount": {
        • "total": "18.37",
        • "currency": "EUR",
        • "details": {
          • "subtotal": "13.37",
          • "shipping": "5.00"
          }
        },
      • "description": "Uber",
      • "item_list": {
        • "items": [
          • {
            • "currency": "EUR",
            • "name": "iPad",
            • "price": "13.37",
            • "quantity": "1"
            }
          ],
        • "shipping_address": {
          • "recipient_name": "Anna Gruneberg",
          • "line1": "Kathwarinenhof 1",
          • "city": "Flensburg",
          • "postal_code": "24939",
          • "country_code": "DE"
          }
        },
      • "payee": {
        • "email": "payee@example.com"
        }
      }
    ],
  • "links": []
}

Execute approved PayPal payment

post/v1/payments/payment/{payment_id}/execute
Deprecation notice: The /v1/payments endpoint is deprecated. Use the /v2/payments endpoint instead. For details, see PayPal Checkout Basic Integration.
Executes a PayPal payment that the customer has approved. You can optionally update one or more transactions when you execute the payment.
Important: This call works only after a customer has approved the payment. For more information, learn about PayPal payments.
SecurityOauth2
Request
path Parameters
payment_id
required
string

The ID of the payment to execute.

header Parameters
PayPal-Request-Id
string <= 78 characters

The server stores keys for 30 days.

PayPal-Partner-Attribution-Id
string <= 32 characters
Request Body schema: application/json
payer_id
string

The ID of the payer that PayPal passes in the return_url.

Array of objects (Cart Base)

An array of transaction details. Includes the amount and item details. For update and execute payment calls, the transactions object accepts only the amount object.

Responses
200

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

Request samples
application/json
{
  • "payer_id": "CR87QHB7JTRSC"
}
Response samples
application/json
{}

Show sale details

get/v1/payments/sale/{sale_id}
Deprecation notice: The /v1/payments endpoint is deprecated. Use the /v2/payments endpoint instead. For details, see PayPal Checkout Basic Integration.
Shows details for a sale, by ID. Returns only sales that were created through the REST API.
SecurityOauth2
Request
path Parameters
sale_id
required
string

The ID of the sale for which to show details.

Responses
200

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

Request samples 
curl -v -X GET https://api-m.sandbox.paypal.com/v1/payments/sale/36C38912MN9658832 \
-H 'X-PAYPAL-SECURITY-CONTEXT: {"actor":{"account_number":"1659371090107732880","party_id":"1659371090107732880","auth_claims":["CLIENT_ID_SECRET"],"auth_state":"ANONYMOUS","client_id":"zf3..4BQ0T9aw-ngFr9dmOUZMwuKocrqe72Zx9D-Lf4"},"auth_token":"A015QQVR4S3u79k.UvhQ-AP4EhQikqOogdx-wIbvcvZ7Qaw","auth_token_type":"ACCESS_TOKEN","last_validated":1393560555,"scopes":["https://api-m.sandbox.paypal.com/v1/payments/.*","https://api-m.sandbox.paypal.com/v1/vault/credit-card/.*","openid","https://uri.paypal.com/services/payments/futurepayments","https://api-m.sandbox.paypal.com/v1/vault/credit-card","https://api-m.sandbox.paypal.com/v1/payments/.*"]}'
Response samples
application/json
{}

Refund sale

post/v1/payments/sale/{sale_id}/refund
Deprecation notice: The /v1/payments endpoint is deprecated. Use the /v2/payments endpoint instead. For details, see PayPal Checkout Basic Integration.
Refunds a sale, by ID. For a full refund, do not include the amount object in the JSON request body. For a partial refund, include an amount object in the JSON request body.
SecurityOauth2
Request
path Parameters
sale_id
required
string

The ID of the sale transaction to refund.

header Parameters
PayPal-Request-Id
string <= 78 characters

The server stores keys for 30 days.

Request Body schema: application/json
description
string <= 255 characters

The refund description. Value is a string of single-byte alphanumeric characters.

reason
string <= 30 characters

The refund reason description.

invoice_number
string <= 127 characters

The invoice number that tracks this payment. Value is a string of single-byte alphanumeric characters.

object (Amount)

The refund amount. Includes both the amount to refund to the payer and the fee amount to refund to the payee.

Responses
201

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

Request samples
application/json
{
  • "amount": {
    • "total": "2.34",
    • "currency": "USD"
    },
  • "invoice_number": "INV-1234567"
}
Response samples
application/json
{
  • "id": "5CY176817C379973E",
  • "create_time": "2018-08-15T17:11:32Z",
  • "update_time": "2018-08-15T17:11:32Z",
  • "state": "COMPLETED",
  • "amount": {
    • "total": "2.34",
    • "currency": "USD"
    },
  • "refund_from_transaction_fee": {
    • "currency": "USD",
    • "value": "0.06"
    },
  • "total_refunded_amount": {
    • "currency": "USD",
    • "value": "2.34"
    },
  • "refund_from_received_amount": {
    • "currency": "USD",
    • "value": "2.28"
    },
  • "sale_id": " 2MU78835H4515710F ",
  • "parent_payment": "PAY-9EH2230144138005NLN2F4EA",
  • "invoice_number": "INV-1234567",
  • "links": []
}

Show authorization details

get/v1/payments/authorization/{authorization_id}
Deprecation notice: The /v1/payments endpoint is deprecated. Use the /v2/payments endpoint instead. For details, see PayPal Checkout Basic Integration.
Shows details for an authorization, by ID.
SecurityOauth2
Request
path Parameters
authorization_id
required
string

The ID of the authorization for which to show details.

Responses
200

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

Request samples 
curl -v -X GET https://api-m.sandbox.paypal.com/v1/payments/authorization/2DC87612EK520411B \
-H 'X-PAYPAL-SECURITY-CONTEXT: {"actor":{"account_number":"1659371090107732880","party_id":"1659371090107732880","auth_claims":["AUTHORIZATION_CODE"],"auth_state":"ANONYMOUS","client_id":"zf3..4BQ0T9aw-ngFr9dmOUZMwuKocrqe72Zx9D-Lf4"},"auth_token":"A015QQVR4S3u79k.UvhQ-AP4EhQikqOogdx-wIbvcvZ7Qaw","auth_token_type":"ACCESS_TOKEN","last_validated":1393560555,"scopes":["https://api-m.sandbox.paypal.com/v1/payments/.*","https://api-m.sandbox.paypal.com/v1/vault/credit-card/.*","openid","https://uri.paypal.com/services/payments/futurepayments","https://api-m.sandbox.paypal.com/v1/vault/credit-card","https://api-m.sandbox.paypal.com/v1/payments/.*"],"subjects":[{"subject":{"account_number":"2245934915437588879","party_id":"2245934915437588879","auth_claims":["PASSWORD"],"auth_state":"LOGGEDIN"}}]}'
Response samples
application/json
{}

Capture authorization

post/v1/payments/authorization/{authorization_id}/capture
Deprecation notice: The /v1/payments endpoint is deprecated. Use the /v2/payments endpoint instead. For details, see PayPal Checkout Basic Integration.
Captures and processes an authorization, by ID. The original payment call must specify an intent of authorize.
SecurityOauth2
Request
path Parameters
authorization_id
required
string

The ID of the authorization to capture.

Request Body schema: application/json
is_final_capture
boolean
Default: false

Indicates whether to release all remaining held funds.

invoice_number
string <= 127 characters

The invoice number to track this payment.

note_to_payer
string <= 255 characters

A free-form field that clients can use to send a note to the payer.

object (Amount)

The amount to capture. If the amount matches the originally authorized amount, the state of the authorization changes to captured. Otherwise, the state changes to partially_captured.

Responses
201

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

Request samples
application/json
{
  • "amount": {
    • "currency": "USD",
    • "total": "4.54"
    },
  • "is_final_capture": true
}
Response samples
application/json
{}

Void authorization

post/v1/payments/authorization/{authorization_id}/void
Deprecation notice: The /v1/payments endpoint is deprecated. Use the /v2/payments endpoint instead. For details, see PayPal Checkout Basic Integration.
Voids, or cancels, an authorization, by ID. You cannot void a fully captured authorization.
SecurityOauth2
Request
path Parameters
authorization_id
required
string

The ID of the authorization to void.

header Parameters
PayPal-Request-Id
string <= 78 characters

The server stores keys for 30 days.

Responses
200

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

Request samples 
curl -v -X POST https://api-m.sandbox.paypal.com/v1/payments/authorization/2DC87612EK520411B/void \
-H 'X-PAYPAL-SECURITY-CONTEXT: {"actor":{"account_number":"1659371090107732880","party_id":"1659371090107732880","auth_claims":["AUTHORIZATION_CODE"],"auth_state":"ANONYMOUS","client_id":"zf3..4BQ0T9aw-ngFr9dmOUZMwuKocrqe72Zx9D-Lf4"},"auth_token":"A015QQVR4S3u79k.UvhQ-AP4EhQikqOogdx-wIbvcvZ7Qaw","auth_token_type":"ACCESS_TOKEN","last_validated":1393560555,"scopes":["https://api-m.sandbox.paypal.com/v1/payments/.*","https://api-m.sandbox.paypal.com/v1/vault/credit-card/.*","openid","https://uri.paypal.com/services/payments/futurepayments","https://api-m.sandbox.paypal.com/v1/vault/credit-card","https://api-m.sandbox.paypal.com/v1/payments/.*"],"subjects":[{"subject":{"account_number":"2245934915437588879","party_id":"2245934915437588879","auth_claims":["PASSWORD"],"auth_state":"LOGGEDIN"}}]}'
Response samples
application/json
{}

Re-authorize payment

post/v1/payments/authorization/{authorization_id}/reauthorize
Deprecation notice: The /v1/payments endpoint is deprecated. Use the /v2/payments endpoint instead. For details, see PayPal Checkout Basic Integration.
Re-authorizes a PayPal account payment, by authorization ID. To ensure that funds are still available, re-authorize a payment after the initial three-day honor period. Supports only the amount request parameter. You can re-authorize a payment only once from four to 29 days after three-day honor period for the original authorization expires. If 30 days have passed from the original authorization, you must create a new authorization instead. A re-authorized payment itself has a new three-day honor period. You can re-authorize a transaction once for up to 115% of the originally authorized amount, not to exceed an increase of $75 USD.
SecurityOauth2
Request
path Parameters
authorization_id
required
string

The ID of the authorization to re-authorize.

Request Body schema: application/json
object (FMF Details)

The Fraud Management Filter (FMF) details that are applied to the payment that result in an accept, deny, or pending action. Returned in a payment response only if the merchant has enabled FMF in the profile settings and one of the fraud filters was triggered based on those settings. For more information, see Fraud Management Filters Summary.

object (Processor Response)

The processor-provided response codes that describe the submitted payment. Supported only when the payment_method is credit_card.

required
object (Amount)

The payment amount, with details.

Responses
201

A successful request returns the HTTP 201 Created status code and a JSON response body that shows details for the re-authorized authorization.

Request samples
application/json
{
  • "amount": {
    • "currency": "USD",
    • "total": "7.00"
    }
}
Response samples
application/json
{}

Show order details

get/v1/payments/orders/{order_id}
Deprecation notice: The /v1/payments endpoint is deprecated. Use the /v2/payments endpoint instead. For details, see PayPal Checkout Basic Integration.
Shows details for an order, by ID.
SecurityOauth2
Request
path Parameters
order_id
required
string

The ID of the order for which to show details.

Responses
200

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

Request samples 
curl -v -X GET https://api-m.sandbox.paypal.com/v1/payments/orders/O-0PW72302W3743444R \
-H 'X-PAYPAL-SECURITY-CONTEXT: {"actor":{"account_number":"1659371090107732880","party_id":"1659371090107732880","auth_claims":["CLIENT_ID_SECRET"],"auth_state":"ANONYMOUS","client_id":"zf3..4BQ0T9aw-ngFr9dmOUZMwuKocrqe72Zx9D-Lf4"},"auth_token":"A015QQVR4S3u79k.UvhQ-AP4EhQikqOogdx-wIbvcvZ7Qaw","auth_token_type":"ACCESS_TOKEN","last_validated":1393560555,"scopes":["https://api-m.sandbox.paypal.com/v1/payments/.*","https://api-m.sandbox.paypal.com/v1/vault/credit-card/.*","openid","https://uri.paypal.com/services/payments/futurepayments","https://api-m.sandbox.paypal.com/v1/vault/credit-card","https://api-m.sandbox.paypal.com/v1/payments/.*"]}'
Response samples
application/json
{}

Capture order

post/v1/payments/orders/{order_id}/capture
Deprecation notice: The /v1/payments endpoint is deprecated. Use the /v2/payments endpoint instead. For details, see PayPal Checkout Basic Integration.
Captures a payment for an order, by ID. To use this call, the original payment call must specify an order intent. In the JSON request body, include the payment amount and indicate whether this capture is the final capture for the authorization.
SecurityOauth2
Request
path Parameters
order_id
required
string

The ID of the order to capture.

Request Body schema: application/json
is_final_capture
boolean
Default: false

Indicates whether to release all remaining held funds.

invoice_number
string <= 127 characters

The invoice number to track this payment.

note_to_payer
string <= 255 characters

A free-form field that clients can use to send a note to the payer.

object (Amount)

The amount to capture. If the amount matches the originally authorized amount, the state of the authorization changes to captured. Otherwise, the state changes to partially_captured.

Responses
201

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

Request samples
application/json
{
  • "amount": {
    • "currency": "USD",
    • "total": "4.54"
    },
  • "is_final_capture": true
}
Response samples
application/json
{}

Void order

post/v1/payments/orders/{order_id}/do-void
Deprecation notice: The /v1/payments endpoint is deprecated. Use the /v2/payments endpoint instead. For details, see PayPal Checkout Basic Integration.
Voids, or cancels, an order, by ID. You can only void orders that are either in the PENDING or AUTHORIZED states or those in the CAPTURED state that are not fully captured.
SecurityOauth2
Request
path Parameters
order_id
required
string

The ID of the order to void.

header Parameters
PayPal-Request-Id
string <= 78 characters

The server stores keys for 30 days.

Responses
200

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

Request samples 
curl -v -X POST https://api-m.sandbox.paypal.com/v1/payments/orders/O-0NR488530V5211123/do-void \
-H 'X-PAYPAL-SECURITY-CONTEXT: {"actor":{"account_number":"1659371090107732880","party_id":"1659371090107732880","auth_claims":["AUTHORIZATION_CODE"],"auth_state":"ANONYMOUS","client_id":"zf3..4BQ0T9aw-ngFr9dmOUZMwuKocrqe72Zx9D-Lf4"},"auth_token":"A015QQVR4S3u79k.UvhQ-AP4EhQikqOogdx-wIbvcvZ7Qaw","auth_token_type":"ACCESS_TOKEN","last_validated":1393560555,"scopes":["https://api-m.sandbox.paypal.com/v1/payments/.*","https://api-m.sandbox.paypal.com/v1/vault/credit-card/.*","openid","https://uri.paypal.com/services/payments/futurepayments","https://api-m.sandbox.paypal.com/v1/vault/credit-card","https://api-m.sandbox.paypal.com/v1/payments/.*"]}'
Response samples
application/json
{}

Authorize order

post/v1/payments/orders/{order_id}/authorize
Deprecation notice: The /v1/payments endpoint is deprecated. Use the /v2/payments endpoint instead. For details, see PayPal Checkout Basic Integration.
Authorizes an order, by ID. In the JSON request body, include an amount object.
SecurityOauth2
Request
path Parameters
order_id
required
string

The ID of the order to authorize.

Request Body schema: application/json
object (FMF Details)

The Fraud Management Filter (FMF) details that are applied to the payment that result in an accept, deny, or pending action. Returned in a payment response only if the merchant has enabled FMF in the profile settings and one of the fraud filters was triggered based on those settings. For more information, see Fraud Management Filters Summary.

required
object (Amount)

The amount to collect.

Note: For an order authorization, you cannot include amount details.

Responses
201

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

Request samples
application/json
{
  • "amount": {
    • "currency": "USD",
    • "total": "4.54"
    }
}
Response samples
application/json
{}

Show captured payment details

get/v1/payments/capture/{capture_id}
Deprecation notice: The /v1/payments endpoint is deprecated. Use the /v2/payments endpoint instead. For details, see PayPal Checkout Basic Integration.
Shows details for a captured payment, by ID.
SecurityOauth2
Request
path Parameters
capture_id
required
string

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

Responses
200

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

Request samples 
curl -v -X GET https://api-m.sandbox.paypal.com/v1/payments/capture/8F148933LY9388354 \
-H 'X-PAYPAL-SECURITY-CONTEXT: {"actor":{"account_number":"1659371090107732880","party_id":"1659371090107732880","auth_claims":["AUTHORIZATION_CODE"],"auth_state":"ANONYMOUS","client_id":"zf3..4BQ0T9aw-ngFr9dmOUZMwuKocrqe72Zx9D-Lf4"},"auth_token":"A015QQVR4S3u79k.UvhQ-AP4EhQikqOogdx-wIbvcvZ7Qaw","auth_token_type":"ACCESS_TOKEN","last_validated":1393560555,"scopes":["https://api-m.sandbox.paypal.com/v1/payments/.*","https://api-m.sandbox.paypal.com/v1/vault/credit-card/.*","openid","https://uri.paypal.com/services/payments/futurepayments","https://api-m.sandbox.paypal.com/v1/vault/credit-card","https://api-m.sandbox.paypal.com/v1/payments/.*"],"subjects":[{"subject":{"account_number":"2245934915437588879","party_id":"2245934915437588879","auth_claims":["PASSWORD"],"auth_state":"LOGGEDIN"}}]}'
Response samples
application/json
{}

Refund captured payment

post/v1/payments/capture/{capture_id}/refund
Deprecation notice: The /v1/payments endpoint is deprecated. Use the /v2/payments endpoint instead. For details, see PayPal Checkout Basic Integration.
Refunds a captured payment, by ID. In the JSON request body, include an amount object.
SecurityOauth2
Request
path Parameters
capture_id
required
string

The ID of the captured payment to refund.

header Parameters
PayPal-Request-Id
string <= 78 characters

The server stores keys for 30 days.

Request Body schema: application/json
description
string <= 255 characters

The refund description. Value is a string of single-byte alphanumeric characters.

reason
string <= 30 characters

The refund reason description.

invoice_number
string <= 127 characters

The invoice number that tracks this payment. Value is a string of single-byte alphanumeric characters.

object (Amount)

The refund amount. Includes both the amount to refund to the payer and the fee amount to refund to the payee.

Responses
201

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

Request samples
application/json
{
  • "amount": {
    • "total": "100.00",
    • "currency": "USD"
    },
  • "invoice_number": "INV-7654321"
}
Response samples
application/json
{}

Show refund details

get/v1/payments/refund/{refund_id}
Deprecation notice: The /v1/payments endpoint is deprecated. Use the /v2/payments endpoint instead. For details, see PayPal Checkout Basic Integration.
Shows details for a refund, by ID.
SecurityOauth2
Request
path Parameters
refund_id
required
string

The ID of the refund for which to show details.

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/v1/payments/refund/4GU360220B627614A \
-H 'X-PAYPAL-SECURITY-CONTEXT: {"actor":{"account_number":"1659371090107732880","party_id":"1659371090107732880","auth_claims":["AUTHORIZATION_CODE"],"auth_state":"ANONYMOUS","client_id":"zf3..4BQ0T9aw-ngFr9dmOUZMwuKocrqe72Zx9D-Lf4"},"auth_token":"A015QQVR4S3u79k.UvhQ-AP4EhQikqOogdx-wIbvcvZ7Qaw","auth_token_type":"ACCESS_TOKEN","last_validated":1393560555,"scopes":["https://api-m.sandbox.paypal.com/v1/payments/.*","https://api-m.sandbox.paypal.com/v1/vault/credit-card/.*","openid","https://uri.paypal.com/services/payments/futurepayments","https://api-m.sandbox.paypal.com/v1/vault/credit-card","https://api-m.sandbox.paypal.com/v1/payments/.*"],"subjects":[{"subject":{"account_number":"2245934915437588879","party_id":"2245934915437588879","auth_claims":["PASSWORD"],"auth_state":"LOGGEDIN"}}]}'
Response samples
application/json
{}

Errors

AGREEMENT_ALREADY_CANCELLED

The requested agreement is already canceled. The agreement that was used to make the payment is already canceled.

AMOUNT_MISMATCH

The totals of the cart item amounts do not match sale amounts. The amount total does not match the item amount totals.

AUTH_SETTLE_NOT_ALLOWED

Authorization and Capture feature is not enabled for the merchant. Make sure that the recipient of the funds is a verified business account.

AUTHORIZATION_ALREADY_COMPLETED

Capture refused - this authorization has already been completed. The capture on the authorization failed because it was already completed by one or more previous captures on this authorization.

AUTHORIZATION_AMOUNT_LIMIT_EXCEEDED

Authorization amount exceeds allowed order limit. The authorization amount exceeds the allowed order limit.

AUTHORIZATION_CANNOT_BE_VOIDED

Authorization is in [x] state and hence cannot be voided. You cannot void this authorization because it is in a state, such as captured or expired, that cannot be voided.

AUTHORIZATION_EXPIRED

Authorization has expired. The authorization related to this request has expired. You must reauthorize the transaction.

AUTHORIZATION_ID_DOES_NOT_EXIST

The requested authorization ID does not exist. The authorization ID in the request does not exist in the PayPal system.

AUTHORIZATION_VOIDED

Authorization has been voided. This authorization was already voided. You can show authorization details for a voided authorization.

BA_TOKEN_CREATION_FAILED

Billing agreement token creation failed. The billing agreement token creation failed.

BANK_ACCOUNT_VALIDATION_FAILED

Bank account validation failed. The validation of the bank account failed.

BILLING_AGREEMENT_CREATION_FAILED

Billing agreement creation failed. The billing agreement creation failed.

BILLING_AGREEMENT_ID_MISMATCH

Billing Agreement ID must match the one that was provided during payment creation. Billing Agreement ID must match the one that was provided during payment creation.

BUYER_NOT_SET

Buyer is not yet set for this purchase. The customer cannot make this purchase.

CANNOT_PAY_SELF

Payer cannot pay him- or herself. The customer cannot pay him- or herself.

CANNOT_REAUTH_CHILD_AUTHORIZATION

Can only reauthorize the original authorization, not a reauthorization. Reauthorization only works on an original authorization ID.

CANNOT_REAUTH_INSIDE_HONOR_PERIOD

Reauthorization is not allowed within the honor period. You can only reauthorize a payment after the three-day honor period concludes.

CAPTURE_AMOUNT_LIMIT_EXCEEDED

Capture amount specified exceeded allowable limit. You can only capture up to the original authorization amount.

CARD_TOKEN_PAYER_MISMATCH

payer_id does not match ID for this token. The payer_id must match the one that was provided when the credit card was stored in the vault.

COMPLIANCE_VIOLATION

Transaction is declined due to compliance violation. The transaction is declined due to a compliance violation.

CREDIT_CARD_CVV_CHECK_FAILED

The credit card CVV check failed. The CVV provided for the credit card was not valid. Resend the payment with a valid CVV for the credit card.

CREDIT_CARD_REFUSED

Credit card was refused. The credit card used for the payment was refused. Resend the request with another credit card.

CREDIT_PAYMENT_NOT_ALLOWED

Buyer cannot use credit to complete the payment. You cannot use credit to complete this payment. Ask the customer to retry the transaction with alternate funding instrument.

CURRENCY_MISMATCH

Currency provided in the request must match the currency of the parent order or authorization. The currency that was used to capture an authorization must match the original currency of the authorization.

CURRENCY_NOT_ALLOWED

Currency is not supported. The currency is not currently supported.

DOMESTIC_TRANSACTION_REQUIRED

This transaction requires the payee and payer to be resident in the same country, a domestic transaction is required to create this payment. The payer and payee do not reside in the same country.

DUPLICATE_REQUEST_ID

The value of PayPal-Request-Id header has already been used. Resend the request with a unique PayPal-Request-Id header value.

DUPLICATE_TRANSACTION

Duplicate invoice Id detected. Resend the request with a unique invoice_number value.

ERROR_AUTH

Unauthorized payment. You do not have the proper permissions to complete this request.

EXPIRED_CREDIT_CARD_TOKEN

Credit card token is expired. Use the Vault API to store the credit card again.

FEATURE_UNSUPPORTED_FOR_PAYEE

This feature is unsupported. This feature is not supported for the payee.

FULL_REFUND_NOT_ALLOWED_AFTER_PARTIAL_REFUND

Full refund refused - partial refund has already been done on this payment. You cannot refund the full payment amount after you have partially refunded a payment.

IMMEDIATE_PAY_NOT_SUPPORTED

Immediate pay is not supported for the specified payment intent. For this payment intent, immediate payment is not supported.

INSTRUMENT_DECLINED

The instrument presented was either declined by the processor or bank, or it can't be used for this payment. If the customer's funding source has insufficient funds, restart the payment and prompt the customer to choose another payment method that is available on your site.

INSUFFICIENT_FUNDS

Buyer cannot pay - insufficient funds. The customer must add a valid funding instrument, such as a credit card or bank account, to their PayPal account.

INTERNAL_SERVICE_ERROR

An internal service error has occurred. Resend the request at another time. If this error persists, contact PayPal Merchant Technical Support.

INVALID_ACCOUNT_NUMBER

Account number does not exist. Provide a valid account number and resend the request.

INVALID_CITY_STATE_ZIP

The combination of city, state, and zip in the address is invalid. The address contains an invalid combination of a city, state, and zip code.

INVALID_EXPERIENCE_PROFILE_ID

The requested experience profile ID was not found. To get the profile ID for a merchant, list web experience profiles.

INVALID_FACILITATOR_CONFIGURATION

This transaction cannot be processed due to an invalid facilitator configuration. To process this transaction type, you must have the right account configuration.

INVALID_PAYER_ID

Payer ID is invalid. The specified payer_id is not valid. Resend the request with a valid payer_id.

INVALID_PAYPAL_PAYMENT_TOKEN

Payment token is invalid. A payment token is typically valid for 3 hours since the time it was issued. Please check the token and try again. Will be returned only for Google Pay Integration for the Create payment call.

INVALID_PICKUP_ADDRESS

Invalid shipping address. If the 'shipping_option.type' is set as 'PICKUP' then the 'shipping_address.recipient_name' should start with 'S2S' meaning Ship To Store. Example: 'S2S My Store'.

INVALID_RESOURCE_ID

The requested resource ID was not found. Provide a valid resource ID and resend the request.

MALFORMED_REQUEST

JSON request is malformed. Review the JSON request.

MAX_NUMBER_OF_PAYMENT_ATTEMPTS_EXCEEDED

You have exceeded the maximum number of payment attempts. The maximum number of payment attempts was reached.

MAXIMUM_ALLOWED_AUTHORIZATION_REACHED_FOR_ORDER

You have reached the configured maximum number of authorizations allowed for an order. You cannot create any more authorizations for this order.

MERCHANT_NOT_ENABLED_FOR_CHANNEL_INITIATED_BILLING

Merchant is not enabled for channel-initiated billing. The merchant cannot use channel-initiated billing.

MERCHANT_NOT_ENABLED_FOR_REFERENCE_TRANSACTION

Merchant is not enabled for reference transaction. The merchant cannot make reference transactions.

NEED_CREDIT_CARD

Need credit card to complete the payment. To complete this payment, a credit card is required.

NEED_CREDIT_CARD_OR_BANK_ACCOUNT

Need bank or credit card to complete the payment. To complete this payment, a bank card or credit card is required.

NOT_IMPLEMENTED

Not implemented. This API capability is not implemented.

ORDER_ALREADY_COMPLETED

Order has already been voided, expired, or completed. This order was already voided, completed, or expired.

ORDER_CANNOT_BE_VOIDED

You can only void orders that are either in the PENDING or AUTHORIZED state, or those in the CAPTURED state that are not fully captured. Due to the state of the order, you cannot void it.

ORDER_IS_EXPIRED

Order has expired. The order has expired.

ORDER_VOIDED

Order has been voided. The order was already voided. For more information, you can show order details.

PAYEE_ACCOUNT_INVALID

Payee account is invalid. The payee account is not valid.

PAYEE_ACCOUNT_LOCKED_OR_CLOSED

Payee account is locked or closed. The recipient account is locked or closed and cannot receive payments.

PAYEE_ACCOUNT_NO_CONFIRMED_EMAIL

Refused - payee account does not have a confirmed email. For this transaction to proceed, the payment recipient must have a confirmed email.

PAYEE_ACCOUNT_RESTRICTED

Refused - payee account is restricted. The account receiving this payment is restricted and cannot receive payments at this time.

PAYEE_BLOCKED_TRANSACTION

The Fraud settings for this seller are such that this payment cannot be executed. The fraud filter configuration for the seller blocks this payment.

PAYEE_COUNTRY_NOT_ENABLED

Payee country is not enabled for this feature. The payee country is not enabled for billing product.

PAYER_ACCOUNT_LOCKED_OR_CLOSED

The payer account cannot be used for this transaction. The payer account is locked or closed.

PAYER_ACCOUNT_RESTRICTED

The payer account is restricted. The payer account cannot be used for this transaction.

PAYER_ACTION_REQUIRED

Transaction cannot complete successfully, instruct the buyer to return to PP. The customer must return to PayPal to before the transaction can complete.

PAYER_CANNOT_PAY

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

PAYER_COUNTRY_NOT_ENABLED

Payer country is not enabled for this feature. The payer country is not enabled for billing product.

PAYER_EMPTY_BILLING_ADDRESS

Billing address is empty. The billing address is required for credit card transactions without a PayPal account.

PAYER_ID_MISSING_FOR_CARD_TOKEN

payer_id is required for payments made with this token. A payer_id is required when one was used to store the credit card in the vault.

PAYMENT_ALREADY_DONE

Payment has been done already for this cart. You have completed the payment for this request already. Look up the transaction to get the details.

PAYMENT_APPROVAL_EXPIRED

Payment approval has expired. Inform customers that the transaction has expired and that they must restart the transaction. Offer customers a link to restart the payment flow from payment creation and redirect the customer to PayPal.

PAYMENT_CANNOT_BE_INITIATED

Payment cannot be processed. PayPal cannot start processing the payment due to an issue with the specified information.

PAYMENT_DENIED

PayPal has declined to process this transaction. PayPal declined the payment due to one or more customer issues.

PAYMENT_EXPIRED

The payment is expired. The payment expired because too much time has passed between payment creation or approval and execution of that payment. Restart the payment request starting from payment creation.

PAYMENT_METHOD_UNUSABLE

Payer cannot pay with this payment method. The specified payment method is not usable. For example, PayPal business rules do not allow the payment method or the payment method information was incorrect in the request.

PAYMENT_NOT_APPROVED_FOR_EXECUTION

Payer has not approved payment. The customer must approve all payments that use the PayPal payment method.

PAYMENT_REQUEST_ID_INVALID

PayPal request ID is invalid. Please try a different one. Try a different PayPal request ID.

PAYMENT_STATE_INVALID

This request is invalid due to the current state of the payment. The payment state does not allow this kind of request.

PERMISSION_DENIED

No permission for the requested operation. You do not have the proper permissions to complete this request.

PHONE_NUMBER_REQUIRED

This transaction requires the payer to provide a valid phone number. The customer must provide a phone number to PayPal to proceed with the payment.

PREVIOUS_REQUEST_IN_PROGRESS

A previous request on this resource is currently in progress. Please wait for some time 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.

REAUTH_NOT_SUPPORTED_FOR_ORDER

Re-authorization is not allowed for this type of authorization. You cannot re-authorize an order.

REDIRECT_PAYER_FOR_ALTERNATE_FUNDING

Transaction failed. Redirect the payer to select another funding source. The transaction failed so try another funding instrument.

REFUND_EXCEEDED_TRANSACTION_AMOUNT

Refund refused - the requested refund amount would exceed the amount of transaction being refunded. The requested refund must be less than or equal to the original transaction amount. To see the original transaction amount, show the refund details.

REFUND_FAILED_INSUFFICIENT_FUNDS

Refund failed due to insufficient funds in your PayPal account. You do not have sufficient funds in your PayPal account to process this refund.

REFUND_TIME_LIMIT_EXCEEDED

This transaction is too old to refund. For information about refund time limits, see PayPal Customer Support. After the time limit expires, you must send a payment instead of issuing a refund.

REQUESTED_OPERATION_REFUSED_DUE_TO_SELLER_OPT_OUT

You cannot perform this operation as payee has opted out on PayPal.com. The third-party-initiated operations are blocked because the payee has opted out on paypal.com.

REQUIRED_SCOPE_MISSING

Access token does not have required scope. You must get user consent with the correct scope for this type of request.

SENDING_LIMIT_EXCEEDED

The transaction exceeds the buyer's sending limit. The customer cannot make any more transactions.

SHIPPING_ADDRESS_INVALID

Provided shipping address is invalid. The specified shipping address is not valid.

TOO_MANY_REAUTHORIZATIONS

Maximum number of reauthorizations for this authorization has been reached. You can only reauthorize a payment once.

TOO_MANY_SETTLEMENTS

Maximum number of allowable settlements has been reached. No more settlement for the authorization. The maximum number of settlements was reached.

TRANSACTION_ALREADY_REFUNDED

Refund transaction refused - this transaction has already been refunded. You can only refund a transaction up to the original amount. While you can do multiple partial refunds up to the original amount, you can only do a full refund once.

TRANSACTION_LIMIT_EXCEEDED

Total payment amount exceeded transaction limit. The transaction limit was exceeded. For information about the PayPal transaction limits, see PayPal Customer Support.

TRANSACTION_RECEIVING_LIMIT_EXCEEDED

The transaction exceeds the receiver’s receiving limit. The amount exceeds the maximum amount for a single transaction.

TRANSACTION_REFUSED

This request was refused. The possible reasons for this failure are:

  • The partial refund amount must be less than or equal to the original transaction amount.
  • The partial refund amount must be less than or equal to the remaining amount.
  • The partial refund amount is not valid.
  • The partial refund must be the same currency as the original transaction.
  • Because a complaint case exists on this transaction, only a refund of the full or full remaining amount of the transaction can be messaged.
  • You are over the time limit to complete a refund on this transaction.
  • Cannot do a full refund after a partial refund.
  • Transaction was fully refunded.
  • You cannot refund this type of transaction.
  • You cannot do a partial refund on this transaction.
  • The merchant account has limitations or restrictions.
  • Refunds are not supported for the payer's selected payment method. Contact the payer directly to arrange a refund via alternative means.
  • The time limit set by the payer's selected payment method to refund this transaction has expired. Contact the payer directly to arrange a refund via alternative means.
  • We're unable to process refunds for the payer's selected payment method. Contact the payer directly to arrange a refund via alternative means.
  • Please find alternate means to refund the payment to the buyer.
  • Please check the amount and the currency of the transaction and try again. Alternately, please find alternate means to refund the payment to the buyer.
  • Please find alternate means to refund the payment to the buyer as this type of transaction cannot be refunded.
  • Please find alternate means to refund the payment to the buyer or try again after some time.
  • The card account is closed or never existed. Please find alternate means to refund the payment to the buyer.
  • The transaction cannot be refunded. Please find alternate means to refund the payment to the buyer.
  • The transaction was refused because of suspected fraud. Please find alternate means to refund the payment to the buyer or try again after some time.
  • The transaction cannot be refunded due to regulatory restrictions that are permanent or temporary. Please find alternate means to refund the payment to the buyer or try again after some time.

TRANSACTION_REFUSED_BY_PAYPAL_RISK

PayPal risk refused this transaction. PayPal risk assessment refused this transaction.

TRANSACTION_REFUSED_PAYEE_PREFERENCE

Merchant profile preference is set to automatically deny certain transactions. The merchant account preferences are set to deny this kind of transaction.

UNAUTHORIZED_PAYMENT

Unauthorized payment. This payment was not authorized.

UNSUPPORTED_PAYEE_COUNTRY

Payee country is not supported for this transaction. The merchant does not accept payments from this country.

UNSUPPORTED_PAYEE_CURRENCY

The currency is not accepted by payee. The merchant does not accept payments in this currency.

VALIDATION_ERROR

Invalid request - see details. A validation error occurred with your request.

Definitions

Address

The billing address or shipping address for a payment.

line1
required
string <= 300 characters

The first line of the address. For example, number, street, and so on.

line2
string <= 300 characters

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

city
string <= 64 characters

The city name.

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.

postal_code
string

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

state
string <= 300 characters

The code for a US state or the equivalent for other countries. Required for transactions if the address is in one of these countries: Argentina, Brazil, Canada, China, India, Italy, Japan, Mexico, Thailand, or United States.

phone
string <phone>

The phone number, in E.123 format. Maximum length is 50 characters.

normalization_status
string

The address normalization status. Returned only for payers from Brazil.

Enum: Description
UNKNOWN

Unknown.

UNNORMALIZED_USER_PREFERRED

Unnormalized user preferred.

NORMALIZED

Normalized.

UNNORMALIZED

Unnormalized.

type
string

The type of address. For example, HOME_OR_WORK, GIFT, and so on.

{
  • "line1": "string",
  • "line2": "string",
  • "city": "string",
  • "country_code": "st",
  • "postal_code": "string",
  • "state": "string",
  • "phone": "string",
  • "normalization_status": "UNKNOWN",
  • "type": "string"
}

Amount

The payment amount, with details.

currency
required
string

The three-character ISO-4217 currency code. PayPal does not support all currencies.

total
required
string

The total amount charged to the payee by the payer. For refunds, represents the amount that the payee refunds to the original payer. Maximum length is 10 characters, which includes:

  • Seven digits before the decimal point.
  • The decimal point.
  • Two digits after the decimal point.
  • For currencies like JPY do not support decimals.

object (Payment Amount Details)

The additional details about the payment amount.

Note: For an order authorization or capture, you cannot include the amount details object.

{
  • "currency": "string",
  • "total": "string",
  • "details": {
    • "subtotal": "string",
    • "shipping": "string",
    • "tax": "string",
    • "handling_fee": "string",
    • "shipping_discount": "string",
    • "insurance": "string",
    • "gift_wrap": "string"
    }
}

Application Context

The application context. Set these properties to customize the payment flow experience for your customers.

brand_name
string <= 127 characters

A label that overrides the business name in the merchant's PayPal account on the PayPal checkout pages.

locale
string

The locale of pages that the PayPal payment experience displays. Please refer here for list of supported local codes. Defaulted to en_US if not provided or invalid.

landing_page
string

The type of landing page to show on the PayPal site for customer checkout. To use the non-PayPal account landing page, set to Billing. To use the PayPal account log in landing page, set to Login.

shipping_preference
string
Default: "GET_FROM_FILE"

The shipping preference.

Enum: Description
NO_SHIPPING

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

GET_FROM_FILE

Uses the customer-selected shipping address on PayPal pages.

SET_PROVIDED_ADDRESS

If available, uses the merchant-provided shipping address, which the customer cannot change on the PayPal pages. If the merchant does not provide an address, the customer can enter the address on PayPal pages.

user_action
string

The user action. Presents the customer with either the Continue or Pay Now checkout flow:

FlowActionDescription
Pay Nowuser_action=commitAfter the customer is redirected to the PayPal payment page, shows the Pay Now button.

Use this option when you know the final amount when checkout is initiated and you want to process the payment immediately when the customer clicks Pay Now.
Continue user_action=continueAfter the customer is redirected to the PayPal payment page, shows the Continue button.

Use this option when you do not know the final amount when you initiate the checkout flow and you want to redirect the customer to the merchant page without processing the payment.

payment_pattern
string (payment_pattern) [ 3 .. 255 ] characters ^[A-Z_]+$

Provides context (e.g. frequency of payment (Single, Recurring) along with whether (Customer is Present, Not Present) for the payment being processed. For Card and PayPal Vaulted/Billing Agreement transactions, this helps specify the appropriate indicators to the networks (e.g. Mastercard, Visa) which ensures compliance as well as ensure a better auth-rate. For bank processing, indicates to clearing house whether the transaction is recurring or not depending on the option chosen.

Enum: Description
CUSTOMER_PRESENT_ONETIME_PURCHASE

If the payments is an e-commerce payment initiated by the customer. Customer typically enters payment information (e.g. card number, approves payment within the PayPal Checkout flow) and such information that has not been previously stored on file.

CUSTOMER_NOT_PRESENT_RECURRING

Subsequent recurring payments (e.g. subscriptions with a fixed amount on a predefined schedule when customer is not present.

CUSTOMER_PRESENT_RECURRING_FIRST

The first payment initiated by the customer which is expected to be followed by a series of subsequent recurring payments transactions (e.g. subscriptions with a fixed amount on a predefined schedule when customer is not present. This is typically used for scenarios where customer stores credentials and makes a purchase on a given date and also set’s up a subscription.

CUSTOMER_PRESENT_ONETIME_PURCHASE_VAULTED

Also known as (card-on-file) transactions. Payment details are stored to enable checkout with one-click, or simply to streamline the checkout process. For card transaction customers typically do not enter a CVC number as part of the Checkout process.

CUSTOMER_NOT_PRESENT_ONETIME_PURCHASE_VAULTED

Unscheduled payments that are not recurring on a predefined schedule (e.g. balance top-up).

MAIL_ORDER_TELEPHONE_ORDER

Payments that are initiated by the customer via the merchant by mail or telephone.

object (payment_source)

The preferred payment source for the payer. Currently supported only for PayPal Billing Agreements. If provided, checkout experience will have this payment source pre-selected for the payer.

{
  • "brand_name": "string",
  • "locale": "string",
  • "landing_page": "string",
  • "shipping_preference": "NO_SHIPPING",
  • "user_action": "string",
  • "payment_pattern": "CUSTOMER_PRESENT_ONETIME_PURCHASE",
  • "preferred_payment_source": {
    • "token": {
      • "id": "string",
      • "type": "BILLING_AGREEMENT"
      }
    }
}

Authorization

The authorization details.

id
string

The ID of the authorization.

payment_mode
string

The payment mode of the authorization.

Value: Description
INSTANT_TRANSFER

Instant transfer.

state
string

The authorized payment state.

Enum: Description
authorized

The authorized payment is authorized.

partially_captured

The authorized payment is partially captured.

captured

The authorized payment is captured.

expired

The authorized payment is expired.

denied

PayPal can no longer authorize funds against this authorization.

voided

The authorized payment is voided.

reason_code
string

The reason code for the pending transaction state.

Value: Description
AUTHORIZATION

Authorization.

pending_reason
string

Deprecated. The reason code for the pending transaction state. Obsolete. Use reason_code instead.

Value: Description
AUTHORIZATION

Authorization.

protection_eligibility
string

The level of seller protection present for the transaction. Supported for the PayPal payment method only.

Enum: Description
ELIGIBLE

Merchant is protected by PayPal's Seller Protection Policy for Unauthorized Payments and Item Not Received.

PARTIALLY_ELIGIBLE

Merchant is protected by PayPal's Seller Protection Policy for Item Not Received or Unauthorized Payments. For details, see protection_eligibility_type.

INELIGIBLE

Merchant is not protected under the Seller Protection Policy.

protection_eligibility_type
string

The type of seller protection for the transaction. Returned only when the protection_eligibility property is ELIGIBLE or PARTIALLY_ELIGIBLE. Supported for the PayPal payment method only.

Enum: Description
ITEM_NOT_RECEIVED_ELIGIBLE

Sellers are protected against claims for items not received.

UNAUTHORIZED_PAYMENT_ELIGIBLE

Sellers are protected against claims for unauthorized payments.

ITEM_NOT_RECEIVED_ELIGIBLE,UNAUTHORIZED_PAYMENT_ELIGIBLE

Sellers are protected against claims for items not received and sellers are protected against claims for unauthorized payments.

object (FMF Details)

The Fraud Management Filter (FMF) details that are applied to the payment that result in an accept, deny, or pending action. Returned in a payment response only if the merchant has enabled FMF in the profile settings and one of the fraud filters was triggered based on those settings. For more information, see Fraud Management Filters Summary.

parent_payment
string

The ID of the payment on which this transaction is based.

object (Processor Response)

The processor-provided response codes that describe the submitted payment. Supported only when the payment_method is credit_card.

valid_until
string <date-time>

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

create_time
string <date-time>

The date and time when the authorization was created, in Internet date and time format.

update_time
string <date-time>

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

receipt_id
string^[0-9]{4}-[0-9]{4}-[0-9]{4}-[0-9]{4}$

The receipt ID, which identifies the payment. Value is 16-digit numeric payment ID number that is returned for guest users.

Array of objects (Link Description)

An array of request-related HATEOAS links.

required
object (Amount)

The payment amount, with details.

{
  • "id": "string",
  • "payment_mode": "INSTANT_TRANSFER",
  • "state": "authorized",
  • "reason_code": "AUTHORIZATION",
  • "pending_reason": "AUTHORIZATION",
  • "protection_eligibility": "ELIGIBLE",
  • "protection_eligibility_type": "ITEM_NOT_RECEIVED_ELIGIBLE",
  • "fmf_details": {
    • "filter_type": "ACCEPT",
    • "filter_id": "AVS_NO_MATCH",
    • "name": "string",
    • "description": "string"
    },
  • "parent_payment": "string",
  • "processor_response": {
    • "response_code": "stri",
    • "avs_code": "s",
    • "cvv_code": "s",
    • "advice_code": "01_NEW_ACCOUNT_INFORMATION",
    • "eci_submitted": "string",
    • "vpas": "string"
    },
  • "valid_until": "2019-08-24T14:15:22Z",
  • "create_time": "2019-08-24T14:15:22Z",
  • "update_time": "2019-08-24T14:15:22Z",
  • "receipt_id": "string",
  • "links": [
    • {
      • "href": "string",
      • "rel": "string",
      • "method": "GET"
      }
    ],
  • "amount": {
    • "currency": "string",
    • "total": "string",
    • "details": {
      • "subtotal": "string",
      • "shipping": "string",
      • "tax": "string",
      • "handling_fee": "string",
      • "shipping_discount": "string",
      • "insurance": "string",
      • "gift_wrap": "string"
      }
    }
}

Capture

The capture transaction details.

<
id
string

The ID of the capture transaction.

is_final_capture
boolean
Default: false

Indicates whether to release all remaining held funds.

state
string

The state of the capture.

Enum: Description
pending

The capture is pending.

completed

The capture has successfully completed.

refunded

The capture was fully refunded.

partially_refunded

The capture was partially refunded.

denied

PayPal has declined to process this transaction.

reason_code
string

The reason code that describes why the transaction state is pending or reversed.

Enum: Description
CHARGEBACK

The transaction state is pending or reversed due to a chargeback.

GUARANTEE

The transaction state is pending or reversed due to a guarantee.

BUYER_COMPLAINT

The transaction state is pending or reversed due to a customer complaint.

REFUND

The transaction state is pending or reversed due to a REFUND.

UNCONFIRMED_SHIPPING_ADDRESS

The transaction state is pending or reversed due to an unconfirmed shipping address.

ECHECK

The transaction state is pending or reversed due to an e-check.

INTERNATIONAL_WITHDRAWAL

The transaction state is pending or reversed due to an international withdrawal.

RECEIVING_PREFERENCE_MANDATES_MANUAL_ACTION

The transaction state is pending or reversed due to a receiving preference that mandates manual action.

PAYMENT_REVIEW

The transaction state is pending or reversed due to a payment review.

REGULATORY_REVIEW

The transaction state is pending or reversed due to a regulatory review.

UNILATERAL

The transaction state is pending or reversed due to a unilateral action.

VERIFICATION_REQUIRED

The transaction state is pending or reversed because verification is required.

TRANSACTION_APPROVED_AWAITING_FUNDING

The transaction state is pending or reversed because an approved transaction is awaiting funding.

NONE

Returned only when the state is 'completed'. Returned only as part of the 'POST' response.

parent_payment
string

The ID of the payment on which this transaction is based.

invoice_number
string <= 127 characters

The invoice number to track this payment.

exchange_rate
string

The exchange rate applied for this transaction. Returned when there is a currency conversion from the transaction currency to the receivable currency.

note_to_payer
string <= 255 characters

A free-form field that clients can use to send a note to the payer.

create_time
string <date-time>

The date and time of the capture, in Internet date and time format.

update_time
string <date-time>

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

Array of objects (Link Description)

An array of request-related HATEOAS links.

object (Amount)

The amount to capture. If the amount matches the originally authorized amount, the state of the authorization changes to captured. Otherwise, the state changes to partially_captured.

object (Currency)

The currency and amount of the transaction fee for this payment. Would not be returned for pending transactions where the funds have not been realized in the payee account.