Payments API

Use the Payments REST API to easily and securely accept online and mobile payments. The payments namespace 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.

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

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.

Notes:
  • Some countries restrict direct credit card payment and related features.

  • Authorizations are guaranteed for up to three days, though you can attempt to capture an authorization for up to 29 days. After the three-day honor period authorization expires, you can reauthorize the payment.

Request

Provide a payment object that includes the payment details. 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.

Important: For PayPal payments, you must redirect the payer to the approval_url in the response links. For more information, see PayPal payments.

The sample requests are:

  • Sample 1. Creates a PayPal payment.

  • Sample 2. Creates a direct credit card payment.

  • intent

    enum

    required

    The payment intent. Value is:

    Allowed values: sale, authorize, order.

  • payer

    object

    required

    The source of the funds for this payment. Payment method is PayPal Wallet payment, bank direct debit, or direct credit card.
  • 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.
  • 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.

Sample Request

curl -v -X POST https://api.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": "http://www.paypal.com/return",
  "cancel_url": "http://www.paypal.com/cancel"
  }
}'

Response

Returns a payment object along with the state of the payment and sale. The response includes a payment ID that uniquely identifies the transaction.

The sample responses are:

  • Sample 1. A PayPal payment.

  • Sample 2. A direct credit card payment.

  • id

    string

    The ID of the payment.

    Read only.

  • intent

    enum

    The payment intent. Value is:

    Possible values: sale, authorize, order.

  • payer

    object

    The source of the funds for this payment. Payment method is PayPal Wallet payment, bank direct debit, or direct credit card.
  • 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.
  • state

    enum

    The state of the payment, authorization, or order transaction. Value is:
    • created. The transaction was successfully created.
    • approved. The buyer approved the transaction.
    • 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 object)

    HATEOAS links related to this call.

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

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.

A successful request returns the HTTP 200 OK status code and a JSON response body that shows details for the executed payment.
Important: This call works only after a customer has approved the payment. For more information, learn about PayPal payments.

Parameters

  • payment_id

    path string

    The ID of the payment to execute.

Request

  • payer_id

    string

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

    array (contains the cart object)

    A cart.
SDK samples: Node.js, PHP, Python, Ruby

Sample Request

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

Response

  • id

    string

    The ID of the payment.

    Read only.

  • intent

    enum

    The payment intent. Value is:

    Possible values: sale, authorize, order.

  • payer

    object

    The source of the funds for this payment. Payment method is PayPal Wallet payment, bank direct debit, or direct credit card.
  • 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.
  • state

    enum

    The state of the payment, authorization, or order transaction. Value is:
    • created. The transaction was successfully created.
    • approved. The buyer approved the transaction.
    • 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 object)

    HATEOAS links related to this call.

    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@paypal.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_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.sandbox.paypal.com/v1/payments/orders/O-3SP845109F051535C",
                "rel": "self",
                "method": "GET"
              },
              {
                "href": "https://api.sandbox.paypal.com/v1/payments/payment/PAY-9N9834337A9191208KOZOQWI",
                "rel": "parent_payment",
                "method": "GET"
              },
              {
                "href": "https://api.sandbox.paypal.com/v1/payments/orders/O-3SP845109F051535C/void",
                "rel": "void",
                "method": "POST"
              },
              {
                "href": "https://api.sandbox.paypal.com/v1/payments/orders/O-3SP845109F051535C/authorize",
                "rel": "authorization",
                "method": "POST"
              },
              {
                "href": "https://api.sandbox.paypal.com/v1/payments/orders/O-3SP845109F051535C/capture",
                "rel": "capture",
                "method": "POST"
              }
            ]
          }
        }
      ]
    }
  ],
  "links": [
    {
      "href": "https://api.sandbox.paypal.com/v1/payments/payment/PAY-9N9834337A9191208KOZOQWI",
      "rel": "self",
      "method": "GET"
    }
  ]
}

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.

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

Parameters

  • payment_id

    path string

    The ID of the payment for which to show details.
SDK samples: JAVA, Node.js, PHP, Python, Ruby

Sample Request

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

Response

Returns a payment object.

  • id

    string

    The ID of the payment.

    Read only.

  • intent

    enum

    The payment intent. Value is:

    Possible values: sale, authorize, order.

  • payer

    object

    The source of the funds for this payment. Payment method is PayPal Wallet payment, bank direct debit, or direct credit card.
  • 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.
  • state

    enum

    The state of the payment, authorization, or order transaction. Value is:
    • created. The transaction was successfully created.
    • approved. The buyer approved the transaction.
    • 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 object)

    HATEOAS links related to this call.

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

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.

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

Parameters

  • payment_id

    path string

    The ID of the payment to update.

Request

Pass the patch_request objects in the body.

  • items

    array (contains the json_patch object)

    A JSON patch object to use to apply partial updates to resources.
SDK samples: JAVA

Sample Request

curl -v -X PATCH https://api.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

Returns the HTTP status of 204 if the call is successful.

Sample Response

{
  "id": "PAY-5YK922393D847794YKER7MUI",
  "intent": "authorize",
  "create_time": "2017-04-24T14:26:59.059Z",
  "payer": {
    "payer_info": {
      "country_code": "DE",
      "email": "a@paypal.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": "paypal-de@paypal.com"
      }
    }
  ],
  "links": [
    {
      "href": "https://api.sandbox.paypal.com/v1/payments/payment/PAY-5YK922393D847794YKER7MUI",
      "method": "GET",
      "rel": "self"
    }
  ]
}

List payments

GET /v1/payments/payment
Lists payments that were created by the create payment call and that are in any state. 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.

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

Parameters

To filter the response, you can use query parameters and pagination.

  • count

    query_string integer

    The number of items to list in the response.

    Default: 10.

  • start_id

    query_string 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

    query_string 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

    query_string 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

    query_string string

    The end 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.
  • payee_id

    query_string string

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

    query_string enum

    Sorts the payments in the response by a create time.

    Possible values: create_time.

  • sort_order

    query_string enum

    Sorts the payments in the response in descending order.

    Possible values: desc.

SDK samples: JAVA, Node.js, PHP, Python, Ruby

Sample Request

curl -v -X GET https://api.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

Returns an array of payment objects along with the count and next_id that you can use to look up the next set of results.

  • payments

    array (contains the payment object)

    A payment. Use this object to create, process, and manage payments.
  • count

    see description

    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. The maximum value is 20.
    Possible types: integer
  • next_id

    string

    The ID of the next element. 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.sandbox.paypal.com/v1/payments/payment/PAY-0US81985GW1191216KOY7OXA",
                    "rel": "parent_payment",
                    "method": "GET"
                  }
                ]
              }
            }
          ]
        }
      ],
      "links": [
        {
          "href": "https://api.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.sandbox.paypal.com/v1/payments/payment/PAY-53485002LD6169910KOZQ25I",
                    "rel": "parent_payment",
                    "method": "GET"
                  }
                ]
              }
            }
          ]
        }
      ],
      "links": [
        {
          "href": "https://api.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.sandbox.paypal.com/v1/payments/capture/26062838D7499294V",
                    "rel": "self",
                    "method": "GET"
                  },
                  {
                    "href": "https://api.sandbox.paypal.com/v1/payments/capture/26062838D7499294V/refund",
                    "rel": "refund",
                    "method": "POST"
                  },
                  {
                    "href": "https://api.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.sandbox.paypal.com/v1/payments/capture/0YU20012P1477553M",
                    "rel": "self",
                    "method": "GET"
                  },
                  {
                    "href": "https://api.sandbox.paypal.com/v1/payments/capture/0YU20012P1477553M/refund",
                    "rel": "refund",
                    "method": "POST"
                  },
                  {
                    "href": "https://api.sandbox.paypal.com/v1/payments/payment/PAY-7F5790198P134484LKOZSG7Q",
                    "rel": "parent_payment",
                    "method": "GET"
                  }
                ]
              }
            }
          ]
        }
      ],
      "links": [
        {
          "href": "https://api.sandbox.paypal.com/v1/payments/payment/PAY-7F5790198P134484LKOZSG7Q",
          "rel": "self",
          "method": "GET"
        }
      ]
    }
  ],
  "count": 3,
  "next_id": "PAY-9X4935091L753623RKOZTRHI"
}

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

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

Parameters

  • sale_id

    path string

    The ID of the sale for which to show details.
SDK samples: C#, JAVA, Node.js, PHP, Python, Ruby

Sample Request

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

