API Version

Payments API

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.

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.

Payment (resource group)

Use the /payment resource to create a sale, an authorized payment, or an order. A sale is a direct credit card payment, stored credit card payment, or PayPal payment. An authorized payment places funds on hold to be captured later. An order is a purchase that a customer has approved but for which the funds are not placed on hold. You can also use this resource to execute approved PayPal payments and show details for, update, and list payments. For more information, see also .

List payments

GET/v1/payments/payment

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.

Query parameters

count
integer
The number of items to list in the response.
Maximum value: 20.
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
enum
Sorts the payments in the response by a create time.
Possible values: create_time.
sort_order
enum
Sorts the payments in the response in descending order.
Possible values: desc.

SDK samples:

Sample Request

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 "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token"

Response

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

payments
array (contains the payment object)
An array of payments that are complete. Payments that you just created with the create payment call do not appear in the list.
count
integer
The number of items returned in each range of results. Note that the last results range might have fewer items than the requested number of items.
Maximum value: 20.
next_id
string
The ID of the element to use to get the next range of results.
Read only.

Sample Response

{
  "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": [
            {
              "authorization": {
                "id": "53P09338XY5426455",
                "create_time": "2017-06-30T23:50:01Z",
                "update_time": "2017-06-30T23:50:01Z",
                "amount": {
                  "total": "41.15",
                  "currency": "USD"
                },
                "parent_payment": "PAY-0US81985GW1191216KOY7OXA",
                "valid_until": "2017-07-29T23:49:52Z",
                "links": [
                  {
                    "href": "https://api-m.sandbox.paypal.com/v1/payments/payment/PAY-0US81985GW1191216KOY7OXA",
                    "rel": "parent_payment",
                    "method": "GET"
                  }
                ]
              }
            }
          ]
        }
      ],
      "links": [
        {
          "href": "https://api-m.sandbox.paypal.com/v1/payments/payment/PAY-0US81985GW1191216KOY7OXA",
          "rel": "self",
          "method": "GET"
        }
      ]
    },
    {
      "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": [
            {
              "authorization": {
                "id": "91527087GH224122L",
                "create_time": "2017-07-01T19:36:22Z",
                "update_time": "2017-07-01T19:36:22Z",
                "amount": {
                  "total": "33.00",
                  "currency": "USD"
                },
                "parent_payment": "PAY-53485002LD6169910KOZQ25I",
                "valid_until": "2017-07-30T19:36:22Z",
                "links": [
                  {
                    "href": "https://api-m.sandbox.paypal.com/v1/payments/payment/PAY-53485002LD6169910KOZQ25I",
                    "rel": "parent_payment",
                    "method": "GET"
                  }
                ]
              }
            }
          ]
        }
      ],
      "links": [
        {
          "href": "https://api-m.sandbox.paypal.com/v1/payments/payment/PAY-53485002LD6169910KOZQ25I",
          "rel": "self",
          "method": "GET"
        }
      ]
    },
    {
      "id": "PAY-7F5790198P134484LKOZSG7Q",
      "create_time": "2017-07-01T21:09:18Z",
      "update_time": "2017-07-01T22:31:56Z",
      "state": "APPROVED",
      "intent": "order",
      "payer": {
        "payment_method": "paypal"
      },
      "transactions": [
        {
          "amount": {
            "total": "42.00",
            "currency": "USD",
            "details": {
              "subtotal": "36.00",
              "tax": "1.00",
              "shipping": "5.00"
            }
          },
          "description": "The payment transaction description.",
          "item_list": {
            "items": [
              {
                "name": "handbag",
                "sku": "product34",
                "price": "36.00",
                "currency": "USD",
                "quantity": "1"
              }
            ],
            "shipping_address": {
              "recipient_name": "Anna Joseph",
              "line1": "2525 North 1st street",
              "line2": "unit 4",
              "city": "San Jose",
              "state": "CA",
              "phone": "011862212345678",
              "postal_code": "95031",
              "country_code": "US"
            }
          },
          "related_resources": [
            {
              "capture": {
                "id": "26062838D7499294V",
                "create_time": "2017-07-01T21:16:22Z",
                "update_time": "2017-07-01T21:16:24Z",
                "amount": {
                  "total": "7.00",
                  "currency": "USD"
                },
                "state": "COMPLETED",
                "parent_payment": "PAY-7F5790198P134484LKOZSG7Q",
                "links": [
                  {
                    "href": "https://api-m.sandbox.paypal.com/v1/payments/capture/26062838D7499294V",
                    "rel": "self",
                    "method": "GET"
                  },
                  {
                    "href": "https://api-m.sandbox.paypal.com/v1/payments/capture/26062838D7499294V/refund",
                    "rel": "refund",
                    "method": "POST"
                  },
                  {
                    "href": "https://api-m.sandbox.paypal.com/v1/payments/payment/PAY-7F5790198P134484LKOZSG7Q",
                    "rel": "parent_payment",
                    "method": "GET"
                  }
                ]
              }
            },
            {
              "capture": {
                "id": "0YU20012P1477553M",
                "create_time": "2017-07-01T22:31:54Z",
                "update_time": "2017-07-01T22:31:56Z",
                "amount": {
                  "total": "35.00",
                  "currency": "USD"
                },
                "state": "COMPLETED",
                "parent_payment": "PAY-7F5790198P134484LKOZSG7Q",
                "links": [
                  {
                    "href": "https://api-m.sandbox.paypal.com/v1/payments/capture/0YU20012P1477553M",
                    "rel": "self",
                    "method": "GET"
                  },
                  {
                    "href": "https://api-m.sandbox.paypal.com/v1/payments/capture/0YU20012P1477553M/refund",
                    "rel": "refund",
                    "method": "POST"
                  },
                  {
                    "href": "https://api-m.sandbox.paypal.com/v1/payments/payment/PAY-7F5790198P134484LKOZSG7Q",
                    "rel": "parent_payment",
                    "method": "GET"
                  }
                ]
              }
            }
          ]
        }
      ],
      "links": [
        {
          "href": "https://api-m.sandbox.paypal.com/v1/payments/payment/PAY-7F5790198P134484LKOZSG7Q",
          "rel": "self",
          "method": "GET"
        }
      ]
    }
  ],
  "count": 3,
  "next_id": "PAY-9X4935091L753623RKOZTRHI"
}

Create payment

POST/v1/payments/payment

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.

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.

Header parameters

PayPal-Partner-Attribution-Id
string
Maximum length: 32.

Request body

id
string
The ID of the payment.
intent
enum
required
The payment intent. Value is:
- sale. Makes an immediate payment.
- authorize. Authorizes a payment for capture later.
- order. Creates an order.
Possible values: sale,authorize,order.
payer
object
required
The source of the funds for this payment. Payment method is PayPal Wallet payment or bank direct debit.
application_context
object
Use the application context resource to customize payment flow experience for your buyers.
transactions
array (contains the transaction object)
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.
state
enum
The state of the payment, authorization, or order transaction. Value is:
- created. The transaction was successfully created.
- approved. The customer approved the transaction. The state changes from created to approved on generation of the sale_id for sale transactions, authorization_id for authorization transactions, or order_id for order transactions.
- failed. The transaction request failed.
Possible values: created,approved,failed.
experience_profile_id
string
The PayPal-generated ID for the merchant's payment experience profile. For information, see create web experience profile.
note_to_payer
string
A free-form field that clients can use to send a note to the payer.
Maximum length: 165.
redirect_urls
object
A set of redirect URLs that you provide for PayPal-based payments.
failure_reason
enum
The reason code for a payment failure.
Possible values: UNABLE_TO_COMPLETE_TRANSACTION,INVALID_PAYMENT_METHOD,PAYER_CANNOT_PAY,CANNOT_PAY_THIS_PAYEE,REDIRECT_REQUIRED,PAYEE_FILTER_RESTRICTIONS.
create_time
string
The date and time when the payment was created, in Internet date and time format.
update_time
string
The date and time when the payment was updated, in Internet date and time format.
links
array (contains the link_description object)
An array of request-related HATEOAS links.

Sample Request

curl -v -X POST https://api-m.sandbox.paypal.com/v1/payments/payment \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
  "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": {
    "return_url": "https://example.com/return",
    "cancel_url": "https://example.com/cancel"
  }
}'

Response

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

id
string
The ID of the payment.
Read only.
intent
enum
The payment intent. Value is:
- sale. Makes an immediate payment.
- authorize. Authorizes a payment for capture later.
- order. Creates an order.
Possible values: sale,authorize,order.
payer
object
The source of the funds for this payment. Payment method is PayPal Wallet payment or bank direct debit.
application_context
object
Use the application context resource to customize payment flow experience for your buyers.
transactions
array (contains the transaction object)
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.
state
enum
The state of the payment, authorization, or order transaction. Value is:
- created. The transaction was successfully created.
- approved. The customer approved the transaction. The state changes from created to approved on generation of the sale_id for sale transactions, authorization_id for authorization transactions, or order_id for order transactions.
- failed. The transaction request failed.
Read only.
Possible values: created,approved,failed.
experience_profile_id
string
The PayPal-generated ID for the merchant's payment experience profile. For information, see create web experience profile.
note_to_payer
string
A free-form field that clients can use to send a note to the payer.
Maximum length: 165.
redirect_urls
object
A set of redirect URLs that you provide for PayPal-based payments.
failure_reason
enum
The reason code for a payment failure.
Read only.
Possible values: UNABLE_TO_COMPLETE_TRANSACTION,INVALID_PAYMENT_METHOD,PAYER_CANNOT_PAY,CANNOT_PAY_THIS_PAYEE,REDIRECT_REQUIRED,PAYEE_FILTER_RESTRICTIONS.
create_time
string
The date and time when the payment was created, in Internet date and time format.
Read only.
update_time
string
The date and time when the payment was updated, in Internet date and time format.
Read only.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
Read only.

Sample Response

{
  "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": [
    {
      "href": "https://api-m.sandbox.paypal.com/v1/payments/payment/PAY-1B56960729604235TKQQIYVY",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://www.sandbox.paypal.com/cgi-bin/webscr?cmd=_express-checkout&token=EC-60385559L1062554J",
      "rel": "approval_url",
      "method": "REDIRECT"
    },
    {
      "href": "https://api-m.sandbox.paypal.com/v1/payments/payment/PAY-1B56960729604235TKQQIYVY/execute",
      "rel": "execute",
      "method": "POST"
    }
  ]
}

Partially update payment

PATCH/v1/payments/payment/{payment_id}

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.

Path parameters

payment_id
string
required
The ID of the payment to update.

Request body

patch_request
array (contains the patch object)
An array of JSON patch objects to apply partial updates to resources.

SDK samples:

JAVA

Sample Request

curl -v -X PATCH https://api-m.sandbox.paypal.com/v1/payments/payment/PAY-5YK922393D847794YKER7MUI \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-d '[
  {
    "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

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

id
string
The ID of the payment.
Read only.
intent
enum
The payment intent. Value is:
- sale. Makes an immediate payment.
- authorize. Authorizes a payment for capture later.
- order. Creates an order.
Possible values: sale,authorize,order.
payer
object
The source of the funds for this payment. Payment method is PayPal Wallet payment or bank direct debit.
application_context
object
Use the application context resource to customize payment flow experience for your buyers.
transactions
array (contains the transaction object)
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.
state
enum
The state of the payment, authorization, or order transaction. Value is:
- created. The transaction was successfully created.
- approved. The customer approved the transaction. The state changes from created to approved on generation of the sale_id for sale transactions, authorization_id for authorization transactions, or order_id for order transactions.
- failed. The transaction request failed.
Read only.
Possible values: created,approved,failed.
experience_profile_id
string
The PayPal-generated ID for the merchant's payment experience profile. For information, see create web experience profile.
note_to_payer
string
A free-form field that clients can use to send a note to the payer.
Maximum length: 165.
redirect_urls
object
A set of redirect URLs that you provide for PayPal-based payments.
failure_reason
enum
The reason code for a payment failure.
Read only.
Possible values: UNABLE_TO_COMPLETE_TRANSACTION,INVALID_PAYMENT_METHOD,PAYER_CANNOT_PAY,CANNOT_PAY_THIS_PAYEE,REDIRECT_REQUIRED,PAYEE_FILTER_RESTRICTIONS.
create_time
string
The date and time when the payment was created, in Internet date and time format.
Read only.
update_time
string
The date and time when the payment was updated, in Internet date and time format.
Read only.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
Read only.

Sample Response

{
  "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": [
    {
      "href": "https://api-m.sandbox.paypal.com/v1/payments/payment/PAY-5YK922393D847794YKER7MUI",
      "method": "GET",
      "rel": "self"
    }
  ]
}

Show payment details

GET/v1/payments/payment/{payment_id}

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.

Path parameters

payment_id
string
required
The ID of the payment for which to show details.

SDK samples:

Sample Request

curl -v -X GET https://api-m.sandbox.paypal.com/v1/payments/payment/PAY-0US81985GW1191216KOY7OXA \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token"

Response

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

id
string
The ID of the payment.
Read only.
intent
enum
The payment intent. Value is:
- sale. Makes an immediate payment.
- authorize. Authorizes a payment for capture later.
- order. Creates an order.
Possible values: sale,authorize,order.
payer
object
The source of the funds for this payment. Payment method is PayPal Wallet payment or bank direct debit.
application_context
object
Use the application context resource to customize payment flow experience for your buyers.
transactions
array (contains the transaction object)
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.
state
enum
The state of the payment, authorization, or order transaction. Value is:
- created. The transaction was successfully created.
- approved. The customer approved the transaction. The state changes from created to approved on generation of the sale_id for sale transactions, authorization_id for authorization transactions, or order_id for order transactions.
- failed. The transaction request failed.
Read only.
Possible values: created,approved,failed.
experience_profile_id
string
The PayPal-generated ID for the merchant's payment experience profile. For information, see create web experience profile.
note_to_payer
string
A free-form field that clients can use to send a note to the payer.
Maximum length: 165.
redirect_urls
object
A set of redirect URLs that you provide for PayPal-based payments.
failure_reason
enum
The reason code for a payment failure.
Read only.
Possible values: UNABLE_TO_COMPLETE_TRANSACTION,INVALID_PAYMENT_METHOD,PAYER_CANNOT_PAY,CANNOT_PAY_THIS_PAYEE,REDIRECT_REQUIRED,PAYEE_FILTER_RESTRICTIONS.
create_time
string
The date and time when the payment was created, in Internet date and time format.
Read only.
update_time
string
The date and time when the payment was updated, in Internet date and time format.
Read only.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
Read only.

Sample Response

{
  "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": [
        {
          "authorization": {
            "id": "53P09338XY5426455",
            "create_time": "2017-06-30T23:50:01Z",
            "update_time": "2017-06-30T23:50:01Z",
            "amount": {
              "total": "41.15",
              "currency": "USD"
            },
            "parent_payment": "PAY-0US81985GW1191216KOY7OXA",
            "valid_until": "2017-07-29T23:49:52Z",
            "links": [
              {
                "href": "https://api-m.sandbox.paypal.com/v1/payments/payment/PAY-0US81985GW1191216KOY7OXA",
                "rel": "parent_payment",
                "method": "GET"
              }
            ]
          }
        }
      ]
    }
  ],
  "links": [
    {
      "href": "https://api-m.sandbox.paypal.com/v1/payments/payment/PAY-0US81985GW1191216KOY7OXA",
      "rel": "self",
      "method": "GET"
    }
  ]
}