Response

  • id

    string

    The ID of the sale transaction.

    Read only.

  • amount

    object

    The amount being collected.

    Read only.

  • payment_mode

    enum

    The transaction payment mode. Supported only when payment_method is paypal.

    Read only.

    Possible values: INSTANT_TRANSFER, MANUAL_BANK_TRANSFER, DELAYED_TRANSFER, ECHECK.

  • state

    enum

    The sale transaction state.

    Read only.

    Possible values: completed, partially_refunded, pending, refunded, denied.

  • reason_code

    enum

    The reason code that describes why the transaction state is pending or reversed. Supported only when the payment_method is paypal.

    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 seller protection level in effect for the transaction. Supported only when the payment_method is paypal.

    Read only.

    Possible values: ELIGIBLE, PARTIALLY_ELIGIBLE, INELIGIBLE.

  • protection_eligibility_type

    enum

    The seller protection type in effect for the transaction. Returned only when protection_eligibility is ELIGIBLE or PARTIALLY_ELIGIBLE. Supported only when the payment_method is paypal.

    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 eCheck transaction is expected to clear. Returned for eCheck payments. Supported only when the payment_method is paypal.

    Read only.

  • transaction_fee

    object

    The transaction fee that applies for this payment.

    Read only.

  • receivable_amount

    object

    The net amount 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.

    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 for the payment that might result in 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.

    Read only.

  • 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 response codes that the processor returns for the submitted payment. Supported only when the payment_method is credit_card.

    Read only.

  • 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 as defined in RFC 3339 Section 5.6.

    Read only.

  • update_time

    string

    The date and time when the resource was last updated, in Internet date and time format in RFC 3339 Section 5.6.

    Read only.

  • links

    array (contains the link object)

    HATEOAS links related to this call.

    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.sandbox.paypal.com/v1/payments/sale/36C38912MN9658832",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://api.sandbox.paypal.com/v1/payments/sale/36C38912MN9658832/refund",
      "rel": "refund",
      "method": "POST"
    },
    {
      "href": "https://api.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, include an empty payload in the JSON request body. For a partial refund, include an amount object in the JSON request body.

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

Parameters

  • sale_id

    path string

    The ID of the sale transaction to refund.

Request

  • amount

    object

    The refund amount. Includes both the amount refunded to the payer and amount of the fee refunded to the payee.
  • refund_source

    enum

    The PayPal funding source type, such as balance or eCheck, to use for auto refund.

    Allowed values: INSTANT_FUNDING_SOURCE, ECHECK, UNRESTRICTED.

    Default: UNRESTRICTED.

  • invoice_number

    string

    The invoice number that is used to track this payment.

    Maximum length: 127.

  • refund_advice

    boolean

    Indicates whether store credit was already given to the payer.
  • items

    array (contains the item object)

    The item details.
  • payer_info

    object

    Payer details.
  • supplementary_data

    array (contains the name_and_value_pair object)

    A type for name-and-value pairs. Limit the use of name-and-value pairs in an API. Requires approval from architecture.
SDK samples: C#, JAVA, Node.js, PHP, Python, Ruby

Sample Request

curl -v -X POST https://api.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

Returns a refund object with details about a refund and whether the refund was successful.

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

    Read only.

    Possible values: pending, completed, cancelled, failed.

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

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

  • reason_code

    enum

    The reason code for the pending refund state.

    Read only.

    Possible values: ECHECK.

  • refund_reason_code

    enum

    The PayPal-assigned reason codes for the refund.

    Read only.

    Possible values: ADJUSTMENT_REVERSAL, ADMIN_FRAUD_REVERSAL, ADMIN_REVERSAL, APPEAL, BUYER_COMPLAINT, CHARGEBACK, CHARGEBACK_SETTLEMENT, DENIED, DISPUTE_PAYOUT, FUNDING, GUARANTEE, LIMITS, NO_FAULT, OTHER, REFUND, REGULATORY_BLOCK, REGULATORY_REJECT, REGULATORY_REVIEW_EXCEEDING_SLA, RISK, SELLER_FAULT, SELLER_VOLUNTARY, THIRDPARTY_LOGISTICS_FAULT, UNAUTH_CLAIM, UNAUTH_SPOOF.

  • refund_funding_type

    enum

    Indicates whether the refund amount is funded by the payee's funding account or another funding account.

    Read only.

    Possible values: PAYOUT.

  • links

    array (contains the link object)

    HATEOAS links related to this call.

    Read only.

  • custom

    string

    A free-form field for the use by clients.

    Maximum length: 127.

  • refund_to_payer

    object

    The amount refunded to the payer of the original transaction, in the current refund call.
  • refund_to_external_funding

    array (contains the external_funding object)

    An external funding account.
  • refund_from_received_amount

    object

    The amount subtracted from the original payment recipient's PayPal balance to make this refund.

    Read only.

  • total_refunded_amount

    object

    The total amount refunded 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.

    Read only.

  • refund_to_msb

    object

    Amount refunded to the merchant specific balance (MSB).

    Read only.

Sample Response

{
  "id": "4CF18861HF410323U",
  "create_time": "2017-01-31T04:13:34Z",
  "update_time": "2017-01-31T04:13:36Z",
  "state": "completed",
  "amount": {
    "total": "2.34",
    "currency": "USD"
  },
  "sale_id": "2MU78835H4515710F",
  "parent_payment": "PAY-46E69296BH2194803KEE662Y",
  "invoice_number": "INV-1234567",
  "links": [
    {
      "href": "https://api.sandbox.paypal.com/v1/payments/refund/4CF18861HF410323U",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://api.sandbox.paypal.com/v1/payments/payment/PAY-46E69296BH2194803KEE662Y",
      "rel": "parent_payment",
      "method": "GET"
    },
    {
      "href": "https://api.sandbox.paypal.com/v1/payments/sale/2MU78835H4515710F",
      "rel": "sale",
      "method": "GET"
    }
  ]
}

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

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

Parameters

  • refund_id

    path string

    The ID of the refund for which to show details.
SDK samples: C#

Sample Request

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

Response

Returns a refund object with details about a refund and whether the refund was successful.

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

    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.

    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.

  • reason_code

    enum

    The reason code for the pending refund state.

    Read only.

    Possible values: ECHECK.

  • refund_reason_code

    enum

    The PayPal-assigned reason codes for the refund.

    Read only.

    Possible values: ADJUSTMENT_REVERSAL, ADMIN_FRAUD_REVERSAL, ADMIN_REVERSAL, APPEAL, BUYER_COMPLAINT, CHARGEBACK, CHARGEBACK_SETTLEMENT, DENIED, DISPUTE_PAYOUT, FUNDING, GUARANTEE, LIMITS, NO_FAULT, OTHER, REFUND, REGULATORY_BLOCK, REGULATORY_REJECT, REGULATORY_REVIEW_EXCEEDING_SLA, RISK, SELLER_FAULT, SELLER_VOLUNTARY, THIRDPARTY_LOGISTICS_FAULT, UNAUTH_CLAIM, UNAUTH_SPOOF.

  • refund_funding_type

    enum

    Indicates whether the refund amount is funded by the payee's funding account or another funding account.

    Read only.

    Possible values: PAYOUT.

  • links

    array (contains the link object)

    HATEOAS links related to this call.

    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.sandbox.paypal.com/v1/payments/refund/4GU360220B627614A",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://api.sandbox.paypal.com/v1/payments/payment/PAY-5YK922393D847794YKER7MUI",
      "rel": "parent_payment",
      "method": "GET"
    },
    {
      "href": "https://api.sandbox.paypal.com/v1/payments/sale/36C38912MN9658832",
      "rel": "sale",
      "method": "GET"
    }
  ]
}

Authorizations (resource group)

Use the /authorization resource and related sub-resources to act on a previously created authorization. You can 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.

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

Parameters

  • authorization_id

    path string

    The ID of the authorization for which to show details.
SDK samples: C#, JAVA, Node.js, PHP, Python, Ruby

Sample Request

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

Response

Returns an authorization object.

  • id

    string

    The ID of the authorization.

    Read only.

  • amount

    object

    The amount being authorized.
  • payment_mode

    enum

    The payment mode of the authorization.

    Read only.

    Possible values: INSTANT_TRANSFER.

  • state

    enum

    The authorization state.

    Read only.

    Possible values: pending, authorized, partially_captured, captured, expired, voided.

  • reason_code

    enum

    The reason code for the pending transaction state.

    Read only.

    Possible values: AUTHORIZATION.

  • pending_reason

    enum

    [DEPRECATED] The reason code for the pending transaction state. Obsolete. Use reason_code instead.

    Read only.

    Possible values: AUTHORIZATION.

  • protection_eligibility

    enum

    The level of seller protection present for the transaction. Supported for the PayPal payment method only. Value is:
    • 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.

    Possible values: ELIGIBLE, PARTIALLY_ELIGIBLE, INELIGIBLE.

  • protection_eligibility_type

    enum

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

    Returns one or both of the allowed values.

    Value is:
    • ITEM_NOT_RECEIVED_ELIGIBLE. Sellers are protected against claims for items not received.
    • UNAUTHORIZED_PAYMENT_ELIGIBLE. Sellers are protected against claims for unauthorized payments.

    Read only.

    Possible values: ITEM_NOT_RECEIVED_ELIGIBLE, UNAUTHORIZED_PAYMENT_ELIGIBLE, ITEM_NOT_RECEIVED_ELIGIBLE,UNAUTHORIZED_PAYMENT_ELIGIBLE.

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

    Read only.

  • parent_payment

    string

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

    Read only.

  • processor_response

    object

    Response codes returned by the processor concerning the submitted payment. Only supported when the payment_method is set to credit_card.

    Read only.

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

  • reference_id

    string

    The ID of the purchase or transaction unit that corresponds to this authorization transaction.

    Read only.

    Maximum length: 256.

  • 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 object)

    HATEOAS links related to this call.

    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.sandbox.paypal.com/v1/payments/authorization/2DC87612EK520411B",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://api.sandbox.paypal.com/v1/payments/authorization/2DC87612EK520411B/capture",
      "rel": "capture",
      "method": "POST"
    },
    {
      "href": "https://api.sandbox.paypal.com/v1/payments/authorization/2DC87612EK520411B/void",
      "rel": "void",
      "method": "POST"
    },
    {
      "href": "https://api.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. To use this call, the original payment call must specify an intent of authorize.

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

Parameters

  • authorization_id

    path string

    The ID of the authorization to capture.

Request

Provide an amount object. For a partial capture, you can provide a lower amount. Additionally, you can explicitly indicate a final capture (prevent future captures) by setting the is_final_capture value to true.

  • amount

    object

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

    boolean

    Indicates whether to release all remaining funds that the authorization holds in the funding instrument (FI). Default is false.

    Default: false.

  • invoice_number

    string

    The invoice number to track this payment.

    Maximum length: 127.

SDK samples: C#, JAVA, Node.js, PHP, Python, Ruby

Sample Request

curl -v -X POST https://api.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

Returns a capture object with the state of the capture.

  • id

    string

    The ID of the capture transaction.

    Read only.

  • amount

    object

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

    boolean

    Indicates whether to release all remaining funds that the authorization holds in the funding instrument (FI). Default is false.

    Default: false.

  • state

    enum

    The capture state. Value is:
    • pending. The capture is pending.
    • completed. The capture has successfully completed.
    • refunded. The capture was fully refunded.
    • partially_refunded. The capture was partially refunded.

    Read only.

    Possible values: pending, completed, refunded, partially_refunded.

  • reason_code

    enum

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

    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.

  • 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 transaction fee for this payment.
  • create_time

    string

    The date and time when the capture occurred, in Internet date and time format as defined in RFC 3339 Section 5.6.

    Read only.

  • update_time

    string

    The date and time when the resource was last updated, in Internet date and time format as defined in RFC 3339 Section 5.6.

    Read only.

  • links

    array (contains the link object)

    HATEOAS links related to this call.

    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.sandbox.paypal.com/v1/payments/capture/6BA17599X0950293U",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://api.sandbox.paypal.com/v1/payments/capture/6BA17599X0950293U/refund",
      "rel": "refund",
      "method": "POST"
    },
    {
      "href": "https://api.sandbox.paypal.com/v1/payments/authorization/5RA45624N3531924N",
      "rel": "authorization",
      "method": "GET"
    },
    {
      "href": "https://api.sandbox.paypal.com/v1/payments/payment/PAY-44664305570317015KGEC5DI",
      "rel": "parent_payment",
      "method": "GET"
    }
  ]
}

Void an authorization

POST /v1/payments/authorization/authorization_id/void
Voids, or cancels, an authorization, by ID. You cannot void a fully captured authorization.

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

Parameters

  • authorization_id

    path string

    The ID of the authorization to void.
SDK samples: C#, JAVA, Node.js, PHP, Python, Ruby

Sample Request

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

Response

Returns an authorization object.

  • id

    string

    The ID of the authorization transaction.

    Read only.

  • amount

    object

    Amount being authorized.

  • state

    enum

    The state of the authorization. The value is:

    • pending. The authorization is pending.
    • authorized. The authorization has successfully completed.
    • partially_captured. The authorization was partially captured.
    • captured. The authorization was fully captured.
    • expired. The authorization has expired.
    • voided. The authorization was voided.

    Read only.

    Possible values: pending, authorized, partially_captured, captured, expired, voided.

  • pending_reason

    enum

    [DEPRECATED] The reason code for the pending transaction state. Obsolete. Use reason_code instead.

    Read only.

    Possible values: AUTHORIZATION.

  • protection_eligibility

    enum

    The level of seller protection in force for the transaction. Only supported when the payment_method is set to paypal. Allowed values:

    • 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. See protection_eligibility_type for details.
    • INELIGIBLE. Merchant is not protected under the Seller Protection Policy.

    Read only.

    Possible values: ELIGIBLE, PARTIALLY_ELIGIBLE, INELIGIBLE.

  • protection_eligibility_type

    enum

    The kind of seller protection in force for the transaction. This property is returned only when the protection_eligibility property is set to ELIGIBLEor PARTIALLY_ELIGIBLE. Only supported when the payment_method is set to paypal. One or both allowed values can be returned:

    • ITEM_NOT_RECEIVED_ELIGIBLE. Sellers are protected against claims for items not received.
    • UNAUTHORIZED_PAYMENT_ELIGIBLE. Sellers are protected against claims for unauthorized payments.

    Read only.

    Possible values: ITEM_NOT_RECEIVED_ELIGIBLE, UNAUTHORIZED_PAYMENT_ELIGIBLE, ITEM_NOT_RECEIVED_ELIGIBLE,UNAUTHORIZED_PAYMENT_ELIGIBLE.

  • parent_payment

    string

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

    Read only.

  • processor_response

    object

    Response codes returned by the processor concerning the submitted payment. Only supported when the payment_method is set to credit_card.

    Read only.

  • valid_until

    string

    The date and time when the authorization expires, as defined in RFC 3339 Section 5.6.

    Read only.

  • create_time

    string

    The date and time of the authorization, as defined in RFC 3339 Section 5.6.

    Read only.

  • update_time

    string

    The date and time when the resource was last updated.

    Read only.

  • reference_id

    string

    The ID of the purchase or transaction unit that corresponds to this authorization transaction.

    Read only.

    Maximum length: 256.

  • 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 object)

    HATEOAS links related to this call.

    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.sandbox.paypal.com/v1/payments/authorization/6CR34526N64144512",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://api.sandbox.paypal.com/v1/payments/payment/PAY-0PL82432AD7432233KGECOIQ",
      "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.

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

Parameters

  • authorization_id

    path string

    The ID of the authorization to re-authorize.

Request

Pass a new authorization object if you must authorize a different amount.

  • amount

    object

    required

    The amount being authorized.
SDK samples: C#, JAVA, Node.js, PHP, Python, Ruby

Sample Request

curl -v -X POST https://api.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

Returns an authorization object with details of the re-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.

    Read only.

    Possible values: INSTANT_TRANSFER.

  • state

    enum

    The authorization state.

    Read only.

    Possible values: pending, authorized, partially_captured, captured, expired, voided.

  • reason_code

    enum

    The reason code for the pending transaction state.

    Read only.

    Possible values: AUTHORIZATION.

  • pending_reason

    enum

    [DEPRECATED] The reason code for the pending transaction state. Obsolete. Use reason_code instead.

    Read only.

    Possible values: AUTHORIZATION.

  • protection_eligibility

    enum

    The level of seller protection present for the transaction. Supported for the PayPal payment method only. Value is:
    • 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.

    Possible values: ELIGIBLE, PARTIALLY_ELIGIBLE, INELIGIBLE.

  • protection_eligibility_type

    enum

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

    Returns one or both of the allowed values.

    Value is:
    • ITEM_NOT_RECEIVED_ELIGIBLE. Sellers are protected against claims for items not received.
    • UNAUTHORIZED_PAYMENT_ELIGIBLE. Sellers are protected against claims for unauthorized payments.

    Read only.

    Possible values: ITEM_NOT_RECEIVED_ELIGIBLE, UNAUTHORIZED_PAYMENT_ELIGIBLE, ITEM_NOT_RECEIVED_ELIGIBLE,UNAUTHORIZED_PAYMENT_ELIGIBLE.

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

    Read only.

  • parent_payment

    string

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

    Read only.

  • processor_response

    object

    Response codes returned by the processor concerning the submitted payment. Only supported when the payment_method is set to credit_card.

    Read only.

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

  • reference_id

    string

    The ID of the purchase or transaction unit that corresponds to this authorization transaction.

    Read only.

    Maximum length: 256.

  • 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 object)

    HATEOAS links related to this call.

    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.sandbox.paypal.com/v1/payments/authorization/8AA831015G517922L",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://api.sandbox.paypal.com/v1/payments/payment/PAY-7LD317540C810384EKHFAGYA",
      "rel": "parent_payment",
      "method": "GET"
    },
    {
      "href": "https://api.sandbox.paypal.com/v1/payments/authorization/8AA831015G517922L/capture",
      "rel": "capture",
      "method": "POST"
    }
  ]
}

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

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

Parameters

  • capture_id

    path string

    The ID of the captured payment for which to show details.
SDK samples: C#, JAVA, Node.js, PHP, Python, Ruby

Sample Request

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

Response

Returns a capture object with details about the capture.

  • id

    string

    The ID of the capture transaction.

    Read only.

  • amount

    object

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

    boolean

    Indicates whether to release all remaining funds that the authorization holds in the funding instrument (FI). Default is false.

    Default: false.

  • state

    enum

    The capture state. Value is:
    • pending. The capture is pending.
    • completed. The capture has successfully completed.
    • refunded. The capture was fully refunded.
    • partially_refunded. The capture was partially refunded.

    Read only.

    Possible values: pending, completed, refunded, partially_refunded.

  • reason_code

    enum

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

    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.

  • 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 transaction fee for this payment.
  • create_time

    string

    The date and time when the capture occurred, in Internet date and time format as defined in RFC 3339 Section 5.6.

    Read only.

  • update_time

    string

    The date and time when the resource was last updated, in Internet date and time format as defined in RFC 3339 Section 5.6.

    Read only.

  • links

    array (contains the link object)

    HATEOAS links related to this call.

    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.sandbox.paypal.com/v1/payments/capture/8F148933LY9388354",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://api.sandbox.paypal.com/v1/payments/capture/8F148933LY9388354/refund",
      "rel": "refund",
      "method": "POST"
    },
    {
      "href": "https://api.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.

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

Parameters

  • capture_id

    path string

    The ID of the captured payment to refund.

Request

  • amount

    object

    The refund amount. Includes both the amount refunded to the payer and amount of the fee refunded to the payee.
  • description

    string

    The refund description. Value must be single-byte alphanumeric characters.

    Maximum length: 255.

  • refund_source

    enum

    The PayPal funding source type, such as balance or eCheck, to use for auto refund.

    Allowed values: INSTANT_FUNDING_SOURCE, ECHECK, UNRESTRICTED.

    Default: UNRESTRICTED.

  • reason

    string

    The refund reason description.

    Maximum length: 30.

  • invoice_number

    string

    The invoice number that is used to track this payment.

    Maximum length: 127.

  • refund_advice

    boolean

    Indicates whether store credit was already given to the payer.
  • items

    array (contains the item object)

    The item details.
  • payer_info

    object

    Payer details.
  • supplementary_data

    array (contains the name_and_value_pair object)

    A type for name-and-value pairs. Limit the use of name-and-value pairs in an API. Requires approval from architecture.
SDK samples: C#, JAVA, Node.js, PHP, Python, Ruby

Sample Request

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

Response

Returns a refund object with details about a refund and whether the refund was successful.

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

    Read only.

    Possible values: pending, completed, cancelled, failed.

  • invoice_number

    string

    The invoice number to track this payment.

    Maximum length: 127.

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

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

  • reason_code

    enum

    The reason code for the pending refund state.

    Read only.

    Possible values: ECHECK.

  • refund_reason_code

    enum

    The PayPal-assigned reason codes for the refund.

    Read only.

    Possible values: ADJUSTMENT_REVERSAL, ADMIN_FRAUD_REVERSAL, ADMIN_REVERSAL, APPEAL, BUYER_COMPLAINT, CHARGEBACK, CHARGEBACK_SETTLEMENT, DENIED, DISPUTE_PAYOUT, FUNDING, GUARANTEE, LIMITS, NO_FAULT, OTHER, REFUND, REGULATORY_BLOCK, REGULATORY_REJECT, REGULATORY_REVIEW_EXCEEDING_SLA, RISK, SELLER_FAULT, SELLER_VOLUNTARY, THIRDPARTY_LOGISTICS_FAULT, UNAUTH_CLAIM, UNAUTH_SPOOF.

  • refund_funding_type

    enum

    Indicates whether the refund amount is funded by the payee's funding account or another funding account.

    Read only.

    Possible values: PAYOUT.

  • links

    array (contains the link object)

    HATEOAS links related to this call.

    Read only.

  • custom

    string

    A free-form field for the use by clients.

    Maximum length: 127.

  • refund_to_payer

    object

    The amount refunded to the payer of the original transaction, in the current refund call.
  • refund_to_external_funding

    array (contains the external_funding object)

    An external funding account.
  • refund_from_received_amount

    object

    The amount subtracted from the original payment recipient's PayPal balance to make this refund.

    Read only.

  • total_refunded_amount

    object

    The total amount refunded 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.

    Read only.

  • refund_to_msb

    object

    Amount refunded to the merchant specific balance (MSB).

    Read only.

Sample Response

{
  "id": "0P209507D6694645N",
  "create_time": "2017-05-06T22:11:51Z",
  "update_time": "2017-05-06T22:11:51Z",
  "state": "completed",
  "amount": {
    "total": "110.54",
    "currency": "USD"
  },
  "capture_id": "8F148933LY9388354",
  "parent_payment": "PAY-8PT597110X687430LKGECATA",
  "invoice_number": "INV-1234567",
  "links": [
    {
      "href": "https://api.sandbox.paypal.com/v1/payments/refund/0P209507D6694645N",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://api.sandbox.paypal.com/v1/payments/payment/PAY-8PT597110X687430LKGECATA",
      "rel": "parent_payment",
      "method": "GET"
    },
    {
      "href": "https://api.sandbox.paypal.com/v1/payments/capture/8F148933LY9388354",
      "rel": "capture",
      "method": "GET"
    }
  ]
}

Orders (resource group)

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

Note: You cannot refund an order directly. Instead, you must refund a completed payment for an order. For integration information, see Orders and refund a payment.

For more information, see also Orders.

Show order details

GET /v1/payments/orders/order_id
Shows details for an order, by ID.

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

Parameters

  • order_id

    path string

    The ID of the order for which to show details.
SDK samples: C#, Node.js, PHP, Python

Sample Request

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

Response

Returns an order object.

  • id

    string

    The ID of the order transaction.

    Read only.

  • reference_id

    string

    The ID of the purchase unit that is associated with this object. Obsolete. Used only in cart_base.

    Read only.

  • amount

    object

    The amount to collect.
  • payment_mode

    enum

    The transaction payment mode.

    Read only.

    Possible values: INSTANT_TRANSFER, MANUAL_BANK_TRANSFER, DELAYED_TRANSFER, ECHECK.

  • state

    enum

    The order transaction state.

    Read only.

    Possible values: pending, completed, voided, authorized, captured.

  • reason_code

    enum

    The reason code that describes why the transaction state is pending or reversed. Eventually, this parameter will replace the pending_reason parameter. Supported only when the payment_method is paypal.

    Read only.

    Possible values: PAYER_SHIPPING_UNCONFIRMED, MULTI_CURRENCY, RISK_REVIEW, REGULATORY_REVIEW, VERIFICATION_REQUIRED, ORDER, OTHER.

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

    Read only.

    Possible values: ELIGIBLE, PARTIALLY_ELIGIBLE, INELIGIBLE.

  • 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 when the payment_method is paypal. One or both of these values can be returned:
    • ITEM_NOT_RECEIVED_ELIGIBLE. Sellers are protected against claims for items not received.
    • UNAUTHORIZED_PAYMENT_ELIGIBLE. Sellers are protected against claims for unauthorized payments.

    Read only.

    Possible values: ITEM_NOT_RECEIVED_ELIGIBLE, UNAUTHORIZED_PAYMENT_ELIGIBLE, ITEM_NOT_RECEIVED_ELIGIBLE,UNAUTHORIZED_PAYMENT_ELIGIBLE.

  • 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 applied for the payment that can result in an accept, deny, or pending action.

    Read only.

  • 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 object)

    HATEOAS links related to this call.

    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.sandbox.paypal.com/v1/payments/orders/O-0PW72302W3743444R",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://api.sandbox.paypal.com/v1/payments/payment/PAY-4D805864V5423372TKOQLRUQ",
      "rel": "parent_payment",
      "method": "GET"
    },
    {
      "href": "https://api.sandbox.paypal.com/v1/payments/orders/O-0PW72302W3743444R/authorization",
      "rel": "authorize",
      "method": "POST"
    },
    {
      "href": "https://api.sandbox.paypal.com/v1/payments/orders/O-0PW72302W3743444R/capture",
      "rel": "capture",
      "method": "POST"
    },
    {
      "href": "https://api.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.

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

Parameters

  • order_id

    path string

    The ID of the order to authorize.

Request

  • amount

    object

    required

    The amount to collect.
SDK samples: C#, Node.js, PHP, Python

Sample Request

curl -v -X POST https://api.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

Returns an authorization object.

  • id

    string

    The ID of the authorization.

    Read only.

  • amount

    object

    The amount being authorized.
  • payment_mode

    enum

    The payment mode of the authorization.

    Read only.

    Possible values: INSTANT_TRANSFER.

  • state

    enum

    The authorization state.

    Read only.

    Possible values: pending, authorized, partially_captured, captured, expired, voided.

  • reason_code

    enum

    The reason code for the pending transaction state.

    Read only.

    Possible values: AUTHORIZATION.

  • pending_reason

    enum

    [DEPRECATED] The reason code for the pending transaction state. Obsolete. Use reason_code instead.

    Read only.

    Possible values: AUTHORIZATION.

  • protection_eligibility

    enum

    The level of seller protection present for the transaction. Supported for the PayPal payment method only. Value is:
    • 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.

    Possible values: ELIGIBLE, PARTIALLY_ELIGIBLE, INELIGIBLE.

  • protection_eligibility_type

    enum

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

    Returns one or both of the allowed values.

    Value is:
    • ITEM_NOT_RECEIVED_ELIGIBLE. Sellers are protected against claims for items not received.
    • UNAUTHORIZED_PAYMENT_ELIGIBLE. Sellers are protected against claims for unauthorized payments.

    Read only.

    Possible values: ITEM_NOT_RECEIVED_ELIGIBLE, UNAUTHORIZED_PAYMENT_ELIGIBLE, ITEM_NOT_RECEIVED_ELIGIBLE,UNAUTHORIZED_PAYMENT_ELIGIBLE.

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

    Read only.

  • parent_payment

    string

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

    Read only.

  • processor_response

    object

    Response codes returned by the processor concerning the submitted payment. Only supported when the payment_method is set to credit_card.

    Read only.

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

  • reference_id

    string

    The ID of the purchase or transaction unit that corresponds to this authorization transaction.

    Read only.

    Maximum length: 256.

  • 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 object)

    HATEOAS links related to this call.

    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.sandbox.paypal.com/v1/payments/orders/O-0NR488530V5211123",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://api.sandbox.paypal.com/v1/payments/authorization/0PG032325D352531H",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://api.sandbox.paypal.com/v1/payments/authorization/0PG032325D352531H/capture",
      "rel": "capture",
      "method": "POST"
    },
    {
      "href": "https://api.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.

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

Parameters

  • order_id

    path string

    The ID of the order to capture.

Request

  • amount

    object

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

    boolean

    Indicates whether to release all remaining funds that the authorization holds in the funding instrument (FI). Default is false.

    Default: false.

  • invoice_number

    string

    The invoice number to track this payment.

    Maximum length: 127.

  • transaction_fee

    object

    The transaction fee for this payment.
SDK samples: C#, Node.js, PHP, Python

Sample Request

curl -v -X POST https://api.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

Returns a capture object.

  • id

    string

    The ID of the capture transaction.

    Read only.

  • amount

    object

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

    boolean

    Indicates whether to release all remaining funds that the authorization holds in the funding instrument (FI). Default is false.

    Default: false.

  • state

    enum

    The capture state. Value is:
    • pending. The capture is pending.
    • completed. The capture has successfully completed.
    • refunded. The capture was fully refunded.
    • partially_refunded. The capture was partially refunded.

    Read only.

    Possible values: pending, completed, refunded, partially_refunded.

  • reason_code

    enum

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

    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.

  • 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 transaction fee for this payment.
  • create_time

    string

    The date and time when the capture occurred, in Internet date and time format as defined in RFC 3339 Section 5.6.

    Read only.

  • update_time

    string

    The date and time when the resource was last updated, in Internet date and time format as defined in RFC 3339 Section 5.6.

    Read only.

  • links

    array (contains the link object)

    HATEOAS links related to this call.

    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.sandbox.paypal.com/v1/payments/capture/51366113MA710110S",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://api.sandbox.paypal.com/v1/payments/capture/51366113MA710110S/refund",
      "rel": "refund",
      "method": "POST"
    },
    {
      "href": "https://api.sandbox.paypal.com/v1/payments/orders/O-3SP845109F051535C",
      "rel": "order",
      "method": "GET"
    },
    {
      "href": "https://api.sandbox.paypal.com/v1/payments/payment/PAY-9N9834337A9191208KOZOQWI",
      "rel": "parent_payment",
      "method": "GET"
    }
  ]
}