Execute approved PayPal payment

POST/v1/payments/payment/{payment_id}/execute

Executes a PayPal payment that the customer has approved. You can optionally update one or more transactions when you execute the payment.

Header parameters

PayPal-Request-Id
string
The server stores keys for 30 days.
Maximum length: 78.
PayPal-Partner-Attribution-Id
string
Maximum length: 32.

Path parameters

payment_id
string
required
The ID of the payment to execute.

Request body

payer_id
string
The ID of the payer that PayPal passes in the return_url.
transactions
array (contains the cart_base object)
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.

SDK samples:

Sample Request

curl -v -X POST https://api-m.sandbox.paypal.com/v1/payments/payment/PAY-9N9834337A9191208KOZOQWI/execute \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
  "payer_id": "CR87QHB7JTRSC"
}'

Response

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

id
string
The ID of the payment.
Read only.
intent
enum
The payment intent. Value is:
- sale. Makes an immediate payment.
- authorize. Authorizes a payment for capture later.
- order. Creates an order.
Possible values: sale,authorize,order.
payer
object
The source of the funds for this payment. Payment method is PayPal Wallet payment or bank direct debit.
application_context
object
Use the application context resource to customize payment flow experience for your buyers.
transactions
array (contains the transaction object)
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.
state
enum
The state of the payment, authorization, or order transaction. Value is:
- created. The transaction was successfully created.
- approved. The customer approved the transaction. The state changes from created to approved on generation of the sale_id for sale transactions, authorization_id for authorization transactions, or order_id for order transactions.
- failed. The transaction request failed.
Read only.
Possible values: created,approved,failed.
experience_profile_id
string
The PayPal-generated ID for the merchant's payment experience profile. For information, see create web experience profile.
note_to_payer
string
A free-form field that clients can use to send a note to the payer.
Maximum length: 165.
redirect_urls
object
A set of redirect URLs that you provide for PayPal-based payments.
failure_reason
enum
The reason code for a payment failure.
Read only.
Possible values: UNABLE_TO_COMPLETE_TRANSACTION,INVALID_PAYMENT_METHOD,PAYER_CANNOT_PAY,CANNOT_PAY_THIS_PAYEE,REDIRECT_REQUIRED,PAYEE_FILTER_RESTRICTIONS.
create_time
string
The date and time when the payment was created, in Internet date and time format.
Read only.
update_time
string
The date and time when the payment was updated, in Internet date and time format.
Read only.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
Read only.

Sample Response

{
  "id": "PAY-9N9834337A9191208KOZOQWI",
  "create_time": "2017-07-01T16:56:57Z",
  "update_time": "2017-07-01T17:05:41Z",
  "state": "APPROVED",
  "intent": "order",
  "payer": {
    "payment_method": "paypal",
    "payer_info": {
      "email": "qa152-biz@example.com",
      "first_name": "Thomas",
      "last_name": "Miller",
      "payer_id": "PUP87RBJV8HPU",
      "shipping_address": {
        "line1": "4th Floor, One Lagoon Drive",
        "line2": "Unit #34",
        "city": "Redwood City",
        "state": "CA",
        "postal_code": "94065",
        "country_code": "US",
        "phone": "011862212345678",
        "recipient_name": "Thomas Miller"
      }
    }
  },
  "transactions": [
    {
      "amount": {
        "total": "41.15",
        "currency": "USD",
        "details": {
          "subtotal": "30.00",
          "tax": "0.15",
          "shipping": "11.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_options": [
          {
            "id": "PICKUP0000001",
            "label": "Free Shipping",
            "type": "PICKUP",
            "amount": {
              "currency_code": "USD",
              "value": "5.00"
            },
            "selected": true
          }
        ],
        "shipping_address": {
          "recipient_name": "Thomas Miller",
          "line1": "4th Floor, One Lagoon Drive",
          "line2": "Unit #34",
          "city": "Redwood City",
          "state": "CA",
          "phone": "011862212345678",
          "postal_code": "94065",
          "country_code": "US"
        }
      },
      "related_resources": [
        {
          "order": {
            "id": "O-3SP845109F051535C",
            "create_time": "2017-07-01T16:56:58Z",
            "update_time": "2017-07-01T17:05:41Z",
            "state": "PENDING",
            "amount": {
              "total": "41.15",
              "currency": "USD"
            },
            "parent_payment": "PAY-9N9834337A9191208KOZOQWI",
            "links": [
              {
                "href": "https://api-m.sandbox.paypal.com/v1/payments/orders/O-3SP845109F051535C",
                "rel": "self",
                "method": "GET"
              },
              {
                "href": "https://api-m.sandbox.paypal.com/v1/payments/payment/PAY-9N9834337A9191208KOZOQWI",
                "rel": "parent_payment",
                "method": "GET"
              },
              {
                "href": "https://api-m.sandbox.paypal.com/v1/payments/orders/O-3SP845109F051535C/void",
                "rel": "void",
                "method": "POST"
              },
              {
                "href": "https://api-m.sandbox.paypal.com/v1/payments/orders/O-3SP845109F051535C/authorize",
                "rel": "authorization",
                "method": "POST"
              },
              {
                "href": "https://api-m.sandbox.paypal.com/v1/payments/orders/O-3SP845109F051535C/capture",
                "rel": "capture",
                "method": "POST"
              }
            ]
          }
        }
      ]
    }
  ],
  "links": [
    {
      "href": "https://api-m.sandbox.paypal.com/v1/payments/payment/PAY-9N9834337A9191208KOZOQWI",
      "rel": "self",
      "method": "GET"
    }
  ]
}

Sale (resource group)

A sale is a completed payment. Use the /sale resource to show sale details and refund a sale. For more information, see also Refund payments.

Show sale details

GET/v1/payments/sale/{sale_id}

Shows details for a sale, by ID. Returns only sales that were created through the REST API.

Path parameters

sale_id
string
required
The ID of the sale for which to show details.

SDK samples:

Sample Request

curl -v -X GET https://api-m.sandbox.paypal.com/v1/payments/sale/36C38912MN9658832 \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token"

Response

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

id
string
The ID of the sale transaction.
Read only.
amount
object
The amount to collect.
payment_mode
enum
The transaction payment mode. Supported only for PayPal payments.
Read only.
Possible values: INSTANT_TRANSFER,MANUAL_BANK_TRANSFER,DELAYED_TRANSFER,ECHECK.
state
enum
The state of the sale transaction.
Read only.
Possible values: completed,partially_refunded,pending,refunded,denied.
reason_code
enum
A reason code that describes why the transaction state is pending or reversed. Supported only for PayPal payments.
Read only.
Possible values: CHARGEBACK,GUARANTEE,BUYER_COMPLAINT,REFUND,UNCONFIRMED_SHIPPING_ADDRESS,ECHECK,INTERNATIONAL_WITHDRAWAL,RECEIVING_PREFERENCE_MANDATES_MANUAL_ACTION,PAYMENT_REVIEW,REGULATORY_REVIEW,UNILATERAL,VERIFICATION_REQUIRED,TRANSACTION_APPROVED_AWAITING_FUNDING.
protection_eligibility
enum
The merchant protection level in effect for the transaction. Supported only for PayPal payments.
Read only.
Possible values: ELIGIBLE,PARTIALLY_ELIGIBLE,INELIGIBLE.
protection_eligibility_type
enum
The merchant protection type in effect for the transaction. Returned only when protection_eligibility is ELIGIBLE or PARTIALLY_ELIGIBLE. Supported only for PayPal payments.
Read only.
Possible values: ITEM_NOT_RECEIVED_ELIGIBLE,UNAUTHORIZED_PAYMENT_ELIGIBLE,ITEM_NOT_RECEIVED_ELIGIBLE,UNAUTHORIZED_PAYMENT_ELIGIBLE.
clearing_time
string
The date and time when the PayPal eCheck transaction is expected to clear, in Internet date and time format.
Read only.
payment_hold_status
enum
The recipient fund status. Returned only when the fund status is held.
Read only.
Possible values: HELD.
payment_hold_reasons
array (contains the payment_hold_reason object)
An array of reasons that PayPal holds the recipient fund. Set only if the payment hold status is HELD.
Read only.
transaction_fee
object
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.
Read only.
receivable_amount
object
The currency and amount of the net that the merchant receives for this transaction in their receivable currency. Returned only in cross-currency use cases where a merchant bills a buyer in a non-primary currency for that buyer.
transaction_fee_in_receivable_currency
object
The currency and amount of the PayPal fee for this payment in the receivable currency. Returned only in cases the fee is charged in the receivable currency. Example 'CNY'. Would not be returned for 'pending' transactions where the funds have not been realized in the payee account.
Read only.
exchange_rate
string
The exchange rate for this transaction. Returned only in cross-currency use cases where a merchant bills a buyer in a non-primary currency for that buyer.
Read only.
fmf_details
object
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.
receipt_id
string
The receipt ID, which is a payment ID number that is returned for guest users to identify the payment.
Read only.
Pattern: ^[0-9]{4}-[0-9]{4}-[0-9]{4}-[0-9]{4}$.
parent_payment
string
The ID of the payment on which this transaction is based.
Read only.
processor_response
object
The processor-provided response codes that describe the submitted payment. Supported only when the payment_method is credit_card.
billing_agreement_id
string
The ID of the billing agreement. Used as reference to execute this transaction.
Read only.
create_time
string
The date and time of the sale, in Internet date and time format.
Read only.
update_time
string
The date and time when the resource was last updated, in Internet date and time format.
Read only.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
Read only.

Sample Response

{
  "id": "36C38912MN9658832",
  "create_time": "2017-02-19T22:01:53Z",
  "update_time": "2017-02-19T22:01:55Z",
  "state": "COMPLETED",
  "amount": {
    "total": "7.47",
    "currency": "USD"
  },
  "protection_eligibility": "ELIGIBLE",
  "protection_eligibility_type": "ITEM_NOT_RECEIVED_ELIGIBLE,UNAUTHORIZED_PAYMENT_ELIGIBLE",
  "transaction_fee": {
    "value": "1.75",
    "currency": "USD"
  },
  "parent_payment": "PAY-5YK922393D847794YKER7MUI",
  "links": [
    {
      "href": "https://api-m.sandbox.paypal.com/v1/payments/sale/36C38912MN9658832",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://api-m.sandbox.paypal.com/v1/payments/sale/36C38912MN9658832/refund",
      "rel": "refund",
      "method": "POST"
    },
    {
      "href": "https://api-m.sandbox.paypal.com/v1/payments/payment/PAY-5YK922393D847794YKER7MUI",
      "rel": "parent_payment",
      "method": "GET"
    }
  ]
}

Refund sale

POST/v1/payments/sale/{sale_id}/refund

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.

Header parameters

PayPal-Request-Id
string
The server stores keys for 30 days.
Maximum length: 78.

Path parameters

sale_id
string
required
The ID of the sale transaction to refund.

Request body

amount
object
The refund amount. Includes both the amount to refund to the payer and the fee amount to refund to the payee.
description
string
The refund description. Value is a string of single-byte alphanumeric characters.
Maximum length: 255.
reason
string
The refund reason description.
Maximum length: 30.
invoice_number
string
The invoice number that tracks this payment. Value is a string of single-byte alphanumeric characters.
Maximum length: 127.

SDK samples:

Sample Request

curl -v -X POST https://api-m.sandbox.paypal.com/v1/payments/sale/2MU78835H4515710F/refund \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
  "amount": {
    "total": "2.34",
    "currency": "USD"
  },
  "invoice_number": "INV-1234567"
}'

Response

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

id
string
The ID of the refund transaction.
Read only.
Maximum length: 17.
amount
object
The refund amount. Includes both the amount refunded to the payer and the fee refunded to the payee.
state
enum
The state of the refund.
Read only.
Possible values: pending,completed,cancelled,failed.
reason
string
The reason that the transaction is being refunded.
invoice_number
string
The invoice number to track this payment.
Maximum length: 127.
sale_id
string
The ID of the sale transaction being refunded.
Read only.
capture_id
string
The ID of the sale transaction being refunded.
Read only.
parent_payment
string
The ID of the payment on which this transaction is based.
Read only.
description
string
The refund description.
create_time
string
The date and time when the refund was created, in Internet date and time format.
Read only.
update_time
string
The date and time when the resource was last updated, in Internet date and time format.
Read only.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
Read only.
custom
string
The note to the payer in this transaction.
Maximum length: 127.
refund_from_transaction_fee
object
The currency and amount of the transaction fee that is refunded to original the recipient of payment.
refund_from_received_amount
object
The currency and amount of the refund that is subtracted from the original payment recipient's PayPal balance.
total_refunded_amount
object
The currency and amount of the total refund from the original purchase. For example, if a payer makes $100 purchase and the payer was refunded $20 a week ago and $30 in this transaction, the gross refund amount is $30 for this transaction and the total refunded amount is $50.

Sample Response

{
  "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": [
    {
      "href": "https://sandbox.paypal.com/v1/payments/refund/5CY176817C379973E",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://sandbox.paypal.com/v1/payments/payment/PAY-9EH2230144138005NLN2F4EA",
      "rel": "parent_payment",
      "method": "GET"
    },
    {
      "href": "https://sandbox.paypal.com/v1/payments/sale/ 2MU78835H4515710F",
      "rel": "sale",
      "method": "GET"
    }
  ]
}

Authorization (resource group)

Use the /authorization resource and related sub-resources to show details for, capture, void, and reauthorize an authorization.

Show authorization details

GET/v1/payments/authorization/{authorization_id}

Shows details for an authorization, by ID.

Path parameters

authorization_id
string
required
The ID of the authorization for which to show details.

SDK samples:

Sample Request

curl -v -X GET https://api-m.sandbox.paypal.com/v1/payments/authorization/2DC87612EK520411B \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token"

Response

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

id
string
The ID of the authorization.
Read only.
amount
object
The amount being authorized.
payment_mode
enum
The payment mode of the authorization.
The possible values are:
- INSTANT_TRANSFER. Instant transfer.
Read only.
state
enum
The authorized payment state.
The possible values are:
- pending. The authorized payment is pending.
- 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.
Read only.
reason_code
enum
The reason code for the pending transaction state.
The possible values are:
- AUTHORIZATION. Authorization.
Read only.
pending_reason
enum
Deprecated. The reason code for the pending transaction state. Obsolete. Use reason_code instead.
The possible values are:
- AUTHORIZATION. Authorization.
Read only.
protection_eligibility
enum
The level of seller protection present for the transaction. Supported for the PayPal payment method only.
The possible values are:
- 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.
Read only.
protection_eligibility_type
enum
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.
The possible values are:
- 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.
Read only.
fmf_details
object
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.
Read only.
processor_response
object
The processor-provided response codes that describe the submitted payment. Supported only when the payment_method is credit_card.
valid_until
string
The date and time when the authorization expires, in Internet date and time format.
Read only.
create_time
string
The date and time when the authorization was created, in Internet date and time format.
Read only.
update_time
string
The date and time when the authorization was last updated, in Internet date and time format.
Read only.
receipt_id
string
The receipt ID, which identifies the payment. Value is 16-digit numeric payment ID number that is returned for guest users.
Read only.
Pattern: ^[0-9]{4}-[0-9]{4}-[0-9]{4}-[0-9]{4}$.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
Read only.