Void an order

POST /v1/payments/orders/order_id/do-void
Voids, or cancels, an order, by ID. You cannot void an order if the payment has already been partially or fully captured.

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

Parameters

  • order_id

    path string

    The ID of the order to void.
SDK samples: C#, Node.js, PHP, Python

Sample Request

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

Response

Returns an order object.

  • id

    string

    The ID of the order transaction.

    Read only.

  • reference_id

    string

    The ID of the purchase unit that is associated with this object. Obsolete. Used only in cart_base.

    Read only.

  • amount

    object

    The amount to collect.
  • payment_mode

    enum

    The transaction payment mode.

    Read only.

    Possible values: INSTANT_TRANSFER, MANUAL_BANK_TRANSFER, DELAYED_TRANSFER, ECHECK.

  • state

    enum

    The order transaction state.

    Read only.

    Possible values: pending, completed, voided, authorized, captured.

  • reason_code

    enum

    The reason code that describes why the transaction state is pending or reversed. Eventually, this parameter will replace the pending_reason parameter. Supported only when the payment_method is paypal.

    Read only.

    Possible values: PAYER_SHIPPING_UNCONFIRMED, MULTI_CURRENCY, RISK_REVIEW, REGULATORY_REVIEW, VERIFICATION_REQUIRED, ORDER, OTHER.

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

    Read only.

    Possible values: ELIGIBLE, PARTIALLY_ELIGIBLE, INELIGIBLE.

  • 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 when the payment_method is paypal. One or both of these values can be returned:
    • ITEM_NOT_RECEIVED_ELIGIBLE. Sellers are protected against claims for items not received.
    • UNAUTHORIZED_PAYMENT_ELIGIBLE. Sellers are protected against claims for unauthorized payments.

    Read only.

    Possible values: ITEM_NOT_RECEIVED_ELIGIBLE, UNAUTHORIZED_PAYMENT_ELIGIBLE, ITEM_NOT_RECEIVED_ELIGIBLE,UNAUTHORIZED_PAYMENT_ELIGIBLE.

  • 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 applied for the payment that can result in an accept, deny, or pending action.

    Read only.

  • 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 object)

    HATEOAS links related to this call.

    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.sandbox.paypal.com/v1/payments/authorization/O-0NR488530V5211123",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://api.sandbox.paypal.com/v1/payments/payment/PAY-0AY778532K612520BKOXHAKY",
      "rel": "parent_payment",
      "method": "GET"
    }
  ]
}

Common object definitions

address

  • line1

    string

    The first line of the address. For example, number, street, and so on. Maximum length is 100 characters.
  • line2

    string

    The second line of the address. For example, suite, apartment number, and so on. Maximum length is 100 characters.
  • city

    string

    The city name. Maximum length is 50 characters.
  • country_code

    string

  • postal_code

    string

    The zip code or equivalent. Typically required for countries that have them. Maximum length is 20 characters. Required in certain countries.
  • state

    string

    The two-letter code for US states or the equivalent for other countries. Maximum length is 100 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.

    Read only.

    Possible values: UNKNOWN, UNNORMALIZED_USER_PREFERRED, NORMALIZED, UNNORMALIZED.

  • type

    string

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

alternative_payment

  • account_id

    string

    The ID of the alternative payment account.

    Maximum length: 128.

  • external_customer_id

    string

    The ID of the payer.

    Maximum length: 128.

  • provider_id

    string

    Optional. The alternative payment provider ID. Required only for certain alternative providers. For example, iDEAL.

    Maximum length: 128.

  • expiration_duration

    string

    Optional. The expiration duration. Used by some payment service providers to control the expiration of the payment link.

    Maximum length: 4.

    Pattern: ^\d{1,2}[a-zA-Z]{1}$.

  • locale

    string

    Optional. The locale. Some payment service providers use this attribute to localize error messages and suggested actions.

    Maximum length: 5.

    Pattern: ^[a-z]{2}_[A-Z]{2}$.

amount

  • currency

    string

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

    string

    The total amount charged to the payee by the payer. For refunds, represents the amount that the payee refunds to the original payer. Maximum length is 10 characters. Supports two decimal places.
  • details

    object

    The additional details about the payment amount.

apple_pay_token

  • payment_token

    string

    An Apple Pay token, as a tokenized and encrypted Apple Pay card and fetched by the Apple Pay SDK.
  • first_name

    string

    The Apple Pay card holder's first name.

    Maximum length: 140.

  • last_name

    string

    The Apple Pay card holder's last name.

    Maximum length: 140.

  • billing_address

    object

    The Apple Pay card holder's billing address.
  • payment_method_display_name

    string

    The Apple Pay card description.

    Maximum length: 100.

  • payment_method_network

    string

    The Apple Pay card payment network.

    Maximum length: 100.

  • payment_method_type

    enum

    The Apple Pay card type.

    Possible values: UNKNOWN, DEBIT, CREDIT, PREPAID, STORE.

    Maximum length: 40.

  • apple_transaction_identifier

    string

    The ID for the Apple Pay transaction. Can be used in a receipt.

    Maximum length: 140.

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.

    Read only.

    Possible values: INSTANT_TRANSFER.

  • state

    enum

    The authorization state.

    Read only.

    Possible values: pending, authorized, partially_captured, captured, expired, voided.

  • reason_code

    enum

    The reason code for the pending transaction state.

    Read only.

    Possible values: AUTHORIZATION.

  • pending_reason

    enum

    [DEPRECATED] The reason code for the pending transaction state. Obsolete. Use reason_code instead.

    Read only.

    Possible values: AUTHORIZATION.

  • protection_eligibility

    enum

    The level of seller protection present for the transaction. Supported for the PayPal payment method only. Value is:
    • 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.

    Possible values: ELIGIBLE, PARTIALLY_ELIGIBLE, INELIGIBLE.

  • protection_eligibility_type

    enum

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

    Returns one or both of the allowed values.

    Value is:
    • ITEM_NOT_RECEIVED_ELIGIBLE. Sellers are protected against claims for items not received.
    • UNAUTHORIZED_PAYMENT_ELIGIBLE. Sellers are protected against claims for unauthorized payments.

    Read only.

    Possible values: ITEM_NOT_RECEIVED_ELIGIBLE, UNAUTHORIZED_PAYMENT_ELIGIBLE, ITEM_NOT_RECEIVED_ELIGIBLE,UNAUTHORIZED_PAYMENT_ELIGIBLE.

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

    Read only.

  • parent_payment

    string

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

    Read only.

  • processor_response

    object

    Response codes returned by the processor concerning the submitted payment. Only supported when the payment_method is set to credit_card.

    Read only.

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

  • reference_id

    string

    The ID of the purchase or transaction unit that corresponds to this authorization transaction.

    Read only.

    Maximum length: 256.

  • 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 object)

    HATEOAS links related to this call.

    Read only.

bank_account

  • account_number

    string

    The account number in either:

    Maximum length: 34.

  • account_number_type

    enum

    The type of the bank account number, which is an International Bank Account Number (IBAN) or Basic Bank Account Number (BBAN).

    Possible values: BBAN, IBAN.

  • routing_number

    string

    The routing transit number, or bank code, of the bank. Typically used for domestic accounts only. For international accounts, the IBAN includes the bank code. For more information, see Bank code.

    Maximum length: 34.

  • account_type

    enum

    The bank account type.

    Possible values: CHECKING, SAVINGS.

  • account_name

    string

    The customer-designated account name.

    Maximum length: 64.

  • check_type

    enum

    The check type. Valid when the facilitator or merchant obtained this information from a check.

    Possible values: PERSONAL, COMPANY.

  • auth_type

    enum

    The method by which the check was obtained from the customer, if a check was the source of the information.

    Possible values: CCD, PPD, TEL, POP, ARC, RCK, WEB.

  • auth_capture_timestamp

    string

    The date and time when the authorization was captured, in Internet date and time format. Use this field if the user authorization must be captured due to any privacy requirements.
  • bank_name

    string

    The bank name.

    Maximum length: 64.

  • country_code

    string

  • first_name

    string

    The account holder's first name.

    Maximum length: 64.

  • last_name

    string

    The account holder's last name.

    Maximum length: 64.

  • birth_date

    string

    The bank account holder's birth date, in Internet date format.
  • billing_address

    object

    The billing address.
  • state

    enum

    The funding instrument's state.

    Read only.

    Possible values: ACTIVE, INACTIVE, DELETED.

  • confirmation_status

    enum

    The bank account's confirmation status.

    Read only.

    Possible values: UNCONFIRMED, CONFIRMED.

  • payer_id

    string

    [DEPRECATED] The payer ID. Use external_customer_id instead.
  • external_customer_id

    string

    The facilitor-provided ID of the customer to whom this bank account belongs. Required when you create or use a funding instrument that is stored in the vault.

    Maximum length: 256.

  • merchant_id

    string

    The facilitator-provided ID of the merchant for which this bank account has been stored. Usage of the bank account is restricted to the specific merchant.

    Maximum length: 256.

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

  • valid_until

    string

    The date and time when the resource can no longer be used to fund a payment, in Internet date and time format.

    Read only.

  • links

    array (contains the link object)

    HATEOAS links related to this call.

    Read only.

bank_token

  • bank_id

    string

    The ID of a bank account that is stored in the PayPal vault.
  • external_customer_id

    string

    The ID of the payer that was used when this bank account was stored in the PayPal vault.
  • mandate_reference_number

    string

    The ID of the direct-debit mandate to validate. Supported for European Union (EU) Single Euro Payments Area (SEPA) bank accounts only.

billing_agreement_token

  • billing_agreement_token

    string

    The PayPal-generated billing agreement token. Returned by the /v1/billing-agreements/agreement-token API endpoint.

    Minimum length: 4.

    Maximum length: 20.

    Pattern: BA-([a-zA-Z0-9]){1,17}.

billing_instrument

  • billing_agreement_id

    string

    The ID of the instrument in the PayPal Wallet.

    Minimum length: 4.

    Maximum length: 20.

    Pattern: BA-([a-zA-Z0-9]){1,17}.

  • selected_installment_option

    object

    The selected installment option for the issuer-based installments (BR and MX).

capture

  • id

    string

    The ID of the capture transaction.

    Read only.

  • amount

    object

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

    boolean

    Indicates whether to release all remaining funds that the authorization holds in the funding instrument (FI). Default is false.

    Default: false.

  • state

    enum

    The capture state. Value is:
    • pending. The capture is pending.
    • completed. The capture has successfully completed.
    • refunded. The capture was fully refunded.
    • partially_refunded. The capture was partially refunded.

    Read only.

    Possible values: pending, completed, refunded, partially_refunded.

  • reason_code

    enum

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

    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.

  • 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 transaction fee for this payment.
  • create_time

    string

    The date and time when the capture occurred, in Internet date and time format as defined in RFC 3339 Section 5.6.

    Read only.

  • update_time

    string

    The date and time when the resource was last updated, in Internet date and time format as defined in RFC 3339 Section 5.6.

    Read only.

  • links

    array (contains the link object)

    HATEOAS links related to this call.

    Read only.

carrier_account

  • id

    string

    The ID of the payer's carrier account. Can be used in subsequent REST API calls, such as to make payments.
  • phone_number

    string

    The phone number of the payer, in E.164 format.
  • external_customer_id

    string

    The merchant-created ID for the customer.
  • phone_source

    enum

    The method that is used to obtain the phone number.

    Possible values: READ_FROM_DEVICE, USER_PROVIDED.

  • country_code

    object

    The two-character code for the country where the phone number is registered.

carrier_account_token

  • carrier_account_id

    string

    The ID of a carrier account that is stored in the PayPal vault.
  • external_customer_id

    string

    The ID of the payer that was used when the carrier account instrument was stored in the PayPal vault.

cart

  • reference_id

    string

    Optional. The merchant-provided ID for the purchase unit.

    Maximum length: 256.

  • amount

    object

    The amount to collect.
  • payee

    object

    The recipient of the funds in this transaction.
  • description

    string

    The description of what is being paid for.

    Maximum length: 127.

  • note_to_payee

    string

    An optional note to the recipient of the funds in this transaction.

    Maximum length: 255.

  • custom

    string

    A free-form field for clients' use.

    Maximum length: 127.

  • invoice_number

    string

    The invoice number to track this payment.

    Maximum length: 127.

  • purchase_order

    string

    purchase order is number or id specific to this payment

    Maximum length: 127.

  • soft_descriptor

    string

    The soft descriptor that is used when charging this funding source. If the string's length is greater than the maximum allowed length, the string is truncated.

    Maximum length: 22.

  • payment_options

    object

    The payment options requested for this transaction.
  • item_list

    object

    The list of items being paid for.
  • notify_url

    string

    The URL to send payment notifications.

    Maximum length: 2048.

  • order_url

    string

    The URL on the merchant site related to this payment.

    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 is used in that country's top-level domain names. Use the C2 country code for CHINA WORLDWIDE (for CUP, bank card, and cross-border transactions).

    Minimum length: 2.

    Maximum length: 2.

    Pattern: ^([A-Z]{2}|C2)$.

country_code

credit_card

  • number

    string

    The credit card number. Numeric characters only with no spaces or punctuation. The string must conform to the modulo and length required by each credit card type. Redacted in responses.
  • type

    string

    The credit card type. Value is visa, mastercard, discover, or amex.
  • expire_month

    see description

    The expiration month with no leading zero. Value is from 1 to 12.
    Possible types: integer
  • expire_year

    see description

    The four-digit expiration year.
    Possible types: integer
  • 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 associated with this card.
  • links

    array (contains the link object)

    HATEOAS links related to this call.

    Read only.

credit_card_token

  • credit_card_id

    string

    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. This ID can be any value you would like to associate with the saved card, such as a UUID, user name, or email address. Required when you use a vaulted credit card 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. Values are in lowercase; do not use these values for display.

    Read only.

  • expire_month

    see description

    The expiration month with no leading zero. Value is from 1 to 12.
    Possible types: integer

    Read only.

  • expire_year

    see description

    The four-digit expiration year.
    Possible types: integer

    Read only.

credit_financing_offered

  • total_cost

    object

    The estimated total payment amount. Includes any interest and fees that the payer must pay during the lifetime of the loan.

    Read only.

  • term

    number

    The length of financing terms, in months.

    Read only.

  • monthly_payment

    object

    The estimated amount per month that the payer must pay. Includes fees and interest.

    Read only.

  • total_interest

    object

    The estimated amount of interest or fees that the payer must pay during the lifetime of the loan.

    Read only.

  • payer_acceptance

    boolean

    The acceptance status of the payer. Indicates whether PayPal approved the payer for installment credit and the payer chose to use this payment method.

    Read only.

  • cart_amount_immutable

    boolean

    Indicates whether the payer can edit the cart amount after PayPal approved the payer. Default is false.

    Read only.

    Default: false.

credit_instrument

  • id

    string

    The ID of the credit instrument.

    Read only.

  • type

    enum

    The type of credit.

    Read only.

    Possible values: BILL_ME_LATER, PAYPAL_EXTRAS_MASTERCARD, EBAY_MASTERCARD, PAYPAL_SMART_CONNECT.

currency

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

    The three-character ISO-4217 currency code of the currency from which to convert the from amount.

    Read only.

  • from_amount

    string

    The from amount, which is the pre-currency conversion value. Default is 1.

    Read only.

  • to_currency

    string

    The three-character ISO-4217 currency code of the currency into which to convert the from amount.

    Read only.

  • to_amount

    string

    The to amount, which is the post-currency conversion value.

    Read only.

  • conversion_type

    enum

    The conversion type to apply.

    Possible values: PAYPAL, VENDOR.

    Default: PAYPAL.

  • conversion_type_changeable

    boolean

    Indicates whether the payer can change the conversion type.

    Read only.

  • spread

    string

    The rate in percentage which PayPal charges that is above the foreign exchange rate provided by PayPal’s financial partners.

    Read only.

  • links

    array (contains the link object)

    HATEOAS links related to this call.

    Read only.

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

    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.

  • reason_code

    enum

    The reason code for the pending refund state.

    Read only.

    Possible values: ECHECK.

  • refund_reason_code

    enum

    The PayPal-assigned reason codes for the refund.

    Read only.

    Possible values: ADJUSTMENT_REVERSAL, ADMIN_FRAUD_REVERSAL, ADMIN_REVERSAL, APPEAL, BUYER_COMPLAINT, CHARGEBACK, CHARGEBACK_SETTLEMENT, DENIED, DISPUTE_PAYOUT, FUNDING, GUARANTEE, LIMITS, NO_FAULT, OTHER, REFUND, REGULATORY_BLOCK, REGULATORY_REJECT, REGULATORY_REVIEW_EXCEEDING_SLA, RISK, SELLER_FAULT, SELLER_VOLUNTARY, THIRDPARTY_LOGISTICS_FAULT, UNAUTH_CLAIM, UNAUTH_SPOOF.

  • refund_funding_type

    enum

    Indicates whether the refund amount is funded by the payee's funding account or another funding account.

    Read only.

    Possible values: PAYOUT.

  • links

    array (contains the link object)

    HATEOAS links related to this call.

    Read only.

  • custom

    string

    A free-form field for the use by clients.

    Maximum length: 127.

  • refund_to_payer

    object

    The amount refunded to the payer of the original transaction, in the current refund call.
  • refund_to_external_funding

    array (contains the external_funding object)

    An external funding account.
  • refund_from_received_amount

    object

    The amount subtracted from the original payment recipient's PayPal balance to make this refund.

    Read only.

  • total_refunded_amount

    object

    The total amount refunded 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.

    Read only.

  • refund_to_msb

    object

    Amount refunded to the merchant specific balance (MSB).

    Read only.

details

  • subtotal

    string

    The subtotal amount for the items. If the request includes line items, this property is required. Maximum length is 10 characters. Supports two decimal places.
  • shipping

    string

    The shipping fee. Maximum length is 10 characters. Supports two decimal places.
  • tax

    string

    The tax. Maximum length is 10 characters. Supports two decimal places.
  • handling_fee

    string

    The handling fee. Supported for the PayPal payment method only.
  • shipping_discount

    string

    The shipping fee discount. Supported for the PayPal payment method only.
  • insurance

    string

    The insurance fee. Supported for the PayPal payment method only.
  • gift_wrap

    string

    The gift wrap fee.

display_phone