Sample Response

{
  "id": "2DC87612EK520411B",
  "create_time": "2017-06-25T21:39:15Z",
  "update_time": "2017-06-25T21:39:17Z",
  "state": "AUTHORIZED",
  "amount": {
    "total": "7.47",
    "currency": "USD",
    "details": {
      "subtotal": "7.47"
    }
  },
  "parent_payment": "PAY-36246664YD343335CKHFA4AY",
  "valid_until": "2017-07-24T21:39:15Z",
  "links": [
    {
      "href": "https://api-m.sandbox.paypal.com/v1/payments/authorization/2DC87612EK520411B",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://api-m.sandbox.paypal.com/v1/payments/authorization/2DC87612EK520411B/capture",
      "rel": "capture",
      "method": "POST"
    },
    {
      "href": "https://api-m.sandbox.paypal.com/v1/payments/authorization/2DC87612EK520411B/void",
      "rel": "void",
      "method": "POST"
    },
    {
      "href": "https://api-m.sandbox.paypal.com/v1/payments/payment/PAY-36246664YD343335CKHFA4AY",
      "rel": "parent_payment",
      "method": "GET"
    }
  ]
}

Capture authorization

POST/v1/payments/authorization/{authorization_id}/capture

Captures and processes an authorization, by ID. The original payment call must specify an intent of authorize.

Path parameters

authorization_id
string
required
The ID of the authorization to capture.

Request body

id
string
The ID of the capture transaction.
amount
object
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.
is_final_capture
boolean
Indicates whether to release all remaining held funds.
state
enum
The state of the capture.
The possible values are:
- 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
enum
The reason code that describes why the transaction state is pending or reversed.
The possible values are:
- 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
The invoice number to track this payment.
Maximum length: 127.
transaction_fee
object
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.
transaction_fee_in_receivable_currency
object
The currency and amount of the PayPal fee for this payment in the receivable currency. Returned only in cases the fee is charged in the receivable currency. Example 'CNY'. Would not be returned for 'pending' transactions where the funds have not been realized in the payee account.
receivable_amount
object
The net amount and currency that the merchant receives for this transaction in the receivable currency.
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
A free-form field that clients can use to send a note to the payer.
Maximum length: 255.
create_time
string
The date and time of the capture, in Internet date and time format.
update_time
string
The date and time when the resource was last updated, in Internet date and time format.
links
array (contains the link_description object)
An array of request-related HATEOAS links.

SDK samples:

Sample Request

curl -v -X POST https://api-m.sandbox.paypal.com/v1/payments/authorization/2DC87612EK520411B/capture \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
  "amount": {
    "currency": "USD",
    "total": "4.54"
  },
  "is_final_capture": true
}'

Response

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

id
string
The ID of the capture transaction.
Read only.
amount
object
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.
is_final_capture
boolean
Indicates whether to release all remaining held funds.
state
enum
The state of the capture.
The possible values are:
- 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.
Read only.
reason_code
enum
The reason code that describes why the transaction state is pending or reversed.
The possible values are:
- 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.
Read only.
parent_payment
string
The ID of the payment on which this transaction is based.
Read only.
invoice_number
string
The invoice number to track this payment.
Maximum length: 127.
transaction_fee
object
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.
Read only.
transaction_fee_in_receivable_currency
object
The currency and amount of the PayPal fee for this payment in the receivable currency. Returned only in cases the fee is charged in the receivable currency. Example 'CNY'. Would not be returned for 'pending' transactions where the funds have not been realized in the payee account.
Read only.
receivable_amount
object
The net amount and currency that the merchant receives for this transaction in the receivable currency.
Read only.
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.
Read only.
note_to_payer
string
A free-form field that clients can use to send a note to the payer.
Maximum length: 255.
create_time
string
The date and time of the capture, in Internet date and time format.
Read only.
update_time
string
The date and time when the resource was last updated, in Internet date and time format.
Read only.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
Read only.

Sample Response

{
  "id": "6BA17599X0950293U",
  "create_time": "2017-05-06T22:32:24Z",
  "update_time": "2017-05-06T22:32:25Z",
  "amount": {
    "total": "4.54",
    "currency": "USD"
  },
  "is_final_capture": true,
  "state": "COMPLETED",
  "parent_payment": "PAY-44664305570317015KGEC5DI",
  "links": [
    {
      "href": "https://api-m.sandbox.paypal.com/v1/payments/capture/6BA17599X0950293U",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://api-m.sandbox.paypal.com/v1/payments/capture/6BA17599X0950293U/refund",
      "rel": "refund",
      "method": "POST"
    },
    {
      "href": "https://api-m.sandbox.paypal.com/v1/payments/authorization/5RA45624N3531924N",
      "rel": "authorization",
      "method": "GET"
    },
    {
      "href": "https://api-m.sandbox.paypal.com/v1/payments/payment/PAY-44664305570317015KGEC5DI",
      "rel": "parent_payment",
      "method": "GET"
    }
  ]
}

Re-authorize payment

POST/v1/payments/authorization/{authorization_id}/reauthorize

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.

Path parameters

authorization_id
string
required
The ID of the authorization to re-authorize.

Request body

id
string
The ID of the authorization.
amount
object
required
The amount being authorized.
payment_mode
enum
The payment mode of the authorization.
The possible values are:
- INSTANT_TRANSFER. Instant transfer.
state
enum
The authorized payment state.
The possible values are:
- pending. The authorized payment is pending.
- 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
enum
The reason code for the pending transaction state.
The possible values are:
- AUTHORIZATION. Authorization.
pending_reason
enum
Deprecated. The reason code for the pending transaction state. Obsolete. Use reason_code instead.
The possible values are:
- AUTHORIZATION. Authorization.
protection_eligibility
enum
The level of seller protection present for the transaction. Supported for the PayPal payment method only.
The possible values are:
- 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
enum
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.
The possible values are:
- 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.
fmf_details
object
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.
processor_response
object
The processor-provided response codes that describe the submitted payment. Supported only when the payment_method is credit_card.
valid_until
string
The date and time when the authorization expires, in Internet date and time format.
create_time
string
The date and time when the authorization was created, in Internet date and time format.
update_time
string
The date and time when the authorization was last updated, in Internet date and time format.
receipt_id
string
The receipt ID, which identifies the payment. Value is 16-digit numeric payment ID number that is returned for guest users.
Pattern: ^[0-9]{4}-[0-9]{4}-[0-9]{4}-[0-9]{4}$.
links
array (contains the link_description object)
An array of request-related HATEOAS links.

SDK samples:

Sample Request

curl -v -X POST https://api-m.sandbox.paypal.com/v1/payments/authorization/2DC87612EK520411B/reauthorize \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
  "amount": {
    "total": "7.00",
    "currency": "USD"
  }
}'

Response

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

id
string
The ID of the authorization.
Read only.
amount
object
The amount being authorized.
payment_mode
enum
The payment mode of the authorization.
The possible values are:
- INSTANT_TRANSFER. Instant transfer.
Read only.
state
enum
The authorized payment state.
The possible values are:
- pending. The authorized payment is pending.
- 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.
Read only.
reason_code
enum
The reason code for the pending transaction state.
The possible values are:
- AUTHORIZATION. Authorization.
Read only.
pending_reason
enum
Deprecated. The reason code for the pending transaction state. Obsolete. Use reason_code instead.
The possible values are:
- AUTHORIZATION. Authorization.
Read only.
protection_eligibility
enum
The level of seller protection present for the transaction. Supported for the PayPal payment method only.
The possible values are:
- 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.
Read only.
protection_eligibility_type
enum
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.
The possible values are:
- 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.
Read only.
fmf_details
object
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.
Read only.
processor_response
object
The processor-provided response codes that describe the submitted payment. Supported only when the payment_method is credit_card.
valid_until
string
The date and time when the authorization expires, in Internet date and time format.
Read only.
create_time
string
The date and time when the authorization was created, in Internet date and time format.
Read only.
update_time
string
The date and time when the authorization was last updated, in Internet date and time format.
Read only.
receipt_id
string
The receipt ID, which identifies the payment. Value is 16-digit numeric payment ID number that is returned for guest users.
Read only.
Pattern: ^[0-9]{4}-[0-9]{4}-[0-9]{4}-[0-9]{4}$.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
Read only.

Sample Response

{
  "id": "8AA831015G517922L",
  "create_time": "2017-06-25T21:39:15Z",
  "update_time": "2017-06-25T21:39:17Z",
  "state": "AUTHORIZED",
  "amount": {
    "total": "7.00",
    "currency": "USD"
  },
  "parent_payment": "PAY-7LD317540C810384EKHFAGYA",
  "valid_until": "2017-07-24T21:39:15Z",
  "links": [
    {
      "href": "https://api-m.sandbox.paypal.com/v1/payments/authorization/8AA831015G517922L",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://api-m.sandbox.paypal.com/v1/payments/payment/PAY-7LD317540C810384EKHFAGYA",
      "rel": "parent_payment",
      "method": "GET"
    },
    {
      "href": "https://api-m.sandbox.paypal.com/v1/payments/authorization/8AA831015G517922L/capture",
      "rel": "capture",
      "method": "POST"
    }
  ]
}

Void authorization

POST/v1/payments/authorization/{authorization_id}/void

Voids, or cancels, an authorization, by ID. You cannot void a fully captured authorization.

Header parameters

PayPal-Request-Id
string
The server stores keys for 30 days.
Maximum length: 78.

Path parameters

authorization_id
string
required
The ID of the authorization to void.

SDK samples:

Sample Request

curl -v -X POST https://api-m.sandbox.paypal.com/v1/payments/authorization/2DC87612EK520411B/void \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token"

Response

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

id
string
The ID of the authorization.
Read only.
amount
object
The amount being authorized.
payment_mode
enum
The payment mode of the authorization.
The possible values are:
- INSTANT_TRANSFER. Instant transfer.
Read only.
state
enum
The authorized payment state.
The possible values are:
- pending. The authorized payment is pending.
- 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.
Read only.
reason_code
enum
The reason code for the pending transaction state.
The possible values are:
- AUTHORIZATION. Authorization.
Read only.
pending_reason
enum
Deprecated. The reason code for the pending transaction state. Obsolete. Use reason_code instead.
The possible values are:
- AUTHORIZATION. Authorization.
Read only.
protection_eligibility
enum
The level of seller protection present for the transaction. Supported for the PayPal payment method only.
The possible values are:
- 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.
Read only.
protection_eligibility_type
enum
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.
The possible values are:
- 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.
Read only.
fmf_details
object
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.
Read only.
processor_response
object
The processor-provided response codes that describe the submitted payment. Supported only when the payment_method is credit_card.
valid_until
string
The date and time when the authorization expires, in Internet date and time format.
Read only.
create_time
string
The date and time when the authorization was created, in Internet date and time format.
Read only.
update_time
string
The date and time when the authorization was last updated, in Internet date and time format.
Read only.
receipt_id
string
The receipt ID, which identifies the payment. Value is 16-digit numeric payment ID number that is returned for guest users.
Read only.
Pattern: ^[0-9]{4}-[0-9]{4}-[0-9]{4}-[0-9]{4}$.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
Read only.

Sample Response

{
  "id": "6CR34526N64144512",
  "create_time": "2017-05-06T21:56:50Z",
  "update_time": "2017-05-06T21:57:51Z",
  "state": "VOIDED",
  "amount": {
    "total": "110.54",
    "currency": "USD",
    "details": {
      "subtotal": "110.54"
    }
  },
  "parent_payment": "PAY-0PL82432AD7432233KGECOIQ",
  "links": [
    {
      "href": "https://api-m.sandbox.paypal.com/v1/payments/authorization/6CR34526N64144512",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://api-m.sandbox.paypal.com/v1/payments/payment/PAY-0PL82432AD7432233KGECOIQ",
      "rel": "parent_payment",
      "method": "GET"
    }
  ]
}

Orders (resource group)

Use the /orders resource to authorize, capture, void, and show details for an order.

For more information, see also Orders.

Show order details

GET/v1/payments/orders/{order_id}

Shows details for an order, by ID.

Path parameters

order_id
string
required
The ID of the order for which to show details.

SDK samples:

Sample Request

curl -v -X GET https://api-m.sandbox.paypal.com/v1/payments/orders/O-0PW72302W3743444R \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token"

Response

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

id
string
The ID of the order transaction.
Read only.
amount
object
The amount to collect.
Note: For an order authorization, you cannot include amount details.
payment_mode
enum
The transaction payment mode.
The possible values are:
- INSTANT_TRANSFER. The payment mode is instant transfer.
- MANUAL_BANK_TRANSFER. The payment mode is manual bank transfer.
- DELAYED_TRANSFER. The payment mode is delayed transfer.
- ECHECK. The payment mode is eCheck.
Read only.
state
enum
The state of the order transaction.
The possible values are:
- PENDING. The order was created but no authorizations or captures were made against the order.
- AUTHORIZED. The order has only been authorized. No capture was made against the order.
- CAPTURED. The order has at least one capture initiated.
- COMPLETED. The order is complete. A capture was made against the order with is_final_capture set to TRUE. No more authorizations or captures can be made against this order.
- VOIDED. The order was voided. No more authorizations or captures can be made against this order.
Read only.
reason_code
enum
The reason code that describes why the transaction state is pending or reversed. Supported only for PayPal payments.
The possible values are:
- PAYER_SHIPPING_UNCONFIRMED. The shipping address of the payer is not confirmed.
- MULTI_CURRENCY. The transaction is in multiple currencies.
- RISK_REVIEW. The transaction is under risk review.
- REGULATORY_REVIEW. The transaction is under regulatory review.
- VERIFICATION_REQUIRED. Verification is required.
- ORDER. The transaction is an order.
- OTHER. Other.
Read only.
pending_reason
enum
Deprecated. The reason code for the pending transaction state. Obsolete. Use reason_code instead.
Read only.
Possible values: payer_shipping_unconfirmed,multi_currency,risk_review,regulatory_review,verification_required,order,other.
protection_eligibility
enum
The level of seller protection in effect for the transaction.
The possible values are:
- ELIGIBLE. The transaction is eligible for seller protection.
- PARTIALLY_ELIGIBLE. The transaction is partially eligible for seller protection.
- INELIGIBLE. The transaction is ineligible for seller protection.
Read only.
protection_eligibility_type
enum
The kind of seller protection in effect for the transaction. Returned only when the protection_eligibility property is ELIGIBLE or PARTIALLY_ELIGIBLE. Supported only for PayPal payments.
The possible values are:
- 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 claims for unauthorized payments.
Read only.
parent_payment
string
The ID of the payment on which this transaction is based.
Read only.
fmf_details
object
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.
create_time
string
The date and time when the resource was created, in Internet date and time format.
Read only.
update_time
string
The date and time when the resource was last updated, in Internet date and time format.
Read only.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
Read only.

Sample Response