email_address

  • email_address

    string

    A valid internationalized email address, as defined by RFC 5322, RFC 6530, and other RFCs. To validate an email address, services must send an email to it and not rely on static validation of the address.

    Minimum length: 3.

    Maximum length: 254.

    Pattern: ^.+@[^"\-].+$.

error

  • name

    string

    The human-readable, unique name of the error.

    Read only.

  • message

    string

    A message that describes the error.

    Read only.

  • details

    array (contains the error_details object)

    The details for a specific error.

    Read only.

  • information_link

    string

    The URI to detailed information related to this error for the developer.

    Read only.

  • debug_id

    string

    The PayPal internal ID, which is used for correlation purposes.

    Read only.

  • links

    array (contains the link object)

    HATEOAS links related to this call.

    Read only.

error_details

  • field

    string

    The name of the field that caused the error.
  • issue

    string

    The reason for the error.

extended_bank_account

  • account_number

    string

    The account number in either:

    Maximum length: 34.

  • account_number_type

    enum

    The type of the bank account number, which is an International Bank Account Number (IBAN) or Basic Bank Account Number (BBAN).

    Possible values: BBAN, IBAN.

  • routing_number

    string

    The routing transit number, or bank code, of the bank. Typically used for domestic accounts only. For international accounts, the IBAN includes the bank code. For more information, see Bank code.

    Maximum length: 34.

  • account_type

    enum

    The bank account type.

    Possible values: CHECKING, SAVINGS.

  • account_name

    string

    The customer-designated account name.

    Maximum length: 64.

  • check_type

    enum

    The check type. Valid when the facilitator or merchant obtained this information from a check.

    Possible values: PERSONAL, COMPANY.

  • auth_type

    enum

    The method by which the check was obtained from the customer, if a check was the source of the information.

    Possible values: CCD, PPD, TEL, POP, ARC, RCK, WEB.

  • auth_capture_timestamp

    string

    The date and time when the authorization was captured, in Internet date and time format. Use this field if the user authorization must be captured due to any privacy requirements.
  • bank_name

    string

    The bank name.

    Maximum length: 64.

  • country_code

    string

  • first_name

    string

    The account holder's first name.

    Maximum length: 64.

  • last_name

    string

    The account holder's last name.

    Maximum length: 64.

  • birth_date

    string

    The bank account holder's birth date, in Internet date format.
  • billing_address

    object

    The billing address.
  • state

    enum

    The funding instrument's state.

    Read only.

    Possible values: ACTIVE, INACTIVE, DELETED.

  • confirmation_status

    enum

    The bank account's confirmation status.

    Read only.

    Possible values: UNCONFIRMED, CONFIRMED.

  • payer_id

    string

    [DEPRECATED] The payer ID. Use external_customer_id instead.
  • external_customer_id

    string

    The facilitor-provided ID of the customer to whom this bank account belongs. Required when you create or use a funding instrument that is stored in the vault.

    Maximum length: 256.

  • merchant_id

    string

    The facilitator-provided ID of the merchant for which this bank account has been stored. Usage of the bank account is restricted to the specific merchant.

    Maximum length: 256.

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

  • valid_until

    string

    The date and time when the resource can no longer be used to fund a payment, in Internet date and time format.

    Read only.

  • links

    array (contains the link object)

    HATEOAS links related to this call.

    Read only.

external_funding

  • reference_id

    string

    The ID for the external funding account.

    Maximum length: 256.

  • code

    string

    The generic ID for the external funding account.

    Maximum length: 256.

  • funding_account_id

    string

    The encrypted PayPal account ID for the funding account.
  • display_text

    string

    The description of the external funding account.

    Maximum length: 127.

  • amount

    object

    The amount that is funded by the external funding account.
  • funding_instruction

    enum

    Indicates whether the payment is to be fully funded by the external funded incentive.

    Possible values: FULLY_FUNDED.

fmf_details

  • filter_type

    enum

    The filter type.

    Read only.

    Possible values: ACCEPT, PENDING, DENY, REPORT.

  • filter_id

    enum

    The filter ID.

    Read only.

    Possible values: AVS_NO_MATCH, AVS_PARTIAL_MATCH, AVS_UNAVAILABLE_OR_UNSUPPORTED, CARD_SECURITY_CODE_MISMATCH, MAXIMUM_TRANSACTION_AMOUNT, UNCONFIRMED_ADDRESS, COUNTRY_MONITOR, LARGE_ORDER_NUMBER, BILLING_OR_SHIPPING_ADDRESS_MISMATCH, RISKY_ZIP_CODE, SUSPECTED_FREIGHT_FORWARDER_CHECK, TOTAL_PURCHASE_PRICE_MINIMUM, IP_ADDRESS_VELOCITY, RISKY_EMAIL_ADDRESS_DOMAIN_CHECK, RISKY_BANK_IDENTIFICATION_NUMBER_CHECK, RISKY_IP_ADDRESS_RANGE, PAYPAL_FRAUD_MODEL.

  • name

    string

    The filter name.

    Read only.

  • description

    string

    The filter description.

    Read only.

funding_instrument

  • credit_card

    object

    The credit card instrument.
  • credit_card_token

    object

    The PayPal vaulted credit card instrument.

funding_option

  • id

    string

    The ID of the funding option.
  • funding_sources

    array (contains the funding_source object)

    The funding source details.
  • backup_funding_instrument

    object

    The backup funding instrument. Used for payment if primary funding instrument fails.
  • currency_conversion

    object

    The currency conversion that applies to this funding option.
  • installment_info

    object

    The installment options available for a funding option.
  • links

    array (contains the link object)

    HATEOAS links related to this call.

    Read only.

funding_source

  • credit_card

    object

    The credit card instrument.
  • credit_card_token

    object

    The PayPal vaulted credit card instrument.
  • funding_mode

    enum

    The funding mode of the funding source.

    Read only.

    Possible values: INSTANT_TRANSFER, MANUAL_BANK_TRANSFER, DELAYED_TRANSFER, ECHECK, PAY_UPON_INVOICE.

  • funding_instrument_type

    enum

    The instrument type for this funding source.

    Read only.

    Possible values: BALANCE, PAYMENT_CARD, BANK_ACCOUNT, CREDIT, INCENTIVE, EXTERNAL_FUNDING, TAB.

  • soft_descriptor

    string

    The soft descriptor for charging this funding source.

    Read only.

    Maximum length: 22.

  • amount

    object

    The total amount that is anticipated to be pulled from the funding source.

    Read only.

  • negative_balance_amount

    object

    The additional amount to be pulled from the source to recover a negative balance on the buyer's account that is owed to PayPal.

    Read only.

  • legal_text

    string

    The localized legal text for the funding source.
  • terms

    string

    The URL to legal terms for the funding source.
  • funding_detail

    object

    The additional details for the funding source.
  • funding_selection_preference

    enum

    The preferred way to select this funding source.

    Read only.

    Possible values: NONE, WALLET_PREFERRED, PAYMENT_PREFERRED, SYSTEM_DEFAULTED.

  • additional_text

    string

    Additional text for the funding source.
  • links

    array (contains the link object)

    HATEOAS links related to this call.

    Read only.

incentive

  • id

    string

    The ID of the instrument in the PayPal Wallet.

    Read only.

  • code

    string

    The code that identifies the incentive.
  • name

    string

    The incentive name.

    Read only.

  • description

    string

    The incentive description.

    Read only.

  • minimum_purchase_amount

    object

    The minimum purchase amount to which this incentive applies.

    Read only.

  • logo_image_url

    string

    The logo image URL for the incentive.

    Read only.

  • expiry_date

    string

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

    Read only.

  • type

    enum

    The type of incentive.

    Read only.

    Possible values: COUPON, GIFT_CARD, MERCHANT_SPECIFIC_BALANCE, VOUCHER, LOYALTY_CARD, MANUFACTURER_COUPON.

  • terms

    string

    The URI to the associated terms.

    Read only.

installment_option

  • term

    see description

    The number of installments.
    Possible types: integer
  • monthly_payment

    object

    The monthly payment.
  • discount_amount

    object

    The discount amount applied to the payment, if any.
  • discount_percentage

    string

    The discount percentage applied to the payment, if any.

installment_options

  • installment_id

    string

    The installment ID.

    Read only.

  • network

    enum

    The credit card network.

    Read only.

    Possible values: VISA, MASTERCARD.

  • issuer

    string

    The credit card issuer.

    Read only.

  • installment_options

    array (contains the installment_option object)

    An installment option.

item

  • sku

    string

    The stock keeping unit (SKU) for the item.

    Maximum length: 127.

  • name

    string

    The item name. Maximum length is 127 characters.
  • description

    string

    The item description. Supported for the PayPal payment method only.

    Maximum length: 127.

  • quantity

    string

    The item quantity. Maximum length is 10 characters.
  • price

    string

    The item cost. Maximum length is 10 characters.
  • currency

    string

  • tax

    string

    The item tax. Supported for the PayPal payment method only.
  • url

    string

    The URL to item information. Available to the payer in the transaction history.

item_list

  • items

    array (contains the item object)

    The item details.
  • shipping_address

    object

    The shipping address.
  • shipping_method

    string

    The shipping method used for this payment, such as USPS Parcel.
  • 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.

item_option_selection

  • name

    string

    The name of the item optional data.

    Maximum length: 64.

  • select

    string

    The description of the item optional selected value.

    Maximum length: 200.

  • amount

    object

    The amount being charged for the item resulting from the specific selected value of the name parameter.

json_patch

  • op

    enum

    The operation to perform.

    Possible values: add, remove, replace, move, copy, test.

  • path

    string

    A JSON pointer that references a location in the target document where the operation is performed.
  • value

    see description

    The value to apply based on the operation. The remove operation does not require a value.
    Possible types: number, integer, string, boolean, null, array, object
  • from

    string

    A JSON pointer that references the location in the target document from which to move the value. Required for the move operation.

json_patch_request

  • items

    (contains the json_patch object)

    A JSON patch object to use to apply partial updates to resources.

measurement

  • value

    string

    The measurement value.
  • unit

    string

    The measurement unit.

name_and_value_pair

  • name

    string

    The key for the name-and-value pair. You must correlate the value and name types.
  • value

    string

    The value for the name-and-value pair.

order

  • id

    string

    The ID of the order transaction.

    Read only.

  • reference_id

    string

    The ID of the purchase unit that is associated with this object. Obsolete. Used only in cart_base.

    Read only.

  • amount

    object

    The amount to collect.
  • payment_mode

    enum

    The transaction payment mode.

    Read only.

    Possible values: INSTANT_TRANSFER, MANUAL_BANK_TRANSFER, DELAYED_TRANSFER, ECHECK.

  • state

    enum

    The order transaction state.

    Read only.

    Possible values: pending, completed, voided, authorized, captured.

  • reason_code

    enum

    The reason code that describes why the transaction state is pending or reversed. Eventually, this parameter will replace the pending_reason parameter. Supported only when the payment_method is paypal.

    Read only.

    Possible values: PAYER_SHIPPING_UNCONFIRMED, MULTI_CURRENCY, RISK_REVIEW, REGULATORY_REVIEW, VERIFICATION_REQUIRED, ORDER, OTHER.

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

    Read only.

    Possible values: ELIGIBLE, PARTIALLY_ELIGIBLE, INELIGIBLE.

  • 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 when the payment_method is paypal. One or both of these values can be returned:
    • ITEM_NOT_RECEIVED_ELIGIBLE. Sellers are protected against claims for items not received.
    • UNAUTHORIZED_PAYMENT_ELIGIBLE. Sellers are protected against claims for unauthorized payments.

    Read only.

    Possible values: ITEM_NOT_RECEIVED_ELIGIBLE, UNAUTHORIZED_PAYMENT_ELIGIBLE, ITEM_NOT_RECEIVED_ELIGIBLE,UNAUTHORIZED_PAYMENT_ELIGIBLE.

  • 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 applied for the payment that can result in an accept, deny, or pending action.

    Read only.

  • 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 object)

    HATEOAS links related to this call.

    Read only.

partner_fee_details

  • receiver

    object

    The partner who receives the partner fees.
  • amount

    object

    The amount being collected as partner fee.

payee

  • email

    string

    The email address associated with the payee's PayPal account. If the provided email address is not associated with any PayPal account, the payee can only receive PayPal Wallet payments. Direct credit card payments are denied due to card compliance requirements.
  • merchant_id

    string

    The PayPal account ID for the payee.
  • payee_display_metadata

    object

    Payee metadata references display only metadata for the Payee

payee_metadata_info

  • email

    string

    The email address for the payer. Maximum length is 127 characters.
  • display_phone

    object

    Payee information.
  • brand_name

    string

    The payer's business name.

payer

  • payment_method

    enum

    The payment method. Value is:
    • credit_card. Direct credit card or bank direct debit.
    • paypal. PayPal Wallet payment.

    Possible values: credit_card, paypal.

  • status

    enum

    The status of payer's PayPal account.

    Read only.

    Possible values: VERIFIED, UNVERIFIED.

  • funding_instruments

    array (contains the funding_instrument object)

    A payer's funding instrument. An instance of this schema is valid if and only if it is valid against exactly one of these supported properties.
  • payer_info

    object

    The payer-related information. If the payment_method is paypal, you must set the email address of the PayPal account that funds the transaction in the payer_info.

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.

  • phone

    string

    The payer's phone number. Maximum length is 20 characters.

    Read only.

  • phone_type

    enum

    The phone type.

    Read only.

    Possible values: HOME, WORK, MOBILE, OTHER.

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

    Possible values: BR_CPF, BR_CNPJ.

  • country_code

    string

  • billing_address

    object

    The payer's billing address.
  • shipping_address

    object

    [DEPRECATED] The shipping address. Use the shipping address for the purchase unit or at the root level of the checkout session.

    Read only.

payer_notification

  • email

    string

    The email address that is associated with the payer's PayPal account.

payment

  • id

    string

    The ID of the payment.

    Read only.

  • intent

    enum

    The payment intent. Value is:

    Possible values: sale, authorize, order.

  • payer

    object

    The source of the funds for this payment. Payment method is PayPal Wallet payment, bank direct debit, or direct credit card.
  • 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.
  • state

    enum

    The state of the payment, authorization, or order transaction. Value is:
    • created. The transaction was successfully created.
    • approved. The buyer approved the transaction.
    • 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 object)

    HATEOAS links related to this call.

    Read only.

payment_card

  • id

    string

    The ID of a credit card to save for later use.

    Read only.

  • number

    string

    The card number.
  • type

    enum

    An enumeration of the card types.

    Possible values: VISA, AMEX, SOLO, JCB, STAR, DELTA, DISCOVER, SWITCH, MAESTRO, CB_NATIONALE, CONFINOGA, COFIDIS, ELECTRON, CETELEM, CHINA_UNION_PAY, MASTERCARD.

  • expire_month

    string

    The two-digit expiry month for the card. Valid value is from 01 to 12.

    Pattern: ([1-9]|0[1-9]|1[012]).

  • expire_year

    string

    The four-digit expiry year for the card.

    Pattern: [0-9]{4}.

  • start_month

    string

    The two-digit start month for the card. Valid value is from 01 to 12. Required for UK Maestro cards.

    Pattern: ([1-9]|0[1-9]|1[012]).

  • start_year

    string

    The four-digit start year for the card. Required for UK Maestro cards.

    Pattern: [0-9]{4}.

  • cvv2

    string

    The validation code for the card. Supported for payments. Not supported for vaulting payment cards for future use.
  • first_name

    string

    The card holder's first name.
  • last_name

    string

    The card holder's last name.
  • billing_country

    string

  • billing_address

    object

    The billing address for the card.
  • external_customer_id

    string

    The facilitator-provided ID of the customer who owns this card account. Required when you create or use a funding instrument that is stored in the PayPal vault.

    Maximum length: 256.

  • status

    enum

    The funding instrument's state.

    Read only.

    Possible values: EXPIRED, ACTIVE.

  • card_product_class

    enum

    An enumeration of the product classes of the financial instrument issuer.

    Read only.

    Possible values: CREDIT, DEBIT, GIFT, PAYPAL_PREPAID, PREPAID, UNKNOWN.

  • valid_until

    string

    The date and time when the instrument can no longer be used to fund a payment, in Internet date and time format.

    Read only.

  • issue_number

    string

    The one- to two-digit card issue number. Required for UK Maestro cards.

    Maximum length: 2.

    Pattern: [0-9]{1,2}.

  • links

    array (contains the link object)

    HATEOAS links related to this call.

    Read only.

payment_execution

  • payer_id

    string

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

    array (contains the cart object)

    A cart.

payment_history

  • payments

    array (contains the payment object)

    A payment. Use this object to create, process, and manage payments.
  • count

    see description

    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. The maximum value is 20.
    Possible types: integer
  • next_id

    string

    The ID of the next element. Use to get the next range of results.

    Read only.

payment_instruction

  • reference_number

    string

    The ID of the payment instruction.

    Read only.

    Maximum length: 128.

  • instruction_type

    enum

    The payment instruction type.

    Read only.

    Possible values: MANUAL_BANK_TRANSFER, PAY_UPON_INVOICE.

  • recipient_banking_instruction

    object

    The recipient bank details.
  • amount

    object

    The amount to transfer.

    Read only.

  • payment_due_date

    string

    The date and time by when payment should be received.

    Read only.

  • note

    string

    A note about payment handling.

    Maximum length: 256.

  • links

    array (contains the link object)

    HATEOAS links related to this call.

    Read only.

payment_options

  • allowed_payment_method

    enum

    The payment method requested for this transaction. This field does not apply to the credit card payment method.

    Possible values: UNRESTRICTED, INSTANT_FUNDING_SOURCE, IMMEDIATE_PAY.

percentage

  • percentage

    string

    A percentage as a fixed-point, signed decimal value. Use for all interest rates. For example, represent an interest rate of 19.99% as 19.99. The allowed number formats are plain decimal numbers and whole numbers. Unlike a JSON number or JSON Schema number type, this value MUST NOT be deserialized in JavaScript into a JavaScript Number object, which is 64-bit floating-point and cannot accurately represent all values transmitted by this type. Likewise, in Java, this type MUST be deserialized into a BigDecimal or other fixed-point numeric type.

    Pattern: ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$.

private_label_card

  • id

    string

    The encrypted ID of the private label card instrument.

    Read only.

  • card_number

    string

    The last four digits of the card number.

    Read only.

  • issuer_id

    string

    The encrypted account number of the associated issuer accounts. Merchants who provide private label store cards have associated issuer account.

    Read only.

  • issuer_name

    string

    The name on the issuer account. Merchants who provide private label store cards have associated issuer accounts.

    Read only.

  • image_key

    string

    The URL to the PLCC program logo image.

    Read only.

processor_response

  • response_code

    string

    The PayPal normalized response code, which is generated from the processor's specific response code.

    Read only.

    Maximum length: 4.

  • avs_code

    string

    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.

    Read only.

    Possible values: 01_NEW_ACCOUNT_INFORMATION, 02_TRY_AGAIN_LATER, 02_STOP_SPECIFIC_PAYMENT, 03_DO_NOT_TRY_AGAIN, 03_REVOKE_AUTHORIZATION_FOR_FUTURE_PAYMENT, 21_DO_NOT_TRY_AGAIN_CARD_HOLDER_CANCELLED_RECURRRING_CHARGE, 21_CANCEL_ALL_RECURRING_PAYMENTS.

  • eci_submitted

    string

    The processor-provided authorization response.

    Read only.

  • vpas

    string

    The processor-provided Visa Payer Authentication Service status.

    Read only.

receipt

  • id

    string

    The ID of the receipt that was created for guest payments.

    Read only.

  • transaction_id

    string

    The ID of the receipt that was created for member payments. This ID is a debit-side transaction ID.

    Read only.

  • funding_sources

    array (contains the funding_source object)

    The funding source details.

    Read only.

  • items

    array (contains the item object)

    The item details.

    Read only.

  • shipping_address

    object

    The shipping address.

    Read only.

  • exchange_rate

    string

    The exchange rate that is applied for this transaction. Returned when the merchant-receiving currency is different from the transaction currency.

    Read only.

    Pattern: ^(([0-9]+)|(([0-9]+)?[.][0-9]+))$.

  • payee

    object

    The receiver of funds for this payment. Readonly for PayPal external REST payments.

    Read only.

  • payer_notification

    object (contains the payer_notification object)

    The payer's notification information.

    Read only.

  • amount

    object

    The amount being collected.

    Read only.

  • create_time

    string

    The date and time when the payment was created, in Internet date and time format as defined in RFC 3339 Section 5.6.

    Read only.

  • links

    array (contains the link object)

    HATEOAS links related to this call.

    Read only.

recipient_banking_instruction

  • bank_name

    string

    The financial institution name.

    Read only.

    Maximum length: 64.

  • account_holder_name

    string

    The account holder name.

    Read only.

    Maximum length: 128.

  • account_number

    string

    The bank account number.

    Read only.

    Maximum length: 34.

  • routing_number

    string

    The bank routing number.

    Read only.

    Maximum length: 34.

  • international_bank_account_number

    string

    The IBAN equivalent of the bank.

    Read only.

    Maximum length: 34.

  • bank_identifier_code

    string

    The BIC ID of the financial institution.

    Read only.

    Maximum length: 34.

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.

    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.

    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.

  • reason_code

    enum

    The reason code for the pending refund state.

    Read only.

    Possible values: ECHECK.

  • refund_reason_code

    enum

    The PayPal-assigned reason codes for the refund.

    Read only.

    Possible values: ADJUSTMENT_REVERSAL, ADMIN_FRAUD_REVERSAL, ADMIN_REVERSAL, APPEAL, BUYER_COMPLAINT, CHARGEBACK, CHARGEBACK_SETTLEMENT, DENIED, DISPUTE_PAYOUT, FUNDING, GUARANTEE, LIMITS, NO_FAULT, OTHER, REFUND, REGULATORY_BLOCK, REGULATORY_REJECT, REGULATORY_REVIEW_EXCEEDING_SLA, RISK, SELLER_FAULT, SELLER_VOLUNTARY, THIRDPARTY_LOGISTICS_FAULT, UNAUTH_CLAIM, UNAUTH_SPOOF.

  • refund_funding_type

    enum

    Indicates whether the refund amount is funded by the payee's funding account or another funding account.

    Read only.

    Possible values: PAYOUT.

  • links

    array (contains the link object)

    HATEOAS links related to this call.

    Read only.

refund_request

  • amount

    object

    The refund amount. Includes both the amount refunded to the payer and amount of the fee refunded to the payee.
  • description

    string

    The refund description. Value must be single-byte alphanumeric characters.

    Maximum length: 255.

  • refund_source

    enum

    The PayPal funding source type, such as balance or eCheck, to use for auto refund.

    Possible values: INSTANT_FUNDING_SOURCE, ECHECK, UNRESTRICTED.

    Default: UNRESTRICTED.

  • reason

    string

    The refund reason description.

    Maximum length: 30.

  • invoice_number

    string

    The invoice number that is used to track this payment.

    Maximum length: 127.

  • refund_advice

    boolean

    Indicates whether store credit was already given to the payer.
  • items

    array (contains the item object)

    The item details.
  • payer_info

    object

    Payer details.
  • supplementary_data

    array (contains the name_and_value_pair object)

    A type for name-and-value pairs. Limit the use of name-and-value pairs in an API. Requires approval from architecture.