{
  "id": "O-0PW72302W3743444R",
  "create_time": "2017-06-19T22:05:06Z",
  "update_time": "2017-06-19T22:08:36Z",
  "state": "PENDING",
  "amount": {
    "total": "41.15",
    "currency": "USD"
  },
  "pending_reason": "order",
  "parent_payment": "PAY-4D805864V5423372TKOQLRUQ",
  "links": [
    {
      "href": "https://api-m.sandbox.paypal.com/v1/payments/orders/O-0PW72302W3743444R",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://api-m.sandbox.paypal.com/v1/payments/payment/PAY-4D805864V5423372TKOQLRUQ",
      "rel": "parent_payment",
      "method": "GET"
    },
    {
      "href": "https://api-m.sandbox.paypal.com/v1/payments/orders/O-0PW72302W3743444R/authorization",
      "rel": "authorize",
      "method": "POST"
    },
    {
      "href": "https://api-m.sandbox.paypal.com/v1/payments/orders/O-0PW72302W3743444R/capture",
      "rel": "capture",
      "method": "POST"
    },
    {
      "href": "https://api-m.sandbox.paypal.com/v1/payments/orders/O-0PW72302W3743444R/void",
      "rel": "void",
      "method": "POST"
    }
  ]
}

Authorize order

POST/v1/payments/orders/{order_id}/authorize

Authorizes an order, by ID. In the JSON request body, include an amount object.

Path parameters

order_id
string
required
The ID of the order to authorize.

Request body

id
string
The ID of the order transaction.
amount
object
required
The amount to collect.
Note: For an order authorization, you cannot include amount details.
payment_mode
enum
The transaction payment mode.
The possible values are:
- INSTANT_TRANSFER. The payment mode is instant transfer.
- MANUAL_BANK_TRANSFER. The payment mode is manual bank transfer.
- DELAYED_TRANSFER. The payment mode is delayed transfer.
- ECHECK. The payment mode is eCheck.
state
enum
The state of the order transaction.
The possible values are:
- PENDING. The order was created but no authorizations or captures were made against the order.
- AUTHORIZED. The order has only been authorized. No capture was made against the order.
- CAPTURED. The order has at least one capture initiated.
- COMPLETED. The order is complete. A capture was made against the order with is_final_capture set to TRUE. No more authorizations or captures can be made against this order.
- VOIDED. The order was voided. No more authorizations or captures can be made against this order.
reason_code
enum
The reason code that describes why the transaction state is pending or reversed. Supported only for PayPal payments.
The possible values are:
- PAYER_SHIPPING_UNCONFIRMED. The shipping address of the payer is not confirmed.
- MULTI_CURRENCY. The transaction is in multiple currencies.
- RISK_REVIEW. The transaction is under risk review.
- REGULATORY_REVIEW. The transaction is under regulatory review.
- VERIFICATION_REQUIRED. Verification is required.
- ORDER. The transaction is an order.
- OTHER. Other.
pending_reason
enum
Deprecated. The reason code for the pending transaction state. Obsolete. Use reason_code instead.
Possible values: payer_shipping_unconfirmed,multi_currency,risk_review,regulatory_review,verification_required,order,other.
protection_eligibility
enum
The level of seller protection in effect for the transaction.
The possible values are:
- ELIGIBLE. The transaction is eligible for seller protection.
- PARTIALLY_ELIGIBLE. The transaction is partially eligible for seller protection.
- INELIGIBLE. The transaction is ineligible for seller protection.
protection_eligibility_type
enum
The kind of seller protection in effect for the transaction. Returned only when the protection_eligibility property is ELIGIBLE or PARTIALLY_ELIGIBLE. Supported only for PayPal payments.
The possible values are:
- 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 claims for unauthorized payments.
parent_payment
string
The ID of the payment on which this transaction is based.
fmf_details
object
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.
create_time
string
The date and time when the resource was created, in Internet date and time format.
update_time
string
The date and time when the resource was last updated, in Internet date and time format.
links
array (contains the link_description object)
An array of request-related HATEOAS links.

SDK samples:

Sample Request

curl -v -X POST https://api-m.sandbox.paypal.com/v1/payments/orders/O-0NR488530V5211123/authorize \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
  "amount": {
    "currency": "USD",
    "total": "4.54"
  }
}'

Response

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

id
string
The ID of the authorization.
Read only.
amount
object
The amount being authorized.
payment_mode
enum
The payment mode of the authorization.
The possible values are:
- INSTANT_TRANSFER. Instant transfer.
Read only.
state
enum
The authorized payment state.
The possible values are:
- pending. The authorized payment is pending.
- 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.
Read only.
reason_code
enum
The reason code for the pending transaction state.
The possible values are:
- AUTHORIZATION. Authorization.
Read only.
pending_reason
enum
Deprecated. The reason code for the pending transaction state. Obsolete. Use reason_code instead.
The possible values are:
- AUTHORIZATION. Authorization.
Read only.
protection_eligibility
enum
The level of seller protection present for the transaction. Supported for the PayPal payment method only.
The possible values are:
- 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.
Read only.
protection_eligibility_type
enum
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.
The possible values are:
- 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.
Read only.
fmf_details
object
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.
Read only.
processor_response
object
The processor-provided response codes that describe the submitted payment. Supported only when the payment_method is credit_card.
valid_until
string
The date and time when the authorization expires, in Internet date and time format.
Read only.
create_time
string
The date and time when the authorization was created, in Internet date and time format.
Read only.
update_time
string
The date and time when the authorization was last updated, in Internet date and time format.
Read only.
receipt_id
string
The receipt ID, which identifies the payment. Value is 16-digit numeric payment ID number that is returned for guest users.
Read only.
Pattern: ^[0-9]{4}-[0-9]{4}-[0-9]{4}-[0-9]{4}$.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
Read only.

Sample Response

{
  "id": "0PG032325D352531H",
  "create_time": "2017-06-28T07:38:10Z",
  "update_time": "2017-06-28T07:38:12Z",
  "state": "PENDING",
  "amount": {
    "total": "41.15",
    "currency": "USD"
  },
  "parent_payment": "O-0NR488530V5211123",
  "links": [
    {
      "href": "https://api-m.sandbox.paypal.com/v1/payments/orders/O-0NR488530V5211123",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://api-m.sandbox.paypal.com/v1/payments/authorization/0PG032325D352531H",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://api-m.sandbox.paypal.com/v1/payments/authorization/0PG032325D352531H/capture",
      "rel": "capture",
      "method": "POST"
    },
    {
      "href": "https://api-m.sandbox.paypal.com/v1/payments/payment/PAY-0AY778532K612520BKOXHAKY",
      "rel": "parent_payment",
      "method": "GET"
    }
  ]
}

Capture order

POST/v1/payments/orders/{order_id}/capture

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.

Path parameters

order_id
string
required
The ID of the order to capture.

Request body

id
string
The ID of the capture transaction.
amount
object
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.
is_final_capture
boolean
Indicates whether to release all remaining held funds.
state
enum
The state of the capture.
The possible values are:
- 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
enum
The reason code that describes why the transaction state is pending or reversed.
The possible values are:
- 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
The invoice number to track this payment.
Maximum length: 127.
transaction_fee
object
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.
transaction_fee_in_receivable_currency
object
The currency and amount of the PayPal fee for this payment in the receivable currency. Returned only in cases the fee is charged in the receivable currency. Example 'CNY'. Would not be returned for 'pending' transactions where the funds have not been realized in the payee account.
receivable_amount
object
The net amount and currency that the merchant receives for this transaction in the receivable currency.
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
A free-form field that clients can use to send a note to the payer.
Maximum length: 255.
create_time
string
The date and time of the capture, in Internet date and time format.
update_time
string
The date and time when the resource was last updated, in Internet date and time format.
links
array (contains the link_description object)
An array of request-related HATEOAS links.

SDK samples:

Sample Request

curl -v -X POST https://api-m.sandbox.paypal.com/v1/payments/orders/O-3SP845109F051535C/capture \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
  "amount": {
    "currency": "USD",
    "total": "4.54"
  },
  "is_final_capture": true
}'

Response

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

id
string
The ID of the capture transaction.
Read only.
amount
object
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.
is_final_capture
boolean
Indicates whether to release all remaining held funds.
state
enum
The state of the capture.
The possible values are:
- 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.
Read only.
reason_code
enum
The reason code that describes why the transaction state is pending or reversed.
The possible values are:
- 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.
Read only.
parent_payment
string
The ID of the payment on which this transaction is based.
Read only.
invoice_number
string
The invoice number to track this payment.
Maximum length: 127.
transaction_fee
object
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.
Read only.
transaction_fee_in_receivable_currency
object
The currency and amount of the PayPal fee for this payment in the receivable currency. Returned only in cases the fee is charged in the receivable currency. Example 'CNY'. Would not be returned for 'pending' transactions where the funds have not been realized in the payee account.
Read only.
receivable_amount
object
The net amount and currency that the merchant receives for this transaction in the receivable currency.
Read only.
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.
Read only.
note_to_payer
string
A free-form field that clients can use to send a note to the payer.
Maximum length: 255.
create_time
string
The date and time of the capture, in Internet date and time format.
Read only.
update_time
string
The date and time when the resource was last updated, in Internet date and time format.
Read only.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
Read only.

Sample Response

{
  "id": "51366113MA710110S",
  "create_time": "2017-07-01T17:13:45Z",
  "update_time": "2017-07-01T17:13:47Z",
  "amount": {
    "total": "7.00",
    "currency": "USD"
  },
  "is_final_capture": false,
  "state": "COMPLETED",
  "parent_payment": "PAY-9N9834337A9191208KOZOQWI",
  "links": [
    {
      "href": "https://api-m.sandbox.paypal.com/v1/payments/capture/51366113MA710110S",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://api-m.sandbox.paypal.com/v1/payments/capture/51366113MA710110S/refund",
      "rel": "refund",
      "method": "POST"
    },
    {
      "href": "https://api-m.sandbox.paypal.com/v1/payments/orders/O-3SP845109F051535C",
      "rel": "order",
      "method": "GET"
    },
    {
      "href": "https://api-m.sandbox.paypal.com/v1/payments/payment/PAY-9N9834337A9191208KOZOQWI",
      "rel": "parent_payment",
      "method": "GET"
    }
  ]
}

Void order

POST/v1/payments/orders/{order_id}/do-void

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.

Header parameters

PayPal-Request-Id
string
The server stores keys for 30 days.
Maximum length: 78.

Path parameters

order_id
string
required
The ID of the order to void.

SDK samples:

Sample Request

curl -v -X POST https://api-m.sandbox.paypal.com/v1/payments/orders/O-0NR488530V5211123/do-void \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token"

Response

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

id
string
The ID of the order transaction.
Read only.
amount
object
The amount to collect.
Note: For an order authorization, you cannot include amount details.
payment_mode
enum
The transaction payment mode.
The possible values are:
- INSTANT_TRANSFER. The payment mode is instant transfer.
- MANUAL_BANK_TRANSFER. The payment mode is manual bank transfer.
- DELAYED_TRANSFER. The payment mode is delayed transfer.
- ECHECK. The payment mode is eCheck.
Read only.
state
enum
The state of the order transaction.
The possible values are:
- PENDING. The order was created but no authorizations or captures were made against the order.
- AUTHORIZED. The order has only been authorized. No capture was made against the order.
- CAPTURED. The order has at least one capture initiated.
- COMPLETED. The order is complete. A capture was made against the order with is_final_capture set to TRUE. No more authorizations or captures can be made against this order.
- VOIDED. The order was voided. No more authorizations or captures can be made against this order.
Read only.
reason_code
enum
The reason code that describes why the transaction state is pending or reversed. Supported only for PayPal payments.
The possible values are:
- PAYER_SHIPPING_UNCONFIRMED. The shipping address of the payer is not confirmed.
- MULTI_CURRENCY. The transaction is in multiple currencies.
- RISK_REVIEW. The transaction is under risk review.
- REGULATORY_REVIEW. The transaction is under regulatory review.
- VERIFICATION_REQUIRED. Verification is required.
- ORDER. The transaction is an order.
- OTHER. Other.
Read only.
pending_reason
enum
Deprecated. The reason code for the pending transaction state. Obsolete. Use reason_code instead.
Read only.
Possible values: payer_shipping_unconfirmed,multi_currency,risk_review,regulatory_review,verification_required,order,other.
protection_eligibility
enum
The level of seller protection in effect for the transaction.
The possible values are:
- ELIGIBLE. The transaction is eligible for seller protection.
- PARTIALLY_ELIGIBLE. The transaction is partially eligible for seller protection.
- INELIGIBLE. The transaction is ineligible for seller protection.
Read only.
protection_eligibility_type
enum
The kind of seller protection in effect for the transaction. Returned only when the protection_eligibility property is ELIGIBLE or PARTIALLY_ELIGIBLE. Supported only for PayPal payments.
The possible values are:
- 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 claims for unauthorized payments.
Read only.
parent_payment
string
The ID of the payment on which this transaction is based.
Read only.
fmf_details
object
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.
create_time
string
The date and time when the resource was created, in Internet date and time format.
Read only.
update_time
string
The date and time when the resource was last updated, in Internet date and time format.
Read only.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
Read only.

Sample Response

{
  "id": "O-0NR488530V5211123",
  "create_time": "2017-06-28T07:35:08Z",
  "update_time": "2017-06-28T07:36:25Z",
  "state": "VOIDED",
  "amount": {
    "total": "41.15",
    "currency": "USD",
    "details": {
      "subtotal": "30.00",
      "tax": "0.15",
      "shipping": "11.00"
    }
  },
  "parent_payment": "PAY-0AY778532K612520BKOXHAKY",
  "links": [
    {
      "href": "https://api-m.sandbox.paypal.com/v1/payments/authorization/O-0NR488530V5211123",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://api-m.sandbox.paypal.com/v1/payments/payment/PAY-0AY778532K612520BKOXHAKY",
      "rel": "parent_payment",
      "method": "GET"
    }
  ]
}

Capture (resource group)

Use the /capture resource and sub-resources to show details for and refund captured payments.

Show captured payment details

GET/v1/payments/capture/{capture_id}

Shows details for a captured payment, by ID.

Path parameters

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

SDK samples:

Sample Request

curl -v -X GET https://api-m.sandbox.paypal.com/v1/payments/capture/8F148933LY9388354 \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token"

Response

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

id
string
The ID of the capture transaction.
Read only.
amount
object
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.
is_final_capture
boolean
Indicates whether to release all remaining held funds.
state
enum
The state of the capture.
The possible values are:
- 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.
Read only.
reason_code
enum
The reason code that describes why the transaction state is pending or reversed.
The possible values are:
- 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.
Read only.
parent_payment
string
The ID of the payment on which this transaction is based.
Read only.
invoice_number
string
The invoice number to track this payment.
Maximum length: 127.
transaction_fee
object
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.
Read only.
transaction_fee_in_receivable_currency
object
The currency and amount of the PayPal fee for this payment in the receivable currency. Returned only in cases the fee is charged in the receivable currency. Example 'CNY'. Would not be returned for 'pending' transactions where the funds have not been realized in the payee account.
Read only.
receivable_amount
object
The net amount and currency that the merchant receives for this transaction in the receivable currency.
Read only.
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.
Read only.
note_to_payer
string
A free-form field that clients can use to send a note to the payer.
Maximum length: 255.
create_time
string
The date and time of the capture, in Internet date and time format.
Read only.
update_time
string
The date and time when the resource was last updated, in Internet date and time format.
Read only.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
Read only.