sale

  • id

    string

    The ID of the sale transaction.

    Read only.

  • purchase_unit_reference_id

    string

    The ID of the transaction that corresponds to this sale transaction.

    Read only.

  • amount

    object

    The amount being collected.

    Read only.

  • payment_mode

    enum

    The transaction payment mode. Supported only when payment_method is paypal.

    Read only.

    Possible values: INSTANT_TRANSFER, MANUAL_BANK_TRANSFER, DELAYED_TRANSFER, ECHECK.

  • state

    enum

    The sale transaction state.

    Read only.

    Possible values: completed, partially_refunded, pending, refunded, denied.

  • reason_code

    enum

    The reason code that describes why the transaction state is pending or reversed. Supported only when the payment_method is paypal.

    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 seller protection level in effect for the transaction. Supported only when the payment_method is paypal.

    Read only.

    Possible values: ELIGIBLE, PARTIALLY_ELIGIBLE, INELIGIBLE.

  • protection_eligibility_type

    enum

    The seller protection type in effect for the transaction. Returned only when protection_eligibility is ELIGIBLE or PARTIALLY_ELIGIBLE. Supported only when the payment_method is paypal.

    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 eCheck transaction is expected to clear. Returned for eCheck payments. Supported only when the payment_method is paypal.

    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

    The reason that PayPal holds the recipient fund. Set only if the payment hold status is held.

    Read only.

  • transaction_fee

    object

    The transaction fee that applies for this payment.

    Read only.

  • receivable_amount

    object

    The net amount 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.

    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 for the payment that might result in 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.

    Read only.

  • 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 response codes that the processor returns for the submitted payment. Supported only when the payment_method is credit_card.

    Read only.

  • 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 as defined in RFC 3339 Section 5.6.

    Read only.

  • update_time

    string

    The date and time when the resource was last updated, in Internet date and time format in RFC 3339 Section 5.6.

    Read only.

  • links

    array (contains the link object)

    HATEOAS links related to this call.

    Read only.

shipping_address

  • line1

    string

    The first line of the address. For example, number, street, and so on. Maximum length is 100 characters.
  • line2

    string

    The second line of the address. For example, suite, apartment number, and so on. Maximum length is 100 characters.
  • city

    string

    The city name. Maximum length is 50 characters.
  • country_code

    string

  • postal_code

    string

    The zip code or equivalent. Typically required for countries that have them. Maximum length is 20 characters. Required in certain countries.
  • state

    string

    The two-letter code for US states or the equivalent for other countries. Maximum length is 100 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.

    Read only.

    Possible values: UNKNOWN, UNNORMALIZED_USER_PREFERRED, NORMALIZED, UNNORMALIZED.

  • 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_details

  • estimated_delivery_date

    string

    The estimated date and time of delivery, in Internet date and time format. For example, 2017-08-15.
  • delivery_location_type

    enum

    The type of shipment delivery location.

    Possible values: CONSUMER, STORE, LOCKER.

  • delivery_location_id

    string

    The ID of the non-consumer location type.

    Maximum length: 50.

  • shipment_category

    enum

    The shipment category.

    Possible values: INTERNATIONAL_SHIPPING, LOCAL_PICKUP, BUY_ONLINE_PICKUP_IN_STORE, PICK_UP_DROP_OFF.

  • fulfillment_address

    object

    The third party logistics (3PL) domestic fulfillment center address where merchants ship merchandise intended for buyers.
  • fulfillment_reference_number

    string

    The reference number associated with the third-party shipping or fulfillment center. Required if a fulfillment address exists.

    Maximum length: 32.

    Pattern: ^[a-zA-Z0-9_]*$.

standin_funding_option

  • standin_funding_token

    string

    An encrypted token for the instrument to use to fund the payment.

    Maximum length: 256.

transaction

  • reference_id

    string

    Optional. The merchant-provided ID for the purchase unit.

    Maximum length: 256.

  • amount

    object

    The amount to collect.
  • payee

    object

    The recipient of the funds in this transaction.
  • description

    string

    The description of what is being paid for.

    Maximum length: 127.

  • note_to_payee

    string

    An optional note to the recipient of the funds in this transaction.

    Maximum length: 255.

  • custom

    string

    A free-form field for clients' use.

    Maximum length: 127.

  • invoice_number

    string

    The invoice number to track this payment.

    Maximum length: 127.

  • purchase_order

    string

    purchase order is number or id specific to this payment

    Maximum length: 127.

  • soft_descriptor

    string

    The soft descriptor that is used when charging this funding source. If the string's length is greater than the maximum allowed length, the string is truncated.

    Maximum length: 22.

  • payment_options

    object

    The payment options requested for this transaction.
  • item_list

    object

    The list of items being paid for.
  • notify_url

    string

    The URL to send payment notifications.

    Maximum length: 2048.

  • order_url

    string

    The URL on the merchant site related to this payment.

    Maximum length: 2048.

  • related_resources

    array (contains the related_resources object)

    The financial transactions that are related to the payment. The related resources include sales, authorizations, captures, and refunds. To get information about a resource, use the ID returned for that resource. For example, to show details for a related authorization, use the ID returned in the authorization object. You can also use the HATEOAS links for a related resource to complete operations for that resource. For example, a sale object provides a refund link that enables you to refund the sale.

    Read only.

Additional API information

Error messages

In addition to common REST API errors, the Payments API can return the following errors. Corrective action is provided where possible.

  • AGREEMENT_ALREADY_CANCELLED

    The requested agreement is already canceled. This error occurs when the agreement used to make the payment is already canceled.

  • AMOUNT_MISMATCH

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

  • AUTHORIZATION_ALREADY_COMPLETED

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

  • AUTHORIZATION_CANNOT_BE_VOIDED

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

  • AUTHORIZATION_EXPIRED

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

  • AUTHORIZATION_ID_DOES_NOT_EXIST

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

  • AUTHORIZATION_VOIDED

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

  • BANK_ACCOUNT_VALIDATION_FAILED

    Bank account validation 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. Reauthorization only works on an original authorization ID.

  • CANNOT_REAUTH_INSIDE_HONOR_PERIOD

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

  • CAPTURE_AMOUNT_LIMIT_EXCEEDED

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

  • CARD_TOKEN_PAYER_MISMATCH

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

  • CREDIT_CARD_CVV_CHECK_FAILED

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

  • CREDIT_CARD_REFUSED

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

  • CREDIT_PAYMENT_NOT_ALLOWED

    Buyer cannot use credit to complete the payment. Credit cannot be used to complete this payment. Ask the buyer to retry with alternate funding instrument.

  • CURRENCY_MISMATCH

    Currency of capture must be the same as currency of authorization. The currency used when capturing an authorization must match the original currency of the authorization.

  • CURRENCY_NOT_ALLOWED

    Currency is not supported. You are using a currency that is not currently supported.

  • DCC_PREPROCESSOR_ERROR

    Error setting up a DCC transaction. A problem occurred during set up to process a Direct Credit Card (DCC) transaction. If this error persists, contact PayPal Merchant Technical Support.

  • DUPLICATE_REQUEST_ID

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

  • EXPIRED_CREDIT_CARD

    Credit card is expired. Use an unexpired credit card.

  • EXPIRED_CREDIT_CARD_TOKEN

    Credit card token is expired. Store the credit card again by using the Vault API.

  • FAILED_TO_CHARGE_CC

    Failed to charge credit card.

  • 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. You cannot refund the full payment amount after you have partially refunded a payment.

  • IMMEDIATE_PAY_NOT_SUPPORTED

    Immediate pay is not supported for the specified payment intent.

  • INSTRUMENT_DECLINED

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

  • INSUFFICIENT_FUNDS

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

  • INTERNAL_SERVICE_ERROR

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

  • INVALID_ACCOUNT_NUMBER

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

  • INVALID_CITY_STATE_ZIP

    The combination of city, state, and zip in the address is invalid.

  • INVALID_EXPERIENCE_PROFILE_ID

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

  • INVALID_FACILITATOR_CONFIGURATION

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

  • INVALID_PAYER_ID

    Payer ID is invalid. The specified payer_id is invalid. Resend the request by using a valid payer_id.

  • INVALID_RESOURCE_ID

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

  • MALFORMED_REQUEST

    JSON request is malformed. Review the JSON request.

  • MAXIMUM_ALLOWED_AUTHORIZATION_REACHED_FOR_ORDER

    Maximum number of allowed authorizations for the order is reached. You have reached the maximum number of authorizations allowed for this order.

  • MERCHANT_NOT_ENABLED_FOR_CHANNEL_INITIATED_BILLING

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

  • MERCHANT_NOT_ENABLED_FOR_REFERENCE_TRANSACTION

    Merchant is not enabled for reference transaction. The merchant is not enabled for the 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. API capability is not implemented.

  • ORDER_ALREADY_COMPLETED

    Order has already been voided, expired, or completed.

  • ORDER_CANNOT_BE_VOIDED

    Order is in {0} state and hence cannot be voided.

  • ORDER_VOIDED

    Order has been voided. Order is already voided. You can show order details.

  • PAYEE_ACCOUNT_LOCKED_OR_CLOSED

    Payee account is locked or closed. The account receiving this payment is locked or closed and cannot receive payments.

  • PAYEE_ACCOUNT_NO_CONFIRMED_EMAIL

    Refused - payee account does not have a confirmed email. The payment recipient must have a confirmed email for this transaction to proceed.

  • PAYEE_ACCOUNT_RESTRICTED

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

  • PAYEE_BLOCKED_TRANSACTION

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

  • PAYEE_COUNTRY_NOT_ENABLED

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

  • PAYER_ACCOUNT_RESTRICTED

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

  • PAYER_CANNOT_PAY

    The combination of payer and payee settings mean that this buyer can't pay this seller.

  • PAYER_COUNTRY_NOT_ENABLED

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

  • PAYER_EMPTY_BILLING_ADDRESS

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

  • PAYER_ID_MISSING_FOR_CARD_TOKEN

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

  • PAYMENT_ALREADY_DONE

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

  • PAYMENT_APPROVAL_EXPIRED

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

  • PAYMENT_CANNOT_BE_INITIATED

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

  • PAYMENT_DENIED

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

  • PAYMENT_EXPIRED

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

  • PAYMENT_METHOD_UNUSABLE

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

  • PAYMENT_NOT_APPROVED_FOR_EXECUTION

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

  • 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. The payment state does not allow this kind of request.

  • PERMISSION_DENIED

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

  • PHONE_NUMBER_REQUIRED

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

  • REFUND_EXCEEDED_TRANSACTION_AMOUNT

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

  • REFUND_TIME_LIMIT_EXCEEDED

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

  • REQUIRED_SCOPE_MISSING

    Access token does not have required scope. Get user consent by using the correct scope required for this type of request.

  • SENDING_LIMIT_EXCEEDED

    The transaction exceeds the buyer's sending limit.

  • SHIPPING_ADDRESS_INVALID

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

  • TOO_MANY_REAUTHORIZATIONS

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

  • TRANSACTION_ALREADY_REFUNDED

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

  • TRANSACTION_LIMIT_EXCEEDED

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

  • TRANSACTION_REFUSED

    This request was refused. Possible reasons:

    • The partial refund amount must be less than or equal to the original transaction amount.
    • The partial refund amount must be less than or equal to the remaining amount.
    • The partial refund amount is not valid.
    • The partial refund must be the same currency as the original transaction.
    • Partial refunds can’t be offered at this time because there is an open case on this transaction. Visit the PayPal Resolution Center to review this case.
    • You are over the time limit to perform a refund on this transaction.
    • Cannot do a full refund after a partial refund.
    • Transaction was fully refunded.
    • You cannot refund this type of transaction.
    • You cannot do a partial refund on this transaction.
    • The merchant account has limitations or restrictions.

  • TRANSACTION_REFUSED_PAYEE_PREFERENCE

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

  • UNSUPPORTED_PAYEE_COUNTRY

    Payee country is not supported for this transaction. Seller is not accepting payments from this country.

  • UNSUPPORTED_PAYEE_CURRENCY

    The currency is not accepted by payee. Seller is not accepting payments in this currency.

  • VALIDATION_ERROR

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