Sample Response

{
  "id": "8F148933LY9388354",
  "amount": {
    "total": "110.54",
    "currency": "USD",
    "details": {
      "subtotal": "110.54"
    }
  },
  "state": "COMPLETED",
  "parent_payment": "PAY-8PT597110X687430LKGECATA",
  "transaction_fee": {
    "value": "3.74",
    "currency": "USD"
  },
  "links": [
    {
      "href": "https://api-m.sandbox.paypal.com/v1/payments/capture/8F148933LY9388354",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://api-m.sandbox.paypal.com/v1/payments/capture/8F148933LY9388354/refund",
      "rel": "refund",
      "method": "POST"
    },
    {
      "href": "https://api-m.sandbox.paypal.com/v1/payments/payment/PAY-8PT597110X687430LKGECATA",
      "rel": "parent_payment",
      "method": "GET"
    }
  ]
}

Refund captured payment

POST/v1/payments/capture/{capture_id}/refund

Refunds a captured payment, by ID. In the JSON request body, include an amount object.

Header parameters

PayPal-Request-Id
string
The server stores keys for 30 days.
Maximum length: 78.

Path parameters

capture_id
string
required
The ID of the captured payment to refund.

Request body

amount
object
The refund amount. Includes both the amount to refund to the payer and the fee amount to refund to the payee.
description
string
The refund description. Value is a string of single-byte alphanumeric characters.
Maximum length: 255.
reason
string
The refund reason description.
Maximum length: 30.
invoice_number
string
The invoice number that tracks this payment. Value is a string of single-byte alphanumeric characters.
Maximum length: 127.

SDK samples:

Sample Request

curl -v -X POST https://api-m.sandbox.paypal.com/v1/payments/capture/2F6652020G264741U/refund \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
  "amount": {
    "total": "100.00",
    "currency": "USD"
  },
  "invoice_number": "INV-7654321"
}'

Response

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

id
string
The ID of the refund transaction.
Read only.
Maximum length: 17.
amount
object
The refund amount. Includes both the amount refunded to the payer and the fee refunded to the payee.
state
enum
The state of the refund.
Read only.
Possible values: pending,completed,cancelled,failed.
reason
string
The reason that the transaction is being refunded.
invoice_number
string
The invoice number to track this payment.
Maximum length: 127.
sale_id
string
The ID of the sale transaction being refunded.
Read only.
capture_id
string
The ID of the sale transaction being refunded.
Read only.
parent_payment
string
The ID of the payment on which this transaction is based.
Read only.
description
string
The refund description.
create_time
string
The date and time when the refund was created, in Internet date and time format.
Read only.
update_time
string
The date and time when the resource was last updated, in Internet date and time format.
Read only.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
Read only.
custom
string
The note to the payer in this transaction.
Maximum length: 127.
refund_from_transaction_fee
object
The currency and amount of the transaction fee that is refunded to original the recipient of payment.
refund_from_received_amount
object
The currency and amount of the refund that is subtracted from the original payment recipient's PayPal balance.
total_refunded_amount
object
The currency and amount of the total refund from the original purchase. For example, if a payer makes $100 purchase and the payer was refunded $20 a week ago and $30 in this transaction, the gross refund amount is $30 for this transaction and the total refunded amount is $50.

Sample Response

{
  "id": "29V87338W7751874U",
  "create_time": "2018-08-15T17:33:46Z",
  "update_time": "2018-08-15T17:33:46Z",
  "state": "COMPLETED",
  "amount": {
    "total": "100.00",
    "currency": "USD"
  },
  "refund_from_transaction_fee": {
    "currency": "USD",
    "value": "2.90"
  },
  "total_refunded_amount": {
    "currency": "USD",
    "value": "100.00"
  },
  "refund_from_received_amount": {
    "currency": "USD",
    "value": "97.10"
  },
  "capture_id": "2F6652020G264741U",
  "parent_payment": "PAY-22L784864U0004637LN2GCYQ",
  "invoice_number": "INV-7654321",
  "links": [
    {
      "href": "https://sandbox.paypal.com/v1/payments/refund/29V87338W7751874U",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://sandbox.paypal.com/v1/payments/payment/PAY-22L784864U0004637LN2GCYQ",
      "rel": "parent_payment",
      "method": "GET"
    },
    {
      "href": "https://sandbox.paypal.com/v1/payments/capture/2F6652020G264741U",
      "rel": "capture",
      "method": "GET"
    }
  ]
}

Refund (resource group)

Use the /refund resource to show details for a refund on direct and captured payments.

Show refund details

GET/v1/payments/refund/{refund_id}

Shows details for a refund, by ID.

Path parameters

refund_id
string
required
The ID of the refund for which to show details.

SDK samples:

Sample Request

curl -v -X GET https://api-m.sandbox.paypal.com/v1/payments/refund/4GU360220B627614A \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token"

Response

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

id
string
The ID of the refund transaction. Maximum length is 17 characters.
Read only.
amount
object
The refund amount. Includes both the amount refunded to the payer and amount of the fee refunded to the payee.
state
enum
The state of the refund.
The possible values are:
- pending. The refund state is pending.
- completed. The refund state is completed.
- cancelled. The refund state is cancelled.
- failed. The refund state is failed.
Read only.
reason
string
The reason that the transaction is being refunded.
invoice_number
string
The invoice or tracking ID number.
Maximum length: 127.
sale_id
string
The ID of the sale transaction being refunded.
Read only.
capture_id
string
The ID of the sale transaction being refunded.
Read only.
parent_payment
string
The ID of the payment on which this transaction is based.
Read only.
description
string
The refund description. Value must be single-byte alphanumeric characters.
create_time
string
The date and time when the refund was created, in Internet date and time format.
Read only.
update_time
string
The date and time when the resource was last updated, in Internet date and time format.
Read only.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
Read only.

Sample Response

{
  "id": "4GU360220B627614A",
  "create_time": "2017-01-01T02:00:00Z",
  "update_time": "2017-01-01T03:00:02Z",
  "state": "COMPLETED",
  "amount": {
    "total": "2.34",
    "currency": "USD"
  },
  "sale_id": "36C38912MN9658832",
  "parent_payment": "PAY-5YK922393D847794YKER7MUI",
  "invoice_number": "INV-1234567",
  "links": [
    {
      "href": "https://api-m.sandbox.paypal.com/v1/payments/refund/4GU360220B627614A",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://api-m.sandbox.paypal.com/v1/payments/payment/PAY-5YK922393D847794YKER7MUI",
      "rel": "parent_payment",
      "method": "GET"
    },
    {
      "href": "https://api-m.sandbox.paypal.com/v1/payments/sale/36C38912MN9658832",
      "rel": "sale",
      "method": "GET"
    }
  ]
}

Common object definitions

ach_debit

account_number
string
required
The US bank account number from which the payment will be debited.
Minimum length: 3.
Maximum length: 17.
Pattern: [0-9]{3,17}.
routing_number
string
required
The 9-digit ABA routing transit number for the bank at which the account is held.
Minimum length: 9.
Maximum length: 9.
Pattern: [0-9]{9}.
account_type
enum
Represents the type of the bank account. If not provided, default is CHECKING.
The possible values are:
- CHECKING. Bank account of type CHECKING.
- SAVINGS. Bank account of type SAVINGS.
Minimum length: 1.
Maximum length: 255.
account_holder_name
string
required
Name of the person or business that owns the bank account.
Minimum length: 1.
Maximum length: 300.

address

line1
string
required
The first line of the address. For example, number, street, and so on.
Maximum length: 300.
line2
string
The second line of the address. For example, suite or apartment number.
Maximum length: 300.
city
string
The city name.
Maximum length: 64.
country_code
string
required
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.
Minimum length: 2.
Maximum length: 2.
Pattern: ^([A-Z]{2}|C2)$.
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
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. Maximum length is 40 single-byte characters.
phone
string
The phone number, in E.123 format. Maximum length is 50 characters.
normalization_status
enum
The address normalization status. Returned only for payers from Brazil.
The possible values are:
- UNKNOWN. Unknown.
- UNNORMALIZED_USER_PREFERRED. Unnormalized user preferred.
- NORMALIZED. Normalized.
- UNNORMALIZED. Unnormalized.
Read only.
type
string
The type of address. For example, HOME_OR_WORK, GIFT, and so on.

address_details

street_number
string
The street number.
Maximum length: 100.
street_name
string
The street name. Just Drury in Drury Lane.
Maximum length: 100.
street_type
string
The street type. For example, avenue, boulevard, road, or expressway.
Maximum length: 100.
delivery_service
string
The delivery service. Post office box, bag number, or post office name.
Maximum length: 100.
building_name
string
A named locations that represents the premise. Usually a building name or number or collection of buildings with a common name or number. For example, Craven House.
Maximum length: 100.
sub_building
string
The first-order entity below a named building or location that represents the sub-premise. Usually a single building within a collection of buildings with a common name. Can be a flat, story, floor, room, or apartment.
Maximum length: 100.

address_portable

address_line_1
string
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.
Maximum length: 300.
address_line_2
string
The second line of the address. For example, suite or apartment number.
Maximum length: 300.
address_line_3
string
The third line of the address, if needed. For example, a street complement for Brazil, direction text, such as next to Walmart, or a landmark in an Indian address.
Maximum length: 100.
admin_area_4
string
The neighborhood, ward, or district. Smaller than admin_area_level_3 or sub_locality. Value is:
- The postal sorting code for Guernsey and many French territories, such as French Guiana.
- The fine-grained administrative levels in China.
Maximum length: 100.
admin_area_3
string
A sub-locality, suburb, neighborhood, or district. Smaller than admin_area_level_2. Value is:
- Brazil. Suburb, bairro, or neighborhood.
- India. Sub-locality or district. Street name information is not always available but a sub-locality or district can be a very small area.
Maximum length: 100.
admin_area_2
string
A city, town, or village. Smaller than admin_area_level_1.
Maximum length: 120.
admin_area_1
string
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.
Maximum length: 300.
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.
Maximum length: 60.
country_code
string
required
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.
Minimum length: 2.
Maximum length: 2.
Pattern: ^([A-Z]{2}|C2)$.
address_details
object
The non-portable additional address details that are sometimes needed for compliance, risk, or other scenarios where fine-grain address information might be needed. Not portable with common third party and open source. Redundant with core fields.
For example, address_portable.address_line_1 is usually a combination of address_details.street_number, street_name, and street_type.

address_portable_postal_code_validation

address_portable_postal_code_validation

amount

currency
string
required
The three-character ISO-4217 currency code. PayPal does not support all currencies.
total
string
required
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.
details
object
The additional details about the payment amount.
Note: For an order authorization or capture, you cannot include the amount details object.

application_context

brand_name
string
A label that overrides the business name in the merchant's PayPal account on the PayPal checkout pages.
Maximum length: 127.
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
enum
The shipping preference.
The possible values are:
- 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:

Flow	Action	Description
Pay Now	`user_action=commit`	After 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=continue`	After 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.

preferred_payment_source
object
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.
payment_pattern
enum
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.
The possible values are:
- 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.
Minimum length: 3.
Maximum length: 255.
Pattern: ^[A-Z_]+$.

application_context.payment_source

token
object
The tokenized payment source to fund a payment.

authorization

id
string
The ID of the authorization.
Read only.
amount
object
required
The amount being authorized.
payment_mode
enum
The payment mode of the authorization.
The possible values are:
- INSTANT_TRANSFER. Instant transfer.
Read only.
state
enum
The authorized payment state.
The possible values are:
- pending. The authorized payment is pending.
- 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.
Read only.
reason_code
enum
The reason code for the pending transaction state.
The possible values are:
- AUTHORIZATION. Authorization.
Read only.
pending_reason
enum
Deprecated. The reason code for the pending transaction state. Obsolete. Use reason_code instead.
The possible values are:
- AUTHORIZATION. Authorization.
Read only.
protection_eligibility
enum
The level of seller protection present for the transaction. Supported for the PayPal payment method only.
The possible values are:
- 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.
Read only.
protection_eligibility_type
enum
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.
The possible values are:
- 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.
Read only.
fmf_details
object
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.
Read only.
processor_response
object
The processor-provided response codes that describe the submitted payment. Supported only when the payment_method is credit_card.
valid_until
string
The date and time when the authorization expires, in Internet date and time format.
Read only.
create_time
string
The date and time when the authorization was created, in Internet date and time format.
Read only.
update_time
string
The date and time when the authorization was last updated, in Internet date and time format.
Read only.
receipt_id
string
The receipt ID, which identifies the payment. Value is 16-digit numeric payment ID number that is returned for guest users.
Read only.
Pattern: ^[0-9]{4}-[0-9]{4}-[0-9]{4}-[0-9]{4}$.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
Read only.

bic

bic
string
The business identification code (BIC). In payments systems, a BIC is used to identify a specific business, most commonly a bank
Minimum length: 8.
Maximum length: 11.

capture

id
string
The ID of the capture transaction.
Read only.
amount
object
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.
is_final_capture
boolean
Indicates whether to release all remaining held funds.
state
enum
The state of the capture.
The possible values are:
- 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.
Read only.
reason_code
enum
The reason code that describes why the transaction state is pending or reversed.
The possible values are:
- 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.
Read only.
parent_payment
string
The ID of the payment on which this transaction is based.
Read only.
invoice_number
string
The invoice number to track this payment.
Maximum length: 127.
transaction_fee
object
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.
Read only.
transaction_fee_in_receivable_currency
object
The currency and amount of the PayPal fee for this payment in the receivable currency. Returned only in cases the fee is charged in the receivable currency. Example 'CNY'. Would not be returned for 'pending' transactions where the funds have not been realized in the payee account.
Read only.
receivable_amount
object
The net amount and currency that the merchant receives for this transaction in the receivable currency.
Read only.
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.
Read only.
note_to_payer
string
A free-form field that clients can use to send a note to the payer.
Maximum length: 255.
create_time
string
The date and time of the capture, in Internet date and time format.
Read only.
update_time
string
The date and time when the resource was last updated, in Internet date and time format.
Read only.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
Read only.

card_brand

card_brand
enum
The card network or brand. Applies to credit, debit, gift, and payment cards.
The possible values are:
- 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.
Minimum length: 1.
Maximum length: 255.
Pattern: ^[A-Z_]+$.

cart_base

reference_id
string
The merchant-provided ID for the purchase unit.
Maximum length: 256.
amount
object
required
The amount to collect.
payee
object
The payee who receives the funds and fulfills the order.
description
string
The purchase description.
Maximum length: 127.
note_to_payee
string
The note to the recipient of the funds in this transaction.
Maximum length: 255.
custom
string
The free-form field for the client's use.
Maximum length: 127.
invoice_number
string
The invoice number to track this payment.
Maximum length: 127.
soft_descriptor
string
The payment descriptor on account transactions on the customer's credit card statement, that PayPal sends to processors. The maximum length of the soft descriptor information that you can pass in the API field is 22 characters, in the following format:
```
22 - len(PAYPAL * (8)) - len(Descriptor in Payment Receiving Preferences of Merchant account + 1)
```
The PAYPAL prefix uses 8 characters.

The soft descriptor supports the following ASCII characters:
- Alphanumeric characters
- Dashes
- Asterisks
- Periods (.)
- Spaces
For Wallet payments marketplace integrations:
- The merchant descriptor in the Payment Receiving Preferences must be the marketplace name.
- You can't use the remaining space to show the customer service number.
- The remaining spaces can be a combination of seller name and country.
For unbranded payments (Direct Card) marketplace integrations, use a combination of the seller name and phone number.
Maximum length: 22.
payment_options
object
The payment options for this transaction.
item_list
object
An array of items that are being purchased.
notify_url
string
The send payment notifications URL.
Maximum length: 2048.
order_url
string
The payment-related URL on the merchant site.
Maximum length: 2048.

country_code

country_code
string
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.
Minimum length: 2.
Maximum length: 2.
Pattern: ^([A-Z]{2}|C2)$.

country_code

country_code
string
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.
Minimum length: 2.
Maximum length: 2.
Pattern: ^([A-Z]{2}|C2)$.

credit_card

number
string
required
The credit card number. Value is numeric characters only with no spaces or punctuation. Must conform to the modulo and length required by each credit card type. Redacted in responses.
type
string
required
The credit card type. Value is visa, mastercard, discover, or amex. Do not use these lowercase values for display.
expire_month
integer
required
The expiration month with no leading zero. Value is from 1 to 12.
expire_year
integer
required
The four-digit expiration year.
cvv2
string
The three- to four-digit card validation code.
first_name
string
The card holder's first name.
last_name
string
The card holder's last name.
billing_address
object
The billing address for this card.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
Read only.

credit_card_token

credit_card_id
string
required
The ID of credit card that is stored in the PayPal vault.
payer_id
string
A unique ID that you can assign and track when you store a credit card in the vault or use a vaulted credit card. This ID can help to avoid unintentional use or misuse of credit cards and can be any value, such as a UUID, user name, or email address. Required when you use a vaulted credit card and if a payer_id was originally provided when you vaulted the credit card.
last4
string
The last four digits of the stored credit card number.
Read only.
type
string
The credit card type. Value is visa, mastercard, discover, or amex. Do not use these lowercase values for display.
Read only.
expire_month
integer
The expiration month with no leading zero. Value is from 1 to 12.
Read only.
expire_year
integer
The four-digit expiration year.
Read only.

currency

currency
string
required
The three-character ISO-4217 currency code. PayPal does not support all currencies.
value
string
required
The amount. Includes the specified number of digits after decimal separator for the ISO-4217 currency code.

currency_code

currency_code
string
The three-character ISO-4217 currency code that identifies the currency.
Minimum length: 3.
Maximum length: 3.

currency_code

currency_code
string
The three-character ISO-4217 currency code that identifies the currency.
Minimum length: 3.
Maximum length: 3.

currency_conversion

conversion_date
string
The date and time when the conversion rate becomes no longer valid, in Internet date and time format.
Read only.
from_currency
string
required
The three-character ISO-4217 currency code of the currency from which to convert the from amount.
Read only.
from_amount
string
required
The from amount, which is the pre-currency conversion value.
Read only.
Minimum value: 1.
to_currency
string
required
The three-character ISO-4217 currency code of the currency into which to convert the from amount.
Read only.
to_amount
string
required
The to amount, which is the post-currency conversion value.
Read only.
conversion_type
enum
The conversion type to apply.
The possible values are:
- PAYPAL. PayPal conversion type.
- VENDOR. Vendor conversion type.
conversion_type_changeable
boolean
Indicates whether the payer can change the conversion type.
Read only.
spread
string
The rate, as a percentage, that PayPal charges above the foreign exchange rate provided by PayPal’s financial partners.
Read only.
Maximum value: 100.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
Read only.

date_year_month

date_year_month
string
The year and month, in ISO-8601 YYYY-MM date format. See Internet date and time format.
Minimum length: 7.
Maximum length: 7.
Pattern: ^[0-9]{4}-(0[1-9]|1[0-2])$.

detailed_refund

id
string
The ID of the refund transaction.
Maximum length: 17.
amount
object
The refund amount. Includes both the amount refunded to the payer and the fee refunded to the payee.
state
string
The state of the refund.
reason
string
The reason that the transaction is being refunded.
invoice_number
string
Your own invoice or tracking ID number. Value is a string of single-byte alphanumeric characters.
Maximum length: 127.
sale_id
string
The ID of the sale transaction being refunded.
capture_id
string
The ID of the sale transaction being refunded.
parent_payment
string
The ID of the payment on which this transaction is based.
description
string
The refund description.
create_time
string
The date and time when the refund was created, in Internet date and time format.
update_time
string
The date and time when the resource was last updated, in Internet date and time format.
links
array (contains the link_description object)
An array of request-related HATEOAS links.

custom
string
The note to the payer in this transaction.
Maximum length: 127.
invoice_number
string
The invoice number to track this payment.
Maximum length: 127.
refund_from_transaction_fee
object
The currency and amount of the transaction fee that is refunded to original the recipient of payment.
refund_from_received_amount
object
The currency and amount of the refund that is subtracted from the original payment recipient's PayPal balance.
total_refunded_amount
object
The currency and amount of the total refund from the original purchase. For example, if a payer makes $100 purchase and the payer was refunded $20 a week ago and $30 in this transaction, the gross refund amount is $30 for this transaction and the total refunded amount is $50.

details

subtotal
string
The subtotal amount for the items. If the request includes line items, this property is required. Maximum length is 10 characters, which includes:
- Seven digits before the decimal point.
- The decimal point.
- Two digits after the decimal point.
Note: For an order authorization or capture, you cannot include the subtotal parameter.
shipping
string
The shipping fee. Maximum length is 10 characters, which includes:
- Seven digits before the decimal point.
- The decimal point.
- Two digits after the decimal point.
Note: For an order authorization or capture, you cannot include the shipping parameter.
tax
string
The tax. Maximum length is 10 characters, which includes:
- Seven digits before the decimal point.
- The decimal point.
- Two digits after the decimal point.
Note: For an order authorization or capture, you cannot include the tax parameter.
handling_fee
string
The handling fee. Maximum length is 10 characters, which includes:
- Seven digits before the decimal point.
- The decimal point.
- Two digits after the decimal point.
Supported for the PayPal payment method only.
Note: For an order authorization or capture, you cannot include the handling_fee parameter.
shipping_discount
string
The shipping fee discount. Maximum length is 10 characters, which includes:
- Seven digits before the decimal point.
- The decimal point.
- Two digits after the decimal point.
Supported for the PayPal payment method only.
Note: For an order authorization or capture, you cannot include the shipping_discount parameter.
insurance
string
The insurance fee. Maximum length is 10 characters, which includes:
- Seven digits before the decimal point.
- The decimal point.
- Two digits after the decimal point.
Supported only for the PayPal payment method.
Note: For an order authorization or capture, you cannot include the insurance parameter.
gift_wrap
string
The gift wrap fee. Maximum length is 10 characters, which includes:
- Seven digits before the decimal point.
- The decimal point.
- Two digits after the decimal point.
Note: For an order authorization or capture, you cannot include the gift_wrap parameter.

email_address

email_address
string
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.
Minimum length: 3.
Maximum length: 254.
Pattern: ^.+@[^"\-].+$.

email_address

email_address
string
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.
Minimum length: 3.
Maximum length: 254.
Pattern: ^.+@[^"\-].+$.

error

name
string
required
The human-readable, unique name of the error.
message
string
required
The message that describes the error.
debug_id
string
required
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.
Read only.
details
array (contains the error_details object)
An array of additional details about the error.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
Read only.

error_details

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
The location of the field that caused the error. Value is body, path, or query.
issue
string
required
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.

error_details

field
string
required
The name of the field that caused the error.
issue
string
required
The reason for the error.

fmf_details

filter_type
enum
required
The filter type.
The possible values are:
- ACCEPT. The accept filter type.
- PENDING. The pending filter type.
- DENY. The deny filter type.
- REPORT. The report filter type.
Read only.
filter_id
enum
required
The filter ID.
The possible values are:
- AVS_NO_MATCH. AVS no match.
- AVS_PARTIAL_MATCH. AVS partial match.
- AVS_UNAVAILABLE_OR_UNSUPPORTED. AVS unavailable or unsupported.
- CARD_SECURITY_CODE_MISMATCH. Card security code mismatch.
- MAXIMUM_TRANSACTION_AMOUNT. The maximum transaction amount.
- UNCONFIRMED_ADDRESS. Unconfirmed address.
- COUNTRY_MONITOR. Country monitor.
- LARGE_ORDER_NUMBER. Large order number.
- BILLING_OR_SHIPPING_ADDRESS_MISMATCH. Billing or shipping address mismatch.
- RISKY_ZIP_CODE. Risky zip code.
- SUSPECTED_FREIGHT_FORWARDER_CHECK. Suspected freight forwarder check.
- TOTAL_PURCHASE_PRICE_MINIMUM. Total purchase price minimum.
- IP_ADDRESS_VELOCITY. IP address velocity.
- RISKY_EMAIL_ADDRESS_DOMAIN_CHECK. Risky email address domain check.
- RISKY_BANK_IDENTIFICATION_NUMBER_CHECK. Risky bank identification number check.
- RISKY_IP_ADDRESS_RANGE. Risky IP address range.
- PAYPAL_FRAUD_MODEL. PayPal fraud model.
Read only.
name
string
The filter name.
Read only.
description
string
The filter description.
Read only.

funding_detail

clearing_time
string
The date and time when the funds are expected to clear, in Internet date and time format.
Read only.
payment_hold_date
string
Deprecated. The date and time when the payment will no longer be held, in Internet date and time format. Instead, use the payment_debit_date.
Read only.
payment_debit_date
string
The date and time when the funds will be debited from the payer's account, in Internet date and time format.
Read only.
processing_type
enum
The processing type of the payment card.
The possible values are:
- CUP_SECURE. CUP secure.
- PINLESS_DEBIT. Pinless debit.
Read only.

funding_instrument

credit_card
object
Deprecated. The credit card details. You can use this instrument to fund a payment. Use a payment card instead.
credit_card_token
object
The tokenized credit card details. You can use this instrument to fund a payment.

funding_source

credit_card
object
Deprecated. The credit card details. You can use this instrument to fund a payment. Use a payment card instead.
credit_card_token
object
The tokenized credit card details. You can use this instrument to fund a payment.

funding_mode
string
required
The funding mode of the funding source.
funding_instrument_type
string
required
The instrument type for this funding source.
soft_descriptor
string
The soft descriptor for charging this funding source.
Maximum length: 22.
amount
object
required
The amount and currency of the total to pull from the funding source.
negative_balance_amount
object
The additional amount to pull from the source to recover a negative balance on the buyer's account that is owed to PayPal.
legal_text
string
The localized legal text for the funding source.
terms
string
The legal terms for the funding source URL.
funding_detail
object
The additional details for the funding source.
funding_selection_preference
string
The preferred way to select this funding source.
additional_text
string
Additional text for the funding source.
links
array (contains the link_description object)
An array of request-related HATEOAS links.

installment_info

installment_id
string
The installment ID.
Read only.
network
enum
The credit card network.
The possible values are:
- VISA. Visa.
- MASTERCARD. Mastercard.
Read only.
issuer
string
The credit card issuer.
Read only.
installment_options
array (contains the installment_option object)
required
An array of installment options and the cost associated with each one.

installment_option

term
integer
required
The number of installments.
monthly_payment
object
required
The amount and currency of the monthly payment.
discount_amount
object
The amount and currency of the discount applied to the payment, if any.
discount_percentage
string
The discount percentage applied to the payment, if any.
Pattern: ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$.

item

sku
string
The stock keeping unit (SKU) for the item.
Maximum length: 127.
name
string
The item name. If this value is greater than the maximum allowed length, the API truncates the string.
Maximum length: 127.
description
string
The item description. Supported for only the PayPal payment method.
Maximum length: 127.
quantity
string
required
The item quantity. Must be a whole number.
Maximum length: 10.
Pattern: ^[0-9]{0,10}$.
price
string
required
The item cost. Supports two decimal places.
Maximum length: 10.
Pattern: ^[0-9]{0,10}(\.[0-9]{0,2})?$.
currency
string
required
The three-character ISO-4217 currency code that identifies the currency.
Minimum length: 3.
Maximum length: 3.
tax
string
The item tax. Supported only for the PayPal payment method.

item_list

items
array (contains the item object)
An array of items that are being purchased.
shipping_address
object
The shipping address details.
shipping_phone_number
string
The shipping phone number, in its canonical international format as defined by the E.164 numbering plan. Enables merchants to share payer’s contact number with PayPal for the current payment. The final contact number for the payer who is associated with the transaction might be the same as or different from the shipping_phone_number based on the payer’s action on PayPal.
Minimum length: 1.
Maximum length: 50.

link_description

href
string
required
The complete target URL. To make the related call, combine the method with this URI Template-formatted link. For pre-processing, include the $, (, and ) characters. The href is the key HATEOAS component that links a completed call with a subsequent call.
rel
string
required
The link relation type, which serves as an ID for a link that unambiguously describes the semantics of the link. See Link Relations.
method
enum
The HTTP method required to make the related call.
Possible values: GET,POST,PUT,DELETE,HEAD,CONNECT,OPTIONS,PATCH.

merchant_partner_customer_id

merchant_partner_customer_id
string
The unique ID for a customer in merchant's or partner's system of records.
Minimum length: 1.
Maximum length: 22.
Pattern: ^[0-9a-zA-Z_-]+$.

money

currency_code
string
required
The three-character ISO-4217 currency code that identifies the currency.
value
string
required
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.
Maximum length: 32.
Pattern: ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$.

money

currency_code
string
required
The three-character ISO-4217 currency code that identifies the currency.
Minimum length: 3.
Maximum length: 3.
value
string
required
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.
Maximum length: 32.
Pattern: ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$.

name

name
string
The full name representation like Mr J Smith
Minimum length: 3.
Maximum length: 300.

name

prefix
string
The prefix, or title, to the party's name.
Maximum length: 140.
given_name
string
When the party is a person, the party's given, or first, name.
Maximum length: 140.
surname
string
When the party is a person, the party's surname or family name. Also known as the last name. Required when the party is a person. Use also to store multiple surnames including the matronymic, or mother's, surname.
Maximum length: 140.
middle_name
string
When the party is a person, the party's middle name. Use also to store multiple middle names including the patronymic, or father's, middle name.
Maximum length: 140.
suffix
string
The suffix for the party's name.
Maximum length: 140.
alternate_full_name
string
DEPRECATED. The party's alternate name. Can be a business name, nickname, or any other name that cannot be split into first, last name. Required when the party is a business.
Maximum length: 300.
full_name
string
When the party is a person, the party's full name.
Maximum length: 300.

name_validation

name_validation

name_validation

name_validation

network_transaction_reference

id
string
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.
Minimum length: 9.
Maximum length: 15.
Pattern: ^[a-zA-Z0-9]+$.
date
string
The date that the transaction was authorized by the scheme. For MasterCard, this is the "BankNet reference date" field in response.
Minimum length: 4.
Maximum length: 4.
Pattern: ^[0-9]+$.
network
enum
Name of the card network through which the transaction was routed.
The possible values are:
- 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.

order

id
string
The ID of the order transaction.
Read only.
amount
object
required
The amount to collect.
Note: For an order authorization, you cannot include amount details.
payment_mode
enum
The transaction payment mode.
The possible values are:
- INSTANT_TRANSFER. The payment mode is instant transfer.
- MANUAL_BANK_TRANSFER. The payment mode is manual bank transfer.
- DELAYED_TRANSFER. The payment mode is delayed transfer.
- ECHECK. The payment mode is eCheck.
Read only.
state
enum
The state of the order transaction.
The possible values are:
- PENDING. The order was created but no authorizations or captures were made against the order.
- AUTHORIZED. The order has only been authorized. No capture was made against the order.
- CAPTURED. The order has at least one capture initiated.
- COMPLETED. The order is complete. A capture was made against the order with is_final_capture set to TRUE. No more authorizations or captures can be made against this order.
- VOIDED. The order was voided. No more authorizations or captures can be made against this order.
Read only.
reason_code
enum
The reason code that describes why the transaction state is pending or reversed. Supported only for PayPal payments.
The possible values are:
- PAYER_SHIPPING_UNCONFIRMED. The shipping address of the payer is not confirmed.
- MULTI_CURRENCY. The transaction is in multiple currencies.
- RISK_REVIEW. The transaction is under risk review.
- REGULATORY_REVIEW. The transaction is under regulatory review.
- VERIFICATION_REQUIRED. Verification is required.
- ORDER. The transaction is an order.
- OTHER. Other.
Read only.
pending_reason
enum
Deprecated. The reason code for the pending transaction state. Obsolete. Use reason_code instead.
Read only.
Possible values: payer_shipping_unconfirmed,multi_currency,risk_review,regulatory_review,verification_required,order,other.
protection_eligibility
enum
The level of seller protection in effect for the transaction.
The possible values are:
- ELIGIBLE. The transaction is eligible for seller protection.
- PARTIALLY_ELIGIBLE. The transaction is partially eligible for seller protection.
- INELIGIBLE. The transaction is ineligible for seller protection.
Read only.
protection_eligibility_type
enum
The kind of seller protection in effect for the transaction. Returned only when the protection_eligibility property is ELIGIBLE or PARTIALLY_ELIGIBLE. Supported only for PayPal payments.
The possible values are:
- 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 claims for unauthorized payments.
Read only.
parent_payment
string
The ID of the payment on which this transaction is based.
Read only.
fmf_details
object
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.
create_time
string
The date and time when the resource was created, in Internet date and time format.
Read only.
update_time
string
The date and time when the resource was last updated, in Internet date and time format.
Read only.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
Read only.

patch

`op`

enum

required

The operation.

The possible values are:

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:

Type	Considered equal if both values
strings	Contain the same number of Unicode characters and their code points are byte-by-byte equal.
numbers	Are numerically equal.
arrays	Contain 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.
objects	Contain 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
number,integer,string,boolean,null,array,object
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.

patch_request

patch_request
array (contains the patch object)
An array of JSON patch objects to apply partial updates to resources.

payee

email
string
The email address associated with the payee's PayPal account. For an intent of authorize or order, the email address must be associated with a confirmed PayPal business account. For an intent of sale, the email can either:
- Be associated with a confirmed PayPal personal or business account.
- Not be associated with a PayPal account.
merchant_id
string
The PayPal account ID for the payee.

payer

payment_method
enum
The payment method.
The possible values are:
- credit_card. Credit card.
- paypal. A PayPal Wallet payment.
- pay_upon_invoice. Pay upon invoice.
- carrier. Carrier.
- alternate_payment. Alternate payment.
- bank. Bank.
status
enum
The status of payer's PayPal account.
The possible values are:
- VERIFIED.
- UNVERIFIED.
Read only.
funding_instruments
array (contains the funding_instrument object)
An array of a single funding instrument for the current payment. Valid only and required for the credit card payment method. The array must include either a credit_card or credit_card_token object. If the array contains more than one instrument, the payment is declined.
payer_info
object
The payer information.

payer_info

email
string
The payer's email address. Maximum length is 127 characters.
salutation
string
The payer's salutation.
Read only.
first_name
string
The payer's first name.
Read only.
middle_name
string
The payer's middle name.
Read only.
last_name
string
The payer's last name.
Read only.
suffix
string
The payer's suffix.
Read only.
payer_id
string
The PayPal-assigned encrypted payer ID.
Read only.
birth_date
string
The birth date of the payer, in Internet date format. For example, 1990-04-12.
tax_id
string
The payer's tax ID. Supported for the PayPal payment method only.
Maximum length: 14.
tax_id_type
enum
The payer's tax ID type. Supported for the PayPal payment method only.
The possible values are:
- BR_CPF. BR CPF tax ID type.
- BR_CNPJ. BR CNPJ tax ID type.
billing_address
object
The payer's billing address.
shipping_address
Deprecated. The shipping address. Use the shipping address for the purchase unit or at the root level of the checkout session.
Read only.

payment

id
string
The ID of the payment.
Read only.
intent
enum
required
The payment intent. Value is:
- sale. Makes an immediate payment.
- authorize. Authorizes a payment for capture later.
- order. Creates an order.
Possible values: sale,authorize,order.
payer
object
required
The source of the funds for this payment. Payment method is PayPal Wallet payment or bank direct debit.
application_context
object
Use the application context resource to customize payment flow experience for your buyers.
transactions
array (contains the transaction object)
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.
state
enum
The state of the payment, authorization, or order transaction. Value is:
- created. The transaction was successfully created.
- approved. The customer approved the transaction. The state changes from created to approved on generation of the sale_id for sale transactions, authorization_id for authorization transactions, or order_id for order transactions.
- failed. The transaction request failed.
Read only.
Possible values: created,approved,failed.
experience_profile_id
string
The PayPal-generated ID for the merchant's payment experience profile. For information, see create web experience profile.
note_to_payer
string
A free-form field that clients can use to send a note to the payer.
Maximum length: 165.
redirect_urls
object
A set of redirect URLs that you provide for PayPal-based payments.
failure_reason
enum
The reason code for a payment failure.
Read only.
Possible values: UNABLE_TO_COMPLETE_TRANSACTION,INVALID_PAYMENT_METHOD,PAYER_CANNOT_PAY,CANNOT_PAY_THIS_PAYEE,REDIRECT_REQUIRED,PAYEE_FILTER_RESTRICTIONS.
create_time
string
The date and time when the payment was created, in Internet date and time format.
Read only.
update_time
string
The date and time when the payment was updated, in Internet date and time format.
Read only.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
Read only.

payment_execution

payer_id
string
The ID of the payer that PayPal passes in the return_url.
transactions
array (contains the cart_base object)
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.

payment_history

payments
array (contains the payment object)
An array of payments that are complete. Payments that you just created with the create payment call do not appear in the list.
count
integer
The number of items returned in each range of results. Note that the last results range might have fewer items than the requested number of items.
Maximum value: 20.
next_id
string
The ID of the element to use to get the next range of results.
Read only.

payment_hold_reason

payment_hold_reason
enum
The reason that PayPal holds the recipient fund. Set only if the payment hold status is HELD.
Possible values: PAYMENT_HOLD,SHIPPING_RISK_HOLD.

payment_initiator

payment_initiator
enum
The person or party who initiated or triggered the payment.
The possible values are:
- 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.
Minimum length: 1.
Maximum length: 255.
Pattern: ^[0-9A-Z_]+$.

payment_options

allowed_payment_method
enum
The payment method for this transaction. This field does not apply to the credit card payment method.
The possible values are:
- UNRESTRICTED. Merchant does not have a preference on how they want the customer to pay.
- INSTANT_FUNDING_SOURCE. Merchant requires that the customer pays with an instant funding source, such as a credit card or PayPal balance. All payments are processed instantly. However, payments that require a manual review are marked as pending. Merchants must handle the pending state as if the payment is not yet complete.
- IMMEDIATE_PAY. Processes all payments immediately. Any payment that requires a manual review is marked failed.

payment_pattern

payment_pattern
enum
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.
The possible values are:
- 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.
Minimum length: 3.
Maximum length: 255.
Pattern: ^[A-Z_]+$.

payment_source

token
object
The tokenized payment source to fund a payment.

percentage

percentage
string
The percentage as a fixed-point, signed decimal value. Use for all interest rates. For example, specify an interest rate of 19.99% as 19.99. The allowed number formats are plain decimal numbers and whole numbers.
Pattern: ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$.

processor_response

response_code
string
required
The PayPal normalized response code, which is generated from the processor's specific response code.
Read only.
Maximum length: 4.
avs_code
string
The Address Verification System (AVS) response code.
Read only.
Maximum length: 1.
Pattern: [A-z0-9]{1}.
cvv_code
string
The CVV system response code.
Read only.
Maximum length: 1.
Pattern: [A-z0-9]{1}.
advice_code
enum
The merchant advice on how to handle declines for recurring payments.
The possible values are:
- 01_NEW_ACCOUNT_INFORMATION. 01 New account information.
- 02_TRY_AGAIN_LATER. 02 Try again later.
- 02_STOP_SPECIFIC_PAYMENT. 02 Stop specific payment.
- 03_DO_NOT_TRY_AGAIN. 03 Do not try again.
- 03_REVOKE_AUTHORIZATION_FOR_FUTURE_PAYMENT. 03 Revoke authorization for future payment.
- 21_DO_NOT_TRY_AGAIN_CARD_HOLDER_CANCELLED_RECURRRING_CHARGE. 21 Do not try again. Card holder cancelled recurring charge.
- 21_CANCEL_ALL_RECURRING_PAYMENTS. 21 Cancel all recurring payments.
Read only.
eci_submitted
string
The processor-provided authorization response.
Read only.
vpas
string
The processor-provided Visa Payer Authentication Service (VPAS) status.
Read only.

redirect_urls

return_url
string
The URL where the payer is redirected after he or she approves the payment. Required for PayPal account payments.
cancel_url
string
The URL where the payer is redirected after he or she cancels the payment. Required for PayPal account payments.

refund

id
string
The ID of the refund transaction. Maximum length is 17 characters.
Read only.
amount
object
The refund amount. Includes both the amount refunded to the payer and amount of the fee refunded to the payee.
state
enum
The state of the refund.
The possible values are:
- pending. The refund state is pending.
- completed. The refund state is completed.
- cancelled. The refund state is cancelled.
- failed. The refund state is failed.
Read only.
reason
string
The reason that the transaction is being refunded.
invoice_number
string
The invoice or tracking ID number.
Maximum length: 127.
sale_id
string
The ID of the sale transaction being refunded.
Read only.
capture_id
string
The ID of the sale transaction being refunded.
Read only.
parent_payment
string
The ID of the payment on which this transaction is based.
Read only.
description
string
The refund description. Value must be single-byte alphanumeric characters.
create_time
string
The date and time when the refund was created, in Internet date and time format.
Read only.
update_time
string
The date and time when the resource was last updated, in Internet date and time format.
Read only.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
Read only.

refund_request

amount
object
The refund amount. Includes both the amount to refund to the payer and the fee amount to refund to the payee.
description
string
The refund description. Value is a string of single-byte alphanumeric characters.
Maximum length: 255.
reason
string
The refund reason description.
Maximum length: 30.
invoice_number
string
The invoice number that tracks this payment. Value is a string of single-byte alphanumeric characters.
Maximum length: 127.

refund_transaction_details

id
string
The ID of the refund transaction.
Read only.
Maximum length: 17.
amount
object
The refund amount. Includes both the amount refunded to the payer and the fee refunded to the payee.
state
enum
The state of the refund.
Read only.
Possible values: pending,completed,cancelled,failed.
reason
string
The reason that the transaction is being refunded.
invoice_number
string
Your own invoice or tracking ID number. Value is a string of single-byte alphanumeric characters.
Maximum length: 127.
sale_id
string
The ID of the sale transaction being refunded.
Read only.
capture_id
string
The ID of the sale transaction being refunded.
Read only.
parent_payment
string
The ID of the payment on which this transaction is based.
Read only.
description
string
The refund description.
create_time
string
The date and time when the refund was created, in Internet date and time format.
Read only.
update_time
string
The date and time when the resource was last updated, in Internet date and time format.
Read only.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
Read only.

related_resources

sale
object
The sale transaction details.
authorization
object
The authorization details.
order
object
The order transaction details.
capture
object
The capture transaction details.
refund
object
The refund details.

sale

id
string
required
The ID of the sale transaction.
Read only.
amount
object
required
The amount to collect.
payment_mode
enum
The transaction payment mode. Supported only for PayPal payments.
Read only.
Possible values: INSTANT_TRANSFER,MANUAL_BANK_TRANSFER,DELAYED_TRANSFER,ECHECK.
state
enum
required
The state of the sale transaction.
Read only.
Possible values: completed,partially_refunded,pending,refunded,denied.
reason_code
enum
A reason code that describes why the transaction state is pending or reversed. Supported only for PayPal payments.
Read only.
Possible values: CHARGEBACK,GUARANTEE,BUYER_COMPLAINT,REFUND,UNCONFIRMED_SHIPPING_ADDRESS,ECHECK,INTERNATIONAL_WITHDRAWAL,RECEIVING_PREFERENCE_MANDATES_MANUAL_ACTION,PAYMENT_REVIEW,REGULATORY_REVIEW,UNILATERAL,VERIFICATION_REQUIRED,TRANSACTION_APPROVED_AWAITING_FUNDING.
protection_eligibility
enum
The merchant protection level in effect for the transaction. Supported only for PayPal payments.
Read only.
Possible values: ELIGIBLE,PARTIALLY_ELIGIBLE,INELIGIBLE.
protection_eligibility_type
enum
The merchant protection type in effect for the transaction. Returned only when protection_eligibility is ELIGIBLE or PARTIALLY_ELIGIBLE. Supported only for PayPal payments.
Read only.
Possible values: ITEM_NOT_RECEIVED_ELIGIBLE,UNAUTHORIZED_PAYMENT_ELIGIBLE,ITEM_NOT_RECEIVED_ELIGIBLE,UNAUTHORIZED_PAYMENT_ELIGIBLE.
clearing_time
string
The date and time when the PayPal eCheck transaction is expected to clear, in Internet date and time format.
Read only.
payment_hold_status
enum
The recipient fund status. Returned only when the fund status is held.
Read only.
Possible values: HELD.
payment_hold_reasons
array (contains the payment_hold_reason object)
An array of reasons that PayPal holds the recipient fund. Set only if the payment hold status is HELD.
Read only.
transaction_fee
object
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.
Read only.
receivable_amount
object
The currency and amount of the net that the merchant receives for this transaction in their receivable currency. Returned only in cross-currency use cases where a merchant bills a buyer in a non-primary currency for that buyer.
transaction_fee_in_receivable_currency
object
The currency and amount of the PayPal fee for this payment in the receivable currency. Returned only in cases the fee is charged in the receivable currency. Example 'CNY'. Would not be returned for 'pending' transactions where the funds have not been realized in the payee account.
Read only.
exchange_rate
string
The exchange rate for this transaction. Returned only in cross-currency use cases where a merchant bills a buyer in a non-primary currency for that buyer.
Read only.
fmf_details
object
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.
receipt_id
string
The receipt ID, which is a payment ID number that is returned for guest users to identify the payment.
Read only.
Pattern: ^[0-9]{4}-[0-9]{4}-[0-9]{4}-[0-9]{4}$.
parent_payment
string
required
The ID of the payment on which this transaction is based.
Read only.
processor_response
object
The processor-provided response codes that describe the submitted payment. Supported only when the payment_method is credit_card.
billing_agreement_id
string
The ID of the billing agreement. Used as reference to execute this transaction.
Read only.
create_time
string
required
The date and time of the sale, in Internet date and time format.
Read only.
update_time
string
The date and time when the resource was last updated, in Internet date and time format.
Read only.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
Read only.

shipping_address

line1
string
required
The first line of the address. For example, number, street, and so on.
Maximum length: 300.
line2
string
The second line of the address. For example, suite or apartment number.
Maximum length: 300.
city
string
The city name.
Maximum length: 64.
country_code
string
required
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.
Minimum length: 2.
Maximum length: 2.
Pattern: ^([A-Z]{2}|C2)$.
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
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. Maximum length is 40 single-byte characters.
phone
string
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.
type
string
The type of address. For example, HOME_OR_WORK, GIFT, and so on.

recipient_name
string
The name of the recipient at this address.
Maximum length: 127.

shipping_type

shipping_type
enum
The method by which the payer wants to get their items.
The possible values are:
- SHIPPING. The payer intends to receive the items at a specified address.
- PICKUP. The payer intends to pick up the items at a specified address. For example, a store address.

shipping_type

shipping_type
enum
The method by which the payer wants to get their items.
The possible values are:
- SHIPPING. The payer intends to receive the items at a specified address.
- PICKUP. The payer intends to pick up the items at a specified address. For example, a store address.

stored_payment_source_payment_type

stored_payment_source_payment_type
enum
Indicates the type of the stored payment_source payment.
The possible values are:
- 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).
Minimum length: 1.
Maximum length: 255.
Pattern: ^[0-9A-Z_]+$.

stored_payment_source_usage_type

stored_payment_source_usage_type
enum
Indicates if this is a first or subsequent payment using a stored payment source (also referred to as stored credential or card on file).
The possible values are:
- 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.
Minimum length: 1.
Maximum length: 255.
Pattern: ^[0-9A-Z_]+$.

token

id
string
required
The PayPal-generated ID for the token.
Minimum length: 1.
Maximum length: 255.
type
enum
required
The tokenization method that generated the ID.
The possible values are:
- BILLING_AGREEMENT. The PayPal billing agreement ID. References an approved recurring payment for goods or services.
Minimum length: 1.
Maximum length: 255.
Pattern: ^[0-9A-Z_-]+$.

transaction

amount
object
The amount to collect.
payee
object
The payee who receives the funds and fulfills the order.
description
string
The purchase description.
Maximum length: 127.
note_to_payee
string
The note to the recipient of the funds in this transaction.
Maximum length: 255.
custom
string
The free-form field for the client's use.
Maximum length: 127.
invoice_number
string
The invoice number to track this payment.
Maximum length: 127.
soft_descriptor
string
The soft descriptor to use to charge this funding source. If greater than the maximum allowed length, the API truncates the string.
Maximum length: 22.
payment_options
object
The payment options for this transaction.
item_list
object
An array of items that are being purchased.
notify_url
string
The URL to send payment notifications.
Maximum length: 2048.
related_resources
array (contains the related_resources object)
An array of payment-related transactions. A transaction defines what the payment is for and who fulfills the payment.
Read only.

Error messages

In addition to the common HTTP status codes that the REST APIs return, the Payments API can return the following errors.

AGREEMENT_ALREADY_CANCELLED
The requested agreement is already canceled.
AMOUNT_MISMATCH
The totals of the cart item amounts do not match sale amounts.
AUTH_SETTLE_NOT_ALLOWED
Authorization and Capture feature is not enabled for the merchant.
AUTHORIZATION_ALREADY_COMPLETED
Capture refused - this authorization has already been completed.
AUTHORIZATION_AMOUNT_LIMIT_EXCEEDED
Authorization amount exceeds allowed order limit.
AUTHORIZATION_CANNOT_BE_VOIDED
Authorization is in x state and hence cannot be voided.
AUTHORIZATION_EXPIRED
Authorization has expired.
AUTHORIZATION_ID_DOES_NOT_EXIST
The requested authorization ID does not exist.
AUTHORIZATION_VOIDED
Authorization has been voided.
BA_TOKEN_CREATION_FAILED
Billing agreement token creation failed.
BANK_ACCOUNT_VALIDATION_FAILED
Bank account validation failed.
BILLING_AGREEMENT_CREATION_FAILED
Billing agreement creation failed.
BUYER_NOT_SET
Buyer is not yet set for this purchase.
CANNOT_PAY_SELF
Payer cannot pay him- or herself.
CANNOT_REAUTH_CHILD_AUTHORIZATION
Can only reauthorize the original authorization, not a reauthorization.
CANNOT_REAUTH_INSIDE_HONOR_PERIOD
Reauthorization is not allowed within the honor period.
CAPTURE_AMOUNT_LIMIT_EXCEEDED
Capture amount specified exceeded allowable limit.
CARD_TOKEN_PAYER_MISMATCH
payer_id does not match ID for this token.
COMPLIANCE_VIOLATION
Transaction is declined due to compliance violation.
CREDIT_CARD_CVV_CHECK_FAILED
The credit card CVV check failed.
CREDIT_CARD_REFUSED
Credit card was refused.
CREDIT_PAYMENT_NOT_ALLOWED
Buyer cannot use credit to complete the payment.
CURRENCY_MISMATCH
Currency provided in the request must match the currency of the parent order or authorization.
CURRENCY_NOT_ALLOWED
Currency is not 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.
DUPLICATE_REQUEST_ID
The value of PayPal-Request-Id header has already been used.
DUPLICATE_TRANSACTION
Duplicate invoice Id detected.
ERROR_AUTH
Unauthorized payment.
EXPIRED_CREDIT_CARD_TOKEN
Credit card token is expired.
FEATURE_UNSUPPORTED_FOR_PAYEE
This feature is unsupported.
FULL_REFUND_NOT_ALLOWED_AFTER_PARTIAL_REFUND
Full refund refused - partial refund has already been done on this payment.
IMMEDIATE_PAY_NOT_SUPPORTED
Immediate pay is not supported for the specified payment intent.
INSTRUMENT_DECLINED
The instrument presented was either declined by the processor or bank, or it can't be used for this payment.
INSUFFICIENT_FUNDS
Buyer cannot pay - insufficient funds.
INTERNAL_SERVICE_ERROR
An internal service error has occurred.
INVALID_ACCOUNT_NUMBER
Account number does not exist.
INVALID_CITY_STATE_ZIP
The combination of city, state, and zip in the address is invalid.
INVALID_EXPERIENCE_PROFILE_ID
The requested experience profile ID was not found.
INVALID_FACILITATOR_CONFIGURATION
This transaction cannot be processed due to an invalid facilitator configuration.
INVALID_PAYER_ID
Payer ID is invalid.
INVALID_RESOURCE_ID
The requested resource ID was not found.
MALFORMED_REQUEST
JSON request is malformed.
MAX_NUMBER_OF_PAYMENT_ATTEMPTS_EXCEEDED
You have exceeded the maximum number of payment attempts.
MAXIMUM_ALLOWED_AUTHORIZATION_REACHED_FOR_ORDER
You have reached the configured maximum number of authorizations allowed for an order.
MERCHANT_NOT_ENABLED_FOR_CHANNEL_INITIATED_BILLING
Merchant is not enabled for channel-initiated billing.
MERCHANT_NOT_ENABLED_FOR_REFERENCE_TRANSACTION
Merchant is not enabled for reference transaction.
NEED_CREDIT_CARD
Need credit card to complete the payment.
NEED_CREDIT_CARD_OR_BANK_ACCOUNT
Need bank or credit card to complete the payment.
NOT_IMPLEMENTED
Not implemented.
ORDER_ALREADY_COMPLETED
Order has already been voided, expired, or completed.
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.
ORDER_IS_EXPIRED
Order has expired.
ORDER_VOIDED
Order has been voided.
PAYEE_ACCOUNT_INVALID
Payee account is invalid.
PAYEE_ACCOUNT_LOCKED_OR_CLOSED
Payee account is locked or closed.
PAYEE_ACCOUNT_NO_CONFIRMED_EMAIL
Refused - payee account does not have a confirmed email.
PAYEE_ACCOUNT_RESTRICTED
Refused - payee account is restricted.
PAYEE_BLOCKED_TRANSACTION
The Fraud settings for this seller are such that this payment cannot be executed.
PAYEE_COUNTRY_NOT_ENABLED
Payee country is not enabled for this feature.
PAYER_ACCOUNT_LOCKED_OR_CLOSED
The payer account cannot be used for this transaction.
PAYER_ACCOUNT_RESTRICTED
The payer account is restricted.
PAYER_ACTION_REQUIRED
Transaction cannot complete successfully, instruct the buyer to return to PP.
PAYER_CANNOT_PAY
Payer cannot pay for this transaction.
PAYER_COUNTRY_NOT_ENABLED
Payer country is not enabled for this feature.
PAYER_EMPTY_BILLING_ADDRESS
Billing address is empty.
PAYER_ID_MISSING_FOR_CARD_TOKEN
payer_id is required for payments made with this token.
PAYMENT_ALREADY_DONE
Payment has been done already for this cart.
PAYMENT_APPROVAL_EXPIRED
Payment approval has expired.
PAYMENT_CANNOT_BE_INITIATED
Payment cannot be processed.
PAYMENT_DENIED
PayPal has declined to process this transaction.
PAYMENT_EXPIRED
The payment is expired.
PAYMENT_METHOD_UNUSABLE
Payer cannot pay with this payment method.
PAYMENT_NOT_APPROVED_FOR_EXECUTION
Payer has not approved payment.
PAYMENT_REQUEST_ID_INVALID
PayPal request ID is invalid. Please try a different one.
PAYMENT_STATE_INVALID
This request is invalid due to the current state of the payment.
PERMISSION_DENIED
No permission for the requested operation.
PHONE_NUMBER_REQUIRED
This transaction requires the payer to provide a valid phone number.
REAUTH_NOT_SUPPORTED_FOR_ORDER
Re-authorization is not allowed for this type of authorization.
REDIRECT_PAYER_FOR_ALTERNATE_FUNDING
Transaction failed. Redirect the payer to select another funding source.
REFUND_EXCEEDED_TRANSACTION_AMOUNT
Refund refused - the requested refund amount would exceed the amount of transaction being refunded.
REFUND_FAILED_INSUFFICIENT_FUNDS
Refund failed due to insufficient funds in your PayPal account.
REFUND_TIME_LIMIT_EXCEEDED
This transaction is too old to refund.
REQUESTED_OPERATION_REFUSED_DUE_TO_SELLER_OPT_OUT
You cannot perform this operation as payee has opted out on PayPal.com.
REQUIRED_SCOPE_MISSING
Access token does not have required scope.
SENDING_LIMIT_EXCEEDED
The transaction exceeds the buyer's sending limit.
SHIPPING_ADDRESS_INVALID
Provided shipping address is invalid.
TOO_MANY_REAUTHORIZATIONS
Maximum number of reauthorizations for this authorization has been reached.
TOO_MANY_SETTLEMENTS
Maximum number of allowable settlements has been reached. No more settlement for the authorization.
TRANSACTION_ALREADY_REFUNDED
Refund transaction refused - this transaction has already been refunded.
TRANSACTION_LIMIT_EXCEEDED
Total payment amount exceeded transaction limit.
TRANSACTION_RECEIVING_LIMIT_EXCEEDED
The transaction exceeds the receiver’s receiving limit.
TRANSACTION_REFUSED
This request was refused.
TRANSACTION_REFUSED_BY_PAYPAL_RISK
PayPal risk refused this transaction.
TRANSACTION_REFUSED_PAYEE_PREFERENCE
Merchant profile preference is set to automatically deny certain transactions.
UNAUTHORIZED_PAYMENT
Unauthorized payment.
UNSUPPORTED_PAYEE_COUNTRY
Payee country is not supported for this transaction.
UNSUPPORTED_PAYEE_CURRENCY
The currency is not accepted by payee.
VALIDATION_ERROR
Invalid request - see details.
BILLING_AGREEMENT_ID_MISMATCH
Billing Agreement ID must match the one that was provided during payment creation.
INVALID_PICKUP_ADDRESS
Invalid shipping address.
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.

PayPal Commerce Platform for Business

PayPal Commerce Platform for Marketplaces and Platforms

PayPal Commerce Platform for Enterprise

Docs Catalog

Reference

Developer Tools

Regional Codes

count

start_id

start_index

start_time

end_time

payee_id

sort_by

sort_order

Sample Request

payments

count

next_id

Sample Response

PayPal-Partner-Attribution-Id

id

intent

payer

application_context

transactions

state

experience_profile_id

note_to_payer

redirect_urls

failure_reason

create_time

update_time

links

Sample Request

id

intent

payer

application_context

transactions

state

experience_profile_id

note_to_payer

redirect_urls

failure_reason

create_time

update_time

links

Sample Response

payment_id

patch_request

Sample Request

id

intent

payer

application_context

transactions

state

experience_profile_id

note_to_payer

redirect_urls

failure_reason

create_time

update_time

links

Sample Response

payment_id

Sample Request

id

intent

payer

application_context

transactions

state

experience_profile_id

note_to_payer

redirect_urls

failure_reason

create_time

update_time

`count`

`start_id`

`start_index`

`start_time`

`end_time`

`payee_id`

`sort_by`

`sort_order`

`payments`

`count`

`next_id`

`PayPal-Partner-Attribution-Id`

`id`

`intent`

`payer`

`application_context`

`transactions`

`state`

`experience_profile_id`

`note_to_payer`

`redirect_urls`

`failure_reason`

`create_time`

`update_time`

`links`

`id`

`intent`

`payer`

`application_context`

`transactions`

`state`

`experience_profile_id`

`note_to_payer`

`redirect_urls`

`failure_reason`

`create_time`

`update_time`

`links`

`payment_id`

`patch_request`

`id`

`intent`

`payer`

`application_context`

`transactions`

`state`

`experience_profile_id`

`note_to_payer`

`redirect_urls`

`failure_reason`

`create_time`

`update_time`

`links`

`payment_id`

`id`

`intent`

`payer`

`application_context`

`transactions`

`state`

`experience_profile_id`

`note_to_payer`

`redirect_urls`

`failure_reason`

`create_time`

`update_time`

`links`

`PayPal-Request-Id`

`PayPal-Partner-Attribution-Id`

`payment_id`

`payer_id`

`transactions`

`id`

`intent`

`payer`

`application_context`

`transactions`

`state`

`experience_profile_id`

`note_to_payer`