REST API Reference

Non-US developers: please read our FAQ.

The PayPal API uses HTTP verbs and a RESTful endpoint structure. OAuth 2.0 is used as the API Authorization framework. Request and response payloads are formatted as JSON.

Table of Contents

Click a tab to see sample code in the corresponding language.

cURL calls

We use cURL calls in this guide so that you can try them yourself. You can download cURL software if needed. Be sure to include your own access token and payment-specific IDs for calls.

Important: The sample requests in this guide are examples only and not runnable as-is. You should substitute all call-specific parameters (such as tokens and IDs) with your own values.

Ruby SDK

Prerequisites

  • Ruby 1.8.7 or above
  • Bundler

All Ruby request samples use and are dependent on the Ruby SDK.

gem install paypal-sdk-rest

If you are using bundler, you can add the following to your Gemfile before running the bundle command:

gem 'paypal-sdk-rest'

Source and documentation at: github.com/paypal/rest-api-sdk-ruby

Python SDK

Prerequisites

  • Python 2.6 or above
  • requests

All Python request samples use and are dependent on the Python SDK.

pip install paypalrestsdk

Source and documentation at: github.com/paypal/rest-api-sdk-python

Node.js SDK

Prerequisites

  • node.js 0.6.x or above

All node.js request samples use and are dependent on the node.js SDK.

npm install paypal-rest-sdk

Source and documentation at: github.com/paypal/rest-api-sdk-nodejs

PHP SDK

Prerequisites

  • PHP 5.3 or above
  • curl, json, and openssl extensions enabled

All PHP request samples use and are dependent on the PHP SDK.

To use the SDK in your app, create a composer.json file with the following require section and run composer update

"require": {
    "php": ">=5.3.0",
    "ext-curl": "*",
    "ext-json": "*",
    "paypal/rest-api-sdk-php" : "0.5.*"
}

Source and documentation at: github.com/paypal/rest-api-sdk-php

Java SDK

Prerequisites

  • Java JDK 1.5 or higher
  • Apache Maven 3 or higher

All Java request samples use and are dependent on the Java SDK.

If you are using Maven, add the following dependency to your POM:

<dependency>
  <groupId>com.paypal.sdk</groupId>
  <artifactId>rest-api-sdk</artifactId>
  <version>0.5.2</version>
</dependency>

Source and documentation at: github.com/paypal/rest-api-sdk-java

.NET SDK

Prerequisites

  • .NET 4.0 or higher
  • NuGet 2.2 or higher

All C# request samples use and are dependent on the .NET SDK.

To install the .NET SDK as a dependency in your project, run the following command in the NuGet Package Manager Console:

Install-Package PayPal

Source and documentation are available on GitHub.

API operations

The PayPal REST APIs are supported in two environments. Use the Sandbox environment for testing purposes, then move to the live environment for production processing. When testing, generate an access token with your test credentials to make calls to the Sandbox URIs. When you’re set to go live, use the live credentials assigned to your app to generate a new access token to be used with the live URIs.

Note If you’re looking for the endpoints to PayPal’s non-RESTful APIs, refer to the Classic API endpoints.

The following endpoints address our two environments:

  • Sandbox (for testing) : https://api.sandbox.paypal.com
  • Live (production) : https://api.paypal.com

A complete REST operation is formed by combining an HTTP method (or “verb”) with the full URI to the resource you’re addressing. For example, here is the operation to create a new payment:

POST https://api.paypal.com/v1/payments/payment

To create a complete request, combine the operation with the appropriate HTTP headers and any required JSON payload.

Operation summary

Here are the available REST API operations:

Payments namespace

payment: create, execute, update, and look up payments

GET POST /v1/payments/payment
GET PATCH /v1/payments/payment/<Payment-Id>
POST /v1/payments/payment/<Payment-Id>/execute/

sale: look up and refund completed payments

GET /v1/payments/sale/<Transaction-Id>
POST /v1/payments/sale/<Transaction-Id>/refund

refund: look up refund details

GET /v1/payments/refund/<Refund-Id>

authorization: look up, capture, reauthorize, and void authorized payments

GET /v1/payments/authorization/<Authorization-Id>
POST /v1/payments/authorization/<Authorization-Id>/capture
POST /v1/payments/authorization/<Authorization-Id>/void
POST /v1/payments/authorization/<Authorization-Id>/reauthorize

capture: look up and refund captured payments

GET /v1/payments/capture/<Capture-Id>
POST /v1/payments/capture/<Capture-Id>/refund

billing plans: Create, retrieve, update, and list billing plans

POST /v1/payments/billing-plans
GET PATCH /v1/payments/billing-plans/<Plan-Id>
GET /v1/payments/billing-plans

billing agreements: Create and manage billing agreements

POST /v1/payments/billing-agreements
POST /v1/payments/billing-agreements/<Payment-Token>/agreement-execute
GET PATCH /v1/payments/billing-agreements/<Agreement-Id>
POST /v1/payments/billing-agreements/<Agreement-Id>/suspend
POST /v1/payments/billing-agreements/<Agreement-Id>/re-activate
POST /v1/payments/billing-agreements/<Agreement-Id>/cancel
POST /v1/payments/billing-agreements/<Agreement-Id>/bill-balance
POST /v1/payments/billing-agreements/<Agreement-Id>/set-balance
GET /v1/payments/billing-agreements/<Agreement-Id>/transactions

orders: Manage orders

GET /v1/payments/orders/<Order-Id>
POST v1/payments/orders/<Order-Id>/authorize
POST /v1/payments/orders/<Order-Id>/do-void
POST /v1/payments/orders/<Order-Id>/capture
POST /v1/payments/capture/<Capture-Id>/refund

payouts: Create and manage payouts

POST /v1/payments/payouts
GET /v1/payments/payouts/<Payout-Batch-Id>
GET /v1/payments/payouts-item/<Payout-Item-Id>
POST /v1/payments/payouts-item/<Payout-Item-Id>/cancel

Vault namespace

credit-card: Store and look up credit cards

POST /v1/vault/credit-cards
DELETE GET PATCH /v1/vault/credit-cards/<Credit-Card-Id>

Identity namespace

openidconnect: Allow customers to log in to your website with a PayPal account

POST /v1/identity/openidconnect/tokenservice
GET /v1/identity/openidconnect/userinfo/?<Schema>

Invoicing namespace

invoices: Create and work with invoices

GET POST /v1/invoicing/invoices
GET PUT DELETE /v1/invoicing/invoices/<Invoice-Id>
GET /v1/invoicing/invoices?<Query-String>
GET /v1/invoicing/invoices/<Invoice-Id>/qr-code?<Query-String>
POST /v1/invoicing/invoices/<Invoice-Id>/send
POST /v1/invoicing/invoices/<Invoice-Id>/remind
POST /v1/invoicing/invoices/<Invoice-Id>/cancel
POST /v1/invoicing/invoices/<Invoice-Id>/record-payment
POST /v1/invoicing/invoices/<Invoice-Id>/record-refund

Payment-experience namespace

web-profiles: Create and work with payment experience profiles

POST GET /v1/payment-experience/web-profiles
GET PUT PATCH DELETE /v1/payment-experience/web-profiles/<id>

Notifications namespace

webhooks: Create and manage webhooks

GET POST /v1/notifications/webhooks
GET PATCH DELETE /v1/notifications/webhooks/<Webhook-Id>
GET v1/notifications/webhooks/<Webhook-Id>/event-types

webhooks-events: Work with subscribed webhooks events

GET /v1/notifications/webhooks-events
GET /v1/notifications/webhooks-events/<Event-Id>
POST /v1/notifications/webhooks-events/<Event-Id>/resend

webhooks-event-types: List available subscription event types for webhooks

GET /v1/notifications/webhooks-event-types

Authentication & Headers

With each API call, you’ll need to set request headers, including an OAuth 2.0 access token. Get an access token by using the OAuth 2.0 client_credentials token grant type with your clientId:secret as your Basic Auth credentials. For more information, see Make your first call. You can use your Sandbox access token to try any of the code in this reference.

Authorization When requesting an access token, send the value as the HTTP Basic Authentication credentials using your clientId and secret. (when using cURL, you can specify them as -u "clientId:secret"). When calling APIs, send the value as the OAuth 2.0 access token with the authentication type set as Bearer (Example: Authorization: Bearer <Access-Token>) Required.
Accept Set to application/json. Required.
PayPal-Request-Id Contains a unique ID that you generate that can be used for enforcing idempotency. Note: Omitting this header increases the risk of duplicate transactions.
PayPal-Partner-Attribution-Id Use this header if you are a PayPal partner. Specify a unique BN Code to receive revenue attribution. To learn more or to request a BN Code, contact your Partner Manager or visit the PayPal Partner Portal.
PayPal-Client-Metadata-Id PayPal uses this Client Metadata ID to verify that the payment is originating from a valid, user-consented device+application. This helps reduce fraud and decrease declines. Transactions that do not include a Client Metadata ID are not eligible for PayPal Seller Protection. See future payments for further details about initiating a pre-consented payment from a mobile device.

OAuth Request / Response

Use the OAuth request to retrieve an access token for use with your payments calls.

For authentication and authorization related to Identity, learn how to obtain a user’s consent.

Request

Include the <Client-Id>:<Secret> as your Basic Auth credentials.

Tip: Learn more about how PayPal uses OAuth 2.0.

Property Type Description
grant_type string Token grant type. Must be set to client_credentials. Required.
content-type string Set to application/x-www-form-urlencoded for access token requests. This is done by default in cURL calls and is not shown in the request sample, but you may need to explicitly set this for non-cURL implementations.

Request Sample

curl https://api.sandbox.paypal.com/v1/oauth2/token \
 -H "Accept: application/json" \
 -H "Accept-Language: en_US" \
 -u "<Client-Id>:<Secret>" \
 -d "grant_type=client_credentials"
require 'paypal-sdk-rest'
include PayPal::SDK::REST

@api = PayPal::SDK::REST.set_config(
    :ssl_options => {}, # Set ssl options
    :mode => :sandbox,  # Set :sandbox or :live
    :client_id     => "CLIENT_ID",
    :client_secret => "CLIENT_SECRET" )
@api.token
import paypalrestsdk
api = paypalrestsdk.set_config(
  mode="sandbox", # sandbox or live
  client_id="CLIENT_ID",
  client_secret="CLIENT_SECRET")
api.get_access_token()
var paypal_sdk = require('paypal-rest-sdk');
paypal_sdk.configure({
  'host': 'api.sandbox.paypal.com',
  'client_id': 'CLIENT_ID',
  'client_secret': 'CLIENT_SECRET' });
paypal_sdk.generate_token(function(error, token){
  if(error){
    console.error(error);
  } else {
    console.log(token);
  }
});
OAuthTokenCredential tokenCredential =
  new OAuthTokenCredential("<CLIENT_ID>", "<CLIENT_SECRET>");
  
String accessToken = tokenCredential.getAccessToken();
use PayPal\Auth\OAuthTokenCredential;

$oauthCredential = new OAuthTokenCredential("<CLIENT_ID>", "<CLIENT_SECRET>");

$accessToken     = $oauthCredential->getAccessToken(array('mode' => 'sandbox'));

Response

Property Type Description
scope string Scopes expressed in the form of resource URL endpoints. The value of the scope parameter is expressed as a list of space-delimited, case-sensitive strings.
Value assigned by PayPal.
access_token string The access token issued by PayPal. The access token will expire (see expires_in), after which you’ll have to request a new access token.
Value assigned by PayPal.
token_type string The type of the token issued as described in OAuth2.0 RFC6749, Section 7.1. Value is case insensitive.
Value assigned by PayPal.
expires_in integer The lifetime in seconds of the access token.
Value assigned by PayPal.

Response Sample

{
  "scope": "https://api.paypal.com/v1/payments/.* https://api.paypal.com/v1/vault/credit-card https://api.paypal.com/v1/vault/credit-card/.*",
  "access_token": "EEwJ6tF9x5WCIZDYzyZGaz6Khbw7raYRIBV_WxVvgmsG",
  "token_type": "Bearer",
  "app_id": "APP-6XR95014BA15863X",
  "expires_in": 28800
}

You obtain a user’s consent to make Identity API calls on their behalf by redirecting them to the authorization endpoint. See Identity API calls for more information.

Authorization endpoint:

Live: https://www.paypal.com/webapps/auth/protocol/openidconnect/v1/authorize

Sandbox: https://www.sandbox.paypal.com/webapps/auth/protocol/openidconnect/v1/authorize

Note: The live environment also supports the optional inclusion of a 2-letter ISO-3166-1 country code: https://www.paypal.com/<2-letter-country-code>/webapps/auth/protocol/ openidconnect/v1/authorize

This results in a localized page if the content has been translated for the app, and if the language is left-to-right.

Invoke the login flow from the application to Log In with PayPal with following URL, using browser redirect (HTTP 302).

Property Type Description
client_id string Unique client identifier obtained through the application registration process. Required.
response_type string Set to code to request that an authorization code be sent back to the application return URL (recommended, as the access tokens are not visible in the user-agent). Set to token to return a token, which is used mostly by public clients, such as JavaScript or mobile applications. Set to id_token for session assertion associated with the user’s authentication (e.g., used in remote procedure calls for explicit session management such as logout).
scope string URL-encoded, space-separated list of requested scope URIs. For example (URL-encoded): “profile+email+address”. For a list of possible values, see the attributes table.
redirect_uri string Application return URL where the authorization code is sent. The specified redirect_uri must match the return URL registered for your app on the Applications page of the PayPal Developer site. All parts of the specified redirect_uri, including protocol, host, port, context path, and query parameter names and values must match with the exception of the state parameter. You can use the state parameter to pass information that was not known at the time the return URL for your app was registered. The state parameter must be URL encoded and Base64 encoded.
nonce string An opaque random identifier to mitigate replay attacks. A simple function would be: (timestamp + Base64 encoding (random\[16\]))
state string Any state parameter that may be required by the application to know the request context.

The Log In with PayPal authorization endpoint validates the authorization/authentication request and directs the user to log in. After successful login, a consent message is displayed to the user. A user consent grants the requesting application access to the user’s PayPal attributes, as indicated by the scope specified in the request.

Return To Application

Once consent is granted, PayPal redirects (HTTP 302) the user back to the return URL with an authorization code appended to the URL. Use the authorization code to obtain a refresh token and initial access token.

Request URI Sample: Grant Consent

https://www.sandbox.paypal.com/webapps/auth/protocol/openidconnect/v1/authorize
  ?client_id=<Client-Id>
  &response_type=code
  &scope=profile+email+address+phone
    +https%3A%2F%2Furi.paypal.com%2Fservices%2Fpaypalattributes
  &redirect_uri=http://example.com/myapp/return.php


Response URI Sample: Grant Consent

http://example.com/myapp/return.php?scope=profile+email+address
  +phone+https%3A%2F%2Furi.paypal.com%2Fservices%2Fpaypalattributes
  &code=<Authorization-Code>

Paging & Filtering

In HTTP GET requests, you can use input parameters for paging and filtering. The input parameters currently are available for the /v1/payments/payment resource and the /v1/payments/billing-plans resource. See list plans for the Billing Plans input parameters.

You can combine filters, as shown in the sample below.

Paging for one-time payments

For the /v1/payments/payment resource, the following input parameters can be used.

Filter Description
count Number of items to return. Default is 10 with a maximum value of 20.
start_id Resource ID that indicates the starting resource to return. When results are paged, you can use the next_id response value as the start_id to continue with the next set of results.
start_index Start index of the resources to be returned. Typically used to jump to a specific position in the resource history based on its order. Example for starting at the second item in a list of results: ?start_index=2
start_time Resource creation time as defined in RFC 3339 Section 5.6 that indicates the start of a range of results. Example: start_time=2013-03-06T11:00:00Z
end_time Resource creation time that indicates the end of a range of results.
sort_by Sort based on create_time or update_time.
sort_order Sort based on order of results. Options include asc for ascending order or desc for descending order (default).

Request Sample

curl -v -X GET https://api.sandbox.paypal.com/v1/payments/payment?sort_order=asc&sort_by=update_time \
-H "Content-Type:application/json" \
-H "Authorization: Bearer <Access-Token>"
@payment_history = Payment.all( :count => 10 )
payment_history = Payment.all({ "count": 10 })
paypal_sdk.payment.list({ "count": 10 }, function(error, payment_history){
  if(error){
    console.error(error);
  } else {
    console.log(payment_history);
  }
});
OAuthTokenCredential tokenCredential =
  new OAuthTokenCredential("<CLIENT_ID>", "<CLIENT_SECRET>");
  
String accessToken = tokenCredential.getAccessToken();

QueryParameters queryParameters = new QueryParameters();
queryParameters.setCount("10");

PaymentHistory paymentHistory = Payment.get(accessToken, queryParameters);
$apiContext = new ApiContext(new OAuthTokenCredential(
		"<CLIENT_ID>", "<CLIENT_SECRET>"));
		
$payments = Payment::all(array('count' => 10, 'start_index' => 0), $apiContext);
OAuthTokenCredential tokenCredential =
  new OAuthTokenCredential("<CLIENT_ID>", "<CLIENT_SECRET>");
  
string accessToken = tokenCredential.GetAccessToken();
var parameters = new QueryParameters();
parameters.SetCount("10");

PaymentHistory paymentHistory = Payment.Get(accessToken, parameters);

Each API call response includes an array of HATEOAS (Hypermedia as the Engine of Application State) links. The beauty of HATEOAS is that it allows you to interact and construct an API flow solely through the hyperlinks we provide you. You no longer need to hardcode logic into your client in order to use our API. We provide HATEOAS links for each call and for transactions within a call, if available. Learn more about how the REST Payment API uses HATEOAS.

Element Description
href URL of the related HATEOAS link you can use for subsequent calls.
rel Link relation that describes how this link relates to the previous call. Examples include self (get details of the current call), parent_payment (get details of the parent payment), or a related call such as execute or refund.
method The HTTP method required for the related call.
"links" : [{
   "href" : "https://api.sandbox.paypal.com/v1/payments/payment/PAY-2XR800907F429382MKEBWOSA",
   "rel" : "self",
   "method" : "GET"
  }, {
   "href" : "https://api.sandbox.paypal.com/v1/payments/payment/PAY-2XR800907F429382MKEBWOSA/execute",
   "rel" : "update",
   "method" : "POST"
  }
 ]

Payments

The payments namespace contains resource collections for payment, sale, refund, authorization, and capture.

Payment

PayPal provides various payment related operations using the /payment resource and related sub-resources. Use payment for direct credit card payments and PayPal account payments. You can also use sub-resources to get payment related details.

URI

https://api.paypal.com/v1/payments/payment

Create a payment

Operation

POST /v1/payments/payment

Depending on the payment_method and the funding_instrument, you can use the payment resource for direct credit card payments, stored credit card payments, or PayPal account payments.

You can authorize payments to be captured later or create an order.

Direct credit card payment and related features are restricted in some countries.

When creating a payment, set the intent (sale, authorize, or order), and specify the actual transactions details like amount, recipients, and items.

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

Request

Provide a payment object that includes an intent, payer, and transactions.

Property Type Description
intent string Payment intent. Must be set to sale for immediate payment, authorize to authorize a payment for capture later, or order to create an order. Required.
payer payer Source of the funds for this payment represented by a PayPal account or a credit card. Required.
transactions array of transaction objects Transactional details including the amount and item details. Required.
redirect_urls redirect_urls Set of redirect URLs you provide only for PayPal-based payments. Required for PayPal payments.
     

Request Sample

curl -v https://api.sandbox.paypal.com/v1/payments/payment \
-H "Content-Type:application/json" \
-H "Authorization: Bearer <Access-Token>" \
-d '{
  "intent":"sale",
  "payer":{
    "payment_method":"credit_card",
    "funding_instruments":[
      {
        "credit_card":{
          "number":"4417119669820331",
          "type":"visa",
          "expire_month":11,
          "expire_year":2018,
          "cvv2":"874",
          "first_name":"Betsy",
          "last_name":"Buyer",
          "billing_address":{
            "line1":"111 First Street",
            "city":"Saratoga",
            "state":"CA",
            "postal_code":"95070",
            "country_code":"US"
          }
        }
      }
    ]
  },
  "transactions":[
    {
      "amount":{
        "total":"7.47",
        "currency":"USD",
        "details":{
          "subtotal":"7.41",
          "tax":"0.03",
          "shipping":"0.03"
        }
      },
      "description":"This is the payment transaction description."
    }
  ]
}'
@payment = Payment.new({
  :intent => "sale",
  :payer => {
    :payment_method => "credit_card",
    :funding_instruments => [{
      :credit_card => {
        :type => "visa",
        :number => "4417119669820331",
        :expire_month => "11", :expire_year => "2018",
        :cvv2 => "874",
        :first_name => "Joe", :last_name => "Shopper",
        :billing_address => {
          :line1 => "52 N Main ST",
          :city => "Johnstown",
          :state => "OH",
          :postal_code => "43210", :country_code => "US" }}}]},
  :transactions => [{
    :amount => {
      :total => "7.47",
      :currency => "USD",
      :details => {
        :subtotal => "7.41",
        :tax => "0.03",
        :shipping => "0.03"}},
    :description => "This is the payment transaction description." }]})

@payment.create
payment = Payment({
  "intent": "sale",
  "payer": {
    "payment_method": "credit_card",
    "funding_instruments": [{
      "credit_card": {
        "type": "visa",
        "number": "4417119669820331",
        "expire_month": "11",
        "expire_year": "2018",
        "cvv2": "874",
        "first_name": "Joe",
        "last_name": "Shopper",
        "billing_address": {
          "line1": "52 N Main ST",
          "city": "Johnstown",
          "state": "OH",
          "postal_code": "43210",
          "country_code": "US" }}}]},
  "transactions": [{
    "amount": {
      "total": "7.47",
      "currency": "USD",
      "details": {
        "subtotal": "7.41",
        "tax": "0.03",
        "shipping": "0.03"}},
    "description": "This is the payment transaction description." }]})

payment.create()  # return True or False
var payment_details = {
  "intent": "sale",
  "payer": {
    "payment_method": "credit_card",
    "funding_instruments": [{
      "credit_card": {
        "type": "visa",
        "number": "4417119669820331",
        "expire_month": "11",
        "expire_year": "2018",
        "cvv2": "874",
        "first_name": "Joe",
        "last_name": "Shopper",
        "billing_address": {
          "line1": "52 N Main ST",
          "city": "Johnstown",
          "state": "OH",
          "postal_code": "43210",
          "country_code": "US" }}}]},
  "transactions": [{
    "amount": {
      "total": "7.47",
      "currency": "USD",
      "details": {
        "subtotal": "7.41",
        "tax": "0.03",
        "shipping": "0.03"}},
    "description": "This is the payment transaction description." }]};

paypal_sdk.payment.create(payment_details, function(error, payment){
  if(error){
    console.error(error);
  } else {
    console.log(payment);
  }
});
OAuthTokenCredential tokenCredential =
  new OAuthTokenCredential("<CLIENT_ID>", "<CLIENT_SECRET>");
  
String accessToken = tokenCredential.getAccessToken();

Address billingAddress = new Address();
billingAddress.setLine1("52 N Main ST");
billingAddress.setCity("Johnstown");
billingAddress.setCountryCode("US");
billingAddress.setPostalCode("43210");
billingAddress.setState("OH");

CreditCard creditCard = new CreditCard();
creditCard.setNumber("4417119669820331");
creditCard.setType("visa");
creditCard.setExpireMonth("11");
creditCard.setExpireYear("2018");
creditCard.setCvv2("874");
creditCard.setFirstName("Joe");
creditCard.setLastName("Shopper");
creditCard.setBillingAddress(billingAddress);

AmountDetails amountDetails = new AmountDetails();
amountDetails.setSubtotal("7.41");
amountDetails.setTax("0.03");
amountDetails.setShipping("0.03");

Amount amount = new Amount();
amount.setTotal("7.47");
amount.setCurrency("USD");
amount.setDetails(amountDetails);
		
Transaction transaction = new Transaction();
transaction.setAmount(amount);
transaction.setDescription("This is the payment transaction description.");

List<Transaction> transactions = new ArrayList<Transaction>();
transactions.add(transaction);

FundingInstrument fundingInstrument = new FundingInstrument();
fundingInstrument.setCreditCard(creditCard);

List<FundingInstrument> fundingInstruments = new ArrayList<FundingInstrument>();
fundingInstruments.add(fundingInstrument);

Payer payer = new Payer();
payer.setFundingInstruments(fundingInstruments);
payer.setPaymentMethod("credit_card");

Payment payment = new Payment();
payment.setIntent("sale");
payment.setPayer(payer);
payment.setTransactions(transactions);

Payment createdPayment = payment.create(accessToken);
$apiContext = new ApiContext(new OAuthTokenCredential(
		"<CLIENT_ID>", "<CLIENT_SECRET>"));
		
$addr = new Address();
$addr->setLine1('52 N Main ST');
$addr->setCity('Johnstown');
$addr->setCountry_code('US');
$addr->setPostal_code('43210');
$addr->setState('OH');

$card = new CreditCard();
$card->setNumber('4417119669820331');
$card->setType('visa');
$card->setExpire_month('11');
$card->setExpire_year('2018');
$card->setCvv2('874');
$card->setFirst_name('Joe');
$card->setLast_name('Shopper');
$card->setBilling_address($addr);

$fi = new FundingInstrument();
$fi->setCredit_card($card);

$payer = new Payer();
$payer->setPayment_method('credit_card');
$payer->setFunding_instruments(array($fi));

$amountDetails = new AmountDetails();
$amountDetails->setSubtotal('7.41');
$amountDetails->setTax('0.03');
$amountDetails->setShipping('0.03');

$amount = new Amount();
$amount->setCurrency('USD');
$amount->setTotal('7.47');
$amount->setDetails($amountDetails);

$transaction = new Transaction();
$transaction->setAmount($amount);
$transaction->setDescription('This is the payment transaction description.');

$payment = new Payment();
$payment->setIntent('sale');
$payment->setPayer($payer);
$payment->setTransactions(array($transaction));

$payment->create($apiContext);
OAuthTokenCredential tokenCredential =
  new OAuthTokenCredential("<CLIENT_ID>", "<CLIENT_SECRET>");
  
string accessToken = tokenCredential.GetAccessToken();

Address billingAddress = new Address();
billingAddress.line1 = "52 N Main ST";
billingAddress.city = "Johnstown";
billingAddress.country_code = "US";
billingAddress.postal_code = "43210";
billingAddress.state = "OH";

CreditCard creditCard = new CreditCard();
creditCard.number = "4417119669820331";
creditCard.type = "visa";
creditCard.expire_month = "11";
creditCard.expire_year = "2018";
creditCard.cvv2 = "874";
creditCard.first_name = "Joe";
creditCard.last_name = "Shopper";
creditCard.billing_address = billingAddress;

AmountDetails amountDetails = new AmountDetails();
amountDetails.subtotal = "7.41";
amountDetails.tax = "0.03";
amountDetails.shipping = "0.03";

Amount amount = new Amount();
amount.total = "7.47";
amount.currency = "USD";
amount.details = amountDetails;

Transaction transaction = new Transaction();
transaction.amount = amount;
transaction.description = "This is the payment transaction description.";

List<Transaction> transactions = new List<Transaction>();
transactions.Add(transaction);

FundingInstrument fundingInstrument = new FundingInstrument();
fundingInstrument.credit_card = creditCard;

List<FundingInstrument> fundingInstruments = new List<FundingInstrument>();
fundingInstruments.Add(fundingInstrument);

Payer payer = new Payer();
payer.funding_instruments = fundingInstruments;
payer.payment_method      = "credit_card"

Payment payment = new Payment();
payment.intent = "sale";
payment.payer  = payer;
payment.transaction = transactions;

Payment createdPayment = payment.Create(accessToken);

Response

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

Property Type Description
intent string Payment intent. Must be either sale for immediate payment, authorize for a delayed payment to be captured at a later time, or order to create an order.
payer payer Source of the funds for this payment represented by a PayPal account or a direct credit card.
transactions array of transaction objects Transactional details including the amount and item details.
redirect_urls redirect_urls Set of redirect URLs you provide only for PayPal-based payments.
id string ID of the created payment
Value assigned by PayPal.
create_time date-time Payment creation time as defined in RFC 3339 Section 5.6
Value assigned by PayPal.
state string Payment state. Must be set to one of the one of the following: created; approved; failed; canceled; expired; pending.
Value assigned by PayPal.
update_time date-time Time the resource was last updated.
Value assigned by PayPal.
links array of links objects HATEOAS links related to this call.
Value assigned by PayPal.
     

Important: When using the paypal payment method, the payer must be redirected to the approval_url provided within the links of the response. For more information, learn how to accept a PayPal payment.

Response Sample

{
  "id": "PAY-17S8410768582940NKEE66EQ",
  "create_time": "2013-01-31T04:12:02Z",
  "update_time": "2013-01-31T04:12:04Z",
  "state": "approved",
  "intent": "sale",
  "payer": {
    "payment_method": "credit_card",
    "funding_instruments": [
      {
        "credit_card": {
          "type": "visa",
          "number": "xxxxxxxxxxxx0331",
          "expire_month": "11",
          "expire_year": "2018",
          "first_name": "Betsy",
          "last_name": "Buyer",
          "billing_address": {
            "line1": "111 First Street",
            "city": "Saratoga",
            "state": "CA",
            "postal_code": "95070",
            "country_code": "US"
          }
        }
      }
    ]
  },
  "transactions": [
    {
      "amount": {
        "total": "7.47",
        "currency": "USD",
        "details": {
          "tax": "0.03",
          "shipping": "0.03"
        }
      },
      "description": "This is the payment transaction description.",
      "related_resources": [
        {
          "sale": {
            "id": "4RR959492F879224U",
            "create_time": "2013-01-31T04:12:02Z",
            "update_time": "2013-01-31T04:12:04Z",
            "state": "completed",
            "amount": {
              "total": "7.47",
              "currency": "USD"
            },
            "parent_payment": "PAY-17S8410768582940NKEE66EQ",
            "links": [
              {
                "href": "https://api.sandbox.paypal.com/v1/payments/sale/4RR959492F879224U",
                "rel": "self",
                "method": "GET"
              },
              {
                "href": "https://api.sandbox.paypal.com/v1/payments/sale/4RR959492F879224U/refund",
                "rel": "refund",
                "method": "POST"
              },
              {
                "href": "https://api.sandbox.paypal.com/v1/payments/payment/PAY-17S8410768582940NKEE66EQ",
                "rel": "parent_payment",
                "method": "GET"
              }
            ]
          }
        }
      ]
    }
  ],
  "links": [
    {
      "href": "https://api.sandbox.paypal.com/v1/payments/payment/PAY-17S8410768582940NKEE66EQ",
      "rel": "self",
      "method": "GET"
    }
  ]
}

Execute an approved PayPal payment

Operation

POST /v1/payments/payment/<Payment-Id>/execute

Use this call to execute (complete) a PayPal payment that has been approved by the payer. You can optionally update transaction information when executing the payment by passing in one or more transactions.

Important: This call only works after a buyer has approved the payment using the provided PayPal approval URL. For more information, learn how to accept a PayPal payment.

Request

Pass the payment id in the endpoint and include updated details as a payment_execution object in the body.

Property Type Description
payer_id string The ID of the Payer, passed in the return_url by PayPal. Required.
transactions array of transaction objects Transactional details if updating a payment. Note that this instance of the transactions object accepts only the amount object.
     

Request Sample

curl -v https://api.sandbox.paypal.com/v1/payments/payment/<Payment-Id>/execute/ \
-H "Content-Type:application/json" \
-H "Authorization: Bearer <Access-Token>" \
-d '{ "payer_id" : "{payerId}" }'
@payment = Payment.find("PAY-34629814WL663112AKEE3AWQ")
@payment.execute( :payer_id => "7E7MGXCWTTKK2" )
payment = Payment.find("PAY-34629814WL663112AKEE3AWQ")
payment.execute({ "payer_id": "7E7MGXCWTTKK2" })
var execute_payment_details = { "payer_id": "7E7MGXCWTTKK2" };
paypal_sdk.payment.execute("PAY-34629814WL663112AKEE3AWQ", execute_payment_details, function(error, payment){
  if(error){
    console.error(error);
  } else {
    console.log(payment);
  }
});
OAuthTokenCredential tokenCredential =
  new OAuthTokenCredential("<CLIENT_ID>", "<CLIENT_SECRET>");
  
String accessToken = tokenCredential.getAccessToken();

Payment payment = Payment.get(accessToken, "PAY-34629814WL663112AKEE3AWQ");

PaymentExecution paymentExecution = new PaymentExecution();
paymentExecution.setPayerId("7E7MGXCWTTKK2");

Payment newPayment = payment.execute(accessToken, paymentExecution);
$apiContext = new ApiContext(new OAuthTokenCredential(
		"<CLIENT_ID>", "<CLIENT_SECRET>"));
		
$payment = Payment::get('PAY-34629814WL663112AKEE3AWQ', $apiContext);

$paymentExecution = new PaymentExecution();
$paymentExecution->setPayer_id('7E7MGXCWTTKK2');

$payment->execute($paymentExecution, $apiContext);
OAuthTokenCredential tokenCredential =
  new OAuthTokenCredential("<CLIENT_ID>", "<CLIENT_SECRET>");
  
string accessToken = tokenCredential.GetAccessToken();

Payment payment = Payment.Get(accessToken, "PAY-34629814WL663112AKEE3AWQ");

PaymentExecution paymentExecution = new PaymentExecution();
paymentExecution.setPayerId("7E7MGXCWTTKK2");

Payment newPayment = payment.Execute(accessToken, paymentExecution);

Response

Returns a payment object for the completed PayPal payment.

Property Type Description
intent string Payment intent; must be set to sale, authorize, or order.
payer payer Source of the funds for this payment represented by a PayPal account or a direct credit card.
transactions array of transaction objects Transactional details including the amount and item details.
links array of links objects HATEOAS links related to this call.
Value assigned by PayPal.
     

Response Sample

{
  "id": "PAY-34629814WL663112AKEE3AWQ",
  "create_time": "2013-01-30T23:44:26Z",
  "update_time": "2013-01-30T23:44:28Z",
  "state": "approved",
  "intent": "sale",
  "payer": {
    "payment_method": "paypal",
    "payer_info": {
      "email": "bbuyer@example.com",
      "first_name": "Betsy",
      "last_name": "Buyer",
      "payer_id": "CR87QHB7JTRSC"
    }
  },
  "transactions": [
    {
      "amount": {
        "total": "7.47",
        "currency": "USD",
        "details": {
          "tax": "0.04",
          "shipping": "0.06"
        }
      },
      "description": "This is the payment transaction description.",
      "related_resources": [
        {
          "sale": {
            "id": "1KE4800207592173L",
            "create_time": "2013-01-30T23:44:26Z",
            "update_time": "2013-01-30T23:44:28Z",
            "state": "completed",
            "amount": {
              "currency": "USD",
              "total": "7.47"
            },
            "transaction_fee": {
              "value": "0.50",
              "currency": "USD"
            },
            "parent_payment": "PAY-34629814WL663112AKEE3AWQ",
            "links": [
              {
                "href": "https://api.sandbox.paypal.com/v1/payments/sale/1KE4800207592173L",
                "rel": "self",
                "method": "GET"
              },
              {
                "href": "https://api.sandbox.paypal.com/v1/payments/sale/1KE4800207592173L/refund",
                "rel": "refund",
                "method": "POST"
              },
              {
                "href": "https://api.sandbox.paypal.com/v1/payments/payment/PAY-34629814WL663112AKEE3AWQ",
                "rel": "parent_payment",
                "method": "GET"
              }
            ]
          }
        }
      ]
    }
  ],
  "links": [
    {
      "href": "https://api.sandbox.paypal.com/v1/payments/payment/PAY-34629814WL663112AKEE3AWQ",
      "rel": "self",
      "method": "GET"
    }
  ]
}

Look up a payment resource

Operation

GET /v1/payments/payment/<Payment-Id>

Use this call to get details about payments that have not completed, such as payments that are created and approved, or if a payment has failed.

Request

Pass the payment id in the endpoint.

Request Sample

curl -v -X GET https://api.sandbox.paypal.com/v1/payments/payment/<Payment-Id> \
-H "Content-Type:application/json" \
-H "Authorization: Bearer <Access-Token>"
@payment = Payment.find("PAY-5YK922393D847794YKER7MUI")
payment = Payment.find("PAY-5YK922393D847794YKER7MUI")
paypal_sdk.payment.get("PAY-5YK922393D847794YKER7MUI", function(error, payment){
  if(error){
    console.error(error);
  } else {
    console.log(payment);
  }
});
OAuthTokenCredential tokenCredential =
  new OAuthTokenCredential("<CLIENT_ID>", "<CLIENT_SECRET>");
  
String accessToken = tokenCredential.getAccessToken();

Payment payment = Payment.get(accessToken, "PAY-5YK922393D847794YKER7MUI");
$apiContext = new ApiContext(new OAuthTokenCredential(
		"<CLIENT_ID>", "<CLIENT_SECRET>"));
		
$payment = Payment::get('PAY-5YK922393D847794YKER7MUI', $apiContext);
OAuthTokenCredential tokenCredential =
  new OAuthTokenCredential("<CLIENT_ID>", "<CLIENT_SECRET>");
  
string accessToken = tokenCredential.GetAccessToken();

Payment payment = Payment.Get(accessToken, "PAY-5YK922393D847794YKER7MUI");

Response

Returns a payment object.

Property Type Description
intent enum Payment intent; use sale, authorize, or order.
payer payer Source of the funds for this payment represented by a PayPal account or a direct credit card.
transactions array of transaction objects Transactional details including the amount and item details.
redirect_urls redirect_urls Set of redirect URLs you provide only for PayPal-based payments. Returned only when the payment is in created state. Required for PayPal payments.
id string ID of the created payment, the “transaction ID”.
Value assigned by PayPal.
create_time date-time Payment creation time as defined in RFC 3339 Section 5.6.
Value assigned by PayPal.
state enum Payment state, one of the following: created, approved, failed, canceled, expired, pending, or in_progress.
Value assigned by PayPal.
update_time date-time Time that the resource was last updated.
Value assigned by PayPal.
     

Response Sample

{
  "id": "PAY-5YK922393D847794YKER7MUI",
  "create_time": "2013-02-19T22:01:53Z",
  "update_time": "2013-02-19T22:01:55Z",
  "state": "approved",
  "intent": "sale",
  "payer": {
    "payment_method": "credit_card",
    "funding_instruments": [
      {
        "credit_card": {
          "type": "mastercard",
          "number": "xxxxxxxxxxxx5559",
          "expire_month": "2",
          "expire_year": "2018",
          "first_name": "Betsy",
          "last_name": "Buyer"
        }
      }
    ]
  },
  "transactions": [
    {
      "amount": {
        "total": "7.47",
        "currency": "USD",
        "details": {
          "subtotal": "7.47"
        }
      },
      "description": "This is the payment transaction description.",
      "related_resources": [
        {
          "sale": {
            "id": "36C38912MN9658832",
            "create_time": "2013-02-19T22:01:53Z",
            "update_time": "2013-02-19T22:01:55Z",
            "state": "completed",
            "amount": {
              "total": "7.47",
              "currency": "USD"
            },
            "protection_eligibility": "ELIGIBLE",
            "protection_eligibility_type": "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"
              }
            ]
          }
        }
      ]
    }
  ],
  "links": [
    {
      "href": "https://api.sandbox.paypal.com/v1/payments/payment/PAY-5YK922393D847794YKER7MUI",
      "rel": "self",
      "method": "GET"
    }
  ]
}

Update a payment resource

Operation

PATCH /v1/payments/payment/<Payment-Id>

Use this call to partially update the payment resource for the given identifier. Please note that it is not possible to use patch after execute has been called.

Request

Pass the payment id in the URI of a PATCH call, including the patch_request object in the body.

Property Type Description
op string Patch operation to perform. Allowed values: add and replace.
path string String containing a JSON-Pointer value that references a location within the target document (the target location) where the operation is performed.
value object New value to apply based on the operation. Allowed objects are amount object or shipping_address object.
     

Request Sample

curl -v -X PATCH https://api.sandbox.paypal.com/v1/payments/payment/<Payment-Id> \
-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": "Gruneberg, Anna",
            "line1": "Kathwarinenhof 1",
            "city": "Flensburg",
            "postal_code": "24939",
            "country_code": "DE"
        }
    }
]'

Response

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

List payment resources

Operation

GET /v1/payments/payment/

Use this call to get a list of payments in any state (created, approved, failed, etc.). The payments returned are the payments made to the merchant making the call.

Request

PayPal offers query parameters and pagination to help filter results.

Request Sample

curl -v -X GET https://api.sandbox.paypal.com/v1/payments/payment \
-H "Content-Type:application/json" \
-H "Authorization: Bearer <Access-Token>"
@payment_history = Payment.all( :count => 10 )
payment_history = Payment.all({ "count": 10 })
paypal_sdk.payment.list({ "count": 10 }, function(error, payment_history){
  if(error){
    console.error(error);
  } else {
    console.log(payment_history);
  }
});
OAuthTokenCredential tokenCredential =
  new OAuthTokenCredential("<CLIENT_ID>", "<CLIENT_SECRET>");
  
String accessToken = tokenCredential.getAccessToken();

QueryParameters queryParameters = new QueryParameters();
queryParameters.setCount("10");

PaymentHistory paymentHistory = Payment.get(accessToken, queryParameters);
$apiContext = new ApiContext(new OAuthTokenCredential(
		"<CLIENT_ID>", "<CLIENT_SECRET>"));
		
$payments = Payment::all(array('count' => 10, 'start_index' => 0), $apiContext);
OAuthTokenCredential tokenCredential =
  new OAuthTokenCredential("<CLIENT_ID>", "<CLIENT_SECRET>");
  
string accessToken = tokenCredential.GetAccessToken();
var parameters = new QueryParameters();
parameters.SetCount("10");

PaymentHistory paymentHistory = Payment.Get(accessToken, parameters);

Response

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

Property Type Description
intent string Payment intent; set to either sale, authorize, or order.
payer payer Source of the funds for this payment represented by a PayPal account or a direct credit card.
transactions array of transaction objects Transactional details including the amount and item details.
redirect_urls redirect_urls Set of redirect URLs you provide only for PayPal-based payments.
id string ID of the created payment
Value assigned by PayPal.
create_time date-time Payment creation time as defined in RFC 3339 Section 5.6
Value assigned by PayPal.
state string Payment state. One of the following: created; approved; failed; canceled; expired; pending.
Value assigned by PayPal.
update_time date-time Time that the resource was last updated.
Value assigned by PayPal.
links array of links objects HATEOAS links related to this call.
Value assigned by PayPal.
     

Response Sample

{
  "payments": [
    {
      "id": "PAY-4D099447DD202993VKEFMRJQ",
      "create_time": "2013-01-31T19:40:22Z",
      "update_time": "2013-01-31T19:40:24Z",
      "state": "approved",
      "intent": "sale",
      "payer": {
        "payment_method": "credit_card",
        "funding_instruments": [
          {
            "credit_card": {
              "type": "visa",
              "number": "xxxxxxxxxxxx0331",
              "expire_month": "10",
              "expire_year": "2018",
              "first_name": "Betsy",
              "last_name": "Buyer",
              "billing_address": {
                "line1": "111 First Street",
                "city": "Saratoga",
                "state": "CA",
                "postal_code": "95070",
                "country_code": "US"
              }
            }
          }
        ]
      },
      "transactions": [
        {
          "amount": {
            "total": "110.54",
            "currency": "USD"
          },
          "description": "This is the payment transaction description.",
          "related_resources": [
            {
              "sale": {
                "id": "1D971400A7097562W",
                "create_time": "2013-01-31T19:40:23Z",
                "update_time": "2013-01-31T19:40:25Z",
                "state": "completed",
                "amount": {
                  "total": "110.54",
                  "currency": "USD"
                },
                "parent_payment": "PAY-4D099447DD202993VKEFMRJQ",
                "links": [
                  {
                    "href": "https://api.sandbox.paypal.com/v1/payments/sale/1D971400A7097562W",
                    "rel": "self",
                    "method": "GET"
                  },
                  {
                    "href": "https://api.sandbox.paypal.com/v1/payments/sale/1D971400A7097562W/refund",
                    "rel": "refund",
                    "method": "POST"
                  },
                  {
                    "href": "https://api.sandbox.paypal.com/v1/payments/payment/PAY-4D099447DD202993VKEFMRJQ",
                    "rel": "parent_payment",
                    "method": "GET"
                  }
                ]
              }
            }
          ]
        }
      ],
      "links": [
        {
          "href": "https://api.sandbox.paypal.com/v1/payments/payment/PAY-4D099447DD202993VKEFMRJQ",
          "rel": "self",
          "method": "GET"
        }
      ]
    }
  ]
}

Sale Transactions

To get details about completed payments (sale transaction) created by a payment request or to refund a direct sale transaction, PayPal provides the /sale resource and related sub-resources. You can find the sale transactions in the payment resource within related_resources.


URI

https://api.paypal.com/v1/payments/sale

Look up a sale

Operation

GET /v1/payments/sale/<Transaction-Id>

Use this call to get details about a sale transaction.

Note: This call returns only the sales that were created via the REST API.

Request

Pass the sale id in the endpoint.

Request Sample

curl -v -X GET https://api.sandbox.paypal.com/v1/payments/sale/<Transaction-Id> \
-H "Content-Type:application/json" \
-H "Authorization: Bearer <Access-Token>"
@sale = Sale.find("36C38912MN9658832")
sale = Sale.find("36C38912MN9658832")
paypal_sdk.sale.get("36C38912MN9658832", function(error, sale){
  if(error){
    console.error(error);
  } else {
    console.log(sale);
  }
});
OAuthTokenCredential tokenCredential =
  new OAuthTokenCredential("<CLIENT_ID>", "<CLIENT_SECRET>");
  
String accessToken = tokenCredential.getAccessToken();

Sale sale = Sale.get(accessToken, "36C38912MN9658832");
$apiContext = new ApiContext(new OAuthTokenCredential(
		"<CLIENT_ID>", "<CLIENT_SECRET>"));
		
$sale = Sale::get('36C38912MN9658832', $apiContext);
OAuthTokenCredential tokenCredential =
  new OAuthTokenCredential("<CLIENT_ID>", "<CLIENT_SECRET>");
  
string accessToken = tokenCredential.GetAccessToken();

Sale sale = Sale.Get(accessToken, "36C38912MN9658832");

Response

Returns a sale object.

Property Type Description
id string ID of the sale transaction.
amount amount Details about the collected amount.
description string Description of sale.
create_time date-time Time of sale as defined in RFC 3339 Section 5.6
Value assigned by PayPal.
state string State of the sale. One of the following: pending; completed; refunded; or partially_refunded.
Value assigned by PayPal.
parent_payment string ID of the payment resource on which this transaction is based.
Value assigned by PayPal.
update_time date-time Time that the resource was last updated.
Value assigned by PayPal.
payment_mode string Specifies payment mode of the transaction. Only supported when the payment_method is set to paypal. Assigned by PayPal. Allowed values: INSTANT_TRANSFER, MANUAL_BANK_TRANSFER, DELAYED_TRANSFER, or ECHECK.
pending_reason string Reason the transaction is in pending state. Only supported when the payment_method is set to paypal. Allowed values: PAYER-SHIPPING-UNCONFIRMED, MULTI-CURRENCY, RISK-REVIEW, REGULATORY-REVIEW, VERIFICATION-REQUIRED, ORDER, or OTHER.
reason_code string Reason code for the transaction state being Pending or Reversed. Only supported when the payment_method is set to paypal. Assigned by PayPal. Allowed values: CHARGEBACK, GUARANTEE, BUYER_COMPLAINT, REFUND, UNCONFIRMED_SHIPPING_ADDRESS, ECHECK, INTERNATIONAL_WITHDRAWAL, RECEIVING_PREFERENCE_MANDATES_MANUAL_ACTION, PAYMENT_REVIEW, REGULATORY_REVIEW, UNILATERAL, or VERIFICATION_REQUIRED.
clearing_time string Expected clearing time for eCheck transactions. Only supported when the payment_method is set to paypal. Assigned by PayPal.
transaction_fee currency Transaction fee charged by PayPal for this transaction.
receivable_amount currency Net amount 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.
exchange_rate string Exchange rate applied for this transaction. Returned only in cross-currency use cases where a merchant bills a buyer in a non-primary currency for that buyer.
fmf_details fmf_details Fraud Management Filter (FMF) details applied for the payment that could 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. See Fraud Management Filters Summary for more information.
receipt_id string Receipt id is 16 digit number payment identification number returned for guest users to identify the payment.
protection_eligibility string 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. Refer to protection_eligibility_type for specifics.
INELIGIBLE- Merchant is not protected under the Seller Protection Policy.
protection_eligibility_type string 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. Allowed values:
ITEM_NOT_RECEIVED_ELIGIBLE- Sellers are protected against claims for items not received.
UNAUTHORIZED_PAYMENT_ELIGIBLE- Sellers are protected against claims for unauthorized payments.
One or both of the allowed values can be returned.
links array of links objects HATEOAS links related to this call.
Value generated by PayPal.
     

Response Sample

{
  "id": "36C38912MN9658832",
  "create_time": "2013-02-19T22:01:53Z",
  "update_time": "2013-02-19T22:01:55Z",
  "state": "completed",
  "amount": {
    "currency": "USD",
    "total": "7.47"
  },
  "protection_eligibility": "ELIGIBLE",
  "protection_eligibility_type": "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 a sale

Operation

POST /v1/payments/sale/<Id>/refund

Use this call to refund a completed payment. Provide the sale_id in the URI and an empty JSON payload for a full refund. For partial refunds, you can include an amount.

Request

Property Type Description
amount amount object Refund details including both the refunded amount (to Payer) and refunded fee (to Payee). If no amount is provided, you must still provide an empty JSON payload ({}) in the body to indicate a full refund.

Request Sample

@sale   = Sale.find("2MU78835H4515710F")
@refund = @sale.refund({
  :amount => {
    :currency => "USD",
    :total => "2.34" })
sale   = Sale.find("2MU78835H4515710F")
refund = sale.refund({
  "amount": {
    "currency": "USD",
    "total": "2.34" })
var refund_details = {
  "amount": {
    "currency": "USD",
    "total": "2.34" }};
paypal_sdk.sale.refund("2MU78835H4515710F", refund_details, function(error, refund){
  if(error){
    console.error(error);
  } else {
    console.log(refund);
  }
});
OAuthTokenCredential tokenCredential =
  new OAuthTokenCredential("<CLIENT_ID>", "<CLIENT_SECRET>");
  
String accessToken = tokenCredential.getAccessToken();

Sale sale = Sale.get(accessToken, "2MU78835H4515710F");

Amount amount = new Amount();
amount.setTotal("2.34");
amount.setCurrency("USD");

Refund refund = new Refund();
refund.setAmount(amount);

Refund newRefund = sale.refund(accessToken, refund);
$apiContext = new ApiContext(new OAuthTokenCredential(
		"<CLIENT_ID>", "<CLIENT_SECRET>"));

$sale = Sale::get('2MU78835H4515710F', $apiContext);

$amt = new Amount();
$amt->setCurrency('USD');
$amt->setTotal('2.34');

$refund = new Refund();
$refund->setAmount($amt);

$refund = $sale->refund($refund, $apiContext);
OAuthTokenCredential tokenCredential =
  new OAuthTokenCredential("<CLIENT_ID>", "<CLIENT_SECRET>");
  
string accessToken = tokenCredential.GetAccessToken();

Sale sale = Sale.Get(accessToken, "2MU78835H4515710F");

Amount amount = new Amount();
amount.total = "2.34";
amount.currency = "USD";

Refund refund = new Refund();
refund.amount = amount;

Refund newRefund = sale.Refund(accessToken, refund);
curl -v https://api.sandbox.paypal.com/v1/payments/sale/<Transaction-Id>/refund \
-H 'Content-Type:application/json'  \
-H 'Authorization: Bearer <Access-Token>' \
-d '{
  "amount":
  {
    "total": "2.34",
    "currency": "USD"
  }
}'

Response

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

Property Type Description
id string ID of the refund transaction.
amount amount Details including both refunded amount (to payer) and refunded fee (to payee).
create_time date-time Time of refund as defined in RFC 3339 Section 5.6.
Value assigned by PayPal.
state string State of the refund. One of the following: pending; completed; or failed.
Value assigned by PayPal.
parent_payment string ID of the payment resource on which this transaction is based.
Value assigned by PayPal.
update_time date-time Time that the resource was last updated.
Value assigned by PayPal.
links array of links objects HATEOAS links related to this call.
Value assigned by PayPal.
     

Response Sample

{
  "id": "4CF18861HF410323U",
  "create_time": "2013-01-31T04:13:34Z",
  "update_time": "2013-01-31T04:13:36Z",
  "state": "completed",
  "amount": {
    "total": "2.34",
    "currency": "USD"
  },
  "parent_payment": "PAY-46E69296BH2194803KEE662Y",
  "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

Use the /refund resource to look up details of a specific refund on direct and captured payments.

See Refund a sale in the API reference and Refund a completed payment (sale) for more information about refunding payments.

URI

https://api.paypal.com/v1/payments/refund

Look up a refund

Operation

GET /v1/payments/refund/<Refund-Id>

Use this call to get details about a specific refund.

To get a list of your refunds, you can first get a list of payments. Within the list, you can see the state of the sale object as refunded and a refund object with the state of completed.

Request

Pass the refund id in the endpoint.

Request Sample

curl -v -X GET https://api.sandbox.paypal.com/v1/payments/refund/<Refund-Id> \
-H "Content-Type:application/json" \
-H "Authorization: Bearer <Access-Token>"
@refund = Refund.find("4GU360220B627614A")
refund = Refund.find("4GU360220B627614A")
paypal_sdk.refund.get("4GU360220B627614A", function(error, refund){
  if(error){
    console.error(error);
  } else {
    console.log(refund);
  }
});
OAuthTokenCredential tokenCredential =
  new OAuthTokenCredential("<CLIENT_ID>", "<CLIENT_SECRET>");
  
String accessToken = tokenCredential.getAccessToken();

Refund refund = Refund.get(accessToken, "4GU360220B627614A");
$apiContext = new ApiContext(new OAuthTokenCredential(
		"<CLIENT_ID>", "<CLIENT_SECRET>"));
		
$refund = Refund::get('4GU360220B627614A', $apiContext);
OAuthTokenCredential tokenCredential =
  new OAuthTokenCredential("<CLIENT_ID>", "<CLIENT_SECRET>");
  
string accessToken = tokenCredential.GetAccessToken();

Refund refund = Refund.Get(accessToken, "4GU360220B627614A");

Response

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

Property Type Description
id string ID of the refund transaction.
amount amount Details including both refunded amount (to payer) and refunded fee (to payee).
create_time date-time Time of refund as defined in RFC 3339 Section 5.6.
Value assigned by PayPal.
state string State of the refund. One of the following: pending; completed; or failed.
Value assigned by PayPal.
capture_id string ID of the transaction.
Value assigned by PayPal.
parent_payment string ID of the payment resource on which this transaction is based.
Value assigned by PayPal.
update_time date-time Time that the resource was last updated.
Value assigned by PayPal.
links array of links objects HATEOAS links related to this call.
Value assigned by PayPal.
     

Response Sample

{
  "id": "4GU360220B627614A",
  "create_time": "2013-01-01T02:00:00Z",
  "update_time": "2013-01-01T03:00:02Z",
  "state": "completed",
  "amount": {
    "total": "2.34",
    "currency": "USD"
  },
  "capture_id": "36C38912MN9658832",
  "parent_payment": "PAY-5YK922393D847794YKER7MUI",
  "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

Use the /authorization resource and related sub-resources to act on a previously created authorization. Options include retrieving, capturing, voiding, and reauthorizing authorizations.

URI

https://api.paypal.com/v1/payments/payment/authorization

Look up an authorization

Operation

GET /v1/payments/authorization/<Authorization-Id>

Use this call to get details about authorizations.

Request

Pass the authorization id in the endpoint.

Request Sample

curl -v -X GET https://api.sandbox.paypal.com/v1/payments/authorization/<Authorization-Id> \
-H "Content-Type:application/json" \
-H "Authorization: Bearer <Access-Token>"
@authorization = Authorization.find("99M58264FG144833V")
authorization = Authorization.find("99M58264FG144833V")
paypal_sdk.authorization.get("99M58264FG144833V", function(error, authorization){
  if(error){
    console.error(error);
  } else {
    console.log(authorization);
  }
});
OAuthTokenCredential tokenCredential = new OAuthTokenCredential(
				"<CLIENT_ID>", "<CLIENT_SECRET>");

String accessToken = tokenCredential.getAccessToken();
Authorization authorization = Authorization.get(accessToken, "5RA45624N3531924N");
$apiContext = new ApiContext(new OAuthTokenCredential(
		"<CLIENT_ID>", "<CLIENT_SECRET>"));
		
$authorization = Authorization::get('1FR49283DF589111P', $apiContext);
OAuthTokenCredential tokenCredential =
  new OAuthTokenCredential("<CLIENT_ID>", "<CLIENT_SECRET>");
  
string accessToken = tokenCredential.GetAccessToken();

Authorization authorization = Authorization.Get(accessToken, "5RA45624N3531924N");

Response

Returns an authorization object.

Property Type Description
amount amount object Amount being authorized.
payment_mode enum Specifies the payment mode of the transaction. Possible values include: INSTANT_TRANSFER, MANUAL_BANK_TRANSFER, DELAYED_TRANSFER, and ECHECK.
Value assigned by PayPal.
create_time date_time Time of authorization as defined in RFC 3339 Section 5.6.
Value assigned by PayPal.
update_time date_time Time that the resource was last updated.
Value assigned by PayPal.
state enum State of the authorization. Either pending, authorized, captured, partially_captured, expired, or voided.
Value assigned by PayPal.
reason_code enum Reason code, AUTHORIZATION, for a transaction state of pending. Value assigned by PayPal.
parent_payment string ID of the payment resource on which this transaction is based.
Value assigned by PayPal.
id string ID of the authorization transaction.
Value assigned by PayPal.
valid_until date_time Authorization expiration time and date as defined in RFC 3339 Section 5.6.
Value assigned by PayPal.
clearing_time string Expected clearing time for eCheck transactions. Only supported when the payment_method is set to paypal. Value assigned by PayPal.
protection_eligibility string Protection eligibility of the payer. Only supported when the payment_method is set to paypal. Allowed values: ELIGIBLE, PARTIALLY_ELIGIBLE, or INELIGIBLE.
protection_eligibility_type string Protection eligibility type of the payer. Only supported when the payment_method is set to paypal. Allowed values: ELIGIBLE, ITEM_NOT_RECEIVED_ELIGIBLE, INELIGIBLE, or UNAUTHORIZED_PAYMENT_ELIGIBLE.
fmf_details fmf_details Fraud Management Filter (FMF) details applied for the payment that could 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. See Fraud Management Filters Summary for more information.
links array of links objects HATEOAS links related to this request.
Value assigned by PayPal.
     

Response Sample

{
  "id": "2DC87612EK520411B",
  "create_time": "2013-06-25T21:39:15Z",
  "update_time": "2013-06-25T21:39:17Z",
  "state": "authorized",
  "amount": {
    "total": "7.47",
    "currency": "USD",
    "details": {
      "subtotal": "7.47"
    }
  },
  "parent_payment": "PAY-36246664YD343335CKHFA4AY",
  "valid_until": "2013-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 an authorization

Operation

POST /v1/payments/authorization/<Authorization-Id>/capture

Use this resource to capture and process a previously created authorization. To use this resource, the original payment call must have the intent set to authorize.

Request

Provide an authorization_id along with 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.

Property Type Description
amount amount object Amount being captured. Use this to capture amounts less than the originally authorized amount. You can set the is_final_capture to true to indicate a final capture. Required.
is_final_capture boolean Use this field when capturing an amount less than the originally authorized amount. If set to true, all remaining funds held by the authorization will be released in the funding instrument. Default is ‘false’.
     

Request Sample

curl -v https://api.sandbox.paypal.com/v1/payments/authorization/<Authorization-Id>/capture \
-H "Content-Type:application/json" \
-H "Authorization: Bearer <Access-Token>" \
-d '{
  "amount":{
    "currency":"USD",
    "total":"4.54"
  },
  "is_final_capture":true
}'
@authorization = Authorization.find("5RA45624N3531924N")
@capture = @authorization.capture({
  :amount => {
    :currency => "USD",
    :total => "4.54" },
  :is_final_capture => true })
@capture.success? # Return true or false
authorization = Authorization.find("5RA45624N3531924N")
capture = authorization.capture({
  "amount": {
    "currency": "USD",
    "total": "4.54" },
  "is_final_capture": True })
capture.success() # Return True or False
var capture_details = {
  "amount": {
    "currency": "USD",
    "total": "4.54" },
  "is_final_capture": true };

paypal_sdk.authorization.capture("5RA45624N3531924N", capture_details, function(error, capture){
  if(error){
    console.error(error);
  } else {
    console.log(capture);
  }
});
OAuthTokenCredential tokenCredential = new OAuthTokenCredential(
				"<CLIENT_ID>", "<CLIENT_SECRET>");

String accessToken = tokenCredential.getAccessToken();
Authorization authorization = Authorization.get(accessToken, "5RA45624N3531924N");

Amount captureAmount = new Amount();
captureAmount.setCurrency("USD");
captureAmount.setTotal("1");

Capture capture = new Capture();
capture.setAmount(captureAmount);
capture.setIsFinalCapture(true);

Capture responseCapture = authorization.capture(accessToken, capture);
$apiContext = new ApiContext(new OAuthTokenCredential(
		"<CLIENT_ID>", "<CLIENT_SECRET>"));
		
$amount = new Amount();
$amount->setCurrency("USD");
$amount->setTotal("1.00");

$captur = new Capture();
$captur->setId('5RA45624N3531924N');
$captur->setAmount($amount);

$authorization = Authorization::get('8UA90289RG279654G', $apiContext);
$capt = $authorization->capture($captur, $apiContext);
OAuthTokenCredential tokenCredential = new OAuthTokenCredential(
				"<CLIENT_ID>", "<CLIENT_SECRET>");

string accessToken = tokenCredential.GetAccessToken();
Authorization authorization = Authorization.Get(accessToken, "5RA45624N3531924N");

Capture capture = new Capture();
Amount captureAmount = new Amount();
captureAmount.currency = "USD";
captureAmount.total = "1";
capture.amount = captureAmount;
capture.is_final_capture = true;

Capture responseCapture = authorization.Capture(accessToken, capture);

Response

Returns a capture object along with the state of the capture.

Property Type Description
amount amount object Amount being captured. If the amount matches the orginally authorized amount, the state of the authorization changes to captured. If not, the state of the authorization changes to partially_captured. Alternatively, you can set the is_final_capture to true to indicate a final capture. Required.
is_final_capture boolean If set to true, all remaining funds held by the authorization will be released in the funding instrument. Default is ‘false’.
create_time date_time Time of capture as defined in RFC 3339 Section 5.6.
Value assigned by PayPal.
update_time date_time Time that the resource was last updated.
Value assigned by PayPal.
state enum State of the capture. Either pending, completed, refunded, or partially_refunded.
Value assigned by PayPal.
parent_payment string ID of the payment resource on which this transaction is based.
Value assigned by PayPal.
id string ID of the capture transaction.
Value assigned by PayPal.
links array of links objects HATEOAS links related to this request.
Value assigned by PayPal.
     

Response Sample

{
  "id": "6BA17599X0950293U",
  "create_time": "2013-05-06T22:32:24Z",
  "update_time": "2013-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

Operation

POST /v1/payments/authorization/<Authorization-Id>/void

Use this call to void a previously authorized payment.

Note: A fully captured authorization cannot be voided.

Request

Pass the authorization id in the endpoint.

Request Sample

curl -v -X POST https://api.sandbox.paypal.com/v1/payments/authorization/<Authorization-Id>/void \
-H "Content-Type:application/json" \
-H "Authorization: Bearer <Access-Token>"
@authorization = Authorization.find("6CR34526N64144512")
@authorization.void # Return true or false
authorization = Authorization.find("6CR34526N64144512")
authorization.void() # Return True or False
paypal_sdk.authorization.void("6CR34526N64144512", function(error, authorization){
  if(error){
    console.error(error);
  } else {
    console.log(authorization);
  }
});
OAuthTokenCredential tokenCredential = new OAuthTokenCredential(
				"<CLIENT_ID>", "<CLIENT_SECRET>");

String accessToken = tokenCredential.getAccessToken();
Authorization authorization = Authorization.get(accessToken, "5RA45624N3531924N");

Authorization responseAuthorization = authorization.doVoid(accessToken);
$apiContext = new ApiContext(new OAuthTokenCredential(
		"<CLIENT_ID>", "<CLIENT_SECRET>"));
		
$authorization = Authorization::get('87U86133WD4359724', $apiContext);
$void = $authorization->void($apiContext);
OAuthTokenCredential tokenCredential =
  new OAuthTokenCredential("<CLIENT_ID>", "<CLIENT_SECRET>");
  
string accessToken = tokenCredential.GetAccessToken();

Authorization authorization = Authorization.Get(accessToken, "5RA45624N3531924N");

Authorization responseAuthorization = authorization.Void(accessToken);

Response

Returns an authorization object.

Property Type Description
amount amount object Amount being authorized.
create_time date_time Time of authorization as defined in RFC 3339 Section 5.6.
Value assigned by PayPal.
update_time date_time Time that the resource was last updated.
Value assigned by PayPal.
state enum State of the authorization. Either pending, authorized, captured, partially_captured, expired, or voided.
Value assigned by PayPal.
parent_payment string ID of the payment resource on which this transaction is based.
Value assigned by PayPal.
id string ID of the authorization transaction.
Value assigned by PayPal.
valid_until date_time Authorization expiration time and date as defined in RFC 3339 Section 5.6.
Value assigned by PayPal.
clearing_time string Expected clearing time for eCheck transactions. Only supported when the payment_method is set to paypal. Value assigned by PayPal.
protection_eligibility string Protection eligibility of the payer. Only supported when the payment_method is set to paypal. Allowed values: ELIGIBLE, PARTIALLY_ELIGIBLE, or INELIGIBLE.
protection_eligibility_type string Protection eligibility type of the payer. Only supported when the payment_method is set to paypal. Allowed values: ELIGIBLE, ITEM_NOT_RECEIVED_ELIGIBLE, INELIGIBLE, or UNAUTHORIZED_PAYMENT_ELIGIBLE.
links array of links objects HATEOAS links related to this request.
Value assigned by PayPal.
     

Response Sample

{
  "id": "6CR34526N64144512",
  "create_time": "2013-05-06T21:56:50Z",
  "update_time": "2013-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"
    }
  ]
}

Reauthorize a payment

Operation

POST /v1/payments/authorization/<Authorization-Id>/reauthorize

Use this call to reauthorize a PayPal account payment. We recommend that you reauthorize a payment after the initial 3-day honor period to ensure that funds are still available.

You can reauthorize a payment only once 4 to 29 days after 3-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 reauthorized payment itself has a new 3-day honor period. You can reauthorize a transaction once for up to 115% of the originally authorized amount, not to exceed an increase of $75 USD.

Note: You can only reauthorize PayPal account payments.

Request

Pass the authorization id in the endpoint along with a new authorization object if you need to authorize a different amount.

Property Type Description
amount amount object Amount being reauthorized. Required.
     

Request Sample

curl -v https://api.sandbox.paypal.com/v1/payments/authorization/<Authorization-Id>/reauthorize \
-H "Content-Type:application/json"  \
-H "Authorization: Bearer <Access-Token>"  \
-d '{
  "amount":{
    "total":"7.00",
    "currency":"USD"
  }
}
@authorization = Authorization.find("7YK97137TM7104916")
@authorization.amount = {
  :currency => "USD",
  :total => "7.00" }
@authorization.reauthorize # Return true or false
authorization = Authorization.find("7YK97137TM7104916")
authorization.amount = {
  "currency": "USD",
  "total": "7.00" }
authorization.reauthorize() # Return True or False
  
var reauthorize_details = {
  "amount": {
    "currency": "USD",
    "total": "7.00" }
  };

paypal_sdk.authorization.reauthorize("7YK97137TM7104916", reauthorize_details, function (error, reauthorization) {
  if (error) {
    console.error(error);
  } else {
    console.log(reauthorization);
  }
});
OAuthTokenCredential tokenCredential = new OAuthTokenCredential(
				"<CLIENT_ID>", "<CLIENT_SECRET>");
				
String accessToken = tokenCredential.getAccessToken();
Authorization authorization = Authorization.get(accessToken, "7YK97137TM7104916");

Amount reauthorizeAmount = new Amount();
reauthorizeAmount.setCurrency("USD");
reauthorizeAmount.setTotal("7.00");
authorization.setAmount(reauthorizeAmount);

Authorization reauthorization = authorization.reauthorize(accessToken);
$apiContext = new ApiContext(new OAuthTokenCredential(
		"<CLIENT_ID>", "<CLIENT_SECRET>"));
		
$amount = new Amount();
$amount->setCurrency("USD");
$amount->setTotal("7.00");

$authorization = Authorization::get('7YK97137TM7104916', $apiContext);
$authorization->setAmount($amount);

$reauthorization = $authorization->reauthorize($apiContext);
OAuthTokenCredential tokenCredential = new OAuthTokenCredential(
				"<CLIENT_ID>", "<CLIENT_SECRET>");
string accessToken = tokenCredential.GetAccessToken();

Authorization authorization = Authorization.Get(accessToken, "7YK97137TM7104916");
Amount reauthorizeAmount = new Amount();
reauthorizeAmount.currency = "USD";
reauthorizeAmount.total = "7.00";
authorization.amount = reauthorizeAmount;

Authorization reauthorization = authorization.Reauthorize(accessToken);

Response

Returns an authorization object with details of the reauthorization.

Property Type Description
amount amount object Amount being reauthorized.
create_time date_time Time of authorization as defined in RFC 3339 Section 5.6.
Value assigned by PayPal.
update_time date_time Time that the resource was last updated.
Value assigned by PayPal.
state enum State of the authorization. Either pending or authorized.
Value assigned by PayPal.
parent_payment string ID of the payment resource on which this transaction is based.
Value assigned by PayPal.
id string ID of the authorization transaction.
Value assigned by PayPal.
valid_until date_time Authorization expiration time and date as defined in RFC 3339 Section 5.6.
Value assigned by PayPal.
links array of links objects HATEOAS links related to this request.
Value assigned by PayPal.
     

Response Sample

{
  "id": "8AA831015G517922L",
  "create_time": "2013-06-25T21:39:15Z",
  "update_time": "2013-06-25T21:39:17Z",
  "state": "authorized",
  "amount": {
    "total": "7.00",
    "currency": "USD"
  },
  "parent_payment": "PAY-7LD317540C810384EKHFAGYA",
  "valid_until": "2013-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

The /capture resource and sub-resources allow you to look up and refund captured payments.

URI

https://api.paypal.com/v1/payments/capture

Look up a captured payment

Operation

GET /v1/payments/capture/<Capture-Id>

Use this call to get details about a captured payment.

Request

Pass the capture id in the endpoint.

Request Sample

curl -v -X GET https://api.sandbox.paypal.com/v1/payments/capture/<Capture-Id> \
-H "Content-Type:application/json" \
-H "Authorization: Bearer <Access-Token>"
@capture = Capture.find("8F148933LY9388354")
capture = Capture.find("8F148933LY9388354")
paypal_sdk.capture.get("8F148933LY9388354", function(error, capture){
  if(error){
    console.error(error);
  } else {
    console.log(capture);
  }
});
OAuthTokenCredential tokenCredential = new OAuthTokenCredential(
				"<CLIENT_ID>", "<CLIENT_SECRET>");

String accessToken = tokenCredential.getAccessToken();

Capture capture = Capture.get(accessToken, "8F148933LY9388354");
$apiContext = new ApiContext(new OAuthTokenCredential(
		"<CLIENT_ID>", "<CLIENT_SECRET>"));
		
$capture = Capture::get('7BA08426L46375838', $apiContext);
OAuthTokenCredential tokenCredential =
  new OAuthTokenCredential("<CLIENT_ID>", "<CLIENT_SECRET>");
  
string accessToken = tokenCredential.GetAccessToken();

Capture capture = Capture.Get(accessToken, "8F148933LY9388354");

Response

Returns a capture object with details about the capture.

Property Type Description
amount amount object Amount being captured. If the amount matches the orginally authorized amount, the state of the authorization changes to captured. If not, the state of the authorization changes to partially_captured.
is_final_capture boolean If set to true, all remaining funds held by the authorization will be released in the funding instrument. Default is false.
create_time date_time Time of capture as defined in RFC 3339 Section 5.6.
Value assigned by PayPal.
update_time date_time Time that the resource was last updated.
Value assigned by PayPal.
state enum State of the capture. Either pending, completed, refunded, or partially_refunded.
Value assigned by PayPal.
parent_payment string ID of the payment resource on which this transaction is based.
Value assigned by PayPal.
transaction_fee currency object Transaction fee applicable for this payment.
id string ID of the capture transaction.
Value assigned by PayPal.
links array of links objects HATEOAS links related to this request.
Value assigned by PayPal.
     

Response Sample

{
  "id": "8F148933LY9388354",
  "amount": {
    "total": "110.54",
    "currency": "USD",
    "details": {
      "subtotal": "110.54"
    }
  },
  "is_final_capture": false,
  "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 a captured payment

Operation

POST /v1/payments/capture/<Capture-Id>/refund

Use this call to refund a captured payment. Provide the captureId in the URI and an amount object. For partial refunds, you can include a lower amount object.

Request

Provide the capture_id in the URI and an amount object.

Property Type Description
amount amount object Refund details including both refunded amount (to Payer) and refunded fee (to Payee). Required.

Request Sample

curl -v https://api.sandbox.paypal.com/v1/payments/capture/<Capture-Id>/refund  \
-H 'Content-Type:application/json'  \
-H 'Authorization: Bearer <Access-Token>'  \
-d '{
  "amount" : {
    "currency" : "USD",
    "total" : "110.54"
  }
}'
@capture = Capture.find("8F148933LY9388354")
@refund  = @capture.refund({
  :amount => {
    :currency => "USD",
    :total => "110.54" }
})
@refund.success? # Return true or false
capture = Capture.find("8F148933LY9388354")
refund  = capture.refund({
  "amount": {
    "currency": "USD",
    "total": "110.54" },
})
refund.success() # Return True or False
var refund_details = {
  "amount": {
    "currency": "USD",
    "total": "110.54" }
};

paypal_sdk.capture.refund("8F148933LY9388354", refund_details, function(error, refund){
  if(error){
    console.error(error);
  } else {
    console.log(refund);
  }
});
OAuthTokenCredential tokenCredential = new OAuthTokenCredential(
				"<CLIENT_ID>", "<CLIENT_SECRET>");

String accessToken = tokenCredential.getAccessToken();

Capture capture = Capture.get(accessToken, "8F148933LY9388354");

Amount refundAmount = new Amount();
refundAmount.setCurrency("USD");
refundAmount.setTotal("1");

Refund refund = new Refund();
refund.setAmount(refundAmount);

Refund responseRefund = capture.refund(accessToken, refund);
$apiContext = new ApiContext(new OAuthTokenCredential(
		"<CLIENT_ID>", "<CLIENT_SECRET>"));
		
$amount = new Amount();
$amount->setCurrency("USD");
$amount->setTotal("1.00");

$refund = new Refund();
$refund->setId('7BA08426L46375838');
$refund->setAmount($amount);

$capture = Capture::get('7BA08426L46375838', $apiContext);
$captureRefund = $capture->refund($refund, $apiContext);
OAuthTokenCredential tokenCredential =
  new OAuthTokenCredential("<CLIENT_ID>", "<CLIENT_SECRET>");
  
string accessToken = tokenCredential.GetAccessToken();

Capture capture = Capture.Get(accessToken, "8F148933LY9388354");

Refund refund = new Refund();

Amount refundAmount = new Amount();
refundAmount.currency = "USD";
refundAmount.total = "1";

refund.amount = refundAmount;
Refund responseRefund = capture.Refund(accessToken, refund);

Response

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

Property Type Description
id string ID of the refund transaction.
Value assigned by PayPal.
amount amount Details including both refunded amount (to payer) and refunded fee (to payee).
create_time date_time Time of refund as defined in RFC 3339 Section 5.6.
Value assigned by PayPal.
update_time date_time Time that the resource was last updated.
Value assigned by PayPal.
state enum State of the refund. Either pending, completed, or failed.
Value assigned by PayPal.
parent_payment string ID of the payment resource on which this transaction is based.
Value assigned by PayPal.
links array of links objects HATEOAS links related to this call.
Value assigned by PayPal.
     

Response Sample

{
  "id": "0P209507D6694645N",
  "create_time": "2013-05-06T22:11:51Z",
  "update_time": "2013-05-06T22:11:51Z",
  "state": "completed",
  "amount": {
    "total": "110.54",
    "currency": "USD"
  },
  "capture_id": "8F148933LY9388354",
  "parent_payment": "PAY-8PT597110X687430LKGECATA",
  "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"
    }
  ]
}

Billing Plans and Agreements

PayPal offers merchants a /billing-plans resource for providing billing plans to users for recurring payments.

After the billing plan is created, the /billing-agreements resource provides billing agreements so that users can agree to be billed for the plans.

URI

https://api.paypal.com/v1/payments/billing-plans https://api.paypal.com/v1/payments/billing-agreements

Create a plan

You can create an empty billing plan and add a trial period and/or regular billing. Alternatively, you can create a fully loaded plan that includes both a trial period and regular billing. Note: By default, a created billing plan is in a CREATED state. A user cannot subscribe to the billing plan unless it has been set to the ACTIVE state.

URI

POST https://api.paypal.com/v1/payments/billing-plans

Use this call to create a billing plan. The request sample shows the plan being created with a regular billing period.

Request

Pass the plan details in the body of a POST call, including the following plan object properties:

Property Type Description
name string Name of the billing plan. Required.
description string Description of the billing plan. Required.
type string Type of the billing plan. Allowed values: FIXED, INFINITE. Required.
payment_definitions array of payment_definition Array of payment definitions for this billing plan.
merchant_preferences merchant_preferences Specific preferences such as: set up fee, max fail attempts, autobill amount, and others that are configured for this billing plan.

Request Sample

curl -v POST https://api.sandbox.paypal.com/v1/payments/billing-plans \
-H 'Content-Type:application/json' \
-H 'Authorization: Bearer <Access-Token>' \
-d '{
    "name": "T-Shirt of the Month Club Plan",
    "description": "Template creation.",
    "type": "fixed",
    "payment_definitions": [
        {
            "name": "Regular Payments",
            "type": "REGULAR",
            "frequency": "MONTH",
            "frequency_interval": "2",
            "amount": {
                "value": "100",
                "currency": "USD"
            },
            "cycles": "12",
            "charge_models": [
                {
                    "type": "SHIPPING",
                    "amount": {
                        "value": "10",
                        "currency": "USD"
                    }
                },
                {
                    "type": "TAX",
                    "amount": {
                        "value": "12",
                        "currency": "USD"
                    }
                }
            ]
        }
    ],
    "merchant_preferences": {
        "setup_fee": {
            "value": "1",
            "currency": "USD"
        },
        "return_url": "http://www.return.com",
        "cancel_url": "http://www.cancel.com",
        "auto_bill_amount": "YES",
        "initial_fail_amount_action": "CONTINUE",
        "max_fail_attempts": "0"
    }
}'

Response

Returns a plan object along with the state of the billing plan. The response includes a billing plan ID that uniquely identifies the plan.

Property Type Description
id string Identifier of the billing plan.
name string Name of the billing plan.
description string Description of the billing plan.
type string Type of the billing plan. Allowed values: FIXED, INFINITE.
state string Status of the billing plan. Allowed values: CREATED, ACTIVE, INACTIVE, and DELETED.
create_time string Time when the billing plan was created. Format YYYY-MM-DDTimeTimezone, as defined in ISO8601.
update_time string Time when this billing plan was updated. Format YYYY-MM-DDTimeTimezone, as defined in ISO8601.
payment_definitions array of payment_definition Array of payment definitions for this billing plan.
terms array of terms Array of terms for this billing plan.
merchant_preferences merchant_preferences Specific preferences such as: set up fee, max fail attempts, autobill amount, and others that are configured for this billing plan.
links array of links HATEOAS links related to this call.

Response Sample

{
  "id": "P-94458432VR012762KRWBZEUA",
  "state": "CREATED",
  "name": "T-Shirt of the Month Club Plan",
  "description": "Template creation.",
  "type": "FIXED",
  "payment_definitions": [
    {
      "id": "PD-50606817NF8063316RWBZEUA",
      "name": "Regular Payments",
      "type": "REGULAR",
      "frequency": "Month",
      "amount": {
        "currency": "USD",
        "value": "100"
      },
      "charge_models": [
        {
          "id": "CHM-55M5618301871492MRWBZEUA",
          "type": "SHIPPING",
          "amount": {
            "currency": "USD",
            "value": "10"
          }
        },
        {
          "id": "CHM-92S85978TN737850VRWBZEUA",
          "type": "TAX",
          "amount": {
            "currency": "USD",
            "value": "12"
          }
        }
      ],
      "cycles": "12",
      "frequency_interval": "2"
    }
  ],
  "merchant_preferences": {
    "setup_fee": {
      "currency": "USD",
      "value": "1"
    },
    "max_fail_attempts": "0",
    "return_url": "http://www.return.com",
    "cancel_url": "http://www.cancel.com",
    "auto_bill_amount": "YES",
    "initial_fail_amount_action": "CONTINUE"
  },
  "create_time": "2014-07-31T17:41:55.920Z",
  "update_time": "2014-07-31T17:41:55.920Z",
  "links": [
    {
      "href": "https://api.sandbox.paypal.com/v1/payments/billing-plans/P-94458432VR012762KRWBZEUA",
      "rel": "self",
      "method": "GET"
    }
  ]
}

Update a plan

Operation

PATCH /v1/payments/billing-plans/<Plan-Id>

You can update the information for an existing billing plan. The state of a plan must be active before a billing agreement is created.

Request

Pass the billing plan id in the URI of a PATCH call, including the replace operation in the body. Other operations in the patch_request object will throw validation exceptions.

Property Type Description
op string The operation to perform. Required. Allowed values: add, remove, replace, move, copy, test
path string String containing a JSON-Pointer value that references a location within the target document where the operation is performed.
value One of the following:
number,
integer,
string,
boolean,
null,
array,
object
New value to apply based on the operation. op=remove does not require value.
from string A string containing a JSON Pointer value that references the location in the target document from which to move the value. Required for use where op=move.

Request Sample

curl -v -k -X PATCH 'https://api.sandbox.paypal.com/v1/payments/billing-plans/P-94458432VR012762KRWBZEUA' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <Access-Token>" \
-d '[
    {
        "path": "/",
        "value": {
            "state": "ACTIVE"
        },
        "op": "replace"
    }
]'

Response

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

Retrieve a plan

Operation

GET /v1/payments/billing-plans/<Plan-Id>

Use this call to get details about a specific billing plan.

Request

Pass the billing plan id in the URI of a GET call.

Request Sample

curl -v -X GET https://api.sandbox.paypal.com/v1/payments/billing-plans/P-94458432VR012762KRWBZEUA \
-H 'Content-Type:application/json' \
-H 'Authorization: Bearer <Access-Token>'

Response

Returns the plan object. A link enables URI access to the billing plan information.

Property Type Description
id string Identifier of the billing plan.
name string Name of the billing plan.
description string Description of the billing plan.
type string Type of the billing plan. Allowed values: FIXED, INFINITE.
state string Status of the billing plan. Allowed values: CREATED, ACTIVE, INACTIVE, and DELETED.
create_time string Time when the billing plan was created. Format YYYY-MM-DDTimeTimezone, as defined in ISO8601.
update_time string Time when this billing plan was updated. Format YYYY-MM-DDTimeTimezone, as defined in ISO8601.
payment_definitions array of payment_definition Array of payment definitions for this billing plan.
terms array of terms Array of terms for this billing plan.
merchant_preferences merchant_preferences Specific preferences such as: set up fee, max fail attempts, autobill amount, and others that are configured for this billing plan.
links array of links HATEOAS links related to this call.

Response Sample

{
  "id": "P-94458432VR012762KRWBZEUA",
  "state": "ACTIVE",
  "name": "T-Shirt of the Month Club Plan",
  "description": "Template creation.",
  "type": "FIXED",
  "payment_definitions": [
    {
      "id": "PD-50606817NF8063316RWBZEUA",
      "name": "Bi-Monthly Regular Payments",
      "type": "REGULAR",
      "frequency": "Month",
      "amount": {
        "currency": "USD",
        "value": "100"
      },
      "cycles": "12",
      "charge_models": [
        {
          "id": "CHM-92S85978TN737850VRWBZEUA",
          "type": "TAX",
          "amount": {
            "currency": "USD",
            "value": "12"
          }
        },
        {
          "id": "CHM-55M5618301871492MRWBZEUA",
          "type": "SHIPPING",
          "amount": {
            "currency": "USD",
            "value": "10"
          }
        }
      ],
      "frequency_interval": "2"
    }
  ],
  "merchant_preferences": {
    "setup_fee": {
      "currency": "USD",
      "value": "1"
    },
    "max_fail_attempts": "0",
    "return_url": "http://www.return.com",
    "cancel_url": "http://www.cancel.com",
    "auto_bill_amount": "YES",
    "initial_fail_amount_action": "CONTINUE"
  },
  "create_time": "2014-07-31T17:41:55.920Z",
  "update_time": "2014-07-31T18:20:53.226Z",
  "links": [
    {
      "href": "https://api.sandbox.paypal.com/v1/payments/billing-plans/P-94458432VR012762KRWBZEUA",
      "rel": "self",
      "method": "GET"
    }
  ]
}

List plans

Operation

GET /v1/payments/billing-plans?page_size=<page_size>& status=<status>&page=<page>&total_required=<total_required>

Use this call to get a list of all billing plans based on their current state and optional query string parameters.

Request

The following input parameters can be used as filters. You can combine filters, as shown in the sample.

Filter Description
status To request billings plans in the CREATED, ACTIVE, or INACTIVE states. The default value is CREATED.
page_size To indicate the maximum number of results to return at one time. The page_size is a non-negative, non-zero integer with a default value of 10.
page To indicate the page to return. The default value is 0.
total_required To indicate that the total number of items (total_items) and pages (total_pages) are expected to be returned in the response.

Request Sample

curl -v -X GET https://api.sandbox.paypal.com/v1/payments/billing-plans?page_size=3&status=CREATED&page=2&total_required=yes \
-H 'Content-Type:application/json' \
-H 'Authorization: Bearer <Access-Token>' \
-d '{}'

Response

Returns a list of billing plans in a plan list object. Note that the plan list object includes only a partial plan resource for each returned plan, including basic information such as the ID, description, and state of each plan as well as a link that enables you to request full details for each returned plan.

The response sample shows billing plans in the CREATED state. Links provide access to the next and previous record.

Property Type Description
plans array of plan Array of billing plans.
total_items string Total number of items.
total_pages string Total number of pages.
links array of links HATEOAS links related to this call.

Response Sample

{
  "total_items": "166",
  "total_pages": "83",
  "plans": [
    {
      "id": "P-94458432VR012762KRWBZEUA",
      "state": "CREATED",
      "name": "T-Shirt of the Month Club Plan",
      "description": "Template creation.",
      "type": "FIXED",
      "create_time": "2014-08-22T04:41:52.836Z",
      "update_time": "2014-08-22T04:41:53.169Z",
      "links": [
        {
          "href": "https://api.sandbox.paypal.com/v1/payments/billing-plans/P-94458432VR012762KRWBZEUA",
          "rel": "self",
          "method": "GET"
        }
      ]
    }
  ],
  "links": [
    {
      "href": "https://api.sandbox.paypal.com/v1/payments/billing-plans?page_size=2&page=1&start=3&status=active",
      "rel": "start",
      "method": "GET"
    },
    {
      "href": "https://api.sandbox.paypal.com/v1/payments/billing-plans?page_size=2&page=0&status=active",
      "rel": "previous_page",
      "method": "GET"
    },
    {
      "href": "https://api.sandbox.paypal.com/v1/payments/billing-plans?page_size=2&page=2&status=active",
      "rel": "next_page",
      "method": "GET"
    },
    {
      "href": "https://api.sandbox.paypal.com/v1/payments/billing-plans?page_size=2&page=82&status=active",
      "rel": "last",
      "method": "GET"
    }
  ]
}

Create an agreement

Operation

POST /v1/payments/v1/payments/billing-agreements

Use this call to create a billing agreement for the buyer. The response for this call includes these HATEOAS links: an approval_url link and an execute link. Each returned link includes the token for the agreement.

For PayPal payments:

  • After successfully creating the agreement, direct the user to the approval_url on the PayPal site so that the user can approve the agreement.
  • Call the execute link to execute the billing agreement.

Note: Billing agreements for credit card payments execute automatically when created. There is no need for the user to approve the agreement or to execute the agreement.

Request

Pass the agreement details in the body of a POST call, including the following agreement object properties:

Property Type Description
name string Name of the agreement. Required.
description string Description of the agreement. Required.
start_date string Start date of the agreement. Date format yyyy-MM-dd z, as defined in ISO8601. Required.
agreement_details agreement_details Details of the agreement.
payer payer Details of the buyer who is enrolling in this agreement. This information is gathered from execution of the approval URL. Required.
shipping_address address Shipping address object of the agreement, which should be provided if it is different from the default address.
override_merchant_preferences merchant_preferences Default merchant preferences from the billing plan are used, unless override preferences are provided here.
override_charge_models array of override_charge_model Array of override_charge_model for this agreement if needed to change the default models from the billing plan.
plan plan Plan details for this agreement. Required.

Request Sample

curl -v POST https://api.sandbox.paypal.com/v1/payments/billing-agreements \
-H 'Content-Type:application/json' \
-H 'Authorization: Bearer <Access-Token>' \
-d '{
    "name": "T-Shirt of the Month Club Agreement",
    "description": "Agreement for T-Shirt of the Month Club Plan",
    "start_date": "2015-02-19T00:37:04Z",
    "plan": {
        "id": "P-94458432VR012762KRWBZEUA"
    },
    "payer": {
        "payment_method": "paypal"
    },
    "shipping_address": {
        "line1": "111 First Street",
        "city": "Saratoga",
        "state": "CA",
        "postal_code": "95070",
        "country_code": "US"
    }
}'

Response

Returns the agreement object based on the billing plan. The response includes a billing agreement id and return links to obtain buyer approval and to execute the agreement.

Property Type Description
id string Identifier of the agreement.
state string State of the agreement. Possible values are Active, Pending, Expired, Suspend, Reactivate, and Cancel.
name string Name of the agreement.
description string Description of the agreement.
start_date string Start date of the agreement. Date format yyyy-MM-dd z, as defined in ISO8601.
agreement_details agreement_details Details of the agreement.
payer payer Details of the buyer who is enrolling in this agreement. This information is gathered from execution of the approval URL.
shipping_address address Shipping address object of the agreement, which should be provided if it is different from the default address.
override_merchant_preferences merchant_preferences Default merchant preferences from the billing plan are used, unless override preferences are provided here.
override_charge_models array of override_charge_model Array of override_charge_model for this agreement if needed to change the default models from the billing plan.
plan plan Plan details for this agreement.
create_time string Date and time that this resource was created. Date format yyyy-MM-dd z, as defined in ISO8601.
update_time string Date and time that this resource was updated. Date format yyyy-MM-dd z, as defined in ISO8601.
links array of links HATEOAS links related to this call.

Response Sample

{
  "name": "T-Shirt of the Month Club Agreement",
  "description": "Agreement for T-Shirt of the Month Club Plan",
  "plan": {
    "id": "P-94458432VR012762KRWBZEUA",
    "state": "ACTIVE",
    "name": "T-Shirt of the Month Club Plan",
    "description": "Template creation.",
    "type": "FIXED",
    "payment_definitions": [
      {
        "id": "PD-50606817NF8063316RWBZEUA",
        "name": "Regular Payments",
        "type": "REGULAR",
        "frequency": "Month",
        "amount": {
          "currency": "USD",
          "value": "100"
        },
        "charge_models": [
          {
            "id": "CHM-92S85978TN737850VRWBZEUA",
            "type": "TAX",
            "amount": {
              "currency": "USD",
              "value": "12"
            }
          },
          {
            "id": "CHM-55M5618301871492MRWBZEUA",
            "type": "SHIPPING",
            "amount": {
              "currency": "USD",
              "value": "10"
            }
          }
        ],
        "cycles": "12",
        "frequency_interval": "2"
      }
    ],
    "merchant_preferences": {
      "setup_fee": {
        "currency": "USD",
        "value": "1"
      },
      "max_fail_attempts": "0",
      "return_url": "http://www.return.com",
      "cancel_url": "http://www.cancel.com",
      "auto_bill_amount": "YES",
      "initial_fail_amount_action": "CONTINUE"
    }
  },
  "links": [
    {
      "href": "https://www.sandbox.paypal.com/cgi-bin/webscr?cmd=_express-checkout&token=EC-0JP008296V451950C",
      "rel": "approval_url",
      "method": "REDIRECT"
    },
    {
      "href": "https://api.sandbox.paypal.com/v1/payments/billing-agreements/EC-0JP008296V451950C/agreement-execute",
      "rel": "execute",
      "method": "POST"
    }
  ],
  "start_date": "2015-02-19T00:37:04Z"
}

Execute an agreement

Operation

POST /v1/payments/billing-agreements/ <token>/agreement-execute

Use this call to execute an agreement after the buyer approves it.

Note: This request is only necessary for PayPal payments. Billing agreements for credit card payments execute automatically at the time of creation and so this request is not necessary for credit card payments.

Request

Pass the token in the URI of a POST call to execute the subscription agreement after buyer approval. You can find the token in the execute link returned by the request to create a billing agreement. For example, in the response sample for creating a billing agreement, the token value is EC-0JP008296V451950C.

Request Sample

curl -v POST https://api.sandbox.paypal.com/v1/payments/billing-agreements/EC-0JP008296V451950C/agreement-execute \
-H 'Content-Type:application/json' \
-H 'Authorization: Bearer <Access-Token>' \
-d '{}'

Response

Returns the agreement object. Links enable access to the plan information and an option to suspend the plan.

Property Type Description
id string Identifier of the agreement.
state string State of the agreement. Possible values are Active, Pending, Expired, Suspend, Reactivate, and Cancel.
name string Name of the agreement.
description string Description of the agreement.
start_date string Start date of the agreement. Date format yyyy-MM-dd z, as defined in ISO8601.
agreement_details agreement_details Details of the agreement.
payer payer Details of the buyer who is enrolling in this agreement. This information is gathered from execution of the approval URL.
shipping_address address Shipping address object of the agreement, which should be provided if it is different from the default address.
override_merchant_preferences merchant_preferences Default merchant preferences from the billing plan are used, unless override preferences are provided here.
override_charge_models array of override_charge_model Array of override_charge_model for this agreement if needed to change the default models from the billing plan.
plan plan Plan details for this agreement.
create_time string Date and time that this resource was created. Date format yyyy-MM-dd z, as defined in ISO8601.
update_time string Date and time that this resource was updated. Date format yyyy-MM-dd z, as defined in ISO8601.
links array of links HATEOAS links related to this call.

Response Sample

{
  "id": "I-0LN988D3JACS",
  "links": [
    {
      "href": "https://api.sandbox.paypal.com/v1/payments/billing-agreements/I-0LN988D3JACS",
      "rel": "self",
      "method": "GET"
    }
  ]
}

Update an agreement

Operation

PATCH /v1/payments/billing-agreements/<Agreement-Id>

Use this call to update an agreement.

Request

Pass the billing agreement id in the URI of a PATCH call, including the replace operation in the body. Other operations in the patch_request object will throw validation exceptions.

Property Type Description
op string The operation to perform. Required. Allowed values: add, remove, replace, move, copy, test
path string String containing a JSON-Pointer value that references a location within the target document where the operation is performed.
value One of the following:
number,
integer,
string,
boolean,
null,
array,
object
New value to apply based on the operation. op=remove does not require value.
from string A string containing a JSON Pointer value that references the location in the target document from which to move the value. Required for use where op=move.

Request Sample

curl -v -k -X PATCH 'https://api.sandbox.paypal.com/v1/payments/billing-agreements/I-0LN988D3JACS' \
-H 'Content-Type:application/json' \
-H 'Authorization: Bearer <Access-Token>' \
-d '[
    {
        "op": "replace",
        "path": "/",
        "value": {
            "description": "New Description",
            "shipping_address": {
                "line1": "2065 Hamilton Ave",
                "city": "San Jose",
                "state": "CA",
                "postal_code": "95125",
                "country_code": "US"
            }
        }
    }
]'

Response

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

Retrieve an agreement

Operation

GET /v1/payments/billing-agreements/<Agreement-Id>

Use this call to retrieve an agreement.

Request

Pass the billing agreement id in the URI of a GET call.

Request Sample

curl -v GET https://api.sandbox.paypal.com/v1/payments/billing-agreements/I-0LN988D3JACS \
-H 'Content-Type:application/json' \
-H 'Authorization: Bearer <Access-Token>'

Response

Returns the agreement object.

Property Type Description
id string Identifier of the agreement.
state string State of the agreement. Possible values are Active, Pending, Expired, Suspend, Reactivate, and Cancel.
name string Name of the agreement.
description string Description of the agreement.
start_date string Start date of the agreement. Date format yyyy-MM-dd z, as defined in ISO8601.
agreement_details agreement_details Details of the agreement.
payer payer Details of the buyer who is enrolling in this agreement. This information is gathered from execution of the approval URL.
shipping_address address Shipping address object of the agreement, which should be provided if it is different from the default address.
override_merchant_preferences merchant_preferences Default merchant preferences from the billing plan are used, unless override preferences are provided here.
override_charge_models array of override_charge_model Array of override_charge_model for this agreement if needed to change the default models from the billing plan.
plan plan Plan details for this agreement.
create_time string Date and time that this resource was created. Date format yyyy-MM-dd z, as defined in ISO8601.
update_time string Date and time that this resource was updated. Date format yyyy-MM-dd z, as defined in ISO8601.
links array of links HATEOAS links related to this call.

Response Sample

{
  "id": "I-0LN988D3JACS",
  "state": "Pending",
  "description": "New Description",
  "plan": {
    "payment_definitions": [
      {
        "type": "REGULAR",
        "frequency": "Month",
        "amount": {
          "currency": "USD",
          "value": "100.00"
        },
        "charge_models": [
          {
            "type": "TAX",
            "amount": {
              "currency": "USD",
              "value": "12.00"
            }
          },
          {
            "type": "SHIPPING",
            "amount": {
              "currency": "USD",
              "value": "10.00"
            }
          }
        ],
        "cycles": "12",
        "frequency_interval": "2"
      }
    ],
    "merchant_preferences": {
      "setup_fee": {
        "currency": "USD",
        "value": "0.00"
      },
      "max_fail_attempts": "0",
      "auto_bill_amount": "YES"
    }
  },
  "links": [
    {
      "href": "https://api.sandbox.paypal.com/v1/payments/billing-agreements/I-0LN988D3JACS/suspend",
      "rel": "suspend",
      "method": "POST"
    },
    {
      "href": "https://api.sandbox.paypal.com/v1/payments/billing-agreements/I-0LN988D3JACS/re-activate",
      "rel": "re_activate",
      "method": "POST"
    },
    {
      "href": "https://api.sandbox.paypal.com/v1/payments/billing-agreements/I-0LN988D3JACS/cancel",
      "rel": "cancel",
      "method": "POST"
    },
    {
      "href": "https://api.sandbox.paypal.com/v1/payments/billing-agreements/I-0LN988D3JACS/bill-balance",
      "rel": "self",
      "method": "POST"
    },
    {
      "href": "https://api.sandbox.paypal.com/v1/payments/billing-agreements/I-0LN988D3JACS/set-balance",
      "rel": "self",
      "method": "POST"
    }
  ],
  "start_date": "2015-02-19T08:00:00Z",
  "agreement_details": {
    "outstanding_balance": {
      "currency": "USD",
      "value": "0.00"
    },
    "cycles_remaining": "12",
    "cycles_completed": "0",
    "final_payment_date": "2016-12-19T10:00:00Z",
    "failed_payment_count": "0"
  }
}

Suspend an agreement

Operation

POST /v1/payments/billing-agreements/<Agreement-Id>/suspend

Use this call to suspend an agreement.

Request

Pass the agreement id in the URI of a POST call. Include the following agreement state descriptor object, with the reason for the suspension in the body.

Property Type Description
note string Reason for changing the state of the agreement.
amount currency The amount and currency of the agreement. It is required to bill outstanding amounts, but is not required when suspending, cancelling or reactivating an agreement.

Request Sample

curl -v POST https://api.sandbox.paypal.com/v1/payments/billing-agreements/I-0LN988D3JACS/suspend \
-H 'Content-Type:application/json' \
-H 'Authorization: Bearer <Access-Token>' \
-d '{
    "note": "Suspending the agreement."
}'

Response

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

Reactivate an agreement

Operation

POST /v1/payments/billing-agreements/<Agreement-Id>/re-activate

Use this call to reactivate an agreement.

Request

Pass the agreement id in the URI of a POST call. Include the following agreement state descriptor object, with the reason for the reactivation in the body.

Property Type Description
note string Reason for changing the state of the agreement.
amount currency The amount and currency of the agreement. It is required to bill outstanding amounts, but is not required when suspending, cancelling or reactivating an agreement.

Request Sample

curl -v POST https://api.sandbox.paypal.com/v1/payments/billing-agreements/I-0LN988D3JACS/re-activate \
-H 'Content-Type:application/json' \
-H 'Authorization: Bearer <Access-Token>' \
-d '{
    "note": "Reactivating the agreement."
}'

Response

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

Cancel an agreement

Operation

POST /v1/payments/billing-agreements/<Agreement-Id>/cancel

Use this call to cancel an agreement.

Request

Pass the agreement id in the URI of a POST call. Include the following agreement state descriptor object, with the reason for the cancellation in the body.

Property Type Description
note string Reason for changing the state of the agreement.
amount currency The amount and currency of the agreement. It is required to bill outstanding amounts, but is not required when suspending, cancelling or reactivating an agreement.

Request Sample

curl -v POST https://api.sandbox.paypal.com/v1/payments/billing-agreements/I-0LN988D3JACS/cancel \
-H 'Content-Type:application/json' \
-H 'Authorization: Bearer <Access-Token>' \
-d '{
    "note": "Canceling the agreement."
}'

Response

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

Search for transactions

Operation

GET /v1/payments/billing-agreements/<Agreement-Id>/transactions? start_date=yyyy-mm-dd&end_date=yyyy-mm-dd

Use this call to search for the transactions within a billing agreement.

Request

The following input parameters can be used as filters. You can combine filters, as shown in the sample.

Filter Description
agreement-id Identifier of the agreement resource for which to list transactions.
start_date The start date of the range of transactions to list.
end_date The end date of the range of transactions to list.

Request Sample

curl -v GET https://api.sandbox.paypal.com/v1/payments/billing-agreements/I-0LN988D3JACS/transactions?start_date=yyyy-mm-dd&end_date=yyyy-mm-dd \
-H 'Content-Type:application/json' \
-H 'Authorization: Bearer <Access-Token>'

Response

Returns the agreement transactions with the following parameters.

Property Type Description
agreement_transaction_list array of agreement_transaction Array of agreement_transaction object.

Response Sample

{
  "agreement_transaction_list": [
    {
      "transaction_id": "I-0LN988D3JACS",
      "status": "Created",
      "transaction_type": "Recurring Payment",
      "payer_email": "bbuyer@example.com",
      "payer_name": "Betsy Buyer",
      "time_stamp": "2014-06-09T09:29:36Z",
      "time_zone": "GMT"
    },
    {
      "transaction_id": "928415314Y5640008",
      "status": "Completed",
      "transaction_type": "Recurring Payment",
      "amount": {
        "currency": "USD",
        "value": "1.00"
      },
      "fee_amount": {
        "currency": "USD",
        "value": "-0.33"
      },
      "net_amount": {
        "currency": "USD",
        "value": "0.67"
      },
      "payer_email": "bbuyer@example.com",
      "payer_name": "Betsy Buyer",
      "time_stamp": "2014-06-09T09:42:47Z",
      "time_zone": "GMT"
    },
    {
      "transaction_id": "I-0LN988D3JACS",
      "status": "Suspended",
      "transaction_type": "Recurring Payment",
      "payer_email": "bbuyer@example.com",
      "payer_name": "Betsy Buyer",
      "time_stamp": "2014-06-09T11:18:34Z",
      "time_zone": "GMT"
    },
    {
      "transaction_id": "I-0LN988D3JACS",
      "status": "Reactivated",
      "transaction_type": "Recurring Payment",
      "payer_email": "bbuyer@example.com",
      "payer_name": "Betsy Buyer",
      "time_stamp": "2014-06-09T11:18:48Z",
      "time_zone": "GMT"
    }
  ]
}

Set outstanding agreement amounts

Operation

POST /v1/payments/billing-agreements/<Agreement-Id>/set-balance

Use this call to set the outstanding amount of an agreement.

Request

Pass the agreement id in the URI of a POST call. Include the following currency properties:

Property Type Description
currency string 3 letter currency code as defined by ISO 4217. Required.
value string amount up to N digit after the decimals separator as defined in ISO 4217 for the appropriate currency code. Required.

Request Sample

curl -v POST https://api.sandbox.paypal.com/v1/payments/billing-agreements/I-0LN988D3JACS/set-balance \
-H 'Content-Type:application/json' \
-H 'Authorization: Bearer <Access-Token>' \
-d '{
    "value": "100",
    "currency": "USD"
}'

Response

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

Bill outstanding agreement amounts

Operation

POST /v1/payments/billing-agreements/<Agreement-Id>/bill-balance

Use this call to bill the outstanding amount of an agreement.

Request

Pass the agreement id in the URI of a POST call. Include the following agreement state descriptor object in the body. The amount parameter is required in this circumstance:

Property Type Description
note string Reason for changing the state of the agreement.
amount currency The amount and currency of the agreement. It is required to bill outstanding amounts, but is not required when suspending, cancelling or reactivating an agreement.

Request Sample

curl -v POST https://api.sandbox.paypal.com/v1/payments/billing-agreements/I-0LN988D3JACS/bill-balance \
-H 'Content-Type:application/json' \
-H 'Authorization: Bearer <Access-Token>' \
-d '{
    "note": "Billing Balance Amount",
    "amount": {
        "value": "100",
        "currency": "USD"
    }
}'

Response

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

Orders

Use the /orders resource to take action on a payment with the the intent of order. Actions include authorize, capture, void, and look up orders. Also see create and process an order for further information about using the /payment resource to create and execute an order.

URIs

https://api.paypal.com/v1/payments/orders

Retrieve an order

Operation

GET /v1/payments/orders/<Order-Id>

Specify an order ID to get details about an order.

Request

Pass the order id in the URI of a GET call.

Request Sample

curl -v -X GET https://api.sandbox.paypal.com/v1/payments/orders/O-4J082351X3132253H \
-H 'Content-Type:application/json' \
-H 'Authorization: Bearer <Access-Token>'

Response

Returns an order object.

Property Type Description
id string Identifier of the order transaction.
purchase_unit_reference_id string Identifier of the purchased unit associated with this object.
create_time date-time Time the resource was created.
update_time date-time Time the resource was last updated.
amount array Amount being collected.
state string State of the order transaction. Allowed values: PENDING, COMPLETED, REFUNDED, or PARTIALLY_REFUNDED.
pending_reason string Reason the transaction is in pending state. Allowed values: PAYER-SHIPPING-UNCONFIRMED, MULTI-CURRENCY, RISK-REVIEW, REGULATORY-REVIEW, VERIFICATION-REQUIRED, ORDER, or OTHER.
reason_code string Reason code for the transaction state being Pending or Reversed. Only supported when the payment_method is set to paypal. Value assigned by PayPal. Allowed values: CHARGEBACK, GUARANTEE, BUYER_COMPLAINT, REFUND, UNCONFIRMED_SHIPPING_ADDRESS, ECHECK, INTERNATIONAL_WITHDRAWAL, RECEIVING_PREFERENCE_MANDATES_MANUAL_ACTION, PAYMENT_REVIEW, REGULATORY_REVIEW, UNILATERAL, or VERIFICATION_REQUIRED.
clearing_time string Expected clearing time for eCheck transactions. Only supported when the payment_method is set to paypal. Value assigned by PayPal.
protection_eligibility string 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. Refer to protection_eligibility_type for specifics.
INELIGIBLE- Merchant is not protected under the Seller Protection Policy.
protection_eligibility_type string 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. Allowed values:
ITEM_NOT_RECEIVED_ELIGIBLE- Sellers are protected against claims for items not received.
UNAUTHORIZED_PAYMENT_ELIGIBLE- Sellers are protected against claims for unauthorized payments.
One or both of the allowed values can be returned.
links array of links objects HATEOAS links related to this request.
Value assigned by PayPal.
     

Response Sample

{
  "id": "O-4J082351X3132253H",
  "create_time": "2014-08-01T18:47:06Z",
  "update_time": "2014-08-01T18:54:58Z",
  "state": "pending",
  "amount": {
    "total": "41.15",
    "currency": "USD",
    "details": {
      "subtotal": "30.00",
      "tax": "0.15",
      "shipping": "11.00"
    }
  },
  "pending_reason": "order",
  "parent_payment": "PAY-7J723524EX658994BKPN6BKQ",
  "links": [
    {
      "href": "https://api.sandbox.paypal.com/v1/payments/orders/O-4J082351X3132253H",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://api.sandbox.paypal.com/v1/payments/payment/PAY-7J723524EX658994BKPN6BKQ",
      "rel": "parent_payment",
      "method": "GET"
    },
    {
      "href": "https://api.sandbox.paypal.com/v1/payments/orders/O-4J082351X3132253H/do-void",
      "rel": "void",
      "method": "POST"
    },
    {
      "href": "https://api.sandbox.paypal.com/v1/payments/orders/O-4J082351X3132253H/authorize",
      "rel": "authorization",
      "method": "POST"
    },
    {
      "href": "https://api.sandbox.paypal.com/v1/payments/orders/O-4J082351X3132253H/capture",
      "rel": "capture",
      "method": "POST"
    }
  ]
}

Authorize an order

Operation

POST /v1/payments/orders/<Order-Id>/authorize

Use this call to authorize an order.

Request

Pass the orderId in the URI of a POST call, including the following order properties in the body.

amount amount object Amount being collected. Required.

Request Sample

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

Response

Returns an authorization object.

Property Type Description
amount amount object Amount being authorized.
create_time date-time Time of authorization as defined in RFC 3339 Section 5.6.
Value assigned by PayPal.
update_time date-time Time that the resource was last updated.
Value assigned by PayPal.
state enum State of the authorization. Either pending, authorized, captured, partially_captured, expired, or voided.
Value assigned by PayPal.
parent_payment string ID of the payment resource on which this transaction is based.
Value assigned by PayPal.
id string ID of the authorization transaction.
Value assigned by PayPal.
valid_until date-time Authorization expiration time and date as defined in RFC 3339 Section 5.6.
Value assigned by PayPal.
clearing_time string Expected clearing time for eCheck transactions. Only supported when the payment_method is set to paypal. Value assigned by PayPal.
protection_eligibility string 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. Refer to protection_eligibility_type for specifics.
INELIGIBLE- Merchant is not protected under the Seller Protection Policy.
protection_eligibility_type string 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. Allowed values:
ITEM_NOT_RECEIVED_ELIGIBLE- Sellers are protected against claims for items not received.
UNAUTHORIZED_PAYMENT_ELIGIBLE- Sellers are protected against claims for unauthorized payments.
One or both of the allowed values can be returned.
links array of links objects HATEOAS links related to this request.
Value assigned by PayPal.
     

Response Sample

{
  "id": "1CT49051HM238133B",
  "create_time": "2014-08-01T19:05:00Z",
  "update_time": "2014-08-01T19:05:01Z",
  "amount": {
    "total": "7.00",
    "currency": "USD"
  },
  "state": "authorized",
  "parent_payment": "PAY-7J723524EX658994BKPN6BKQ",
  "links": [
    {
      "href": "https://api.sandbox.paypal.com/v1/payments/orders/O-4J082351X3132253H",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://api.sandbox.paypal.com/v1/payments/authorization/1CT49051HM238133B/reauthorize",
      "rel": "reauthorize",
      "method": "POST"
    },
    {
      "href": "https://api.sandbox.paypal.com/v1/payments/authorization/1CT49051HM238133B",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://api.sandbox.paypal.com/v1/payments/authorization/1CT49051HM238133B/capture",
      "rel": "capture",
      "method": "POST"
    },
    {
      "href": "https://api.sandbox.paypal.com/v1/payments/authorization/1CT49051HM238133B/void",
      "rel": "void",
      "method": "POST"
    },
    {
      "href": "https://api.sandbox.paypal.com/v1/payments/payment/PAY-7J723524EX658994BKPN6BKQ",
      "rel": "parent_payment",
      "method": "GET"
    }
  ]
}

Capture an order

Operation

POST /v1/payments/orders/<Order-Id>/capture

Use this call to capture a payment on an order. To use this call, an original payment call must specify an intent of order.

Request

Pass the orderId in the URI of a POST call, including the following capture properties in the body.

Property Type Description
amount amount Amount being captured. If the amount matches the orginally authorized amount, the state of the authorization changes to captured. If not, the state of the authorization changes to partially_captured. Alternatively, you can set the is_final_capture to true to indicate a final capture.
is_final_capture boolean If set to true, all remaining funds held by the authorization will be released in the funding instrument. Default is ‘false’.
transaction_fee currency Transaction fee applicable for this payment.

Request Sample

curl -v -X POST https://api.sandbox.paypal.com/v1/payments/orders/O-4J082351X3132253H/capture \
-H 'Content-Type:application/json' \
-H 'Authorization: Bearer <Access-Token>' \
-d '{
    "amount": {
        "total": "7.00",
        "currency": "USD"
    },
    "is_final_capture": false
}'

Response

Returns a capture object.

Property Type Description
id string ID of the capture transaction.
amount amount Amount being captured. If the amount matches the orginally authorized amount, the state of the authorization changes to captured. If not, the state of the authorization changes to partially_captured. Alternatively, you can set the is_final_capture to true to indicate a final capture.
is_final_capture boolean If set to true, all remaining funds held by the authorization will be released in the funding instrument. Default is ‘false’.
state string State of the sale. Allowed values: pending, completed, refunded, partially_refunded
parent_payment string ID of the payment resource on which this transaction is based.
transaction_fee currency Transaction fee applicable for this payment.
create_time string Time of capture as defined in RFC 3339 Section 5.6.
update_time string Time that the resource was last updated.
links array of links HATEOAS links related to this call.

Response Sample

{
  "id": "1HF371213Y593954N",
  "create_time": "2014-08-01T19:09:50Z",
  "update_time": "2014-08-01T19:09:51Z",
  "amount": {
    "total": "7.00",
    "currency": "USD"
  },
  "is_final_capture": false,
  "state": "completed",
  "parent_payment": "PAY-7J723524EX658994BKPN6BKQ",
  "links": [
    {
      "href": "https://api.sandbox.paypal.com/v1/payments/capture/1HF371213Y593954N",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://api.sandbox.paypal.com/v1/payments/capture/1HF371213Y593954N/refund",
      "rel": "refund",
      "method": "POST"
    },
    {
      "href": "https://api.sandbox.paypal.com/v1/payments/orders/O-4J082351X3132253H",
      "rel": "order",
      "method": "GET"
    },
    {
      "href": "https://api.sandbox.paypal.com/v1/payments/payment/PAY-7J723524EX658994BKPN6BKQ",
      "rel": "parent_payment",
      "method": "GET"
    }
  ]
}

Void an order

Operation

POST /v1/payments/orders/<Order-Id>/do-void

Use this call to void an existing order.

Note: An order cannot be voided if payment has already been partially or fully captured.

Request

Pass the orderID in the URI of a POST call.

Request Sample

curl -v -X POST https://api.sandbox.paypal.com/v1/payments/orders/O-4J082351X3132253H/do-void \
-H 'Content-Type:application/json' \
-H 'Authorization: Bearer <Access-Token>'

Response

Returns an order object.

Property Type Description
id string Identifier of the order transaction.
purchase_unit_reference_id string Identifier of the purchased unit associated with this object.
create_time date-time Time the resource was created.
update_time date-time Time the resource was last updated.
amount array Amount being collected.
state string State of the order transaction. Allowed values: PENDING, COMPLETED, REFUNDED, or PARTIALLY_REFUNDED.
pending_reason string Reason the transaction is in pending state. Allowed values: PAYER-SHIPPING-UNCONFIRMED, MULTI-CURRENCY, RISK-REVIEW, REGULATORY-REVIEW, VERIFICATION-REQUIRED, ORDER, or OTHER.
reason_code string Reason code for the transaction state being Pending or Reversed. Only supported when the payment_method is set to paypal. Value assigned by PayPal. Allowed values: CHARGEBACK, GUARANTEE, BUYER_COMPLAINT, REFUND, UNCONFIRMED_SHIPPING_ADDRESS, ECHECK, INTERNATIONAL_WITHDRAWAL, RECEIVING_PREFERENCE_MANDATES_MANUAL_ACTION, PAYMENT_REVIEW, REGULATORY_REVIEW, UNILATERAL, or VERIFICATION_REQUIRED.
clearing_time string Expected clearing time for eCheck transactions. Only supported when the payment_method is set to paypal. Value assigned by PayPal.
protection_eligibility string 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. Refer to protection_eligibility_type for specifics.
INELIGIBLE- Merchant is not protected under the Seller Protection Policy.
protection_eligibility_type string 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. Allowed values:
ITEM_NOT_RECEIVED_ELIGIBLE- Sellers are protected against claims for items not received.
UNAUTHORIZED_PAYMENT_ELIGIBLE- Sellers are protected against claims for unauthorized payments.
One or both of the allowed values can be returned.
links array of links objects HATEOAS links related to this request.
Value assigned by PayPal.
     

Response Sample

{
  "id": "O-4J082351X3132253H",
  "create_time": "2014-06-28T07:35:08Z",
  "update_time": "2014-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-7J723524EX658994BKPN6BKQ",
  "links": [
    {
      "href": "https://api.sandbox.paypal.com/v1/payments/authorization/O-4J082351X3132253H",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://api.sandbox.paypal.com/v1/payments/payment/PAY-7J723524EX658994BKPN6BKQ",
      "rel": "parent_payment",
      "method": "GET"
    }
  ]
}

Refund an order

It is not possible to refund an order directly. Instead, you must refund a completed payment of the order. Refer to the following how-to guides for integration information:

For operation information as well as request and response details, see Refund a captured payment.

Payouts

The Payouts feature enables you to make PayPal payments to multiple PayPal accounts in a single API call. You can specify the recipients using their PayPal email addresses, phone numbers, or encrypted PayPal account numbers.

The Payout APIs are a fast, convenient way to send commissions, rebates, rewards, and general disbursements. Payouts appear as Mass Payments in the sender’s PayPal account and are provided with the Mass Payment reports.

Important: To use Payouts, you must request access through your account page. Alternatively, contact your Account Manager or PayPal Customer Support. You must have a PayPal business account.

As in the case of other REST APIs, the Payouts APIs use ISO 8601 as the date format.

The payout batch sections begin at Create a batch or single payout.

URIs

https://api.paypal.com/v1/payments/payouts https://api.paypal.com/v1/payments/payouts-item

Create a batch or single payout

Operation

POST /v1/payments/payouts

You can make payouts to multiple PayPal accounts or to a single PayPal account.

By default, a payout API call is asynchronous, which means you retrieve the results of the payout at a later time. See Create a batch payout.

If you are submitting a single payout, you can make a synchronous payout call, which immediately returns the results of the payout. In a synchronous payout call, the response is similar to a batch payout status response. To make a synchronous payout, specify sync_mode=true in the URL: /v1/payments/payouts?sync_mode=true

The asynchronous payout mode (sync_mode=false, which is the default) enables a maximum of 500 individual payouts to be specified in one API call. Exceeding 500 payouts in one call returns an HTTP response message with status code 400 (Bad Request).

PayPal prevents duplicate batches from being processed. If you specify a sender_batch_id that was used in the last 30 days, PayPal does not process the batch and returns a status of DUPLICATE for batch_status. For items, you can specify a sender_item_id. The sender_item_id of an item must be unique within a given batch. If the same sender_item_id is used for more than one item within the same batch, only the first item will be processed; the duplicate items having the same sender_item_id will not be processed.

Note: Payouts does not currently support BN Codes. In a future release of Payouts, BN Codes optionally can be provided in the PayPal-Partner-Attribution-Id header of the request. For information about the PayPal-Partner-Attribution-Id header, see Authentication & Headers. To learn more or to request a BN Code, contact your Partner Manager or visit the following location: PayPal Partner Portal.

Request

Include a sender_batch_header object to describe how the payments in a specified items array are handled.

For the difference between creating a payout asynchronously and creating a payout synchronously, see the information above. The items array in a synchronous call is the same as the items array in an asynchronous call, except that only one item is specified. To make a synchronous payout, specify sync_mode=true in the URL; see Create a single payout.

The recipient_type in the sender_batch_header is the type of identification that can be used for payment receivers. If recipient_type is provided in the sender_batch_header, the payout items without a recipient_type will use the value in the sender_batch_header. If recipient_type is not provided in the sender_batch_header, each payout item must include a value for the recipient_type.

Thus, the recipient_type specifies the type of reciever data you are using to identify the receiver. The allowed values are unencrypted email (EMAIL), unencrypted phone number (PHONE), or encrypted PayPal account number (PAYPAL_ID). Note that the recipient_type of PHONE is not supported in the sandbox.

The items array contains payouts (payments) to individual recipients. Each item in the array has data for a single payout (to a single recipient).

Property Type Description
sender_batch_header sender_batch_header The original batch header as provided by the payment sender. Required.
items array of payout_item An array of payout items (that is, a set of individual payouts). Required.

Request Sample

curl -v https://api.sandbox.paypal.com/v1/payments/payouts/ \
-H "Content-Type:application/json" \
-H "Authorization: Bearer <Access-Token>" \
-d '{
    "sender_batch_header": {
        "sender_batch_id": "2014021801",
        "email_subject": "You have a Payout!",
        "recipient_type": "EMAIL"
    },
    "items": [
        {
            "recipient_type": "EMAIL",
            "amount": {
                "value": "1.0",
                "currency": "USD"
            },
            "note": "Thanks for your patronage!",
            "sender_item_id": "201403140001",
            "receiver": "shirt-supplier-one@mail.com"
        }
    ]
}'

Response

The asynchronous payout response contains an ID for a newly created batch payout. The ID, returned in the payout_batch_id field, can be used to get the status of a batch payout. The response also contains data about the batch payout resource that was created by the request.

The batch_status will be PENDING if an initial scan (which checks for syntax errors, missing or duplicated keywords, and more) succeeds. Some payout item values (such as the receiver phone numbers) are not immediately validated before a call response is provided.

For a batch request, if the batch_status is DUPLICATE, it means the sender_batch_id was a duplicate of a sender_batch_id processed in the last 30 days.

For information about the response to a synchronous Payout request, see Create a single payout.

Property Type Description
batch_header batch_header Batch header resource.
links array of string HATEOAS links.

Response Sample

{
  "batch_header": {
    "payout_batch_id": "CDZEC5MJ8R5HY",
    "batch_status": "SUCCESS",
    "time_created": "2014-46-14T06:46:22Z",
    "time_completed": "2014-46-14T06:46:23Z",
    "sender_batch_header": {
      "sender_batch_id": "2014021801",
      "email_subject": "You have a Payout!"
    },
    "amount": {
      "currency": "USD",
      "value": "1.0"
    },
    "fees": {
      "currency": "USD",
      "value": "0.02"
    }
  },
  "items": [
    {
      "payout_item_id": "VHBFGN95AWV82",
      "transaction_id": "0728664497487461D",
      "transaction_status": "SUCCESS",
      "payout_item_fee": {
        "currency": "USD",
        "value": "0.02"
      },
      "payout_batch_id": "CDZEC5MJ8R5HY",
      "payout_item": {
        "amount": {
          "currency": "USD",
          "value": "1.0"
        },
        "note": "Thanks for your patronage!",
        "receiver": "shirt-supplier-one@mail.com",
        "recipient_type": "EMAIL",
        "sender_item_id": "201403140001"
      },
      "time_processed": "2014-46-14T06:46:23Z",
      "links": [
        {
          "href": "https://api.sandbox.paypal.com/v1/payments/payouts-item/VHBFGN95AWV82",
          "rel": "item",
          "method": "GET"
        }
      ]
    }
  ],
  "links": [
    {
      "href": "https://api.sandbox.paypal.com/v1/payments/payouts/CDZEC5MJ8R5HY",
      "rel": "self",
      "method": "GET"
    }
  ]
}

Get the status of a batch payout

Operation

GET /v1/payments/payouts/<Payout-Batch-Id>

This call can be used to periodically to get the latest status of a batch, along with the transaction status and other data for individual items.

This call also returns the payout item IDs for the individual items, e.g. for use when you get the status of an individual payout item.

The following table contains the supported values for the retrieved batch status:

Status value Description
PENDING The batch is waiting to be processed.
PROCESSING The batch is being processed.
DENIED No batch items will be processed.
SUCCESS The batch has been successfully processed. Note that some batch items may not have been completely processed, e.g. because they are unclaimed, or because they are on hold, or for another reason.

The following table contains the supported values for the retrieved item transaction status:

Status Description
SUCCESS The item has been successfully processed.
DENIED The item has been denied payment.
PENDING The item is awaiting payment.
PROCESSING The item is being processed.
FAILED Processing failed for the item.
UNCLAIMED The item is unclaimed. If the item is not claimed within 30 days, the funds will be returned to the sender.
RETURNED The item is returned. The funds are returned if the recipient hasn’t claimed them in 30 days.
ONHOLD The item is on hold.
BLOCKED The item is blocked.
CANCELLED It is not possible for the CANCELLED state to occur if the sender is solely using the API to send Payouts. This status is an edge-case if a sender uses both the MassPay web upload and the Payouts API, cancels the web upload, and then uses the API to find the batch/items. In this case, CANCELLED status is possible.

Request

In the URL, specify the ID of a batch payout. You can use the ID that was returned in the payout_batch_id field when the batch was created.

Request Sample

curl -v -X GET https://api.sandbox.paypal.com/v1/payments/payouts/12345678 \
-H "Content-Type:application/json" \
-H "Authorization: Bearer <Access-Token>"
-d '{}'

Response

Returns the data (including the status) for a batch resource. Also returns the individual payout item IDs (each in a payout_item_id field) and other item data.

Property Type Description
batch_header batch_header A batch header that includes the generated batch status.
items array of payout_item_details Array of the items in a batch payout.

Response Sample

{
  "batch_header": {
    "payout_batch_id": "12345678",
    "batch_status": "PROCESSING",
    "sender_batch_id": "2014021801",
    "time_created": "2014-01-27T10:17:00Z",
    "time_completed": "2014-01-27T11:17:39.00Z",
    "sender_batch_header": {
      "sender_batch_id": "2014021801",
      "email_subject": "You have a Payout!"
    },
    "amount": {
      "value": "435.85",
      "currency": "USD"
    },
    "fees": {
      "value": "5.84",
      "currency": "USD"
    }
  },
  "items": [
    {
      "payout_item_id": "452176",
      "transaction_id": "434176",
      "transaction_status": "SUCCESS",
      "payout_batch_id": "12345678",
      "sender_batch_id": "2014021887",
      "payout_item_fee": {
        "currency": "USD",
        "value": "1.00"
      },
      "payout_item": {
        "recipient_type": "EMAIL",
        "amount": {
          "value": "65.24",
          "currency": "EUR"
        },
        "note": "Thanks for your patronage!",
        "receiver": "shirt-supplier@mail.com",
        "payouts_item_id": "1421388",
        "sender_item_id": "14Feb_978"
      },
      "time_created": "2014-01-27T10:17:00:00Z",
      "time_processed": "2014-01-27T10:18:32Z"
    },
    {
      "payout_item_id": "452123",
      "transaction_id": "434123",
      "transaction_status": "SUCCESS",
      "payout_batch_id": "12345678",
      "sender_batch_id": "2014021802",
      "payout_item_fee": {
        "currency": "USD",
        "value": "1.00"
      },
      "payout_item": {
        "recipient_type": "EMAIL",
        "amount": {
          "value": "59.87",
          "currency": "EUR"
        },
        "note": "Thanks for your patronage!",
        "receiver": "shirt-supplier-two@mail.com",
        "payouts_item_id": "1421345",
        "sender_item_id": "14Feb_321"
      },
      "time_created": "2014-01-27T10:17:00Z",
      "time_processed": "2014-01-27T10:18:15Z"
    },
    {
      "payout_item_id": "452323",
      "transaction_id": "434543",
      "transaction_status": "SUCCESS",
      "payout_batch_id": "12345678",
      "sender_batch_id": "2014021802",
      "payout_item_fee": {
        "currency": "USD",
        "value": "1.00"
      },
      "payout_item": {
        "recipient_type": "EMAIL",
        "amount": {
          "value": "59.87",
          "currency": "EUR"
        },
        "note": "Thanks for your patronage!",
        "receiver": "shirt-supplier-three@mail.com",
        "payouts_item_id": "1421355",
        "sender_item_id": "14Feb_239"
      },
      "time_created": "2014-01-27T10:17:00Z",
      "time_processed": "2014-01-27T10:17:15Z"
    },
    {
      "payout_item_id": "452350",
      "transaction_id": "434543",
      "transaction_status": "SUCCESS",
      "payout_batch_id": "12345678",
      "sender_batch_id": "2014021801",
      "payout_item_fee": {
        "value": "USD",
        "currency": "0.75"
      },
      "payout_item": {
        "recipient_type": "EMAIL",
        "amount": {
          "value": "19.87",
          "currency": "USD"
        },
        "note": "Thanks for your patronage!",
        "receiver": "shirt-supplier-four@mail.com@gmail.com",
        "payouts_item_id": "1421332",
        "sender_item_id": "14Feb_235"
      },
      "time_created": "2014-01-27T10:17:00Z",
      "time_processed": "2014-01-27T10:17:25Z"
    },
    {
      "payout_item_id": "452345",
      "transaction_id": "4345",
      "transaction_status": "SUCCESS",
      "payout_batch_id": "12345678",
      "sender_batch_id": "2014021801",
      "payout_item_fee": {
        "currency": "USD",
        "value": "0.75"
      },
      "payout_item": {
        "recipient_type": "EMAIL",
        "amount": {
          "value": "9.87",
          "currency": "USD"
        },
        "note": "Thanks for your patronage!",
        "receiver": "shirt-supplier-five@mail.com",
        "payouts_item_id": "1421342",
        "sender_item_id": "14Feb_234"
      },
      "time_created": "2014-01-27T10:17:00Z",
      "time_processed": "2014-01-27T10:17:37Z"
    },
    {
      "payout_item_id": "4782902",
      "transaction_id": "6456456",
      "transaction_status": "SUCCESS",
      "payout_item_fee": {
        "currency": "USD",
        "value": "2.35"
      },
      "payout_batch_id": "12345678",
      "sender_batch_id": "2014021801",
      "payout_item": {
        "recipient_type": "PHONE",
        "amount": {
          "value": "112.34",
          "currency": "EUR"
        },
        "note": "Thanks for your support!",
        "receiver": "91-734-234-1234",
        "payouts_item_id": "1421343",
        "sender_item_id": "14Feb_235"
      },
      "time_created": "2014-01-27T10:17:00Z",
      "time_processed": "2014-01-27T10:17:52Z"
    },
    {
      "payout_item_id": "4782902",
      "transaction_id": "",
      "transaction_status": "PROCESSING",
      "payout_batch_id": "12345678",
      "sender_batch_id": "2014021801",
      "payout_item": {
        "recipient_type": "PHONE",
        "amount": {
          "value": "5.32",
          "currency": "USD"
        },
        "note": "Thanks for your patronage!",
        "receiver": "408X234-1234",
        "payouts_item_id": "1421344",
        "sender_item_id": "14Feb_235"
      },
      "time_created": "2014-01-27T10:17:00Z",
      "time_processed": "2014-01-27T10:17:41Z"
    }
  ]
}

Get the status of a payout item

Operation

GET /v1/payments/payouts-item/<Payout-Item-Id>

Use this call to get data about a payout item, including the status, without retrieving an entire batch. You can get the status of an individual payout item in a batch in order to review the current status of a previously-unclaimed, or pending, payout item.

For a table with the supported status values, see the transaction status table in the following section: Get the status of a batch payout.

Request

Specify the value of an individual payout ID (that is, a payout item ID). Individual payout IDs were returned in the payout_item_id field in a previous call for getting the status of a batch payout.

Request Sample

curl -v -X GET https://api.sandbox.paypal.com/v1/payments/payouts-item/452345 \
-H "Content-Type:application/json" \
-H "Authorization: Bearer <Access-Token>"

Response

Returns a payout_item_details object, which contains data about a payout item, including the transaction status.

A payout_item_id is returned to help you identify denied payments. If a payment is denied, even though it lacks a transaction_id, you can identify the payment with the payout_item_id.

Property Type Description
payout_item_id string An ID for an individual payout. Provided by PayPal, such as in the case of getting the status of a batch request.
transaction_id string Generated ID for the transaction.
transaction_status string Status of a transaction. Allowed values: SUCCESS, DENIED, PENDING, PROCESSING, FAILED, UNCLAIMED, RETURNED, ONHOLD, BLOCKED, CANCELLED
payout_item_fee currency Amount of money in U.S. dollars for fees.
payout_batch_id string An ID for the batch payout. Generated by PayPal.
sender_batch_id string Sender-created ID for tracking the batch in an accounting system.
payout_item payout_item The data for a payout item that the sender initially provided.
time_processed string Time of the last processing for this item.
errors error Details of an Error
links array of string HATEOAS links

Response Sample

{
  "payout_item_id": "1421342",
  "transaction_id": "4345",
  "transaction_status": "SUCCESS",
  "payout_item_fee": {
    "currency": "USD",
    "value": "0.35"
  },
  "payout_batch_id": "20140724",
  "payout_item": {
    "amount": {
      "value": "9.87",
      "currency": "USD"
    },
    "recipient_type": "EMAIL",
    "note": "Thanks for your patronage!",
    "receiver": "shirt-supplier@mail.com",
    "sender_item_id": "14Feb_234"
  },
  "time_created": "2014-01-27T10:17:00Z",
  "time_processed": "2014-01-27T10:17:41Z",
  "links": [
    {
      "rel": "self",
      "href": "https://api.sandbox.paypal.com/v1/payments/payouts-item/1421342",
      "method": "GET"
    },
    {
      "rel": "batch",
      "href": "https://api.sandbox.paypal.com/v1/payments/payouts/20140724",
      "method": "GET"
    }
  ]
}

Cancel an unclaimed payout item

Operation

POST /v1/payments/payouts-item/<Payout-Item-Id>/cancel

Use this call to cancel an existing, unclaimed transaction. If an unclaimed item is not claimed within 30 days, the funds will be automatically returned to the sender. This call can be used to cancel the unclaimed item prior to the automatic 30-day return.

Request

Specify the value of an individual payout ID (that is, a payout item ID) in the URI of a POST call, followed by /cancel. Individual payout IDs were returned in the payout_item_id field in a previous call for getting the status of a batch payout. If the transaction_status of the payout_item_id that you originally sent is not equal to UNCLAIMED, then the item cannot be cancelled.

Request Sample

curl -v -X POST https://api.sandbox.paypal.com/v1/payments/payouts-item/452345/cancel \
-H "Content-Type:application/json" \
-H "Content-Encoding":gzip" \
-H "Authorization: Bearer <Access-Token>" \
-d '{}'

Response

If successful, this call returns the payout_item_details object with a transaction_status of RETURNED.

Property Type Description
payout_item_id string An ID for an individual payout. Provided by PayPal, such as in the case of getting the status of a batch request.
transaction_id string Generated ID for the transaction.
transaction_status string Status of a transaction. Allowed values: SUCCESS, DENIED, PENDING, PROCESSING, FAILED, UNCLAIMED, RETURNED, ONHOLD, BLOCKED, CANCELLED
payout_item_fee currency Amount of money in U.S. dollars for fees.
payout_batch_id string An ID for the batch payout. Generated by PayPal.
sender_batch_id string Sender-created ID for tracking the batch in an accounting system.
payout_item payout_item The data for a payout item that the sender initially provided.
time_processed string Time of the last processing for this item.
errors error Details of an Error
links array of string HATEOAS links

Response Sample

{
  "payout_item_id": "1421342",
  "transaction_id": "4345",
  "transaction_status": "RETURNED",
  "payout_item_fee": {
    "currency": "USD",
    "value": "0.35"
  },
  "payout_batch_id": "20140724",
  "sender_batch_id": "2014021801",
  "payout_item": {
    "recipient_type": "EMAIL",
    "amount": {
      "value": "9.87",
      "currency": "USD"
    },
    "note": "Thanks for your patronage!",
    "receiver": "shirt-supplier@mail.com",
    "payouts_item_id": "1421342",
    "sender_item_id": "14Feb_234"
  },
  "time_processed": "2014-01-27T10:17:41Z",
  "errors": {
    "name": "RECEIVER_UNREGISTERED",
    "message": "Receiver is unregistered",
    "information_link": "https://developer.paypal.com/docs/api/#RECEIVER_UNREGISTERED"
  },
  "links": [
    {
      "rel": "self",
      "href": "https://api.sandbox.paypal.com/v1/payments/payouts-item/1421342",
      "method": "GET"
    },
    {
      "rel": "batch",
      "href": "https://api.sandbox.paypal.com/v1/payments/payouts/20140724",
      "method": "GET"
    }
  ]
}

Vault

PayPal offers merchants a /vault API to store sensitive details like credit card related details.

You can currently use the /vault API to store credit card details with PayPal instead of storing them on your own server. After storing a credit card, you can then pass the credit card id instead of the related credit card details to complete a payment.

For more information, learn about using the /vault API to store a credit card.

Direct credit card payment and related features are restricted in some countries.

URI

https://api.paypal.com/v1/vault

Store a credit card

Operation

POST /v1/vault/credit-cards

Use this call to store credit card details with PayPal. To use the stored card, you can then use the returned id as the credit_card_id within a credit_card_token. We also recommend including an external_customer_id.

Request

Provide a credit_card object that includes credit card details.

Property Type Description
number string Credit card number. Numeric characters only with no spaces or punctuation. The string must conform with modulo and length required by each credit card type. Redacted in responses. Required.
type string Credit card type. Valid types are: visa, mastercard, discover, amex Required.
expire_month integer Expiration month with no leading zero. Acceptable values are 1 through 12. Required.
expire_year integer 4-digit expiration year. Required.
payer_id string A unique identifier that you can assign and track when storing a credit card or using a stored 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, username, or email address. This is being deprecated in favor of the external_customer_id property.
cvv2 string 3-4 digit card validation code.
first_name string Cardholder’s first name. 25 characters max.
last_name string Cardholder’s last name.
billing_address address Billing address associated with card. 25 characters max.
external_customer_id string A unique identifier of the customer to whom this bank account belongs. Generated and provided by the facilitator. This is now used in favor of payer_id when creating or using a stored funding instrument in the vault.
merchant_id string A user-provided, optional field that functions as a unique identifier for the merchant holding the card. Note that this has no relation to PayPal merchant id.
external_card_id string A unique identifier of the bank account resource. Generated and provided by the facilitator so it can be used to restrict the usage of the bank account to the specific merchant.
     

Request Sample

curl -v -X POST --insecure https://api.sandbox.paypal.com/v1/vault/credit-cards \
-H 'Content-Type:application/json' \
-H 'Authorization: Bearer <Access-Token>' \
-d '{
    "payer_id": "user12345",
    "type": "visa",
    "number": "4417119669820331",
    "expire_month": "11",
    "expire_year": "2018",
    "first_name": "Betsy",
    "last_name": "Buyer",
    "billing_address": {
        "line1": "111 First Street",
        "city": "Saratoga",
        "country_code": "US",
        "state": "CA",
        "postal_code": "95070"
    }
}'
@credit_card = CreditCard.new({
  :type => "visa",
  :number => "4417119669820331",
  :expire_month => "11",
  :expire_year => "2018",
  :first_name => "Joe",
  :last_name => "Shopper",
  :payer_id => "123456789" })

@credit_card.create # Return true or false

credit_card = CreditCard({
  "type": "visa",
  "number": "4417119669820331",
  "expire_month": "11",
  "expire_year": "2018",
  "first_name": "Joe",
  "last_name": "Shopper",
  "payer_id": "123456789" })

credit_card.create() # Return True or False
var create_card_details = {
  "type": "visa",
  "number": "4417119669820331",
  "expire_month": "11",
  "expire_year": "2018",
  "first_name": "Joe",
  "last_name": "Shopper",
  "payer_id": "123456789" };

paypal_sdk.credit_card.create(create_card_details, function(error, credit_card){
  if(error){
    console.error(error);
  } else {
    console.log(credit_card);
  }
});
OAuthTokenCredential tokenCredential =
  new OAuthTokenCredential("<CLIENT_ID>", "<CLIENT_SECRET>");
String accessToken = tokenCredential.getAccessToken();

CreditCard creditCard = new CreditCard();
creditCard.setNumber("4417119669820331");
creditCard.setExpireMonth("11");
creditCard.setExpireYear("2018");
creditCard.setFirstName("Joe");
creditCard.setLastName("Shopper");
creditCard.setType("visa");
creditCard.setPayerId("123456789");

CreditCard newCreditCard = creditCard.create(accessToken);
$apiContext = new ApiContext(new OAuthTokenCredential(
		"<CLIENT_ID>", "<CLIENT_SECRET>"));
		
$card = new CreditCard();
$card->setNumber('4417119669820331');
$card->setExpire_month('11');
$card->setExpire_year('2018');
$card->setFirst_name('Joe');
$card->setLast_name('Shopper');
$card->setType('visa');
$card->setPayer_Id('123456789');

$card->create($apiContext);
OAuthTokenCredential tokenCredential =
  new OAuthTokenCredential("<CLIENT_ID>", "<CLIENT_SECRET>");
  
string accessToken = tokenCredential.GetAccessToken();

CreditCard creditCard = new CreditCard();
creditCard.number       = "4417119669820331";
creditCard.expire_month = "11";
creditCard.expire_year  = "2018";
creditCard.first_name   = "Joe";
creditCard.last_name    = "Shopper";
creditCard.type         = "visa";
creditCard.payer_id = "123456789";

CreditCard newCreditCard = creditCard.Create(accessToken);

Response

Returns a credit_card object along with state of the funding instrument and valid_until date and time.

Property Type Description
id string ID of the credit card used to complete payment.
Value assigned by PayPal.
payer_id string A unique identifier that you can assign and track when storing a credit card or using a stored 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, username, or email address. This is being deprecated in favor of the external_customer_id property.
number string Credit card number. Numeric characters only with no spaces or punctuation. The string must conform with modulo and length required by each credit card type. Redacted in responses.
type string Credit card type. Valid types are: visa, mastercard, discover, amex
expire_month integer Expiration month with no leading zero. Acceptable values are 1 through 12. month.
expire_year integer 4-digit expiration year.
first_name string Cardholder’s first name.
last_name string Cardholder’s last name.
billing_address address Billing address associated with card.
external_customer_id string A unique identifier of the customer to whom this bank account belongs. Generated and provided by the facilitator. This is now used in favor of payer_id when creating or using a stored funding instrument in the vault.
merchant_id string A user-provided, optional field that functions as a unique identifier for the merchant holding the card. Note that this has no relation to PayPal merchant id.
external_card_id string A unique identifier of the bank account resource. Generated and provided by the facilitator so it can be used to restrict the usage of the bank account to the specific merchant.
create_time date-time Resource creation time in ISO8601 date-time format (ex: 1994-11-05T13:15:30Z).
update_time date-time Resource update time in ISO8601 date-time format (ex: 1994-11-05T13:15:30Z).
state string State of the credit card funding instrument: expired or ok.
Value assigned by PayPal.
valid_until string Funding instrument expiration date.
Value assigned by PayPal.
links array of links objects HATEOAS links related to this call.
Value assigned by PayPal.
     

Response Sample

{
  "id": "CARD-1MD19612EW4364010KGFNJQI",
  "valid_until": "2016-05-07T00:00:00Z",
  "state": "ok",
  "payer_id": "user12345",
  "type": "visa",
  "number": "xxxxxxxxxxxx0331",
  "expire_month": "11",
  "expire_year": "2018",
  "first_name": "Betsy",
  "last_name": "Buyer",
  "links": [
    {
      "href": "https://api.sandbox.paypal.com/v1/vault/credit-cards/CARD-1MD19612EW4364010KGFNJQI",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://api.sandbox.paypal.com/v1/vault/credit-cards/CARD-1MD19612EW4364010KGFNJQI",
      "rel": "delete",
      "method": "DELETE"
    }
  ]
}

Delete a stored credit card

Operation

DELETE /v1/vault/credit-cards/<Credit-Card-Id>

Use this call to delete details of a credit card. Simply include the credit card id in the request URI.

Note: Even if you delete a credit card, some limited information about that credit card is provided when you look up a sale.

Request

Pass the credit card id in the endpoint.

Request Sample

curl -v -X DELETE --insecure https://api.sandbox.paypal.com/v1/vault/credit-cards/<Credit-Card-Id> \
-H "Content-Type:application/json" \
-H "Authorization: Bearer <Access-Token>"
@credit_card = CreditCard.find("CARD-7LT50814996943336KESEVWA")
@credit_card.delete # Return true or false
credit_card = CreditCard.find("CARD-7LT50814996943336KESEVWA")
credit_card.delete() # Return True or False
paypal_sdk.credit_card.delete("CARD-7LT50814996943336KESEVWA", function(error, no_response){
  if(error){
    console.error(error);
  } else {
    console.log(no_response);
  }
});
OAuthTokenCredential tokenCredential =
  new OAuthTokenCredential("<CLIENT_ID>", "<CLIENT_SECRET>");
String accessToken = tokenCredential.getAccessToken();

CreditCard creditCard = CreditCard.get(accessToken, "CARD-7LT50814996943336KESEVWA");

creditCard.delete(accessToken);
$apiContext = new ApiContext(new OAuthTokenCredential(
		"<CLIENT_ID>", "<CLIENT_SECRET>"));
		
$creditCard = CreditCard::get('CARD-38K23067VS968933SKGPU66Q', $apiContext);
$creditCard->delete($apiContext);
OAuthTokenCredential tokenCredential =
  new OAuthTokenCredential("<CLIENT_ID>", "<CLIENT_SECRET>");
  
string accessToken = tokenCredential.GetAccessToken();

CreditCard creditCard = CreditCard.Get(accessToken, "CARD-7LT50814996943336KESEVWA");

creditCard.Delete(accessToken);

Response

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

Look up a stored credit card

Operation

GET /v1/vault/credit-cards/<Credit-Card-Id>

Use this call to look up details of a credit card. Simply include the credit card id in the request URI.

Request

Pass the credit card id in the endpoint.

Request Sample

curl -v --insecure https://api.sandbox.paypal.com/v1/vault/credit-cards/<Credit-Card-Id> \
-H "Content-Type:application/json" \
-H "Authorization: Bearer <Access-Token>"
@credit_card = CreditCard.find("CARD-7LT50814996943336KESEVWA")
credit_card = CreditCard.find("CARD-7LT50814996943336KESEVWA")
paypal_sdk.credit_card.get("CARD-7LT50814996943336KESEVWA", function(error, credit_card){
  if(error){
    console.error(error);
  } else {
    console.log(credit_card);
  }
});
OAuthTokenCredential tokenCredential =
  new OAuthTokenCredential("<CLIENT_ID>", "<CLIENT_SECRET>");
String accessToken = tokenCredential.getAccessToken();

CreditCard creditCard = CreditCard.get(accessToken, "CARD-7LT50814996943336KESEVWA");
$apiContext = new ApiContext(new OAuthTokenCredential(
		"<CLIENT_ID>", "<CLIENT_SECRET>"));
		
$credit_card = CreditCard::get('CARD-7LT50814996943336KESEVWA', $apiContext);
OAuthTokenCredential tokenCredential =
  new OAuthTokenCredential("<CLIENT_ID>", "<CLIENT_SECRET>");
  
string accessToken = tokenCredential.GetAccessToken();

CreditCard creditCard = CreditCard.Get(accessToken, "CARD-7LT50814996943336KESEVWA");

Response

Returns a credit_card object along with state of the funding instrument and valid_until date and time.

Property Type Description
id string ID of the credit card. This ID is provided when creating funding instruments.
payer_id string A unique identifier that you can assign and track when storing a credit card or using a stored 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, username, or email address. This is being deprecated in favor of the external_customer_id property.
number string Credit card number. Numeric characters only with no spaces or punctuation. The string must conform with modulo and length required by each credit card type. Redacted in responses.
type string Credit card type. Valid types are: visa, mastercard, discover, amex
expire_month integer Expiration month with no leading zero. Acceptable values are 1 through 12. month.
expire_year integer 4-digit expiration year.
first_name string Cardholder’s first name.
last_name string Cardholder’s last name.
billing_address address Billing address associated with card.
external_customer_id string A unique identifier of the customer to whom this bank account belongs. Generated and provided by the facilitator. This is now used in favor of payer_id when creating or using a stored funding instrument in the vault.
merchant_id string A user-provided, optional field that functions as a unique identifier for the merchant holding the card. Note that this has no relation to PayPal merchant id.
external_card_id string A unique identifier of the bank account resource. Generated and provided by the facilitator so it can be used to restrict the usage of the bank account to the specific merchant.
create_time date-time Resource creation time in ISO8601 date-time format (ex: 1994-11-05T13:15:30Z).
update_time date-time Resource update time in ISO8601 date-time format (ex: 1994-11-05T13:15:30Z).
state string State of the credit card funding instrument: expired or ok.
Value assigned by PayPal.
valid_until string Funding instrument expiration date.
Value assigned by PayPal.
links array of links objects HATEOAS links related to this call.
Value assigned by PayPal.
     

Response Sample

{
  "id": "CARD-1MD19612EW4364010KGFNJQI",
  "valid_until": "2016-05-07T00:00:00Z",
  "state": "ok",
  "payer_id": "user12345",
  "type": "visa",
  "number": "xxxxxxxxxxxx0331",
  "expire_month": "11",
  "expire_year": "2018",
  "first_name": "Betsy",
  "last_name": "Buyer",
  "links": [
    {
      "href": "https://api.sandbox.paypal.com/v1/vault/credit-cards/CARD-1MD19612EW4364010KGFNJQI",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://api.sandbox.paypal.com/v1/vault/credit-cards/CARD-1MD19612EW4364010KGFNJQI",
      "rel": "delete",
      "method": "DELETE"
    }
  ]
}

List credit card resources

Operation

GET /v1/vault/credit-cards

Use this call to retrieve a list of credit card resources.

Request

The preceding URI lists credit card resources according to the parameters that you specify. The parameters act as filters for the results and you can append one or more of the following query parameters to the request URI:

Filter Description
merchant_id ID of the merchant for which you want to list credit card resources.
external_card_id Externally provided ID of the card for which you want to list credit card resources.
external_customer_id Externally provided ID of the customer for which you want to list credit card resources.
page The page number to retrieve. The default is 1, the minimum is 1.
page_size Number of resources to be retrieved, starting with the specified page. The default is 10, the minimum is 1, and the maximum is 20.
start_time Resource creation time as ISO8601 date-time format that indicates the start of a range of results. Example: 2013-11-05T13:15:30Z
end_time Resource creation time as ISO8601 date-time format that indicates the end of a range of results. Example: 2014-11-05T13:15:30Z
sort_order Sort based on order of results. Options include asc for ascending order or desc for descending order (default).
sort_by Sort based on create_time or update_time.

Request Sample

curl -v --insecure -X GET https://api.sandbox.paypal.com/v1/vault/credit-cards?external_card_id=card-1 \
-H "Content-Type:application/json" \
-H "Authorization: Bearer <Bearer-Token>" \
-d '{}'

Response

Returns an HTTP status code of 200 OK and an array of credit-card objects.

Property Type Description
items array of credit-card objects Array of credit card objects.
total_items string Total number of items.
total_pages string Total number of pages.
links array of links objects HATEOAS links related to this call.
Value assigned by PayPal.

Response Sample

{
  "items": [
    {
      "id": "CARD-1SW33690TH184423CKM2ZMVY",
      "state": "ok",
      "payer_id": "user12345",
      "type": "visa",
      "number": "xxxxxxxxxxxx0331",
      "expire_month": "11",
      "expire_year": "2018",
      "first_name": "Betsy",
      "last_name": "Buyer",
      "billing_address": {
        "line1": "111 First Street",
        "city": "Saratoga",
        "country_code": "US",
        "state": "CA",
        "postal_code": "95070",
        "phone": "408-334-8890"
      },
      "valid_until": "2017-03-27T00:00:00Z",
      "create_time": "2014-03-28T15:33:43Z",
      "update_time": "2014-03-28T15:42:15Z",
      "links": [
        {
          "href": "https://api.sandbox.paypal.com/v1/vault/credit-cards/CARD-1SW33690TH184423CKM2ZMVY",
          "rel": "self",
          "method": "GET"
        },
        {
          "href": "https://api.sandbox.paypal.com/v1/vault/credit-cards/CARD-1SW33690TH184423CKM2ZMVY",
          "rel": "delete",
          "method": "DELETE"
        },
        {
          "href": "https://api.sandbox.paypal.com/v1/vault/credit-cards/CARD-1SW33690TH184423CKM2ZMVY",
          "rel": "patch",
          "method": "PATCH"
        }
      ]
    }
  ],
  "total_items": 1,
  "total_pages": 1,
  "links": [
    {
      "href": "https://api.sandbox.paypal.com/v1/vault/credit-cards/?page_size=10&sort_by=create_time&external_card_id=card-1&sort_order=asc",
      "rel": "first",
      "method": "GET"
    },
    {
      "href": "https://api.sandbox.paypal.com/v1/vault/credit-cards/?page_size=10&sort_by=create_time&external_card_id=card-1&sort_order=asc&page=1",
      "rel": "last",
      "method": "GET"
    }
  ]
}

Update a stored credit card

Operation

PATCH /v1/vault/credit-cards/<Credit-Card-Id>

Use this call to modify a credit card.

Request

Pass the the credit card id in the URI of a PATCH call, including the patch_request object object with credit-card fields to update in the body.

Property Type Description
op string Patch operation to perform.Value required for add & remove operation can be any JSON value. Required. Allowed values: add, remove, replace
path string string containing a JSON-Pointer value that references a location within the target document (the target location) where the operation is performed. Required.
value object Object to be patched. Optional and not needed when operation is remove.

Request Sample

curl -v --insecure -X PATCH https://api.sandbox.paypal.com/v1/vault/credit-cards/<Credit-Card-ID> \
-H "Content-Type:application/json" \
-H "Authorization: Bearer <Bearer-Token>" \
-d '[
    {
        "op": "replace",
        "path": "/billing_address",
        "value": {
            "line1": "111 First Street",
            "city": "Saratoga",
            "country_code": "US",
            "state": "CA",
            "postal_code": "95070"
        }
    }
]'

Response

Returns an HTTP status code of 200 OK and a credit-card object.

Property Type Description
id string ID of the credit card. This ID is provided when creating funding instruments.
number string Credit card number. Numeric characters only with no spaces or punctuation. The string must conform with modulo and length required by each credit card type. Redacted in responses.
type string Credit card type. Valid types are: visa, mastercard, discover, amex
expire_month integer 2 digit card expiration month.
expire_year integer 4-digit expiration year.
cvv2 integer Card validation code. Only supported when making a Payment but not when saving a credit card for future use.
first_name string Cardholder’s first name.
last_name string Cardholder’s last name.
billing_address address Billing address associated with card.
external_customer_id string A unique identifier of the customer to whom this bank account belongs. Generated and provided by the facilitator. This is now used in favor of payer_id when creating or using a stored funding instrument in the vault.
merchant_id string A user-provided, optional field that functions as a unique identifier for the merchant holding the card. Note that this has no relation to PayPal merchant id.
external_card_id string A unique identifier of the bank account resource. Generated and provided by the facilitator so it can be used to restrict the usage of the bank account to the specific merchant.
create_time date-time Resource creation time in ISO8601 date-time format (ex: 1994-11-05T13:15:30Z).
update_time date-time Resource update time in ISO8601 date-time format (ex: 1994-11-05T13:15:30Z).
state string State of the credit card funding instrument: expired or ok.
Value assigned by PayPal.
valid_until string Funding instrument expiration date.
Value assigned by PayPal.
links array of links objects HATEOAS links related to this call.
Value assigned by PayPal.
     

Response Sample

{
  "id": "CARD-1SW33690TH184423CKM2ZMVY",
  "state": "ok",
  "type": "visa",
  "number": "xxxxxxxxxxxx0331",
  "expire_month": "11",
  "expire_year": "2015",
  "first_name": "Betsy",
  "last_name": "Buyer",
  "billing_address": {
    "line1": "111 First Street",
    "city": "Saratoga",
    "country_code": "US",
    "state": "CA",
    "postal_code": "95070",
    "phone": "408-334-8890"
  },
  "valid_until": "2017-03-27T00:00:00Z",
  "create_time": "2014-03-28T15:33:43Z",
  "update_time": "2014-03-28T15:42:15Z",
  "links": [
    {
      "href": "https://api.sandbox.paypal.com/v1/vault/credit-cards/CARD-1SW33690TH184423CKM2ZMVY",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://api.sandbox.paypal.com/v1/vault/credit-cards/CARD-1SW33690TH184423CKM2ZMVY",
      "rel": "delete",
      "method": "DELETE"
    },
    {
      "href": "https://api.sandbox.paypal.com/v1/vault/credit-cards/CARD-1SW33690TH184423CKM2ZMVY",
      "rel": "patch",
      "method": "PATCH"
    }
  ]
}

Identity

Log In with PayPal (formerly PayPal Access) is a commerce identity solution that enables your customers to sign in to your web site quickly and securely using their PayPal login credentials. Log In with PayPal utilizes the latest security standards, and you don’t have to worry about storing user data on your system.

For more information, learn about Log In with PayPal.

URI

https://api.paypal.com/v1/identity

Grant token from authorization code

Operation

POST /v1/identity/openidconnect/tokenservice

Use this call to grant a new access token, using the previously obtained authorization code.

Request

Create an access token from an authorization code.

Property Type Description
grant_type string Token grant type. Value must be set to authorization_code.
code string Authorization code previously received from the authorization server.
redirect_uri string Application return URL where the authorization code is sent. The specified redirect_uri must match the return URL registered for your app on the Applications page of the PayPal Developer site. All parts of the specified redirect_uri, including protocol, host, port, and context path must match the registered return URL.
     

Request Sample

curl -v https://api.sandbox.paypal.com/v1/identity/openidconnect/tokenservice \
-u "<Client-Id>:<Secret>" \
-d "grant_type=authorization_code
    &code=<Authorization-Code>
    &redirect_uri=http://example.com/myapp/return.php"

Response

Returns a tokeninfo object.

Property Type Description
token_type string The type of the token issued as described in OAuth2.0 RFC6749 - Section 7.1. Value is case insensitive.
expires_in integer The lifetime of the access token in seconds. After the access token expires, use the refresh_token to refresh the access token.
access_token string The access token issued by the authorization server.
refresh_token string The refresh token, which can be used to obtain new access tokens using the same authorization grant as described in OAuth2.0 RFC6749 - Section 6.
     

Response Sample

{
  "token_type": "Bearer",
  "expires_in": "900",
  "refresh_token": "<Refresh-Token>",
  "access_token": "<Access-Token>"
}

Grant token from refresh token

Operation

POST /v1/identity/openidconnect/tokenservice

Use this call to grant a new access token, using a refresh token.

Request

Create an access token from a refresh token.

Property Type Description
grant_type string Token grant type. Value must be set to refresh_token. Required.
refresh_token string Refresh token previously received along with the access token that is to be refreshed. Required.
scope string Resource URL endpoints that the client wants the token to be scoped for. The value of the scope parameter is expressed as a list of space-delimited, case-sensitive strings. These scope values must be a subset of the scopes originally granted by the resource owner. For a list of possible values, see the attributes table.
     

Request Sample

curl -v https://api.sandbox.paypal.com/v1/identity/openidconnect/tokenservice \
-u "<Client-Id>:<Secret>" \
-d "grant_type=refresh_token
    &refresh_token=<Refresh-Token>"
@tokeninfo = Tokeninfo.refresh("jaXPGJ7KIkPkc5Bh9R6kBRFJE6Emmv7M/ukgo46qyTgfIgOt3Yi9Ko/jzj3u09y3nHsld0tyYt03B1rP")
tokeninfo = Tokeninfo.create_with_refresh_token("jaXPGJ7KIkPkc5Bh9R6kBRFJE6Emmv7M/ukgo46qyTgfIgOt3Yi9Ko/jzj3u09y3nHsld0tyYt03B1rP")
var refresh_token = "jaXPGJ7KIkPkc5Bh9R6kBRFJE6Emmv7M/ukgo46qyTgfIgOt3Yi9Ko/jzj3u09y3nHsld0tyYt03B1rP";

paypal_sdk.openid_connect.tokeninfo.refresh(refresh_token, function(error, tokeninfo){
  if(error){
    console.error(error);
  } else {
    console.log(tokeninfo);
  }
});
CreateFromAuthorizationCodeParameters createFromAuthorizationCodeParameters = new CreateFromAuthorizationCodeParameters();
createFromAuthorizationCodeParameters.setCode("6Aam6hMOrHl4v7l...sv16l");
Tokeninfo tokenInfo = Tokeninfo.createFromAuthorizationCode(createFromAuthorizationCodeParameters);

CreateFromRefreshTokenParameters createFromRefreshTokenParameters = new CreateFromRefreshTokenParameters();

Tokeninfo refreshedTokenInfo = tokenInfo.createFromRefreshToken(createFromRefreshTokenParameters);
$token->createFromRefreshToken(array('refresh_token', 'jaXPGJ7KIkPkc5Bh9R6kBRFJE6Emmv7M/ukgo46qyTgfIgOt3Yi9Ko/jzj3u09y3nHsld0tyYt03B1rP'));
CreateFromAuthorizationCodeParameters createFromAuthorizationCodeParameters = new CreateFromAuthorizationCodeParameters();
createFromAuthorizationCodeParameters.setCode("6Aam6hMOrHl4v7l...sv16l");
Tokeninfo tokenInfo = Tokeninfo.CreateFromAuthorizationCode(createFromAuthorizationCodeParameters);

CreateFromRefreshTokenParameters createFromRefreshTokenParameters = new CreateFromRefreshTokenParameters();

Tokeninfo refreshedTokenInfo = tokenInfo.CreateFromRefreshToken(createFromRefreshTokenParameters);

Response

Returns a tokeninfo object.

Property Type Description
token_type string The type of the token issued as described in OAuth2.0 RFC6749 - Section 7.1. Value is case insensitive.
expires_in integer The lifetime of the access token in seconds. After the access token expires, use the refresh_token to refresh the access token.
access_token string The access token issued by the authorization server.
     

Response Sample

{
  "token_type": "Bearer",
  "expires_in": "900",
  "access_token": "4muUxf8pQEdsXYZL1Y8frK9owE1VEmzdT0HUjpT5QEntuFlbKJyIWIP0D9WaLAIOaqHHTg"
}

Get user information

Operation

GET /v1/identity/openidconnect/userinfo/?schema=<Schema>

Use this call to retrieve user profile attributes.

Request

Pass the schema that is used to return as per openidconnect protocol. The only supported schema value is openid.

Request Sample

curl -v https://api.sandbox.paypal.com/v1/identity/openidconnect/userinfo/?schema=openid \
-H "Content-Type:application/json" \
-H "Authorization: Bearer <Access-Token>"
@userinfo = Userinfo.get("ENxom5Fof1KqAffEsXtxwEDa6E1HTEK__KVdIsaCYF8C")
userinfo = Userinfo.get("ENxom5Fof1KqAffEsXtxwEDa6E1HTEK__KVdIsaCYF8C")
paypal_sdk.openid_connect.userinfo.get("ENxom5Fof1KqAffEsXtxwEDa6E1HTEK__KVdIsaCYF8C", function(error, userinfo){
  if(error){
    console.error(error);
  } else {
    console.log(userinfo);
  }
});
CreateFromAuthorizationCodeParameters createFromAuthorizationCodeParameters = new CreateFromAuthorizationCodeParameters();
createFromAuthorizationCodeParameters.setCode("6Aam6hMOrHl4v7l...sv16l");
Tokeninfo tokenInfo = Tokeninfo.createFromAuthorizationCode(createFromAuthorizationCodeParameters);

UserinfoParameters userinfoParameters = new UserinfoParameters();
userinfoParameters.setAccessToken(tokenInfo.getAccessToken());
Userinfo userInfo = Userinfo.getUserinfo(userinfoParameters);
$user = PPOpenIdUserinfo::getUserinfo(
    array(
        'access_token' => 'ENxom5Fof1KqAffEsXtxwEDa6E1HTEK__KVdIsaCYF8C'
    )   
);
CreateFromAuthorizationCodeParameters createFromAuthorizationCodeParameters = new CreateFromAuthorizationCodeParameters();
createFromAuthorizationCodeParameters.setCode("6Aam6hMOrHl4v7l...sv16l");
Tokeninfo tokenInfo = Tokeninfo.CreateFromAuthorizationCode(createFromAuthorizationCodeParameters);

UserinfoParameters userinfoParameters = new UserinfoParameters();
userinfoParameters.setAccessToken(tokenInfo.access_token);
Userinfo userInfo = Userinfo.GetUserinfo(userinfoParameters);

Response

Returns a userinfo object, containing user profile attributes. The attributes returned depend on the scopes configured for the REST app. For example, if the address scope is not configured for the app, the response does not include the address attribute.

Property Type Description
user_id string Identifier for the end-user at the issuer.
name string End-User’s full name in displayable form including all name parts, possibly including titles and suffixes, ordered according to the end-user’s locale and preferences.
given_name string Given name(s) or first name(s) of the end-user.
family_name string Surname(s) or last name(s) of the end-user.
email string End-user’s preferred email address.
verified boolean True if the End-User’s e-mail address has been verified; otherwise false.
gender string End-user’s gender.
birthdate string End-user’s birthday, represented as an YYYY-MM-DD format. They year MAY be 0000, indicating it is omited. To represent only the year, YYYY format would be used.
zoneinfo string Time zone database representing the End-User’s time zone.
locale string End-user’s locale.
phone_number string End-user’s preferred telephone number.
address address End-user’s preferred address.
verified_account boolean Verified account status.
account_type string Account type, either personal or business.
age_range string Account holder age range.
payer_id string Account payer identifier.
     

Response Sample

{
  "user_id": "https://www.paypal.com/webapps/auth/server/64ghr894040044",
  "name": "Peter Pepper",
  "given_name": "Peter",
  "family_name": "Pepper",
  "email": "ppuser@example.com"
}

Invoicing

Use the Invoicing service to create, send, and manage invoices. Also use the Invoicing service to track payments.

When you send an invoice, PayPal emails the specified customer with a link to the invoice on PayPal’s website.

Customers who have a PayPal account can log in and pay with PayPal. Alternatively, customers can pay with a check, debit card, or credit card.

URI

https://api.paypal.com/v1/invoicing/

Create an invoice

Operation

POST /v1/invoicing/invoices

Creates an invoice in a draft state. After you create an invoice that includes an items array, you can send the invoice.

Note: The merchant specified in an invoice must have a PayPal account in good standing.

Request

Specify an Invoice object.

Property Type Description
number string Unique number that appears on the invoice. If left blank will be auto-incremented from the last number. 25 characters max.
merchant_info merchant_info Information about the merchant who is sending the invoice. Required.
billing_info array of billing_info Email address of invoice recipient (required) and optional billing information. (Note: We currently only allow one recipient).
shipping_info shipping_info Shipping information for entities to whom items are being shipped.
items array of invoice_item List of items included in the invoice. 100 items max per invoice.
invoice_date string Date on which the invoice was enabled. Date format yyyy-MM-dd z, as defined in ISO8601.
payment_term payment_term Optional field to pass payment deadline for the invoice. Either term_type or due_date can be passed, but not both.
discount cost Invoice level discount in percent or amount.
shipping_cost shipping_cost Shipping cost in percent or amount.
custom custom_amount Custom amount applied on an invoice. If a label is included then the amount cannot be empty.
tax_calculated_after_discount boolean Indicates whether tax is calculated before or after a discount. If false (the default), the tax is calculated before a discount. If true, the tax is calculated after a discount.
tax_inclusive boolean A flag indicating whether the unit price includes tax. Default is false
terms string General terms of the invoice. 4000 characters max.
note string Note to the payer. 4000 characters max.
merchant_memo string Bookkeeping memo that is private to the merchant. 150 characters max.
logo_url string Full URL of an external image to use as the logo. 4000 characters max.

Request Sample

curl -v -X 'POST' 'https://api.sandbox.paypal.com/v1/invoicing/invoices' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <Access-Token>' \
-d '{
  "merchant_info": {
    "email": "dennis@sample.com",
    "first_name": "Dennis",
    "last_name": "Doctor",
    "business_name": "Medical Professionals, LLC",
    "phone": {
      "country_code": "001",
      "national_number": "5032141716"
    },
    "address": {
      "line1": "1234 Main St.",
      "city": "Portland",
      "state": "OR",
      "postal_code": "97217",
      "country_code": "US"
    }
  },
  "billing_info": [
  {
    "email": "example@example.com"
  }
  ],
  "items": [
  {
    "name": "Sutures",
    "quantity": 100,
    "unit_price": {
    "currency": "USD",
    "value": 5
    }
  }
  ],
  "note": "Medical Invoice 16 Jul, 2013 PST",
  "payment_term" :{
	  "term_type": "NET_45"
  },
  "shipping_info": {
    "first_name": "Sally",
    "last_name": "Patient",
    "business_name": "Not applicable",
    "address": {
    "line1": "1234 Broad St.",
    "city": "Portland",
    "state": "OR",
    "postal_code": "97216",
    "country_code": "US"
    }
  }
}'

Response

Returns an invoice object that includes the invoice ID of the created invoice.

Property Type Description
id string Unique invoice resource identifier.
number string Unique number that appears on the invoice. If left blank will be auto-incremented from the last number. 25 characters max.
uri string URI of the invoice resource.
status string Status of the invoice. Allowed values: DRAFT, SENT, PAID, MARKED_AS_PAID, CANCELLED, REFUNDED, PARTIALLY_REFUNDED, MARKED_AS_REFUNDED
merchant_info merchant_info Information about the merchant who is sending the invoice.
billing_info array of billing_info Email address of invoice recipient (required) and optional billing information. (Note: We currently only allow one recipient).
shipping_info shipping_info Shipping information for entities to whom items are being shipped.
items array of invoice_item List of items included in the invoice. 100 items max per invoice.
invoice_date string Date on which the invoice was enabled. Date format yyyy-MM-dd z, as defined in ISO8601.
payment_term payment_term Optional field to pass payment deadline for the invoice. Either term_type or due_date can be passed, but not both.
discount cost Invoice level discount in percent or amount.
shipping_cost shipping_cost Shipping cost in percent or amount.
custom custom_amount Custom amount applied on an invoice. If a label is included then the amount cannot be empty.
tax_calculated_after_discount boolean Indicates whether tax is calculated before or after a discount. If false (the default), the tax is calculated before a discount. If true, the tax is calculated after a discount.
tax_inclusive boolean A flag indicating whether the unit price includes tax. Default is false
terms string General terms of the invoice. 4000 characters max.
note string Note to the payer. 4000 characters max.
merchant_memo string Bookkeeping memo that is private to the merchant. 150 characters max.
logo_url string Full URL of an external image to use as the logo. 4000 characters max.
total_amount currency The total amount of the invoice.
payments array of payment_detail List of payment details for the invoice.
refunds array of refund_detail List of refund details for the invoice.
metadata metadata Audit information for the invoice.

Response Sample

{
  "id": "INV2-RUVR-ADWQ-H89Y-ABCD",
  "number": "ABCD4971",
  "status": "DRAFT",
  "merchant_info": {
    "email": "dennis@sample.com",
    "first_name": "Dennis",
    "last_name": "Doctor",
    "business_name": "Medical Professionals, LLC",
    "phone": {
      "country_code": "1",
      "national_number": "5032141234"
    },
    "address": {
      "line1": "1234 Main St.",
      "city": "Portland",
      "state": "OR",
      "postal_code": "97217",
      "country_code": "US"
    }
  },
  "billing_info": [
    {
      "email": "email@example.com"
    }
  ],
  "shipping_info": {
    "first_name": "Sally",
    "last_name": "Patient",
    "business_name": "Not applicable",
    "address": {
      "line1": "1234 Broad St.",
      "city": "Portland",
      "state": "OR",
      "postal_code": "97216",
      "country_code": "US"
    }
  },
  "items": [
    {
      "name": "Sutures",
      "quantity": 100.0,
      "unit_price": {
        "currency": "USD",
        "value": "5.00"
      }
    }
  ],
  "invoice_date": "2014-02-27 PST",
  "payment_term": {
    "term_type": "NET_45",
    "due_date": "2014-04-13 PDT"
  },
  "tax_calculated_after_discount": false,
  "tax_inclusive": false,
  "note": "Medical Invoice 16 Jul, 2013 PST",
  "total_amount": {
    "currency": "USD",
    "value": "500.00"
  }
}

Send an invoice

Operation

POST /v1/invoicing/invoices/<Invoice-Id>/send

Sends the specified invoice to the payer. An invoice cannot be sent unless it includes an items array.

Note: Once you’ve sent an invoice, it cannot be re-sent.

Request

In the URI, specify the invoice ID of the invoice to send.

Request Sample

curl -v -X 'POST' 'https://api.sandbox.paypal.com/v1/invoicing/invoices/<Invoice-Id>/send' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <Access-Token>'

Response

Returns an HTTP response message with status code 202 (Accepted).

Update an invoice

Operation

PUT /v1/invoicing/invoices/<Invoice-Id>

Makes the specified changes to the specified invoice.

Request

In the request URI, pass the invoice ID of the invoice to update. In the message body, provide an invoice object containing the changes to make.

Property Type Description
number string Unique number that appears on the invoice. If left blank will be auto-incremented from the last number. 25 characters max.
merchant_info merchant_info Information about the merchant who is sending the invoice. Required.
billing_info array of billing_info Email address of invoice recipient (required) and optional billing information. (Note: We currently only allow one recipient).
shipping_info shipping_info Shipping information for entities to whom items are being shipped.
items array of invoice_item List of items included in the invoice. 100 items max per invoice.
invoice_date string Date on which the invoice was enabled. Date format yyyy-MM-dd z, as defined in ISO8601.
payment_term payment_term Optional field to pass payment deadline for the invoice. Either term_type or due_date can be passed, but not both.
discount cost Invoice level discount in percent or amount.
shipping_cost shipping_cost Shipping cost in percent or amount.
custom custom_amount Custom amount applied on an invoice. If a label is included then the amount cannot be empty.
tax_calculated_after_discount boolean Indicates whether tax is calculated before or after a discount. If false (the default), the tax is calculated before a discount. If true, the tax is calculated after a discount.
tax_inclusive boolean A flag indicating whether the unit price includes tax. Default is false
terms string General terms of the invoice. 4000 characters max.
note string Note to the payer. 4000 characters max.
merchant_memo string Bookkeeping memo that is private to the merchant. 150 characters max.
logo_url string Full URL of an external image to use as the logo. 4000 characters max.

Request Sample

curl -v -X 'PUT' 'https://api.sandbox.paypal.com/v1/invoicing/invoices/<Invoice-Id>' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <Access-Token>' \
-d '{
  "id": "<Invoice-Id>",
  "number": "12345",
  "status": "DRAFT",
  "merchant_info": {
    "email": "dennis@sample.com",
    "first_name": "Dennis",
    "last_name": "Doctor",
    "business_name": "Medical Professionals, LLC",
    "phone": {
      "country_code": "US",
      "national_number": "5032141716"
    },
    "address": {
      "line1": "1234 Main St.",
      "city": "Portland",
      "state": "OR",
      "postal_code": "97217",
      "country_code": "US"
    }
  },
  "billing_info": [
  {
    "email": "sally-patient@example.com"
  }
  ],
  "shipping_info": {
    "first_name": "Sally",
    "last_name": "Patient",
    "business_name": "Not applicable",
    "address": {
      "line1": "1234 Broad St.",
      "city": "Portland",
      "state": "OR",
      "postal_code": "97216",
      "country_code": "US"
    }
  },
  "items": [
  {
    "name": "Sutures",
    "quantity": 100,
    "unit_price": {
      "currency": "USD",
      "value": "250"
    }
  }
  ],
  "invoice_date": "2014-01-07 PST",
  "payment_term": {
    "term_type": "NO_DUE_DATE"
  },
  "tax_calculated_after_discount": false,
  "tax_inclusive": false,
  "note": "Medical Invoice 16 Jul, 2013 PST",
  "total_amount": {
    "currency": "USD",
    "value": "250"
  }
}'

Response

Returns an invoice object containing the specified changes.

Property Type Description
id string Unique invoice resource identifier.
number string Unique number that appears on the invoice. If left blank will be auto-incremented from the last number. 25 characters max.
uri string URI of the invoice resource.
status string Status of the invoice. Allowed values: DRAFT, SENT, PAID, MARKED_AS_PAID, CANCELLED, REFUNDED, PARTIALLY_REFUNDED, MARKED_AS_REFUNDED
merchant_info merchant_info Information about the merchant who is sending the invoice.
billing_info array of billing_info Email address of invoice recipient (required) and optional billing information. (Note: We currently only allow one recipient).
shipping_info shipping_info Shipping information for entities to whom items are being shipped.
items array of invoice_item List of items included in the invoice. 100 items max per invoice.
invoice_date string Date on which the invoice was enabled. Date format yyyy-MM-dd z, as defined in ISO8601.
payment_term payment_term Optional field to pass payment deadline for the invoice. Either term_type or due_date can be passed, but not both.
discount cost Invoice level discount in percent or amount.
shipping_cost shipping_cost Shipping cost in percent or amount.
custom custom_amount Custom amount applied on an invoice. If a label is included then the amount cannot be empty.
tax_calculated_after_discount boolean Indicates whether tax is calculated before or after a discount. If false (the default), the tax is calculated before a discount. If true, the tax is calculated after a discount.
tax_inclusive boolean A flag indicating whether the unit price includes tax. Default is false
terms string General terms of the invoice. 4000 characters max.
note string Note to the payer. 4000 characters max.
merchant_memo string Bookkeeping memo that is private to the merchant. 150 characters max.
logo_url string Full URL of an external image to use as the logo. 4000 characters max.
total_amount currency The total amount of the invoice.
payments array of payment_detail List of payment details for the invoice.
refunds array of refund_detail List of refund details for the invoice.
metadata metadata Audit information for the invoice.

Response Sample

{
  "id": "INV2-35FM-LH48-9WKF-P2XS",
  "number": "12345",
  "status": "DRAFT",
  "merchant_info": {
    "email": "dennis@sample.com",
    "first_name": "Dennis",
    "last_name": "Doctor",
    "business_name": "Medical Professionals, LLC",
    "phone": {
      "country_code": "US",
      "national_number": "5032141716"
    },
    "address": {
      "line1": "1234 Main St.",
      "city": "Portland",
      "state": "OR",
      "postal_code": "97217",
      "country_code": "US"
    }
  },
  "billing_info": [
    {
      "email": "sally-patient@example.com"
    }
  ],
  "shipping_info": {
    "first_name": "Sally",
    "last_name": "Patient",
    "business_name": "Not applicable",
    "address": {
      "line1": "1234 Broad St.",
      "city": "Portland",
      "state": "OR",
      "postal_code": "97216",
      "country_code": "US"
    }
  },
  "items": [
    {
      "name": "Sutures",
      "quantity": 100,
      "unit_price": {
        "currency": "USD",
        "value": "250"
      }
    }
  ],
  "invoice_date": "2014-01-07 PST",
  "payment_term": {
    "term_type": "NO_DUE_DATE"
  },
  "tax_calculated_after_discount": false,
  "tax_inclusive": false,
  "note": "Medical Invoice 16 Jul, 2013 PST",
  "total_amount": {
    "currency": "USD",
    "value": "250"
  }
}

Retrieve an invoice

Operation

GET /v1/invoicing/invoices/<Invoice-Id>

Returns the specified invoice.

Request

In the request URI, provide the ID of the invoice to retrieve.

Request Sample

curl -v -X 'GET' 'https://api.sandbox.paypal.com/v1/invoicing/invoices/<Invoice-Id>' \
-H 'Authorization: Bearer <Access-Token>'

Response

Returns an invoice object containing the specified invoice.

Property Type Description
id string Unique invoice resource identifier.
number string Unique number that appears on the invoice. If left blank will be auto-incremented from the last number. 25 characters max.
uri string URI of the invoice resource.
status string Status of the invoice. Allowed values: DRAFT, SENT, PAID, MARKED_AS_PAID, CANCELLED, REFUNDED, PARTIALLY_REFUNDED, MARKED_AS_REFUNDED
merchant_info merchant_info Information about the merchant who is sending the invoice.
billing_info array of billing_info Email address of invoice recipient (required) and optional billing information. (Note: We currently only allow one recipient).
shipping_info shipping_info Shipping information for entities to whom items are being shipped.
items array of invoice_item List of items included in the invoice. 100 items max per invoice.
invoice_date string Date on which the invoice was enabled. Date format yyyy-MM-dd z, as defined in ISO8601.
payment_term payment_term Optional field to pass payment deadline for the invoice. Either term_type or due_date can be passed, but not both.
discount cost Invoice level discount in percent or amount.
shipping_cost shipping_cost Shipping cost in percent or amount.
custom custom_amount Custom amount applied on an invoice. If a label is included then the amount cannot be empty.
tax_calculated_after_discount boolean Indicates whether tax is calculated before or after a discount. If false (the default), the tax is calculated before a discount. If true, the tax is calculated after a discount.
tax_inclusive boolean A flag indicating whether the unit price includes tax. Default is false
terms string General terms of the invoice. 4000 characters max.
note string Note to the payer. 4000 characters max.
merchant_memo string Bookkeeping memo that is private to the merchant. 150 characters max.
logo_url string Full URL of an external image to use as the logo. 4000 characters max.
total_amount currency The total amount of the invoice.
payments array of payment_detail List of payment details for the invoice.
refunds array of refund_detail List of refund details for the invoice.
metadata metadata Audit information for the invoice.

Response Sample

{
  "id": "INV2-SKP5-8A3J-A866-ABCD",
  "number": "ABCD4972",
  "status": "SENT",
  "merchant_info": {
    "email": "dennis@sample.com",
    "first_name": "Dennis",
    "last_name": "Doctor",
    "business_name": "Medical Professionals, LLC",
    "phone": {
      "country_code": "1",
      "national_number": "5032141234"
    },
    "address": {
      "line1": "1234 Main St.",
      "city": "Portland",
      "state": "OR",
      "postal_code": "97217",
      "country_code": "US"
    }
  },
  "billing_info": [
    {
      "email": "example@example.com"
    }
  ],
  "shipping_info": {
    "first_name": "Sally",
    "last_name": "Patient",
    "business_name": "Not applicable",
    "address": {
      "line1": "1234 Broad St.",
      "city": "Portland",
      "state": "OR",
      "postal_code": "97216",
      "country_code": "US"
    }
  },
  "items": [
    {
      "name": "Sutures",
      "quantity": 100.0,
      "unit_price": {
        "currency": "USD",
        "value": "5.00"
      }
    }
  ],
  "invoice_date": "2014-02-27 PST",
  "payment_term": {
    "term_type": "NET_45",
    "due_date": "2014-04-13 PDT"
  },
  "tax_calculated_after_discount": false,
  "tax_inclusive": false,
  "note": "Medical Invoice 16 Jul, 2013 PST",
  "total_amount": {
    "currency": "USD",
    "value": "500.00"
  },
  "metadata": {
    "created_date": "2014-02-27 23:20:27 PST",
    "first_sent_date": "2014-02-27 23:20:27 PST",
    "last_sent_date": "2014-02-27 23:20:27 PST"
  }
}

Get invoices of a merchant

Operation

GET /v1/invoicing/invoices

Returns invoices that belong to the merchant who makes the call.

Request

The above URI returns the first 20 invoices that belong to the calling merchant. You can append one or more of the following parameters to the above URI:

  • page: A zero-relative index of the merchant’s list of invoices
  • page_size: The number of invoices to retrieve, beginning with the specified page
  • total_count_required: Determines if the total count is returned. False by default.

Request Sample

curl -v -X 'GET' 'https://api.sandbox.paypal.com/v1/invoicing/invoices?page=0&page_size=4&total_count_required=true' \
-H 'Authorization: Bearer <Access-Token>'

Response

Returns an array containing one invoice object for each invoice requested.

Property Type Description
id string Unique invoice resource identifier.
number string Unique number that appears on the invoice. If left blank will be auto-incremented from the last number. 25 characters max.
uri string URI of the invoice resource.
status string Status of the invoice. Allowed values: DRAFT, SENT, PAID, MARKED_AS_PAID, CANCELLED, REFUNDED, PARTIALLY_REFUNDED, MARKED_AS_REFUNDED
merchant_info merchant_info Information about the merchant who is sending the invoice.
billing_info array of billing_info Email address of invoice recipient (required) and optional billing information. (Note: We currently only allow one recipient).
shipping_info shipping_info Shipping information for entities to whom items are being shipped.
items array of invoice_item List of items included in the invoice. 100 items max per invoice.
invoice_date string Date on which the invoice was enabled. Date format yyyy-MM-dd z, as defined in ISO8601.
payment_term payment_term Optional field to pass payment deadline for the invoice. Either term_type or due_date can be passed, but not both.
discount cost Invoice level discount in percent or amount.
shipping_cost shipping_cost Shipping cost in percent or amount.
custom custom_amount Custom amount applied on an invoice. If a label is included then the amount cannot be empty.
tax_calculated_after_discount boolean Indicates whether tax is calculated before or after a discount. If false (the default), the tax is calculated before a discount. If true, the tax is calculated after a discount.
tax_inclusive boolean A flag indicating whether the unit price includes tax. Default is false
terms string General terms of the invoice. 4000 characters max.
note string Note to the payer. 4000 characters max.
merchant_memo string Bookkeeping memo that is private to the merchant. 150 characters max.
logo_url string Full URL of an external image to use as the logo. 4000 characters max.
total_amount currency The total amount of the invoice.
payments array of payment_detail List of payment details for the invoice.
refunds array of refund_detail List of refund details for the invoice.
metadata metadata Audit information for the invoice.

Response Sample

{
  "total_count": 24827,
  "invoices": [
    {
      "id": "INV2-2NB5-UJ7A-YSUJ-ABCD",
      "number": "9879878979003791",
      "status": "DRAFT",
      "merchant_info": {
        "email": "sample@sample.com"
      },
      "billing_info": [
        {
          "email": "example@example.com"
        }
      ],
      "shipping_info": {
        "email": "example@example.com",
        "first_name": "Sally",
        "last_name": "Patient",
        "business_name": "Not applicable"
      },
      "invoice_date": "2014-02-27 PST",
      "note": "Medical Invoice 16 Jul, 2013 PST",
      "total_amount": {
        "currency": "USD",
        "value": "0.00"
      },
      "metadata": {
        "created_date": "2014-02-27 23:55:58 PST"
      }
    },
    {
      "id": "INV2-5AYC-UE5K-XXEG-ABCD",
      "number": "9879878979003790",
      "status": "DRAFT",
      "merchant_info": {
        "email": "sample@sample.com"
      },
      "billing_info": [
        {
          "email": "example@example.com"
        }
      ],
      "shipping_info": {
        "email": "example@example.com",
        "first_name": "Sally",
        "last_name": "Patient",
        "business_name": "Not applicable"
      },
      "invoice_date": "2014-02-27 PST",
      "note": "Medical Invoice 16 Jul, 2013 PST",
      "total_amount": {
        "currency": "USD",
        "value": "0.00"
      },
      "metadata": {
        "created_date": "2014-02-27 19:41:56 PST"
      }
    },
    {
      "id": "INV2-C4QH-KEKM-C5QE-ABCD",
      "number": "9879878979003789",
      "status": "DRAFT",
      "merchant_info": {
        "email": "sample@sample.com"
      },
      "billing_info": [
        {
          "email": "example@example.com"
        }
      ],
      "shipping_info": {
        "email": "example@example.com",
        "first_name": "Sally",
        "last_name": "Patient",
        "business_name": "Not applicable"
      },
      "invoice_date": "2014-02-27 PST",
      "note": "Medical Invoice 16 Jul, 2013 PST",
      "total_amount": {
        "currency": "USD",
        "value": "0.00"
      },
      "metadata": {
        "created_date": "2014-02-27 15:34:11 PST"
      }
    },
    {
      "id": "INV2-YP6Y-9LJU-9NFS-ABCD",
      "number": "9879878979003788",
      "status": "DRAFT",
      "merchant_info": {
        "email": "sample@sample.com"
      },
      "billing_info": [
        {
          "email": "example@example.com"
        }
      ],
      "shipping_info": {
        "email": "example@example.com",
        "first_name": "Sally",
        "last_name": "Patient",
        "business_name": "Not applicable"
      },
      "invoice_date": "2014-02-27 PST",
      "note": "Medical Invoice 16 Jul, 2013 PST",
      "total_amount": {
        "currency": "USD",
        "value": "12.00"
      },
      "metadata": {
        "created_date": "2014-02-27 15:34:01 PST"
      }
    }
  ]
}

Search for invoices

Operation

POST /v1/invoicing/search

Returns invoices that match the specified criteria.

Request

In the payload of the request message, pass a search object whose fields are set to your search criteria.

Property Type Description
email string Initial letters of the email address.
recipient_first_name string Initial letters of the recipient’s first name.
recipient_last_name string Initial letters of the recipient’s last name.
recipient_business_name string Initial letters of the recipient’s business name.
number string The invoice number that appears on the invoice.
status string Status of the invoice. Allowed values: DRAFT, SENT, PAID, MARKED_AS_PAID, CANCELLED, REFUNDED, PARTIALLY_REFUNDED, MARKED_AS_REFUNDED
lower_total_amount currency Lower limit of total amount.
upper_total_amount currency Upper limit of total amount.
start_invoice_date string Start invoice date. Date format yyyy-MM-dd z, as defined in ISO8601.
end_invoice_date string End invoice date. Date format yyyy-MM-dd z, as defined in ISO8601.
start_due_date string Start invoice due date. Date format yyyy-MM-dd z, as defined in ISO8601.
end_due_date string End invoice due date. Date format yyyy-MM-dd z, as defined in ISO8601.
start_payment_date string Start invoice payment date. Date format yyyy-MM-dd z, as defined in ISO8601.
end_payment_date string End invoice payment date. Date format yyyy-MM-dd z, as defined in ISO8601.
start_creation_date string Start invoice creation date. Date format yyyy-MM-dd z, as defined in ISO8601.
end_creation_date string End invoice creation date. Date format yyyy-MM-dd z, as defined in ISO8601.
page number Offset of the search results.
page_size number Page size of the search results.
total_count_required boolean A flag indicating whether total count is required in the response.

Request Sample

curl -v -X https://api.sandbox.paypal.com/v1/invoicing/search \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <Access-Token>' \
-d '{
  "start_invoice_date" : "2010-05-10 PST",
  "end_invoice_date" : "2013-05-11 PST",
  "page" : 1,
  "page_size" : 20,
  "total_count_required" : true
}'

Response

Returns an array of invoice objects, one for each invoice that matches your search criteria.

Property Type Description
id string Unique invoice resource identifier.
number string Unique number that appears on the invoice. If left blank will be auto-incremented from the last number. 25 characters max.
uri string URI of the invoice resource.
status string Status of the invoice. Allowed values: DRAFT, SENT, PAID, MARKED_AS_PAID, CANCELLED, REFUNDED, PARTIALLY_REFUNDED, MARKED_AS_REFUNDED
merchant_info merchant_info Information about the merchant who is sending the invoice.
billing_info array of billing_info Email address of invoice recipient (required) and optional billing information. (Note: We currently only allow one recipient).
shipping_info shipping_info Shipping information for entities to whom items are being shipped.
items array of invoice_item List of items included in the invoice. 100 items max per invoice.
invoice_date string Date on which the invoice was enabled. Date format yyyy-MM-dd z, as defined in ISO8601.
payment_term payment_term Optional field to pass payment deadline for the invoice. Either term_type or due_date can be passed, but not both.
discount cost Invoice level discount in percent or amount.
shipping_cost shipping_cost Shipping cost in percent or amount.
custom custom_amount Custom amount applied on an invoice. If a label is included then the amount cannot be empty.
tax_calculated_after_discount boolean Indicates whether tax is calculated before or after a discount. If false (the default), the tax is calculated before a discount. If true, the tax is calculated after a discount.
tax_inclusive boolean A flag indicating whether the unit price includes tax. Default is false
terms string General terms of the invoice. 4000 characters max.
note string Note to the payer. 4000 characters max.
merchant_memo string Bookkeeping memo that is private to the merchant. 150 characters max.
logo_url string Full URL of an external image to use as the logo. 4000 characters max.
total_amount currency The total amount of the invoice.
payments array of payment_detail List of payment details for the invoice.
refunds array of refund_detail List of refund details for the invoice.
metadata metadata Audit information for the invoice.

Response Sample

{
  "total_count": 1,
  "invoices": [
    {
      "id": "INV2-KXVU-7Z64-DT6W-MG2X",
      "number": "0001",
      "status": "SENT",
      "merchant_info": {
        "email": "dennis@sample.com"
      },
      "billing_info": [
        {
          "email": "sally-patient@example.com"
        }
      ],
      "shipping_info": {
        "email": "sally-patient@example.com"
      },
      "invoice_date": "2012-05-09 PST",
      "payment_term": {
        "due_date": "2012-05-24 PST"
      },
      "total_amount": {
        "currency": "USD",
        "value": "250"
      },
      "metadata": {
        "created_date": "2012-05-09 04:48:57 PST"
      }
    }
  ]
}

Send an invoice reminder

Operation

POST /v1/invoicing/invoices/<Invoice-Id>/remind

Sends a reminder that a payment is due for an existing invoice.

Request

In the request URI, specify the ID of the invoice for which to send a reminder. In the message body, pass a notification object containing reminder information.

Property Type Description
subject string Subject of the notification.
note string Note to the payer.
send_to_merchant boolean A flag indicating whether a copy of the email has to be sent to the merchant.

Request Sample

curl -v -X 'POST' 'https://api.sandbox.paypal.com/v1/invoicing/invoices/<Invoice-Id>/remind' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <Access-Token>' \
-d '{
  "subject":"Past due",
  "note":"Please pay soon",
  "send_to_merchant":true
}'

Response

Returns an HTTP response message with status code 202 (Accepted).

Cancel an invoice

Operation

POST /v1/invoicing/invoices/<Invoice-Id>/cancel

Cancels an invoice and (optionally) notifies the payer of the cancellation.

Request

In the request URI, specify the ID of the invoice to cancel.

Property Type Description
subject string Subject of the notification.
note string Note to the payer.
send_to_merchant boolean A flag indicating whether a copy of the email has to be sent to the merchant.
send_to_payer boolean A flag indicating whether a copy of the email has to be sent to the payer.

Request Sample

curl -v -X 'POST' 'https://api.sandbox.paypal.com/v1/invoicing/invoices/<Invoice-Id>/cancel' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <Access-Token> \'
-d '{
  "subject":"Past due",
  "note":"Canceling invoice",
  "send_to_merchant":true,
  "send_to_payer":true
}'

Response

Returns an HTTP response message with status code 202 (Accepted).

Delete an invoice

Operation

DELETE /v1/invoicing/invoices/<Invoice-Id>

Deletes a draft invoice. Note that this call works for invoices in the draft state only.

For invoices that have already been sent, you can cancel the invoice. See Cancel an invoice for instructions.

Once you’ve deleted a draft invoice, it can no longer be used and cannot be retrieved. However, you can reuse its invoice number.

Request

In the request URI, specify the ID of the invoice to delete.

Request Sample

curl -v -X 'DELETE' 'https://api.sandbox.paypal.com/v1/invoicing/invoices/<Invoice-Id>' \
-H 'Authorization: Bearer <Access-Token>'

Response

Returns an HTTP response containing a status code and status message.

Retrieve a QR code

Operation

GET /v1/invoicing/invoices/<invoice-id>/qr-code?<Query-String>

Specify an invoice ID to get a QR code (image) that corresponds to the invoice ID. A QR code for an invoice can be added to a paper or PDF invoice. When a customer uses their mobile device to scan the QR code, the customer is redirected to the PayPal mobile payment flow, where they can pay online with PayPal or a credit card.

Before getting a QR code, you create an invoice. It is recommended that you specify qrinvoice@paypal.com as the recipient email address in the billing_info object. (Use a customer email address only if you want the invoice to be emailed.)

After you create the invoice, you must send it. This step is necessary to move the invoice from a draft state to a payable state. As stated above, if you specify qrinvoice@paypal.com as the recipient email address, the invoice will not be emailed.

Request

You can append one or more of these optional parameters to the above URI:

  • width: The width of the QR code image, in pixels. Range of 150 to 500. The default value is 500.
  • height: The height of the QR code image, in pixels. Range of 150 to 500. The default value is 500.
  • action: The type of URL for which a QR code is provided. The only supported value is pay, which is the default value.

Request Sample

curl -v -X 'GET' 'https://api.sandbox.paypal.com/v1/invoicing/invoices/INV2-AAAA-VMML-X9TG-AC2X/qr-code?height=200&width=200' \
-H 'Authorization: Bearer <Access-Token>'

Response

Returns a QR code as a PNG image, in base-64 encoded format, with an HTTP status code of 200 (OK).

Response Sample

{
  "image": "iVBORw...SuQmCC"
}

Record a payment

Operation

POST /v1/invoicing/invoices/<invoice-id>/record-payment

Use this call to mark an invoice as paid.

Request

In the URL, specify the ID of the invoice to mark as paid.

The fields that you provide in the body of the request are the following.

Property Type Description
method string The payment method or mode. Valid values: BANK_TRANSFER, CASH, CHECK, CREDIT_CARD, DEBIT_CARD, PAYPAL, WIRE_TRANSFER, OTHER. Required.
date string Date on which the invoice was paid. Date format: yyyy-MM-dd z. For example, 2014-02-27 PST.
note string Note associated with the payment.
     

Request Sample

curl -v -X 'POST' 'https://api.sandbox.paypal.com/v1/invoicing/invoices/INV2-AAAA-VMML-X9TG-AC2X/record-payment' \
-H "Content-Type:application/json" \
-H 'Authorization: Bearer <Access-Token>'\
-d '{
  "method" : "CASH",
  "date" : "2014-07-06 03:30:00 PST",
  "note" : "Cash received."
}'

Response

Returns an HTTP status of 204 if the call was successful.

Record a refund

Operation

POST /v1/invoicing/invoices/<invoice-id>/record-refund

Use this call to mark an invoice as refunded.

Request

In the URL, specify the ID of the invoice to mark as refunded.

Optional fields that you provide in the body of the request are the following.

Property Type Description
date string Date on which the invoice was refunded. Date format: yyyy-MM-dd z. For example, 2014-02-27 PST.
note string Note associated with the refund.
     

Request Sample

curl -v -X 'POST' 'https://api.sandbox.paypal.com/v1/invoicing/invoices/INV2-AAAA-VMML-X9TG-AC2X/record-refund' \
-H "Content-Type:application/json" \
-H 'Authorization: Bearer <Access-Token>'\
-d '{
  "date" : "2014-07-06 03:30:00 PST",
  "note" : "Refund provided by cash."
}'

Response

Returns an HTTP status of 204 if the call was successful.

Payment Experience

Use the /web-profiles resource to create seamless payment experience profiles. See the payment experience overview for further information about using the /payment resource to create the PayPal payment and pass the experience_profile_id.

URIs

/v1/payment-experience/web-profiles

Create a web experience profile

Operation

POST /v1/payment-experience/web-profiles

Use this call to create a profile.

Request

Provide a web_profile object in the body of a POST call.

Property Type Description
name string Name of the web experience profile. Unique only among the profiles for a given merchant. Required.
flow_config flow_config Parameters for flow configuration.
input_fields input_fields Parameters for input fields customization.
presentation presentation Parameters for style and presentation.

Request Sample

curl -v POST https://api.sandbox.paypal.com/v1/payment-experience/web-profiles \
-H 'Content-Type:application/json' \
-H 'Authorization: Bearer <Access-Token>' \
-d '{
    "name": "YeowZa! T-Shirt Shop",
    "presentation": {
        "brand_name": "YeowZa! Paypal",
        "logo_image": "http://www.yeowza.com",
        "locale_code": "US"
    },
    "input_fields": {
        "allow_note": true,
        "no_shipping": 0,
        "address_override": 1
    },
    "flow_config": {
        "landing_page_type": "billing",
        "bank_txn_pending_url": "http://www.yeowza.com"
    }
}'

Response

If your request is successful, the API returns a create_profile_response object that contains the unique profile id of the profile created.

Property Type Description
id string ID of the payment web experience profile.

Response Sample

{
  "id": "XP-CP6S-W9DY-96H8-MVN2"
}

Retrieve a web experience profile

Operation

GET /v1/payment-experience/web-profiles/<Profile-Id>

Request

Specify the profile-id in the URI of a GET call.

Request Sample

curl -v -X GET https://api.sandbox.paypal.com/v1/payment-experience/web-profiles/XP-CP6S-W9DY-96H8-MVN2 \
-H 'Content-Type:application/json' \
-H 'Authorization: Bearer <Access-Token>'

Response

If your request is successful, the API returns a web_profile object response that contains the profile details.

Property Type Description
id string Unique ID of the web experience profile.
name string Name of the web experience profile. Unique only among the profiles for a given merchant.
flow_config flow_config Parameters for flow configuration.
input_fields input_fields Parameters for input fields customization.
presentation presentation Parameters for style and presentation.

Response Sample

{
  "id": "XP-CP6S-W9DY-96H8-MVN2",
  "name": "YeowZa! T-Shirt Shop",
  "flow_config": {
    "landing_page_type": "billing",
    "bank_txn_pending_url": "http://www.yeowza.com"
  },
  "input_fields": {
    "allow_note": true,
    "no_shipping": 0,
    "address_override": 1
  },
  "presentation": {
    "brand_name": "YeowZa! Paypal",
    "logo_image": "http://www.yeowza.com",
    "locale_code": "US"
  }
}

List web experience profiles

Operation

GET /v1/payment-experience/web-profiles

Get a list of all profiles that exist for a given merchant (or subject).

Request

Use the GET operation above.

Request Sample

curl -v -X GET https://api.sandbox.paypal.com/v1/payment-experience/web-profiles \
-H 'Content-Type:application/json' \
-H 'Authorization: Bearer <Access-Token>'

Response

If your request is successful, the API returns a web_profile_list object that contains the list of all the profiles (with details) that the merchant owns.

Property Type Description
id string Unique ID of the web experience profile.
name string Name of the web experience profile. Unique only among the profiles for a given merchant.
flow_config flow_config Parameters for flow configuration.
input_fields input_fields Parameters for input fields customization.
presentation presentation Parameters for style and presentation.

Response Sample

[
  {
    "id": "XP-CP6S-W9DY-96H8-MVN2",
    "name": "YeowZa! T-Shirt Shop",
    "flow_config": {
      "landing_page_type": "billing",
      "bank_txn_pending_url": "http://www.yeowza.com"
    },
    "input_fields": {
      "allow_note": true,
      "no_shipping": 0,
      "address_override": 1
    },
    "presentation": {
      "brand_name": "YeowZa! Paypal",
      "logo_image": "http://www.yeowza.com",
      "locale_code": "US"
    }
  }
]

Update a web experience profile

Operation

PUT /v1/payment-experience/web-profiles/<Profile-Id>

Use this call to update an experience profile.

Request

Pass the relevant profile id in the URI of a PUT call, including a web_profile object in the body.

Property Type Description
name string Name of the web experience profile. Unique only among the profiles for a given merchant. Required.
flow_config flow_config Parameters for flow configuration.
input_fields input_fields Parameters for input fields customization.
presentation presentation Parameters for style and presentation.

Request Sample

curl -v -X PUT https://api.sandbox.paypal.com/v1/payment-experience/web-profiles/XP-CP6S-W9DY-96H8-MVN2 \
-H 'Content-Type:application/json' \
-H 'Authorization: Bearer <Access-Token>' \
-d '{
    "name": "YeowZa! T-Shirt Shop",
    "presentation": {
        "logo_image": "http://www.yeowza.jpg"
    },
    "input_fields": {
        "no_shipping": 1,
        "address_override": 1
    },
    "flow_config": {
        "landing_page_type": "billing",
        "bank_txn_pending_url": "http://www.yeowza.com"
    }
}'

Response

If your request is successful, the API returns the HTTP status code of 204.

Partially update a web experience profile

Operation

PATCH /v1/payment-experience/web-profiles/<Profile-Id>

Use this call to partially update a web experience profile.

Request

Pass the relevant profile id in the URI of a PATCH call, including a patch_request object in the body. The API supports add, remove, replace and test operations only.

Property Type Description
op string The operation to perform. Required. Allowed values: add, remove, replace, move, copy, test
path string string containing a JSON-Pointer value that references a location within the target document (the target location) where the operation is performed. Required.
value string New value to apply based on the operation.
from string A string containing a JSON Pointer value that references the location in the target document to move the value from.

Request Sample

curl -v -X PATCH https://api.sandbox.paypal.com/v1/payment-experience/web-profiles/XP-CP6S-W9DY-96H8-MVN2 \
-H 'Content-Type:application/json' \
-H 'Authorization: Bearer <Access-Token>' \
-d '[
    {
        "op": "add",
        "path": "/presentation/brand_name",
        "value": "new_brand_name"
    },
    {
        "op": "remove",
        "path": "/flow_config/landing_page_type"
    }
]'

Response

If your request is successful, the API returns the HTTP status code of 204.

Delete a web experience profile

Operation

DELETE /v1/payment-experience/web-profiles/<Profile-Id>

Use this call to delete a web experience profile.

Request

Pass the profile id in the URI of a DELETE call.

Request Sample

curl -v -X DELETE https://api.sandbox.paypal.com/v1/payment-experience/web-profiles/XP-CP6S-W9DY-96H8-MVN2 \
-H 'Content-Type:application/json' \
-H 'Authorization: Bearer <Access-Token>'

Response

If your request is successful, the API returns the HTTP status code of 204.

Notifications

The notifications namespace contains resource collections for webhooks.

Webhooks

  • Use /webhooks-event-types for listing webhook event types.
  • Use /webhooks for creating, listing, updating, and deleting webhooks.
  • Use /webhooks-events for searching and resending webhook events.

URIs

https://api.paypal.com/v1/notifications/webhooks-event-types https://api.paypal.com/v1/notifications/webhooks https://api.paypal.com/v1/notifications/webhooks-events

Get a reference list of webhook event types

Operation

GET /v1/notifications/webhooks-event-types

Use this call to retrieve the list of event types that are available to any webhook for subscription. For further information about supported event types, refer to the webhooks overview.

Request

Use the GET operation as shown in the sample.

Request Sample

curl -v -X GET https://api.sandbox.paypal.com/v1/notifications/webhooks-event-types \
-H 'Content-Type:application/json' \
-H 'Authorization: Bearer <Access-Token>'

Response

If successful, this call returns the HTTP status of 200 and an event_type_list object.

Property Type Description
event_types array of event_type A list of Webhooks event-types

Response Sample

{
  "event_types": [
    {
      "name": "PAYMENT.AUTHORIZATION.CREATED",
      "description": "A payment authorization was created"
    },
    {
      "name": "PAYMENT.AUTHORIZATION.VOIDED",
      "description": "A payment authorization was voided"
    },
    {
      "name": "PAYMENT.CAPTURE.REFUNDED",
      "description": "A capture payment was refunded by the merchant"
    },
    {
      "name": "PAYMENT.CAPTURE.REVERSED",
      "description": "A capture payment was reversed by PayPal"
    },
    {
      "name": "PAYMENT.SALE.COMPLETED",
      "description": "A sale payment was completed"
    },
    {
      "name": "PAYMENT.SALE.REFUNDED",
      "description": "A sale payment was refunded by the merchant"
    },
    {
      "name": "PAYMENT.SALE.REVERSED",
      "description": "A sale payment was reversed by PayPal"
    }
  ]
}

Create a webhook

Operation

POST /v1/notifications/webhooks

Use this call to create a webhook. The maximum number of webhooks you can register is 10.

Request

Provide a webhook object in the body of a POST call including the URL that is configured to accept webhooks, and subscribing to the event_types that interest you.

Note: To subscribe to all event types, use an * (asterisk) as a wildcard for an event name in the event_types field. When you specify the * wildcard for an event name in the event_types field, your webhook is automatically subscribed to all event types, including any new event types as support for them is added. This is also true when you update an existing webhook by replacing a previously specified array of event types with the * wildcard as the only event name. To see all currently supported event types, you can issue a request to Get a reference list of webhook event types.

Property Type Description
url string Webhook notification endpoint url. Required.
event_types array of event_type List of Webhooks event-types. Required.
links array of links HATEOAS links related to this call.

Request Sample

curl -v POST https://api.sandbox.paypal.com/v1/notifications/webhooks \
-H 'Content-Type:application/json' \
-H 'Authorization: Bearer <Access-Token>' \
-d '{
    "url": "https://www.yeowza.com/paypal_webhook",
    "event_types": [
        {
            "name": "PAYMENT.AUTHORIZATION.CREATED"
        },
        {
            "name": "PAYMENT.AUTHORIZATION.VOIDED"
        }
    ]
}'

Response

If successful, this call returns the HTTP status of 201 and a webhook object. This object includes the webhook id for later use.

Property Type Description
id string Identifier of the webhook resource.
url string Webhook notification endpoint url.
event_types array of event_type List of Webhooks event-types.
links array of links HATEOAS links related to this call.

Response Sample

{
  "id": "0EH40505U7160970P",
  "url": "https://www.yeowza.com/paypal_webhook",
  "event_types": [
    {
      "name": "PAYMENT.AUTHORIZATION.CREATED",
      "description": "A payment authorization was created"
    },
    {
      "name": "PAYMENT.AUTHORIZATION.VOIDED",
      "description": "A payment authorization was voided"
    }
  ],
  "links": [
    {
      "href": "https://api.sandbox.paypal.com/v1/notifications/webhooks/0EH40505U7160970P",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://api.sandbox.paypal.com/v1/notifications/webhooks/0EH40505U7160970P",
      "rel": "update",
      "method": "PATCH"
    },
    {
      "href": "https://api.sandbox.paypal.com/v1/notifications/webhooks/0EH40505U7160970P",
      "rel": "delete",
      "method": "DELETE"
    }
  ]
}

Get a webhook

Operation

GET /v1/notifications/webhooks/<Webhook-Id>

Retrieve a webhook by using the webhook id as an identifier.

Request

Specify the webhook id in the URI of a GET call.

Request Sample

curl -v -X GET https://api.sandbox.paypal.com/v1/notifications/webhooks/0EH40505U7160970P \
-H 'Content-Type:application/json' \
-H 'Authorization: Bearer <Access-Token>'

Response

If successful, this call returns the HTTP status of 200 and a webhook object.

Property Type Description
id string Identifier of the webhook resource.
url string Webhook notification endpoint url.
event_types array of event_type List of Webhooks event-types.
links array of links HATEOAS links related to this call.

Response Sample

{
  "id": "0EH40505U7160970P",
  "url": "https://www.yeowza.com/paypal_webhook",
  "event_types": [
    {
      "name": "PAYMENT.AUTHORIZATION.CREATED",
      "description": "A payment authorization was created"
    },
    {
      "name": "PAYMENT.AUTHORIZATION.VOIDED",
      "description": "A payment authorization was voided"
    }
  ],
  "links": [
    {
      "href": "https://api.sandbox.paypal.com/v1/notifications/webhooks/0EH40505U7160970P",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://api.sandbox.paypal.com/v1/notifications/webhooks/0EH40505U7160970P",
      "rel": "update",
      "method": "PATCH"
    },
    {
      "href": "https://api.sandbox.paypal.com/v1/notifications/webhooks/0EH40505U7160970P",
      "rel": "delete",
      "method": "DELETE"
    }
  ]
}

List subscribed webhook event types

Operation

GET v1/notifications/webhooks/<Webhook-Id>/event-types

Use this call to retrieve the list of events types that are subscribed to a webhook.

Request

Pass the webhook id in the URI of a GET call.

Request Sample

curl -v -X GET https://api.sandbox.paypal.com/v1/notifications/webhooks/0EH40505U7160970P/event-types \
-H 'Content-Type:application/json' \
-H 'Authorization: Bearer <Access-Token>'

Response

If successful, this call returns the HTTP status of 200 and an event_type_list object.

Property Type Description
event_types array of event_type A list of Webhooks event-types

Response Sample

{
  "event_types": [
    {
      "name": "PAYMENT.AUTHORIZATION.CREATED",
      "description": "A payment authorization was created"
    },
    {
      "name": "PAYMENT.AUTHORIZATION.VOIDED",
      "description": "A payment authorization was voided"
    }
  ]
}

List all webhooks

Operation

GET /v1/notifications/webhooks

Use this call to list all the webhooks.

Request

Use the GET operation as shown in the sample.

Request Sample

curl -v -X GET https://api.sandbox.paypal.com/v1/notifications/webhooks \
-H 'Content-Type:application/json' \
-H 'Authorization: Bearer <Access-Token>'

Response

If successful, this call returns the HTTP status of 200 and a webhook_list object.

Property Type Description
webhooks array of webhook A list of Webhooks

Response Sample

{
  "webhooks": [
    {
      "id": "40Y916089Y8324740",
      "url": "https://www.yeowza.com/paypal_webhook",
      "event_types": [
        {
          "name": "PAYMENT.AUTHORIZATION.CREATED",
          "description": "A payment authorization was created"
        },
        {
          "name": "PAYMENT.AUTHORIZATION.VOIDED",
          "description": "A payment authorization was voided"
        }
      ],
      "links": [
        {
          "href": "https://api.sandbox.paypal.com/v1/notifications/webhooks/40Y916089Y8324740",
          "rel": "self",
          "method": "GET"
        },
        {
          "href": "https://api.sandbox.paypal.com/v1/notifications/webhooks/40Y916089Y8324740",
          "rel": "update",
          "method": "PATCH"
        },
        {
          "href": "https://api.sandbox.paypal.com/v1/notifications/webhooks/40Y916089Y8324740",
          "rel": "delete",
          "method": "DELETE"
        }
      ]
    },
    {
      "id": "0EH40505U7160970P",
      "url": "https://www.yeowza.com/another_paypal_webhook",
      "event_types": [
        {
          "name": "PAYMENT.AUTHORIZATION.CREATED",
          "description": "A payment authorization was created"
        },
        {
          "name": "PAYMENT.AUTHORIZATION.VOIDED",
          "description": "A payment authorization was voided"
        }
      ],
      "links": [
        {
          "href": "https://api.sandbox.paypal.com/v1/notifications/webhooks/0EH40505U7160970P",
          "rel": "self",
          "method": "GET"
        },
        {
          "href": "https://api.sandbox.paypal.com/v1/notifications/webhooks/0EH40505U7160970P",
          "rel": "update",
          "method": "PATCH"
        },
        {
          "href": "https://api.sandbox.paypal.com/v1/notifications/webhooks/0EH40505U7160970P",
          "rel": "delete",
          "method": "DELETE"
        }
      ]
    }
  ]
}

Update a webhook

Operation

PATCH v1/notifications/webhooks/<Webhook-Id>

Use this call to update a webhook; supports the replace operation only.

Request

Pass the webhook id in the URI of a PATCH call, including the replace operation in a patch_request object in the body.

When replacing event_types, the value property is a list. When replacing a url, the value property is a string.

Property Type Description
op string The operation to perform. Required. Allowed values: add, remove, replace, move, copy, test
path string String containing a JSON Pointer value that references a location within the target document where the operation is performed.
value One of the following:
number,
integer,
string,
boolean,
null,
array,
object
New value to apply based on the operation. op=remove does not require value.
from string A string containing a JSON Pointer value that references the location in the target document from which to move the value. Required for use where op=move.

Request Sample

curl -v -X PATCH https://api.sandbox.paypal.com/v1/notifications/webhooks/0EH40505U7160970P \
-H 'Content-Type:application/json' \
-H 'Authorization: Bearer <Access-Token>' \
-d '[
    {
        "op": "replace",
        "path": "/url",
        "value": "https://www.yeowza.com/paypal_webhook_new_url"
    },
    {
        "op": "replace",
        "path": "/event_types",
        "value": [
            {
                "name": "PAYMENT.SALE.REFUNDED"
            }
        ]
    }
]'

Response

If successful, this call returns the HTTP status of 200 and a webhook object.

Property Type Description
id string Identifier of the webhook resource.
url string Webhook notification endpoint url.
event_types array of event_type List of Webhooks event-types.
links array of links HATEOAS links related to this call.

Response Sample

{
  "id": "0EH40505U7160970P",
  "url": "https://www.yeowza.com/paypal_webhook_new_url",
  "event_types": [
    {
      "name": "PAYMENT.SALE.REFUNDED",
      "description": "A sale payment was refunded"
    }
  ],
  "links": [
    {
      "href": "https://api.sandbox.paypal.com/v1/notifications/webhooks/0EH40505U7160970P",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://api.sandbox.paypal.com/v1/notifications/webhooks/0EH40505U7160970P",
      "rel": "update",
      "method": "PATCH"
    },
    {
      "href": "https://api.sandbox.paypal.com/v1/notifications/webhooks/0EH40505U7160970P",
      "rel": "delete",
      "method": "DELETE"
    }
  ]
}

Delete a webhook

Operation

DELETE v1/notifications/webhooks/<Webhook-Id>

Use this call to delete a webhook.

Request

Pass the webhook id in the URI of a DELETE call.

Request Sample

curl -v -X DELETE https://api.sandbox.paypal.com/v1/notifications/webhooks/5GP028458E2496506 \
-H 'Content-Type:application/json' \
-H 'Authorization: Bearer <Access-Token>'

Response

If the call is successful, the HTTP status code of 204 No Content is returned.

Retrieve a webhook event

GET /v1/notifications/webhooks-events/<Event-Id>

Use this call to retrieve a webhook event.

Request

Pass the event id in the URI of a GET call.

Request Sample

curl -v GET https://api.sandbox.paypal.com/v1/notifications/webhooks-events/8PT597110X687430LKGECATA \
-H 'Content-Type:application/json' \
-H 'Authorization: Bearer <Access-Token>'

Response

If successful, this call returns the HTTP status of 200 and an event object.

Property Type Description
id string Identifier of the Webhooks event resource.
create_time string Time the resource was created.
resource_type string Name of the resource contained in the resource property.
event_type string Name of the event type that occurred on the resource to trigger the Webhooks event.
summary string A summary description of the event. For example: A successful payment authorization was created.
resource object This contains the resource that is identified by the resource_type property.
links array of links HATEOAS links related to this call.

Response Sample

{
  "id": "8PT597110X687430LKGECATA",
  "create_time": "2013-06-25T21:41:28Z",
  "resource_type": "authorization",
  "event_type": "PAYMENT.AUTHORIZATION.CREATED",
  "summary": "A payment authorization was created",
  "resource": {
    "id": "2DC87612EK520411B",
    "create_time": "2013-06-25T21:39:15Z",
    "update_time": "2013-06-25T21:39:17Z",
    "state": "authorized",
    "amount": {
      "total": "7.47",
      "currency": "USD",
      "details": {
        "subtotal": "7.47"
      }
    },
    "parent_payment": "PAY-36246664YD343335CKHFA4AY",
    "valid_until": "2013-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"
      }
    ]
  },
  "links": [
    {
      "href": "https://api.sandbox.paypal.com/v1/notfications/webhooks-events/8PT597110X687430LKGECATA",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://api.sandbox.paypal.com/v1/notfications/webhooks-events/8PT597110X687430LKGECATA/resend",
      "rel": "resend",
      "method": "POST"
    }
  ]
}

Search webhook events

Operation

GET /v1/notifications/webhooks-events

Use this call to search for all webhook events.

Request

Use the GET operation as shown in the sample, plus optional input parameters. The maximum date range to search is 45 days.

Parameter Type Description
page_size integer Number of items to be returned by a GET operation. Default value is 10.
start_time string Resource creation time that indicates the start of a range of results. Date_time format as defined in RFC 3339 Section 5.6. Example: start_time=2013-03-06T11:00:00Z
end_time string Resource creation time that indicates the end of a range of results. Date_time format as defined in RFC 3339 Section 5.6. Example: end_time=2013-04-06T11:00:00Z

Request Sample

curl -v -X GET https://api.sandbox.paypal.com/v1/notifications/webhooks-events \
-H 'Content-Type:application/json' \
-H 'Authorization: Bearer <Access-Token>'

Response

If successful, this call returns the HTTP status of 200 and an event_list object.

Property Type Description
events array of event A list of Webhooks event resources
count integer Number of items returned in each range of results. Note that the last results range could have fewer items than the requested number of items.
links array of links HATEOAS links related to this call.

Response Sample

{
  "events": [
    {
      "id": "8PT597110X687430LKGECATA",
      "create_time": "2013-06-25T21:41:28Z",
      "resource_type": "authorization",
      "event_type": "PAYMENT.AUTHORIZATION.CREATED",
      "summary": "A payment authorization was created",
      "resource": {
        "id": "2DC87612EK520411B",
        "create_time": "2013-06-25T21:39:15Z",
        "update_time": "2013-06-25T21:39:17Z",
        "state": "authorized",
        "amount": {
          "total": "7.47",
          "currency": "USD",
          "details": {
            "subtotal": "7.47"
          }
        },
        "parent_payment": "PAY-36246664YD343335CKHFA4AY",
        "valid_until": "2013-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"
          }
        ]
      },
      "links": [
        {
          "href": "https://api.sandbox.paypal.com/v1/notfications/webhooks-events/8PT597110X687430LKGECATA",
          "rel": "self",
          "method": "GET"
        },
        {
          "href": "https://api.sandbox.paypal.com/v1/notfications/webhooks-events/8PT597110X687430LKGECATA/resend",
          "rel": "resend",
          "method": "POST"
        }
      ]
    },
    {
      "id": "HTSPGS710X687430LKGECATA",
      "create_time": "2013-06-25T21:41:28Z",
      "resource_type": "authorization",
      "event_type": "PAYMENT.AUTHORIZATION.CREATED",
      "summary": "A payment authorization was created",
      "resource": {
        "id": "HATH7S72EK520411B",
        "create_time": "2013-06-25T21:39:15Z",
        "update_time": "2013-06-25T21:39:17Z",
        "state": "authorized",
        "amount": {
          "total": "7.47",
          "currency": "USD",
          "details": {
            "subtotal": "7.47"
          }
        },
        "parent_payment": "PAY-ALDSFJ64YD343335CKHFA4AY",
        "valid_until": "2013-07-24T21:39:15Z",
        "links": [
          {
            "href": "https://api.sandbox.paypal.com/v1/payments/authorization/HATH7S72EK520411B",
            "rel": "self",
            "method": "GET"
          },
          {
            "href": "https://api.sandbox.paypal.com/v1/payments/authorization/HATH7S72EK520411B/capture",
            "rel": "capture",
            "method": "POST"
          },
          {
            "href": "https://api.sandbox.paypal.com/v1/payments/authorization/HATH7S72EK520411B/void",
            "rel": "void",
            "method": "POST"
          },
          {
            "href": "https://api.sandbox.paypal.com/v1/payments/payment/PAY-HATH7S72EK520411B",
            "rel": "parent_payment",
            "method": "GET"
          }
        ]
      },
      "links": [
        {
          "href": "https://api.sandbox.paypal.com/v1/notfications/webhooks-events/HTSPGS710X687430LKGECATA",
          "rel": "self",
          "method": "GET"
        },
        {
          "href": "https://api.sandbox.paypal.com/v1/notfications/webhooks-events/HTSPGS710X687430LKGECATA/resend",
          "rel": "resend",
          "method": "POST"
        }
      ]
    }
  ],
  "count": 2,
  "links": [
    {
      "href": "https://api.sandbox.paypal.com/v1/notifications/webhooks-events/?start_time=2014-08-04T12:46:47-07:00&amp;amp;end_time=2014-09-18T12:46:47-07:00&amp;amp;page_size=2&amp;amp;move_to=next&amp;amp;index_time=2014-09-17T23:07:35Z&amp;amp;index_id=3",
      "rel": "next",
      "method": "GET"
    },
    {
      "href": "https://api.sandbox.paypal.com/v1/notifications/webhooks-events/?start_time=2014-08-04T12:46:47-07:00&amp;amp;end_time=2014-09-18T12:46:47-07:00&amp;amp;page_size=2&amp;amp;move_to=previous&amp;amp;index_time=2014-09-17T23:07:35Z&amp;amp;index_id=0",
      "rel": "previous",
      "method": "GET"
    }
  ]
}

Resend a webhook event

Operation

POST /v1/notifications/webhooks-events/<Event-Id>/resend

Specify a received webhook event-id to resend the event notification.

Request

Pass the event id in the URI of a POST call.

Request Sample

curl -v -X POST https://api.sandbox.paypal.com/v1/notifications/webhooks-events/8PT597110X687430LKGECATA/resend \
-H 'Content-Type:application/json' \
-H 'Authorization: Bearer <Access-Token>'

Response

If successful, this call returns the HTTP status of 202 and an event object.

Property Type Description
id string Identifier of the Webhooks event resource.
create_time string Time the resource was created.
resource_type string Name of the resource contained in the resource property.
event_type string Name of the event type that occurred on the resource to trigger the Webhooks event.
summary string A summary description of the event. For example: A successful payment authorization was created.
resource object This contains the resource that is identified by the resource_type property.
links array of links HATEOAS links related to this call.

Response Sample

{
  "id": "8PT597110X687430LKGECATA",
  "create_time": "2013-06-25T21:41:28Z",
  "resource_type": "authorization",
  "event_type": "PAYMENT.AUTHORIZATION.CREATED",
  "summary": "A payment authorization was created",
  "resource": {
    "id": "2DC87612EK520411B",
    "create_time": "2013-06-25T21:39:15Z",
    "update_time": "2013-06-25T21:39:17Z",
    "state": "authorized",
    "amount": {
      "total": "7.47",
      "currency": "USD",
      "details": {
        "subtotal": "7.47"
      }
    },
    "parent_payment": "PAY-36246664YD343335CKHFA4AY",
    "valid_until": "2013-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"
      }
    ]
  },
  "links": [
    {
      "href": "https://api.sandbox.paypal.com/v1/notfications/webhooks-events/8PT597110X687430LKGECATA",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://api.sandbox.paypal.com/v1/notfications/webhooks-events/8PT597110X687430LKGECATA/resend",
      "rel": "resend",
      "method": "POST"
    }
  ]
}

Simulate a webhook event

Operation

POST /v1/notifications/simulate-event

Simulate a webhook event using a sample payload. You can also use the Webhooks Simulator interface to send static mock event data to the URLs that you have configured to accept webhooks. For more information about simulation capabilities, see the webhooks overview.

Note: The mock event data sent by the simulator cannot be manipulated using other API operations such as resending or retrieving a webhook.

Request

In the body of a POST call, provide the URL that is configured to accept webhooks and the type of event that you want to simulate.

Property Type Description
webhook_id string Webhook ID. If the webhook ID is not provided, the URL is required.
url string Webhook endpoint URL. If the URL is not provided, the webhook ID is required.
event_type string Event-type name. Specify any of the subscribed event types. Provide only one event type for each request. Required.

Request Sample

curl -v -X POST https://api.sandbox.paypal.com/v1/notifications/simulate-event \
-H 'Content-Type:application/json' \
-H 'Authorization: Bearer <Access-Token>' \
-d '{
    "url": "https://www.yeowza.com/paypal_webhook",
    "event_type": "PAYMENT.CAPTURE.COMPLETED"
}'

Response

If successful, this call returns the HTTP status of 202 and an event object that contains static sample data.

Property Type Description
id string Identifier of the Webhooks event resource.
create_time string Time the resource was created.
resource_type string Name of the resource contained in the resource property.
event_type string Name of the event type that occurred on the resource to trigger the Webhooks event.
summary string A summary description of the event. For example: A successful payment authorization was created.
resource object This contains the resource that is identified by the resource_type property.
links array of links HATEOAS links related to this call.

Response Sample

{
  "id": "8PT597110X687430LKGECATA",
  "create_time": "2013-06-25T21:41:28Z",
  "resource_type": "authorization",
  "event_type": "PAYMENT.AUTHORIZATION.CREATED",
  "summary": "A payment authorization was created",
  "resource": {
    "id": "2DC87612EK520411B",
    "create_time": "2013-06-25T21:39:15Z",
    "update_time": "2013-06-25T21:39:17Z",
    "state": "authorized",
    "amount": {
      "total": "7.47",
      "currency": "USD",
      "details": {
        "subtotal": "7.47"
      }
    },
    "parent_payment": "PAY-36246664YD343335CKHFA4AY",
    "valid_until": "2013-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"
      }
    ]
  },
  "links": [
    {
      "href": "https://api.sandbox.paypal.com/v1/notfications/webhooks-events/8PT597110X687430LKGECATA",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://api.sandbox.paypal.com/v1/notfications/webhooks-events/8PT597110X687430LKGECATA/resend",
      "rel": "resend",
      "method": "POST"
    }
  ]
}

Common Payments Objects

These are common objects used by payments resources.

address object (for payments)

This object is used for shipping or billing addresses.

Property Type Description
line1 string Line 1 of the address (e.g., Number, street, etc). 100 characters max. Required.
line2 string Line 2 of the address (e.g., Suite, apt #, etc). 100 characters max.
city string City name. 50 characters max. Required.
country_code string 2-letter country code. 2 characters max. Required.
postal_code string Zip code or equivalent is usually required for countries that have them. 20 characters max. Required in certain countries.
state string 2-letter code for US states, and the equivalent for other countries. 100 characters max.
phone string Phone number in E.123 format.
normalization_status enum Address normalization status, returned only for payers from Brazil. Allowed values: UNKNOWN, UNNORMALIZED_USER_PREFERRED, NORMALIZED, UNNORMALIZED
status enum Address status. Allowed values: CONFIRMED, UNCONFIRMED
     

amount object

This object defines a amount object

Property Type Description
currency string 3-letter currency code. PayPal does not support all currencies. Required.
total string Total amount charged from the payer to the payee. In case of a refund, this is the refunded amount to the original payer from the payee. 10 characters max with support for 2 decimal places. Required.
details details Additional details related to a payment amount.
     

authorization object

This object defines an authorization object.

Property Type Description
amount amount object Amount being authorized.
payment_mode enum Specifies the payment mode of the transaction. Possible values include: INSTANT_TRANSFER, MANUAL_BANK_TRANSFER, DELAYED_TRANSFER, and ECHECK.
Value assigned by PayPal.
create_time date-time Time of authorization as defined in RFC 3339 Section 5.6.
Value assigned by PayPal.
update_time date-time Time that the resource was last updated.
Value assigned by PayPal.
state enum State of the authorization. Either pending, authorized, captured, partially_captured, expired, or voided.
Value assigned by PayPal.
reason_code enum Reason code, AUTHORIZATION, for a transaction state of pending. Value assigned by PayPal.
parent_payment string ID of the payment resource on which this transaction is based.
Value assigned by PayPal.
id string ID of the authorization transaction.
Value assigned by PayPal.
valid_until date-time Authorization expiration time and date as defined in RFC 3339 Section 5.6.
Value assigned by PayPal.
clearing_time string Expected clearing time for eCheck transactions. Only supported when the payment_method is set to paypal. Value assigned by PayPal.
protection_eligibility string 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. Refer to protection_eligibility_type for specifics.
INELIGIBLE- Merchant is not protected under the Seller Protection Policy.
protection_eligibility_type string 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. Allowed values:
ITEM_NOT_RECEIVED_ELIGIBLE- Sellers are protected against claims for items not received.
UNAUTHORIZED_PAYMENT_ELIGIBLE- Sellers are protected against claims for unauthorized payments.
One or both of the allowed values can be returned.
fmf_details fmf_details Fraud Management Filter (FMF) details applied for the payment that could 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. See Fraud Management Filters Summary for more information.
links array of links objects HATEOAS links related to this request.
Value assigned by PayPal.
     

capture object

This object defines a capture object.

Property Type Description
amount amount object Amount being captured. If the amount matches the orginally authorized amount, the state of the authorization changes to captured. If not, the state of the authorization changes to partially_captured. Alternatively, you can set the is_final_capture to true to indicate a final capture.
is_final_capture boolean If set to true, all remaining funds held by the authorization will be released in the funding instrument. Default is ‘false’.
create_time date-time Time of capture as defined in RFC 3339 Section 5.6.
Value assigned by PayPal.
update_time date-time Time that the resource was last updated.
Value assigned by PayPal.
state enum State of the sale. Either pending, completed, refunded, or partially_refunded.
Value assigned by PayPal.
parent_payment string ID of the payment resource on which this transaction is based.
Value assigned by PayPal.
transaction_fee currency object Transaction fee applicable for this payment.
id string ID of the capture transaction.
Value assigned by PayPal.
links array of links objects HATEOAS links related to this request.
Value assigned by PayPal.
     

details object

This object defines amount details

Property Type Description
shipping string Amount charged for shipping. 10 characters max with support for 2 decimal places.
subtotal string Amount of the subtotal of the items. Required if line items are specified. 10 characters max, with support for 2 decimal places.
tax string Amount charged for tax. 10 characters max with support for 2 decimal places.
handling_fee string Amount being charged for the handling fee. Only supported when the payment_method is set to paypal.
insurance string Amount being charged for the insurance fee. Only supported when the payment_method is set to paypal.
shipping_discount string Amount being discounted for the shipping fee. Only supported when the payment_method is set to paypal.
     

error object (for Payments)

This object represents an error returned in the response.

Property Type Description
name string Human readable, unique name of the error.
debug_id string PayPal internal identifier used for correlation purposes.
message string Message describing the error.
information_link string URI for detailed information related to this error for the developer.
details error_details Additional details of the error.
     

error_details object

This object represents an error returned in the response.

Property Type Description
field string Name of the field that caused the error.
issue string Reason for the error.
     

credit_card object

This object represents a payer’s funding instrument, such as a credit card or token that represents a credit card.

Property Type Description
id string ID of the credit card. This ID is provided in the response when storing credit cards. Required if using a stored credit card.
payer_id string A unique identifier that you can assign and track when storing a credit card or using a stored 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, username, or email address. This is being deprecated in favor of the external_customer_id property.
number string Credit card number. Numeric characters only with no spaces or punctuation. The string must conform with modulo and length required by each credit card type. Redacted in responses. Required.
type string Credit card type. Valid types are: visa, mastercard, discover, amex Required.
expire_month integer Expiration month with no leading zero. Acceptable values are 1 through 12. Required.
expire_year integer 4-digit expiration year. Required.
cvv2 string 3-4 digit card validation code.
first_name string Cardholder’s first name.
last_name string Cardholder’s last name.
billing_address address object Billing address associated with card.
external_customer_id string A unique identifier of the customer to whom this bank account belongs. Generated and provided by the facilitator. This is now used in favor of payer_id when creating or using a stored funding instrument in the vault.
merchant_id string A user-provided, optional field that functions as a unique identifier for the merchant holding the card. Note that this has no relation to PayPal merchant id.
external_card_id string A unique identifier of the bank account resource. Generated and provided by the facilitator so it can be used to restrict the usage of the bank account to the specific merchant.
create_time date-time Resource creation time in ISO8601 date-time format (ex: 1994-11-05T13:15:30Z).
update_time date-time Resource update time in ISO8601 date-time format (ex: 1994-11-05T13:15:30Z).
state string State of the credit card funding instrument: expired or ok.
Value assigned by PayPal.
valid_until string Funding instrument expiration date.
Value assigned by PayPal.
     

credit_card_token object

This object represents a token corresponding to a credit card stored with PayPal.

Property Type Description
credit_card_id string ID of credit card previously stored using /vault/credit-card. Required.
payer_id string A unique identifier that you can assign and track when storing a credit card or using a stored 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, username, or email address. Required when using a stored credit card if a payer_id was originally provided when storing the credit card in vault.
last4 string Last four digits of the stored credit card number.
Value assigned by PayPal.
type string Credit card type. Valid types are: visa, mastercard, discover, amex. Values are presented in lowercase and not should not be used for display.
Value assigned by PayPal.
expire_year integer 4-digit expiration year.
Value assigned by PayPal.
expire_month integer Expiration month with no leading zero. Acceptable values are 1 through 12.
Value assigned by PayPal.
     

fmf_details object

This object represents Fraud Management Filter (FMF) details for a payment.

Property Type Description
filter_type enum Type of filter. Allowed values:
ACCEPT - An ACCEPT filter is triggered only for the TOTAL_PURCHASE_PRICE_MINIMUM filter setting and is returned only in direct credit card payments where payment is accepted.
PENDING - Triggers a PENDING filter action where you need to explicitly accept or deny the transaction.
DENY - Triggers a DENY action where payment is denied automatically.
REPORT - Triggers the Flag testing mode where payment is accepted.
filter_id enum Name of the fraud management filter. For more information about filters, see Fraud Management Filters Summary. Allowed values:
MAXIMUM_TRANSACTION_AMOUNT - basic filter
UNCONFIRMED_ADDRESS- basic filter
COUNTRY_MONITOR - basic filter
AVS_NO_MATCH - Address Verification Service No Match (advanced filter)
AVS_PARTIAL_MATCH - Address Verification Service Partial Match (advanced filter)
AVS_UNAVAILABLE_OR_UNSUPPORTED - Address Verification Service Unavailable or Not Supported (advanced filter)
CARD_SECURITY_CODE_MISMATCH- advanced filter
BILLING_OR_SHIPPING_ADDRESS_MISMATCH - advanced filter
RISKY_ZIP_CODE - high risk lists filter
SUSPECTED_FREIGHT_FORWARDER_CHECK - high risk lists filter
RISKY_EMAIL_ADDRESS_DOMAIN_CHECK - high risk lists filter
RISKY_BANK_IDENTIFICATION_NUMBER_CHECK - high risk lists filter
RISKY_IP_ADDRESS_RANGE - high risk lists filter
LARGE_ORDER_NUMBER - transaction data filter
TOTAL_PURCHASE_PRICE_MINIMUM - transaction data filter
IP_ADDRESS_VELOCITY - transaction data filter
PAYPAL_FRAUD_MODEL - transaction data filter
name string Name of the filter. This property is reserved for future use.
description string Description of the filter. This property is reserved for future use.

funding_instrument object

This object represents a payer’s funding instrument (credit card).

Property Type Description
credit_card credit_card Credit card details. Required if creating a funding instrument.
credit_card_token credit_card_token Token for credit card details stored with PayPal. You can use this in place of a credit card. Required if not passing credit card details.

item object

This object defines a item object.

Property Type Description
quantity string Number of a particular item. 10 characters max. Required.
name string Item name. 127 characters max. Required.
price string Item cost. 10 characters max. Required.
currency string 3-letter currency code. Required.
sku string Stock keeping unit corresponding (SKU) to item. 50 characters max.
description string Description of the item. Only supported when the payment_method is set to paypal. 127 characters max.
tax string Tax of the item. Only supported when the payment_method is set to paypal.

item_list object

This object provides a list of items and the related shipping address within a transaction.

Property Type Description
items array of item objects List of items.
shipping_address shipping_address Shipping address, if different than the payer address.

order object

This object includes information about the order.

Property Type Description
id string Identifier of the order transaction.
purchase_unit_reference_id string Identifier of the purchased unit associated with this object.
create_time date-time Time the resource was created.
update_time date-time Time the resource was last updated.
amount array Amount being collected.
state string State of the order transaction. Allowed values: PENDING, COMPLETED, REFUNDED, or PARTIALLY_REFUNDED.
pending_reason string Reason the transaction is in pending state. Allowed values: PAYER-SHIPPING-UNCONFIRMED, MULTI-CURRENCY, RISK-REVIEW, REGULATORY-REVIEW, VERIFICATION-REQUIRED, ORDER, or OTHER.
reason_code string Reason code for the transaction state being Pending or Reversed. Only supported when the payment_method is set to paypal. Value assigned by PayPal. Allowed values: CHARGEBACK, GUARANTEE, BUYER_COMPLAINT, REFUND, UNCONFIRMED_SHIPPING_ADDRESS, ECHECK, INTERNATIONAL_WITHDRAWAL, RECEIVING_PREFERENCE_MANDATES_MANUAL_ACTION, PAYMENT_REVIEW, REGULATORY_REVIEW, UNILATERAL, or VERIFICATION_REQUIRED.
clearing_time string Expected clearing time for eCheck transactions. Only supported when the payment_method is set to paypal. Value assigned by PayPal.
protection_eligibility string 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. Refer to protection_eligibility_type for specifics.
INELIGIBLE- Merchant is not protected under the Seller Protection Policy.
protection_eligibility_type string 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. Allowed values:
ITEM_NOT_RECEIVED_ELIGIBLE- Sellers are protected against claims for items not received.
UNAUTHORIZED_PAYMENT_ELIGIBLE- Sellers are protected against claims for unauthorized payments.
One or both of the allowed values can be returned.
links array of links objects HATEOAS links related to this request.
Value assigned by PayPal.
     

payer object

This object includes information about the payer including payment method, funding instruments, and details about the payer.

Property Type Description
payment_method string Payment method used. Must be either credit_card or paypal. Required.
funding_instruments array of funding_instrument objects A list of funding instruments for the current payment
payer_info payer_info Information related to the payer.
status string Status of the payer’s PayPal account. Only supported when the payment_method is set to paypal. Allowed values: VERIFIED or UNVERIFIED.

payer_info object

This object is pre-filled by PayPal when the payment_method is paypal.

Property Type Description
email string Email address representing the payer. 127 characters max.
salutation string Salutation of the payer.
first_name string First name of the payer.
Value assigned by PayPal.
middle_name string Middle name of the payer.
Value assigned by PayPal.
last_name string Last name of the payer.
Value assigned by PayPal.
suffix string Suffix of the payer.
payer_id string PayPal assigned Payer ID.
Value assigned by PayPal.
phone string Phone number representing the payer. 20 characters max.
country_code string Two-letter registered country code of the payer to identify the buyer country.
shipping_address shipping_address Shipping address of payer PayPal account.
Value assigned by PayPal.
tax_id_type string Payer’s tax ID type. Allowed values: BR_CPF or BR_CNPJ. Only supported when the payment_method is set to paypal.
tax_id string Payer’s tax ID. Only supported when the payment_method is set to paypal.

payment object

This object represents a payer’s funding instrument, such as a credit card or token that represents a credit card.

Property Type Description
intent string Payment intent. Must be set to sale for immediate payment, authorize to authorize a payment for capture later, or order to create an order. Required.
payer payer Source of the funds for this payment represented by a PayPal account or a direct credit card. Required.
transactions array of transaction objects Transactional details including the amount and item details. Required.
redirect_urls redirect_urls Set of redirect URLs you provide only for PayPal-based payments. Returned only when the payment is in created state. Required for PayPal payments.
id string ID of the created payment
Value assigned by PayPal.
create_time date-time Payment creation time as defined in RFC 3339 Section 5.6.
Value assigned by PayPal.
state string Payment state. Must be one of the following: created; approved; failed; pending; canceled; expired, or in_progress.
Value assigned by PayPal.
update_time date-time Time that the resource was last updated.
Value assigned by PayPal.
experience_profile_id string Identifier for the payment experience.
     

payment_execution object

This object includes information necessary to execute a PayPal account payment with the payer_id obtained in the web approval_url.

Property Type Description
payer_id string The ID of the Payer, passed in the return_url by PayPal. Required.
transactions array of transaction objects Transactional details including the amount and item details. Required.
     

payment_options object

This object includes payment options requested for the purchase unit.

Property Type Description
allowed_payment_method string Optional payment method type. If specified, the transaction will go through for only instant payment. Allowed values: INSTANT_FUNDING_SOURCE. Only for use with the paypal payment_method, not relevant for the credit_card payment_method.

redirect_urls object

This object represents a set of redirect URLs you provide to PayPal for PayPal account payments.

Property Type Description
return_url string The payer is redirected to this URL after approving the payment. Required for PayPal account payments.
cancel_url string The payer is redirected to this URL after canceling the payment. Required for PayPal account payments.

refund object

This object defines a refund object

Property Type Description
id string ID of the refund transaction. 17 characters max.
amount amount Details including both refunded amount (to payer) and refunded fee (to payee). 10 characters max.
create_time date-time Time of refund as defined in RFC 3339 Section 5.6
Value assigned by PayPal.
state string State of the refund. One of the following: pending; completed; or failed.
Value assigned by PayPal.
capture_id string ID of the sale transaction being refunded.
Value assigned by PayPal.
parent_payment string ID of the payment resource on which this transaction is based.
Value assigned by PayPal.
update_time date-time Time that the resource was last updated.
Value assigned by PayPal.
     

sale object

This object defines a sale object.

Property Type Description
id string ID of the sale transaction.
amount amount Details about the collected amount.
description string Description of sale.
create_time date-time Time of sale as defined in RFC 3339 Section 5.6
Value assigned by PayPal.
state string State of the sale. One of the following: pending; completed; refunded; or partially_refunded.
Value assigned by PayPal.
parent_payment string ID of the payment resource on which this transaction is based.
Value assigned by PayPal.
update_time date-time Time that the resource was last updated.
Value assigned by PayPal.
payment_mode string Specifies payment mode of the transaction. Only supported when the payment_method is set to paypal. Assigned by PayPal. Allowed values: INSTANT_TRANSFER, MANUAL_BANK_TRANSFER, DELAYED_TRANSFER, or ECHECK.
reason_code string Reason code for the transaction state being Pending or Reversed. Only supported when the payment_method is set to paypal.Assigned by PayPal. Allowed values: CHARGEBACK, GUARANTEE, BUYER_COMPLAINT, REFUND, UNCONFIRMED_SHIPPING_ADDRESS, ECHECK, INTERNATIONAL_WITHDRAWAL, RECEIVING_PREFERENCE_MANDATES_MANUAL_ACTION, PAYMENT_REVIEW, REGULATORY_REVIEW, UNILATERAL, or VERIFICATION_REQUIRED.
clearing_time string Expected clearing time for eCheck transactions. Only supported when the payment_method is set to paypal. Assigned by PayPal.
transaction_fee currency Transaction fee charged by PayPal for this transaction.
receivable_amount currency Net amount 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.
exchange_rate string Exchange rate applied for this transaction. Returned only in cross-currency use cases where a merchant bills a buyer in a non-primary currency for that buyer.
fmf_details fmf_details Fraud Management Filter (FMF) details applied for the payment that could 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. See Fraud Management Filters Summary for more information.
receipt_id string Receipt ID is a 16-digit payment identification number returned for guest users to identify the payment.
protection_eligibility string 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. Refer to protection_eligibility_type for specifics.
INELIGIBLE- Merchant is not protected under the Seller Protection Policy.
protection_eligibility_type string 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. Allowed values:
ITEM_NOT_RECEIVED_ELIGIBLE- Sellers are protected against claims for items not received.
UNAUTHORIZED_PAYMENT_ELIGIBLE- Sellers are protected against claims for unauthorized payments.
One or both of the allowed values can be returned.
links array of links objects HATEOAS links related to this call.
Value generated by PayPal.
     

shipping_address object

This object is used for the shipping address.

Property Type Description
recipient_name string Name of the recipient at this address. 50 characters max. Required
type string Address type. Must be one of the following: residential, business, or mailbox.
line1 string Line 1 of the address (e.g., Number, street, etc). 100 characters max. Required.
line2 string Line 2 of the address (e.g., Suite, apt #, etc). 100 characters max.
city string City name. 50 characters max. Required.
country_code string 2-letter country code. 2 characters max. Required.
postal_code string Zip code or equivalent is usually required for countries that have them. 20 characters max. Required in certain countries.
state string 2-letter code for US states, and the equivalent for other countries. 100 characters max.
phone string Phone number in E.123 format. 50 characters max.
     

transaction object

This object provides payment transactions details.

Property Type Description
amount amount Amount being collected . Required.
description string Description of transaction. 127 characters max.
item_list item_list Items and related shipping address within a transaction.
related_resources array of sale, authorization, capture, or refund, objects Financial transactions related to a payment.
invoice_number string Invoice number used to track the payment. Only supported when the payment_method is set to paypal. 256 characters max.
custom string Free-form field for the use of clients. Only supported when the payment_method is set to paypal. 256 characters max.
soft_descriptor string Soft descriptor used when charging this funding source. Only supported when the payment_method is set to paypal. 22 characters max.
payment_options payment_options Payment options requested for this purchase unit.
     

Common Billing Plans Objects

The following are used by billing plans:

plan object

Billing plan resource that will be used to create a billing agreement.

Property Type Description
id string Identifier of the billing plan. Assigned in response.
name string Name of the billing plan. Required.
description string Description of the billing plan. Required.
type string Type of the billing plan. Allowed values: FIXED, INFINITE. Required.
state string Status of the billing plan. Allowed values: CREATED, ACTIVE, INACTIVE, and DELETED. Assigned in response.
create_time string Time when the billing plan was created. Format YYYY-MM-DDTimeTimezone, as defined in ISO8601. Assigned in response.
update_time string Time when this billing plan was updated. Format YYYY-MM-DDTimeTimezone, as defined in ISO8601. Assigned in response.
payment_definitions array of payment_definition Array of payment definitions for this billing plan.
terms array of terms Array of terms for this billing plan. Assigned in response.
merchant_preferences merchant_preferences Specific preferences such as: set up fee, max fail attempts, autobill amount, and others that are configured for this billing plan.
links array of links HATEOAS links related to this call. Assigned in response.

payment_definition object

Resource representing payment definition scheduling information.

Property Type Description
id string Identifier of the payment_definition. Assigned in response.
name string Name of the payment definition. Required.
type string Type of the payment definition. Allowed values: TRIAL, REGULAR. Required.
frequency_interval string How frequently the customer should be charged. It can’t be more than 12 months. Required.
frequency string Frequency of the payment definition offered. Allowed values: WEEK, DAY, YEAR, MONTH. Required.
cycles string Number of cycles in this payment definition. For INFINITE type plans, cycles should be set to 0 for a REGULAR type payment_definition. Required.
amount currency Amount that will be charged at the end of each cycle for this payment definition. Required.
charge_models array of charge_models Array of charge_models for this payment definition.

currency object

Base object for all financial value related fields (balance, payment due, etc.)

Property Type Description
currency string 3 letter currency code as defined by ISO 4217. Required.
value string amount up to N digit after the decimals separator as defined in ISO 4217 for the appropriate currency code. Required.

charge_models object

A resource representing a charge model for a payment definition.

Property Type Description
id string Identifier of the charge model. Assigned in response.
type string Type of charge model. Allowed values: SHIPPING, TAX. Required.
amount currency Specific amount for this charge model. Required.

terms object

Resource representing terms used by the plan.

Property Type Description
id string Identifier of the terms. Assigned in response.
type string Term type. Allowed values: MONTHLY, WEEKLY, YEARLY. Required.
max_billing_amount currency Max Amount associated with this term. Required.
occurrences string How many times money can be pulled during this term. Required.
amount_range currency Amount_range associated with this term. Required.
buyer_editable string Buyer’s ability to edit the amount in this term. Required.

merchant_preferences object

Resource representing merchant preferences like max failed attempts, set up fee and others for a plan.

Property Type Description
id string Identifier of the merchant_preferences. Assigned in response.
setup_fee currency Setup fee amount. Default is 0.
cancel_url string Redirect URL on cancellation of agreement request. Required.
return_url string Redirect URL on creation of agreement request. Required.
notify_url string Notify URL on agreement creation. Read-only and reserved for future use. Assigned in response.
max_fail_attempts string Total number of failed attempts allowed. Default is 0, representing an infinite number of failed attempts.
auto_bill_amount string Allow auto billing for the outstanding amount of the agreement in the next cycle. Allowed values: YES, NO. Default is NO.
initial_fail_amount_action string Action to take if a failure occurs during initial payment. Allowed values: CONTINUE, CANCEL. Default is continue.
accepted_payment_type string Payment types that are accepted for this plan. Assigned in response.
char_set string char_set for this plan. Assigned in response.

patch_request object

Request object used for a JSON Patch.

Property Type Description
op string The operation to perform. Required. Allowed values: add, remove, replace, move, copy, test
path string String containing a JSON-Pointer value that references a location within the target document where the operation is performed.
value One of the following:
number,
integer,
string,
boolean,
null,
array,
object
New value to apply based on the operation. op=remove does not require value.
from string A string containing a JSON Pointer value that references the location in the target document from which to move the value. Required for use where op=move.

plan_list object

Resource representing a list of billing plans with basic information and get link.

Property Type Description
plans array of plan Array of billing plans.
total_items string Total number of items. Assigned in response.
total_pages string Total number of pages. Assigned in response.
links array of links HATEOAS links related to this call.

Common Billing Agreements Objects

The following are used by billing agreements:

agreement object

A resource representing an agreement.

Property Type Description
id string Identifier of the agreement. Assigned in response.
state string State of the agreement. Possible values are Active, Pending, Expired, Suspend, Reactivate, and Cancel. Assigned in response.
name string Name of the agreement. Required.
description string Description of the agreement. Required.
start_date string Start date of the agreement. Date format yyyy-MM-dd z, as defined in ISO8601. Required.
agreement_details agreement_details Details of the agreement.
payer payer Details of the buyer who is enrolling in this agreement. This information is gathered from execution of the approval URL. Required.
shipping_address address Shipping address object of the agreement, which should be provided if it is different from the default address.
override_merchant_preferences merchant_preferences Default merchant preferences from the billing plan are used, unless override preferences are provided here.
override_charge_models array of override_charge_model Array of override_charge_model for this agreement if needed to change the default models from the billing plan.
plan plan Plan details for this agreement. Required.
create_time string Date and time that this resource was created. Date format yyyy-MM-dd z, as defined in ISO8601. Assigned in response.
update_time string Date and time that this resource was updated. Date format yyyy-MM-dd z, as defined in ISO8601. Assigned in response.
links array of links HATEOAS links related to this call. Assigned in response.

agreement_details object

A resource representing the agreement details.

Property Type Description
outstanding_balance currency The outstanding balance for this agreement.
cycles_remaining string Number of cycles remaining for this agreement.
cycles_completed string Number of cycles completed for this agreement.
next_billing_date string The next billing date for this agreement, represented as 2014-02-19T10:00:00Z format.
last_payment_date string Last payment date for this agreement, represented as 2014-06-09T09:42:31Z format.
last_payment_amount currency Last payment amount for this agreement.
final_payment_date string Last payment date for this agreement, represented as 2015-02-19T10:00:00Z format.
failed_payment_count string Total number of failed payments for this agreement.

currency object

Base object for all financial value related fields (balance, payment due, etc.)

Property Type Description
currency string 3 letter currency code as defined by ISO 4217. Required.
value string amount up to N digit after the decimals separator as defined in ISO 4217 for the appropriate currency code. Required.

payer object

A resource representing a Payer that funds a payment.

Property Type Description
payment_method string Payment method being used - PayPal Wallet payment, Bank Direct Debit, or Direct Credit card. Required. Allowed values: credit_card, paypal
funding_instruments array of funding_instrument List of funding instruments from which the funds of the current payment come. Typically a credit card.
payer_info payer_info Information related to the Payer.

funding_instrument object

A resource representing a Payer’s funding instrument.

Property Type Description
credit_card credit_card Credit Card information.

credit_card object

A resource representing a credit card that can be used to fund a payment.

Property Type Description
id string ID of the credit card being saved for later use. Assigned in response.
number string Card number. Required.
type string Type of the Card (eg. Visa, Mastercard, etc.). Required.
expire_month integer Two digit card expiry month, represented as 01 - 12. Required.
expire_year integer Four digit card expiry year, represented as YYYY format. Required.
cvv2 integer Card validation code. Only supported when making a Payment, but not when saving a credit card for future use.
first_name string Card holder’s first name.
last_name string Card holder’s last name.
billing_address address Billing Address associated with this card.
state string State of the funding instrument. Assigned in response. Allowed values: expired, ok
valid_until string Date/Time until this resource can be used fund a payment. Assigned in response.
links array of links HATEOAS links related to this call.

address object

Base Address object used as billing address in a payment or extended for Shipping Address.

Property Type Description
line1 string Line 1 of the Address (eg. number, street, etc). Required.
line2 string Optional line 2 of the Address (eg. suite, apt #, etc.).
city string City name. Required.
country_code string 2 letter country code. Required.
postal_code string Zip code or equivalent is usually required for countries that have them. For list of countries that do not have postal codes please refer to http://en.wikipedia.org/wiki/Postal_code.
state string 2 letter code for US states, and the equivalent for other countries.
phone string Phone number in E.123 format.

payer_info object

A resource representing information about a Payer.

Property Type Description
email string Email address representing the Payer.
first_name string First Name of the Payer. Assigned in response.
last_name string Last Name of the Payer. Assigned in response.
payer_id string PayPal assigned Payer ID. Assigned in response.
phone string Phone number representing the Payer.
billing_address address Billing address of the Payer.

merchant_preferences object

Resource representing merchant preferences like max failed attempts,set up fee and others for a plan

Property Type Description
id string Identifier of the merchant_preferences. Assigned in response.
setup_fee currency Setup fee amount. Default is 0.
cancel_url string Redirect URL on cancellation of agreement request. Required.
return_url string Redirect URL on creation of agreement request. Required.
notify_url string Notify URL on agreement creation. 1000 characters max. Read-only and reserved for future use. Assigned in response.
max_fail_attempts string Total number of failed attempts allowed. Default is 0, representing an infinite number of failed attempts.
auto_bill_amount string Allow auto billing for the outstanding amount of the agreement in the next cycle. Default is false.
initial_fail_amount_action string Action to take if a failure occurs during initial payment. Default is continue.
accepted_payment_type string Payment types that are accepted for this plan. Assigned in response.
char_set string char_set for this plan. Assigned in response.

override_charge_model object

A resource representing an override_charge_model to be used during creation of the agreement.

Property Type Description
charge_id string ID of charge model. Required.
amount currency Updated Amount to be associated with this charge model. Required.

plan object

Billing plan resource that will be used to create a billing agreement.

Property Type Description
id string Identifier of the billing plan. Assigned in response.
name string Name of the billing plan. Required.
description string Description of the billing plan. Required.
type string Type of the billing plan. Possible types include: FIXED and INFINITE. Required.
state string Status of the billing plan. Possible states include: CREATED, ACTIVE, and INACTIVE. Assigned in response.
create_time string Time when the billing plan was created. Format YYYY-MM-DDTimeTimezone, as defined in ISO8601. Assigned in response.
update_time string Time when this billing plan was updated. Format YYYY-MM-DDTimeTimezone, as defined in ISO8601. Assigned in response.
payment_definitions array of payment_definition Array of payment definitions for this billing plan.
terms array of terms Array of terms for this billing plan. Assigned in response.
merchant_preferences merchant_preferences Specific preferences such as: set up fee, max fail attempts, autobill amount, and others that are configured for this billing plan.
links array of links HATEOAS links related to this call.

payment_definition object

Resource representing payment definition scheduling information.

Property Type Description
id string Identifier of the payment_definition. Assigned in response.
name string Name of the payment definition. Required.
type string Type of the payment definition. Possible types include: TRIAL and REGULAR. Required.
frequency_interval string How frequently the customer should be charged. Required.
frequency string Frequency of the payment definition offered. Required.
cycles string Number of cycles in this payment definition. Required.
amount currency Amount that will be charged at the end of each cycle for this payment definition. Required.
charge_models array of charge_models Array of charge_models for this payment definition.

charge_models object

A resource representing a charge model for a payment definition.

Property Type Description
id string Identifier of the charge model. Assigned in response.
type string Type of charge model, possible values can be shipping/tax. Required.
amount currency Specific amount for this charge model. Required.

terms object

Resource representing terms used by the plan.

Property Type Description
id string Identifier of the terms. Assigned in response.
type string Term type Required.
max_billing_amount currency Max Amount associated with this term. Required.
occurrences string How many times money can be pulled during this term. Required.
amount_range currency Amount_range associated with this term. Required.
buyer_editable string Buyer’s ability to edit the amount in this term. Required.

patch_request object

Request object used for a JSON Patch.

Property Type Description
op string The operation to perform. Required. Allowed values: add, remove, replace, move, copy, test
path string String containing a JSON-Pointer value that references a location within the target document where the operation is performed.
value One of the following:
number,
integer,
string,
boolean,
null,
array,
object
New value to apply based on the operation. op=remove does not require value.
from string A string containing a JSON Pointer value that references the location in the target document from which to move the value. Required for use where op=move.

agreement_state_descriptor object

Description of the current state of the agreement.

Property Type Description
note string Reason for changing the state of the agreement.
amount currency The amount and currency of the agreement. It is required to bill outstanding amounts, but is not required when suspending, cancelling or reactivating an agreement.

agreement_transactions object

A resource representing agreement_transactions that is returned during a transaction search.

Property Type Description
agreement_transaction_list array of agreement_transaction Array of agreement_transaction object.

agreement_transaction object

A resource representing an agreement_transaction that is returned during a transaction search.

Property Type Description
transaction_id string Id corresponding to this transaction. Assigned in response.
status string State of the subscription at this time. Possible values include: Created, Suspended, Reactivated, Canceled, and Completed. Assigned in response.
transaction_type string Type of transaction, usually Recurring Payment. Assigned in response.
amount currency Amount for this transaction. Required.
fee_amount currency Fee amount for this transaction. Required.
net_amount currency Net amount for this transaction. Required.
payer_email string Email id of payer. Assigned in response.
payer_name string Business name of payer. Assigned in response.
time_stamp string Time at which this transaction happened. Assigned in response.
time_zone string Time zone of time_updated field. Assigned in response.

Common Objects for Payouts

payouts_batch_request object

This object represents a set of payouts that includes status data for the payouts. This object enables you to create a payout using a POST request.

Property Type Description
sender_batch_header sender_batch_header The original batch header as provided by the payment sender. Required.
items array of payout_item An array of payout items (that is, a set of individual payouts). Required.

sender_batch_header object

This object represents sender-provided data about a batch header. The data is provided in a POST request. All batch submissions must have a batch header.

Property Type Description
sender_batch_id string Sender-created ID for tracking the batch payout in an accounting system.
email_subject string The subject line text for the email that PayPal sends when a payout item is completed. (The subject line is the same for all recipients.) Maximum of 255 single-byte alphanumeric characters.
recipient_type string The type of ID for a payment receiver. If this field is provided, the payout items without a recipient_type will use the provided value. If this field is not provided, each payout item must include a value for the recipient_type. Allowed values: EMAIL, PHONE, PAYPAL_ID

payout_item object

Sender-created description of a payout to a single recipient.

Property Type Description
recipient_type string The type of identification for the payment receiver. If this field is provided, the payout items without a recipient_type will use the provided value. If this field is not provided, each payout item must include a value for the recipient_type. Allowed values: EMAIL, PHONE, PAYPAL_ID
amount currency The amount of money to pay a receiver. Required.
note string Note for notifications. The note is provided by the payment sender. This note can be any string. Assigned in response.
receiver string The receiver of the payment. In a call response, the format of this value corresponds to the recipient_type specified in the request. Required.
sender_item_id string A sender-specific ID number, used in an accounting system for tracking purposes. Assigned in response.

currency object

Base object for all financial value related fields (balance, payment due, etc.)

Property Type Description
currency string 3 letter currency code Required.
value string amount upto 2 decimals represented as string Required.

payouts_batch_response object

Response to a POST request that creates a payout.

Property Type Description
batch_header batch_header Batch header resource.
links array of string HATEOAS links.

batch_header object

Batch header resource.

Property Type Description
payout_batch_id string An ID for a batch payout. Generated by PayPal.
batch_status string The generated batch status. If the batch passes the elementary checks, the status will be PENDING. Allowed values: DENIED, PENDING, PROCESSING, SUCCESS
sender_batch_header sender_batch_header The original batch header as provided by the payment sender. Required.

batch_status object

The batch status as generated by PayPal.

Property Type Description
batch_header batch_header A batch header that includes the generated batch status. Required.
items array of payout_item_details Array of the items in a batch payout. Required.

payout_item_details object

This object contains status and other data for an individual payout of a batch.

Property Type Description
payout_item_id string An ID for an individual payout. Provided by PayPal, such as in the case of getting the status of a batch request. Required.
transaction_id string Generated ID for the transaction.
transaction_status string Status of a transaction. Allowed values: SUCCESS, DENIED, PENDING, PROCESSING, FAILED, UNCLAIMED, RETURNED, ONHOLD, BLOCKED, CANCELLED
payout_item_fee currency Amount of money in U.S. dollars for fees.
payout_batch_id string An ID for the batch payout. Generated by PayPal. Required.
sender_batch_id string Sender-created ID for tracking the batch in an accounting system.
payout_item payout_item The data for a payout item that the sender initially provided. Required.
time_processed string Time of the last processing for this item. Required.
errors error Details of an Error
links array of string HATEOAS links

error object

Details of an Error

Property Type Description
name string Human readable, unique name of the error. Required.
debug_id string PayPal internal identifier used for correlation purposes. Assigned in response.
message string Message describing the error. Required.
information_link string URI for detailed information related to this error for the developer. Required.
details array of error_details Additional details of the error Assigned in response.

error_details object

Details about a specific error.

Property Type Description
field string Name of the field that caused the error. Required.
issue string Reason for the error. Required.

Common Identity Objects

These are common objects used by the identity resources.

address object (for Identity)

This object represents an end user’s preferred address.

Property Type Description
street_address string Full street address component, which may include house number, street name.
locality string City or locality component.
region string State, province, prefecture or region component.
postal_code string Zip code or postal code component.
country string Country name component.
     

error object (for Identity)

This object represents an error returned in the response.

Property Type Description
error string One of the following enum list ascii error codes: invalid_request, invalid_client, invalid_grant, unauthorized_client, unsupported_grant_type, invalid_scope.
error_description string A resource ID that indicates the starting resource in the returned results.
error_uri string A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error.
     

tokeninfo object

This object represents an error returned in the response.

Property Type Description
scope string Required if different from the scope requested by the client. For a list of possible values, see the attributes table.
access_token string The access token issued by the authorization server.
refresh_token string The refresh token, which can be used to obtain new access tokens using the same authorization grant as described in OAuth2.0 RFC6749 - Section 6.
token_type string The type of the token issued as described in OAuth2.0 RFC6749 - Section 7.1. Value is case insensitive.
expires_in integer The lifetime of the access token in seconds. After the access token expires, use the refresh_token to refresh the access token.
     

userinfo object

This object represents an end user’s profile details.

Property Type Description
user_id string Identifier for the End-User at the Issuer.
name string End-User’s full name in displayable form including all name parts, possibly including titles and suffixes, ordered according to the End-User’s locale and preferences.
given_name string Given name(s) or first name(s) of the End-User.
family_name string Surname(s) or last name(s) of the End-User.
email string End-User’s preferred e-mail address.
verified boolean True if the End-User’s e-mail address has been verified; otherwise false.
gender string End-User’s gender.
birthdate string End-User’s birthday, represented as an YYYY-MM-DD format. They year MAY be 0000, indicating it is omited. To represent only the year, YYYY format would be used.
zoneinfo string Time zone database representing the End-User’s time zone.
locale string End-User’s locale.
phone_number string End-User’s preferred telephone number.
address address End-User’s preferred address.
verified_account boolean Verified account status.
account_type string Account type: either personal or business.
age_range string Account holder age range.
payer_id string Account payer identifier.
     

Common Invoicing Objects

These are common objects used by the invoicing resources.

invoice object

Detailed invoice information.

Property Type Description
id string Unique invoice resource identifier. Assigned in response.
number string Unique number that appears on the invoice. If left blank will be auto-incremented from the last number. 25 characters max.
uri string URI of the invoice resource. Assigned in response.
status string Status of the invoice. Assigned in response. Allowed values: DRAFT, SENT, PAID, MARKED_AS_PAID, CANCELLED, REFUNDED, PARTIALLY_REFUNDED, MARKED_AS_REFUNDED
merchant_info merchant_info Information about the merchant who is sending the invoice. Required.
billing_info array of billing_info Email address of invoice recipient (required) and optional billing information. (Note: We currently only allow one recipient).
shipping_info shipping_info Shipping information for entities to whom items are being shipped.
items array of invoice_item List of items included in the invoice. 100 items max per invoice.
invoice_date string Date on which the invoice was enabled. Date format yyyy-MM-dd z, as defined in ISO8601.
payment_term payment_term Optional field to pass payment deadline for the invoice. Either term_type or due_date can be passed, but not both.
discount cost Invoice level discount in percent or amount.
shipping_cost shipping_cost Shipping cost in percent or amount.
custom custom_amount Custom amount applied on an invoice. If a label is included then the amount cannot be empty.
tax_calculated_after_discount boolean Indicates whether tax is calculated before or after a discount. If false (the default), the tax is calculated before a discount. If true, the tax is calculated after a discount.
tax_inclusive boolean A flag indicating whether the unit price includes tax. Default is false
terms string General terms of the invoice. 4000 characters max.
note string Note to the payer. 4000 characters max.
merchant_memo string Bookkeeping memo that is private to the merchant. 150 characters max.
logo_url string Full URL of an external image to use as the logo. 4000 characters max.
total_amount currency The total amount of the invoice. Assigned in response.
payments array of payment_detail List of payment details for the invoice. Assigned in response.
refunds array of refund_detail List of refund details for the invoice. Assigned in response.
metadata metadata Audit information for the invoice. Assigned in response.

invoices object

List of invoices belonging to a merchant.

Property Type Description
id string Unique invoice resource identifier. Assigned in response.
number string Unique number that appears on the invoice. If left blank will be auto-incremented from the last number. 25 characters max.
uri string URI of the invoice resource. Assigned in response.
status string Status of the invoice. Assigned in response. Allowed values: DRAFT, SENT, PAID, MARKED_AS_PAID, CANCELLED, REFUNDED, PARTIALLY_REFUNDED, MARKED_AS_REFUNDED
merchant_info merchant_info Information about the merchant who is sending the invoice. Required.
billing_info array of billing_info Email address of invoice recipient (required) and optional billing information. (Note: We currently only allow one recipient).
shipping_info shipping_info Shipping information for entities to whom items are being shipped.
items array of invoice_item List of items included in the invoice. 100 items max per invoice.
invoice_date string Date on which the invoice was enabled. Date format yyyy-MM-dd z, as defined in ISO8601.
payment_term payment_term Optional field to pass payment deadline for the invoice. Either term_type or due_date can be passed, but not both.
discount cost Invoice level discount in percent or amount.
shipping_cost shipping_cost Shipping cost in percent or amount.
custom custom_amount Custom amount applied on an invoice. If a label is included then the amount cannot be empty.
tax_calculated_after_discount boolean Indicates whether tax is calculated before or after a discount. If false (the default), the tax is calculated before a discount. If true, the tax is calculated after a discount.
tax_inclusive boolean A flag indicating whether the unit price includes tax. Default is false
terms string General terms of the invoice. 4000 characters max.
note string Note to the payer. 4000 characters max.
merchant_memo string Bookkeeping memo that is private to the merchant. 150 characters max.
logo_url string Full URL of an external image to use as the logo. 4000 characters max.
total_amount currency The total amount of the invoice. Assigned in response.
payments array of payment_detail List of payment details for the invoice. Assigned in response.
refunds array of refund_detail List of refund details for the invoice. Assigned in response.
metadata metadata Audit information for the invoice. Assigned in response.

invoice_item object

Information about a single line item.

Property Type Description
name string Name of the item. 60 characters max. Required.
description string Description of the item. 1000 characters max.
quantity number Quantity of the item. Range of 0 to 9999.999. Required.
unit_price currency Unit price of the item. Range of -999999.99 to 999999.99. Required.
tax tax Tax associated with the item.
date string Date on which the item or service was provided. Date format yyyy-MM-dd z, as defined in ISO8601.
discount cost Item discount in percent or amount.

merchant_info object

Business information of the merchant that will appear on the invoice.

Property Type Description
email string Email address of the merchant. 260 characters max. Required.
first_name string First name of the merchant. 30 characters max.
last_name string Last name of the merchant. 30 characters max.
address address Address of the merchant.
business_name string Company business name of the merchant. 100 characters max.
phone phone Phone number of the merchant.
fax phone Fax number of the merchant.
website string Website of the merchant. 2048 characters max.
tax_id string Tax ID of the merchant. 100 characters max.
additional_info string Option to display additional information such as business hours. 40 characters max.

billing_info object

Billing information for the invoice recipient.

Property Type Description
email string Email address of the invoice recipient. 260 characters max. Required.
first_name string First name of the invoice recipient. 30 characters max.
last_name string Last name of the invoice recipient. 30 characters max.
business_name string Company business name of the invoice recipient. 100 characters max.
address address Address of the invoice recipient.
language string Language of the email sent to the payer. Will only be used if payer doesn’t have a PayPal account. Allowed values: da_DK, de_DE, en_AU, en_GB, en_US, es_ES, es_XC, fr_CA, fr_FR, fr_XC, he_IL, id_ID, it_IT, ja_JP, nl_NL, no_NO, pl_PL, pt_BR, pt_PT, ru_RU, sv_SE, th_TH, tr_TR, zh_CN, zh_HK, zh_TW, zh_XC
additional_info string Option to display additional information such as business hours. 40 characters max.

shipping_info object

Shipping information for the invoice recipient.

Property Type Description
first_name string First name of the invoice recipient. 30 characters max.
last_name string Last name of the invoice recipient. 30 characters max.
business_name string Company business name of the invoice recipient. 100 characters max.
address address Address of the invoice recipient.

payment_term object

Payment term of the invoice. If term_type is present, due_date must not be present and vice versa.

Property Type Description
term_type string Terms by which the invoice payment is due. Allowed values: DUE_ON_RECEIPT, NET_10, NET_15, NET_30, NET_45
due_date string Date on which invoice payment is due. It must be always a future date. Date format yyyy-MM-dd z, as defined in ISO8601.

cost object

Cost as a percent. For example, 10% should be entered as 10. Alternatively, cost as an amount. For example, an amount of 5 should be entered as 5.

Property Type Description
percent number Cost in percent. Range of 0 to 100.
amount currency Cost in amount. Range of 0 to 999999.99.

currency object

Base object for all financial value related fields (balance, payment due, etc.)

Property Type Description
currency string 3 letter currency code as defined by ISO 4217. Required.
value string amount up to N digit after the decimals separator as defined in ISO 4217 for the appropriate currency code. Required.

shipping_cost object

Shipping cost in percent or amount.

Property Type Description
amount currency Shipping cost in amount. Range of 0 to 999999.99.
tax tax Tax percentage on shipping amount.

tax object

Tax information.

Property Type Description
id string Identifier of the resource. Assigned in response.
name string Name of the tax. 10 characters max. Required.
percent number Rate of the specified tax. Range of 0.001 to 99.999. Required.
amount currency Tax in the form of money. Cannot be specified in a request. Assigned in response.

custom_amount object

Custom amount applied on an invoice. If a label is included then the amount cannot be empty.

Property Type Description
label string Custom amount label. 25 characters max.
amount currency Custom amount value. Range of 0 to 999999.99.

payment_detail object

Invoicing payment information.

Property Type Description
type string PayPal payment detail indicating whether payment was made in an invoicing flow via PayPal or externally. In the case of the mark-as-paid API, payment type is EXTERNAL and this is what is now supported. The PAYPAL value is provided for backward compatibility. Assigned in response. Allowed values: PAYPAL, EXTERNAL
transaction_id string PayPal payment transaction id. Mandatory field in case the type value is PAYPAL. Assigned in response.
transaction_type string Type of the transaction. Assigned in response. Allowed values: SALE, AUTHORIZATION, CAPTURE
date string Date when the invoice was paid. Date format yyyy-MM-dd z, as defined in ISO8601.
method string Payment mode or method. This field is mandatory if the value of the type field is OTHER. Required. Allowed values: BANK_TRANSFER, CASH, CHECK, CREDIT_CARD, DEBIT_CARD, PAYPAL, WIRE_TRANSFER, OTHER
note string Optional note associated with the payment.

refund_detail object

Invoicing refund information.

Property Type Description
type string PayPal refund type indicating whether refund was done in invoicing flow via PayPal or externally. In the case of the mark-as-refunded API, refund type is EXTERNAL and this is what is now supported. The PAYPAL value is provided for backward compatibility. Required. Allowed values: PAYPAL, EXTERNAL
date string Date when the invoice was marked as refunded. If no date is specified, the current date and time is used as the default. In addition, the date must be after the invoice payment date. Date format yyyy-MM-dd z, as defined in ISO8601.
note string Optional note associated with the refund.

metadata object

Audit information of the resource.

Property Type Description
created_date string Date when the resource was created. Assigned in response.
created_by string Email address of the account that created the resource. Assigned in response.
cancelled_date string Date when the resource was cancelled. Assigned in response.
cancelled_by string Actor who cancelled the resource. Assigned in response.
last_updated_date string Date when the resource was last edited. Assigned in response.
last_updated_by string Email address of the account that last edited the resource. Assigned in response.
first_sent_date string Date when the resource was first sent. Assigned in response.
last_sent_date string Date when the resource was last sent. Assigned in response.
last_sent_by string Email address of the account that last sent the resource. Assigned in response.

address object

Base Address object used as billing address in a payment or extended for Shipping Address.

Property Type Description
line1 string Line 1 of the Address (eg. number, street, etc). Required.
line2 string Optional line 2 of the Address (eg. suite, apt #, etc.).
city string City name. Required.
country_code string 2 letter country code. Required.
postal_code string Zip code or equivalent is usually required for countries that have them. For list of countries that do not have postal codes please refer to http://en.wikipedia.org/wiki/Postal_code.
state string 2 letter code for US states, and the equivalent for other countries.
phone string Phone number in E.123 format.

phone object

Representation of a phone number.

Property Type Description
country_code string Country code (in E.164 format). Assume length is n. Required.
national_number string In-country phone number (in E.164 format). Maximum (15 - n) digits. Required.

notification object

Email/SMS notification.

Property Type Description
subject string Subject of the notification.
note string Note to the payer.
send_to_merchant boolean A flag indicating whether a copy of the email has to be sent to the merchant.

search object

Invoice search parameters.

Property Type Description
email string Initial letters of the email address.
recipient_first_name string Initial letters of the recipient’s first name.
recipient_last_name string Initial letters of the recipient’s last name.
recipient_business_name string Initial letters of the recipient’s business name.
number string The invoice number that appears on the invoice.
status string Status of the invoice. Allowed values: DRAFT, SENT, PAID, MARKED_AS_PAID, CANCELLED, REFUNDED, PARTIALLY_REFUNDED, MARKED_AS_REFUNDED
lower_total_amount currency Lower limit of total amount.
upper_total_amount currency Upper limit of total amount.
start_invoice_date string Start invoice date. Date format yyyy-MM-dd z, as defined in ISO8601.
end_invoice_date string End invoice date. Date format yyyy-MM-dd z, as defined in ISO8601.
start_due_date string Start invoice due date. Date format yyyy-MM-dd z, as defined in ISO8601.
end_due_date string End invoice due date. Date format yyyy-MM-dd z, as defined in ISO8601.
start_payment_date string Start invoice payment date. Date format yyyy-MM-dd z, as defined in ISO8601.
end_payment_date string End invoice payment date. Date format yyyy-MM-dd z, as defined in ISO8601.
start_creation_date string Start invoice creation date. Date format yyyy-MM-dd z, as defined in ISO8601.
end_creation_date string End invoice creation date. Date format yyyy-MM-dd z, as defined in ISO8601.
page number Offset of the search results.
page_size number Page size of the search results.
total_count_required boolean A flag indicating whether total count is required in the response.

cancel_notification object

Email/SMS notification.

Property Type Description
subject string Subject of the notification.
note string Note to the payer.
send_to_merchant boolean A flag indicating whether a copy of the email has to be sent to the merchant.
send_to_payer boolean A flag indicating whether a copy of the email has to be sent to the payer.

Common Payment Experience Objects

These are common objects used by the payment experience resources.

web_profile object

Payment Web experience profile resource

Property Type Description
id string Unique ID of the web experience profile. Assigned in response.
name string Name of the web experience profile. Unique only among the profiles for a given merchant. Required.
flow_config flow_config Parameters for flow configuration.
input_fields input_fields Parameters for input fields customization.
presentation presentation Parameters for style and presentation.

flow_config object

Parameters for flow configuration.

Property Type Description
landing_page_type string Type of PayPal page to be displayed when a user lands on the PayPal site for checkout. Allowed values: Billing or Login. When set to Billing, the Non-PayPal account landing page is used. When set to Login, the PayPal account login landing page is used.
bank_txn_pending_url string The URL on the merchant site for transferring to after a bank transfer payment. Use this field only if you are using giropay or bank transfer payment methods in Germany.

input_fields object

Parameters for input fields customization.

Property Type Description
allow_note boolean Enables the buyer to enter a note to the merchant on the PayPal page during checkout.
no_shipping integer Determines whether or not PayPal displays shipping address fields on the experience pages. Allowed values: 0, 1, or 2. When set to 0, PayPal displays the shipping address on the PayPal pages. When set to 1, PayPal does not display shipping address fields whatsoever. When set to 2, if you do not pass the shipping address, PayPal obtains it from the buyer’s account profile. For digital goods, this field is required, and you must set it to 1.
address_override integer Determines if the PayPal pages should display the shipping address supplied in this call, rather than the shipping address on file with PayPal for this buyer. Displaying the address on file does not allow the buyer to edit the address. Allowed values: 0 or 1. When set to 0, the PayPal pages should display the address on file. When set to 1, the PayPal pages should display the addresses supplied in this call instead of the address from the buyer’s PayPal account.

presentation object

Parameters for style and presentation.

Property Type Description
brand_name string A label that overrides the business name in the PayPal account on the PayPal pages. Character length and limitations: 127 single-byte alphanumeric characters.
logo_image string A URL to logo image. Allowed vaues: .gif, .jpg, or .png. Limit the image to 190 pixels wide by 60 pixels high. PayPal crops images that are larger. PayPal places your logo image at the top of the cart review area. PayPal recommends that you store the image on a secure (https) server. Otherwise, web browsers display a message that checkout pages contain non-secure items. Character length and limit: 127 single-byte alphanumeric characters.
locale_code string Locale of pages displayed by PayPal payment experience. Allowed values: AU, AT, BE, BR, CA, CH, CN, DE, ES, GB, FR, IT, NL, PL, PT, RU, US. The following 5-character codes are also allowed for languages in specific countries: da_DK, he_IL, id_ID, ja_JP, no_NO, pt_BR, ru_RU, sv_SE, th_TH, tr_TR, zh_CN, zh_HK, zh_TW.

create_profile_response object

Response schema for create profile api

Property Type Description
id string ID of the payment web experience profile.

patch_request object

Request object used for a JSON Patch.

Property Type Description
op string The operation to perform. Required. Allowed values: add, remove, replace, move, copy, test
path string string containing a JSON-Pointer value that references a location within the target document (the target location) where the operation is performed. Required.
value string New value to apply based on the operation.
from string A string containing a JSON Pointer value that references the location in the target document to move the value from.

web_profile_list object

Web profile list

Property Type Description
id string Unique ID of the web experience profile. Assigned in response.
name string Name of the web experience profile. Unique only among the profiles for a given merchant. Required.
flow_config flow_config Parameters for flow configuration.
input_fields input_fields Parameters for input fields customization.
presentation presentation Parameters for style and presentation.

Common Notifications Objects

These are common objects used by the notifications resources.

event_type_list object

List of Webhooks event-types

Property Type Description
event_types array of event_type A list of Webhooks event-types

webhook_list object

List of Webhooks

Property Type Description
webhooks array of webhook A list of Webhooks

event_list object

List of Webhooks event resources

Property Type Description
events array of event A list of Webhooks event resources
count integer Number of items returned in each range of results. Note that the last results range could have fewer items than the requested number of items.
links array of links HATEOAS links related to this call.

error_type_list object

List of Webhooks error types

Property Type Description
error_types array of error_type A list of Webhooks error-types

error_list object

List of Webhooks error resources

Property Type Description
items array of error A list of Webhooks error resources
total_count integer Number of items returned in each range of results. Note that the last results range could have fewer items than the requested number of items.
links array of links HATEOAS links related to this call.

event_type object

Contains the information for a Webhooks event-type

Property Type Description
name string Unique event-type name. Required.
description string Human readable description of the event-type Assigned in response.

webhook object

Represents Webhook resource.

Property Type Description
id string Identifier of the webhook resource. Assigned in response.
url string Webhook notification endpoint url. Required.
event_types array of event_type List of Webhooks event-types. Required.
links array of links HATEOAS links related to this call.

event object

Represents a Webhooks event

Property Type Description
id string Identifier of the Webhooks event resource. Assigned in response.
create_time string Time the resource was created. Assigned in response.
resource_type string Name of the resource contained in the resource property. Assigned in response.
event_type string Name of the event type that occurred on the resource to trigger the Webhooks event. Assigned in response.
summary string A summary description of the event. For example: A successful payment authorization was created. Assigned in response.
resource object This contains the resource that is identified by the resource_type property. Assigned in response.
links array of links HATEOAS links related to this call.

error_type object

Contains information to classify the kind of error happened in the system

Property Type Description
id string Uniquely identify each Webhooks error-type resource Assigned in response.
name string Unique error-type name. Required.
description string Human readable description of the error-type Assigned in response.

error object

Represents a Webhooks Error

Property Type Description
id string Identifier of the Webhooks error resource. Assigned in response.
create_time string Time the resource was created. Assigned in response.
error_type string error that resulted in creation of this resource Required.
client_id string client_id for which this error occured Required.
event_name string name of the event that is being processed Required.
resource_identifier string Resource identifier for the resource that should be posted to webhooks endpoint
resource_type string The type of the resource pointed to by resource_identifier e.g. authorization, capture, notification, etc.
resource object Most appropriate resource that is available in the context of the error.
resource_url string url from which aforementioned resource can be retrieved
webhook_ids array of string list of webhook id’s that you are trying to post when this error happened
debug_id string correlation id that resulted in this error Required.
description string Detailed description why this error has happened/stack trace of the exception Required.
error_message string Error message providing description of error Required.
status string status of the error. Acceptable status at this point are OPEN and RESOLVED. Default is OPEN Allowed values: OPEN, RESOLVED
links array of links HATEOAS links related to this call.

patch_request object

Request object used for a JSON Patch.

Property Type Description
op string The operation to perform. Required. Allowed values: add, remove, replace, move, copy, test
path string String containing a JSON Pointer value that references a location within the target document where the operation is performed.
value One of the following:
number,
integer,
string,
boolean,
null,
array,
object
New value to apply based on the operation. op=remove does not require value.
from string A string containing a JSON Pointer value that references the location in the target document from which to move the value. Required for use where op=move.

simulate_event object

Contains the information for a Webhooks simulator resource

Property Type Description
webhook_id string Webhook ID. If the webhook ID is not provided, the URL is required.
url string Webhook endpoint URL. If the URL is not provided, the webhook ID is required.
event_type string Event-type name. Specify any of the subscribed event types. Provide only one event type for each request. Required.

http_status_report object

Status Report for a transmission to an HTTP Endpoint

Property Type Description
transmission_type object Discriminator Allowed values: http
address string The HTTP URL being targettted
http_status integer The Http Status Code
reason_phrase string The HTTP reason string if available
response_headers object A set of HTTP headers represented as key/value pairs
transmission_id string The Identifier for the tranmission
status definitions_deliverystatus The enumerated list of possible delivery statuses Allowed values: SENT, DELIVERED, OPENED, FAIL_HARD, FAIL_SOFT, EXPIRED_BEFORE_DELIVERY
status_timestamp string The time at which the status occured
classifiers classifiers Allows a client to tag requests for future retrieval

definitions_deliverystatus object

The enumerated list of possible delivery statuses

Allowed values: SENT, DELIVERED, OPENED, FAIL_HARD, FAIL_SOFT, EXPIRED_BEFORE_DELIVERY

classifiers object

Allows a client to tag requests for future retrieval

Property Type Description
tags array of string A set of simple tags
pairs object A set of regular JSON style properties and values

Errors

PayPal uses standard HTTP status codes when returning errors. Additionally, we provide details about errors in the body of the response in the following format:

{
  "name": "{ERROR NAME}",
  "message": "{Error description}",
  "information_link": "{Link to error documentation}",
  "details": "[Additional details about the error]"
}

Payments Errors

The following is a list of errors related to Payments. We provide corrective action where available.

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

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 that cannot be voided, such as captured or expired.

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_VOIDED

Authorization has been voided

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 3-day honor period is over.

CAPTURE_AMOUNT_LIMIT_EXCEEDED

Capture amount specified exceeded allowable limit

CARD_TOKEN_PAYER_MISMATCH

payer_id does not match id for this token

The payer_id must match the one that was provided when storing the credit card.

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 using another credit card.

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.

DATA_RETRIEVAL

Error retrieving data

There was a problem getting data. Resend the request. If this error continues, contact PayPal Merchant Technical Support.

DUPLICATE_REQUEST_ID

The value of PayPal-Request-Id header has already been used

Resend the request using a unique PayPal-Request-Id.

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 using the /vault API.

FEATURE_UNSUPPORTED_FOR_PAYEE

Feature is unsupported for Payee, please contact Paypal customer support

Feature is unsupported for Payee, please contact Paypal customer support.

FULL_REFUND_NOT_ALLOWED_AFTER_PARTIAL_REFUND

Full refund refused - partial refund has already been done on this payment

You can’t refund the full payment amount after you have partially refunded a payment.

IMMEDIATE_PAY_NOT_SUPPORTED

Immediate pay is not supported for the Intent passed

Immediate pay is not supported for the Intent passed.

INSTRUMENT_DECLINED

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

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

INSUFFICIENT_FUNDS

Buyer cannot pay - insufficient funds.

Buyer needs to add a valid funding instrument (e.g. 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 continues, contact PayPal Merchant Technical Support.

INVALID_ACCOUNT_NUMBER

Account number does not exist

Provide a valid account number and resend the request.

INVALID_ARGUMENT

Transaction refused because of an invalid argument

An invalid argument has been passed in this request.

INVALID_CITY_STATE_ZIP

Invalid state city zip combination

Invalid state city zip combination.

INVALID_EXPERIENCE_PROFILE_ID

The requested experience profile ID was not found

The requested experience profile ID was not found.

INVALID_FACILITATOR_CONFIGURATION

This transaction cannot be processed due to an invalid facilitator configuration.

You must have the right account configuration to process this kind of transaction.

INVALID_PAYER_ID

Payer ID is invalid

The provided payer_id is invalid. Resend the request using a valid payer_id.

INVALID_RESOURCE_ID

The requested resource ID was not found

Provide a valid resource ID and resent the request.

PAYEE_ACCOUNT_INVALID

payee account does not have a confirmed email

payee account does not have a confirmed email.

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.

PAYER_ACCOUNT_LOCKED_OR_CLOSED

Payer account is locked or closed

Payer account is locked or closed.

PAYER_ACCOUNT_RESTRICTED

Refused - payer account is restricted

Payer account is restricted.

PAYER_CANNOT_PAY

Payer cannot pay for this transaction with Paypal

Payer cannot pay for this transaction with Paypal.

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_APPROVAL_EXPIRED

Payment approval has expired

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

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_NOT_APPROVED_FOR_EXECUTION

Payer has not approved payment

All payments that use the PayPal payment method must first be approved by the payer.

PAYMENT_REQUEST_ID_INVALID

Paypal request id is invalid. Please try a different one

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 don’t have the proper permissions to perform this request.

REFUND_EXCEEDED_TRANSACTION_AMOUNT

Refund refused - the requested refund amount would exceed the amount of transaction being refunded

REFUND_TIME_LIMIT_EXCEEDED

This transaction is too old to refund

Read more about refund time limits. After the time limit expires, you will need to send a payment instead of issuing a refund.

REQUIRED_SCOPE_MISSING

Access token does not have required scope.

Obtain user consent using the correct scope required for this type of request.

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 amount sent must be within PayPal transaction limits.

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
  • Because a complaint case exists on this transaction, only a refund of the full or full remaining amount of the transaction can be issued
  • You are over the time limit to perform a refund on this transaction
  • Cannot do a full refund after a partial refund
  • This transaction has already been 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_BY_PAYPAL_RISK

This transaction has been refused by PayPal risk

This transaction has been refused by PayPal risk.

TRANSACTION_REFUSED_PAYEE_PREFERENCE

Merchant profile preference is set to automatically deny certain transactions

The merchant account preferences are set to deny this particular kind of transaction.

UNKNOWN_ERROR

An unknown error has occurred

An unknown error has occurred.

UNSUPPORTED_PAYEE_COUNTRY

Payee country is unsupported

Payee country is unsupported.

VALIDATION_ERROR

Invalid request - see details

There was a validation issue with your request - see details

ORDER_ALREADY_COMPLETED

Order has already been voided, expired or completed

MAXIMUM_ALLOWED_AUTHORIZATION_REACHED_FOR_ORDER

** Maximum number of allowed authorizations for the order is reached. **

ORDER_VOIDED

Order has been voided

ORDER_CANNOT_BE_VOIDED

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


Billing Plans Errors

The following is a list of errors related to Billing Plans. We provide corrective action where available.

INTERNAL_SERVICE_ERROR

An internal service error has occurred

Resend the request at another time. If this error continues, contact PayPal Merchant Technical Support.

VALIDATION_ERROR

Invalid request - see details

There was a validation issue with your request - see details

REQUIRED_SCOPE_MISSING

Access token does not have required scope.

Obtain user consent using the correct scope required for this type of request.

UNAUTHORIZED_ACCESS

You don’t have permission to access this resource.

Please pass a valid plan id.


Billing Agreements Errors

The following is a list of errors related to Billing Agreements. We provide corrective action where available.

INTERNAL_SERVICE_ERROR

An internal service error has occurred

Resend the request at another time. If this error continues, contact PayPal Merchant Technical Support.

SUBSCRIPTION_UNMAPPED_ERROR

Some unmapped business/ internal error has occurred

Some unmapped business/ internal error has occurred. Please look into message details for resolution.

ADDRESS_INVALID

Provided user address is invalid

Provided user address is invalid.

DUPLICATE_REQUEST_ID

The value of PayPal-Request-Id header has already been used

Resend the request using a unique PayPal-Request-Id.

VALIDATION_ERROR

Invalid request - see details

There was a validation issue with your request - see details

REQUIRED_SCOPE_MISSING

Access token does not have required scope.

Obtain user consent using the correct scope required for this type of request.

UNAUTHORIZED_AGREEMENT_REQUEST

You don’t have permission to create such agreement.

Obtain the permission to create agreement in one shot.

MERCHANT_COUNTRY_NOT_SUPPORTED

The merchant’s country is currently not supported

Merchant country not supported.

FEATURE_NOT_AVAILABLE

Recurring payments feature is not currently available; try again later

Recurring payments feature is not currently available; try again later.

INVALID_ARGS

Invalid argument; description field or custom field is empty and the status is active

Pass correct arguments in description field and make sure status is active.

WALLET_TOO_MANY_ATTEMPTS

You have exceeded the maximum number of payment attempts for this token.

Please create a new token and create agreement using that.

USR_BILLING_AGRMNT_NOT_ACTIVE

This transaction cannot be processed due to an invalid merchant configuration.

Occurs when the billing agreement is disabled or inactive.

ACCOUNT_RESTRICTED

This transaction cannot be processed. Please contact PayPal Customer Service.

Transaction cannot be processed. Please contact PayPal Customer Service.

INVALID_CC_NUMBER

This transaction cannot be processed. Please enter a valid credit card number and type.

Please enter a valid credit card number and type.

FEATURE_DISABLED

This transaction cannot be processed.

This feature is disabled for now.

CC_TYPE_NOT_SUPPORTED

The credit card type is not supported

Please use another type of credit card.

SHP_INVALID_COUNTRY_CODE

This transaction cannot be processed. Please enter a valid country code in the shipping address.

Please enter a valid country code in the shipping address.

MISSING_CVV2

This transaction cannot be processed without a Credit Card Verification number

Please enter cvv2 for credit-card.

INVALID_CURRENCY

This transaction cannot be processed due to an unsupported currency.

This currency is not supported right now.

BUSADD_STATE_UNSUPPORTED

This transaction cannot be processed. The country listed for your business address is not currently supported.

The country listed for your business address is not currently supported.

INVALID_TOKEN

The token is missing or is invalid

Please use a valid token.

INVALID_AMOUNT

Bill amount must be greater than 0

Please pass valid amount.

INVALID_PROFILE_STATUS

The profile status must be one of (A)ctive, (C)ancelled, or e(X)pired

Please enter valid profile status.

PAYER_ACCOUNT_DENIED

Payer’s account is denied

Payer’s account is denied.

PAYER_COUNTRY_NOT_SUPPORTED

The payer’s country is currently not supported

The payer’s country is currently not supported.

MERCHANT_ACCOUNT_DENIED

Merchant account is denied

Merchant account is denied.

CANNOT_MIX_CURRENCIES

Invalid currency code, all currency codes much match

Please use same currency for all the amount objects.

START_DATE_INVALID_FORMAT

Subscription start date should be valid

Please pass a valid start date.

INVALID_PROFILE_ID

The profile ID is invalid

Please provide a valid agreement ID.

INVALID_PROFILE_ACTION

Invalid action value provided

Please provide a valid action value.

INVALID_STATUS_TO_CANCEL

Invalid profile status for suspend action; profile should be active

Agreement should be active before suspending it.

INVALID_STATUS_TO_SUSPEND

Invalid profile status for reactivate action; profile should be suspended

Agreement should be suspended to perform this action.

INVALID_STATUS_TO_REACTIVATE

The activation type is invalid.

Please pass a valid activate type.

BILL_AMOUNT_GREATER_THAN_OUTSTANDING_BALANCE

Bill amount is greater than outstanding balance

Bill amount should be less than outstanding balance.

OUTSTANDING_PAYMENT_ALREADY_SCHEDULED

Another outstanding payment is scheduled

Another outstanding payment is scheduled

RECURRING_PAYMENT_SCHEDULED_WITHIN_24HOURS

Recurring payment scheduled within 24 hours, so we are not processing the bill outstanding amoun

Recurring payment scheduled within 24 hours, so we are not processing the bill outstanding amount.

CALL_FAILED_PAYMENT

Payment is failing

Payment is failing.

CANNOT_FIND_PROFILE_DESC

Profile description is invalid.

Please provide a valid description of agreement.

DPRP_DISABLED

DPRP is disabled for this merchant.

Please enable dprp for creating such agreement.

GATEWAY_DECLINE_CVV2

This transaction cannot be processed. Please enter a valid Credit Card Verification Number.

Please use a valid credit card.

PROCESSOR_DECLINE_INVALID_CC_COUNTRY

This credit card was issued from an unsupported country.

This credit card was issued from an unsupported country.

SHIPPING_ADDRESS_NOT_IN_RESIDENCE_COUNTRY

This transaction cannot be processed. The shipping country is not allowed by the buyer’s country of residence.

The shipping country is not allowed by the buyer’s country of residence.

CANT_INCREASE_OUTSTANDING_AMOUNT

Cannot increase delinquent amount

Bill outstanding amount cannot be increased.

TIME_TO_UPDATE_CLOSE_TO_BILLING_DATE

The time of the update is too close to the billing date

The time of the update is too close to the billing date.

SET_BALANCE_INVALID_CURRENCY_CODE

Invalid currency for delinquent amount

Please pass valid currency in bill-balance call.

STATUS_INVALID

Invalid profile status for reactivate action; profile should be suspended

Please pass valid status for agreement state change.

INTERNAL_ERROR

Internal Error

Resend the request at another time. If this error continues, contact PayPal Merchant Technical Support.

CC_STATUS_INVALID

Profile is not active

Profile is not in active state.


Payouts Errors

The following is a list of payouts errors related to the REST API.

VALIDATION_ERROR

Invalid request - see details.

INTERNAL_ERROR

An internal service error has occurred.

AUTHORIZATION_ERROR

Authorization error occurred

USER_BUSINESS_ERROR

User business error.

MALFORMED_REQUEST_ERROR

Json request malformed.

INVALID_RESOURCE_ID

The requested resource ID was not found.

REQUIRED_SCOPE_MISSING

Access token does not have required scope.

ITEM_INCORRECT_STATUS

Only items in Unclaimed status can be cancelled.

BATCH_NOT_COMPLETED

Only item belonging to a batch in Processed status can be cancelled.

ITEM_ALREADY_CANCELLED

Requested item is already cancelled.

ITEM_CANCELLATION_FAILED

Cancel request for the item failed due to internal error.

DUPLICATE_ITEM

REF_ID matches with another item in the batch

RISK_DECLINE

Transaction was declined

CURRENCY_NOT_SUPPORTED_FOR_RECEIVER

Transaction currency cannot be received by the recipient

TRANSACTION_LIMIT_EXCEEDED

Per-transaction sending limit exceeded

RECEIVER_ACCOUNT_INVALID

Receiver’s account is invalid

ZERO_AMOUNT

Zero amount

RECEIVING_LIMIT_EXCEEDED

Receiving limit exceeded

NEGATIVE_BALANCE

Negative balance

RECEIVER_YOUTH_ACCOUNT

Youth account recipient

RECEIVER_UNCONFIRMED

This error indicates that the receiver’s email is unconfirmed. Any payment made to this account will show up as UNCLAIMED until the receiver’s account is confirmed

RECEIVER_UNREGISTERED

Receiver is unregistered

REGULATORY_BLOCKED

Regulatory review - Blocked

REGULATORY_PENDING

Regulatory review - Pending

POS_LIMIT_EXCEEDED

POS cumulative sending limit exceeded

SPENDING_LIMIT_EXCEEDED

Spending limit exceeded

RECEIVER_ACCOUNT_LOCKED

The receiver’s account is locked or inactive. Any payment made to the account will show up as FAILED

ACCOUNT_RESTRICTED

User is restricted

INVALID_CURRENCY

Invalid currency

CLOSED_MARKET

Market closed and transaction is between 2 different countries

SENDER_STATE_RESTRICTED

Sender’s address is located in a restricted State (e.g., California)

RECEIVER_STATE_RESTRICTED

Receiver’s address is located in a restricted State (e.g., California)

CURRENCY_COMPLIANCE

Currency compliance

SENDER_ACCOUNT_LOCKED

Sender’s account is locked or inactive

SELF_PAY_NOT_ALLOWED

Cannot pay self

USER_COUNTRY_NOT_ALLOWED

User’s country is not allowed

RECEIVER_COUNTRY_NOT_ALLOWED

Receiver’s address is in a non-receivable country or a PayPal zero country

INSUFFICIENT_FUNDS

Sender has insufficient funds

USER_FUNDING_SOURCE_INELIGIBLE

User’s credit card is not in the list of allowed countries of the gaming merchant

THIRD_PARTY_CALLS_FORBIDDEN

A third-party access token cannot be used for this operation

UNDEFINED

Unknown error

Vault Errors

The following is a list of errors related to Vault. We provide corrective action where available.

INTERNAL_SERVICE_ERROR

An internal service error has occurred

EXPIRED_CREDIT_CARD

Credit card is expired

INVALID_RESOURCE_ID

The requested resource ID was not found

DUPLICATE_REQUEST_ID

The value of PayPal-Request-Id header has already been used

PERMISSION_DENIED

No permission for the requested operation

VALIDATION_ERROR

Invalid request - see details

DATA_RETRIEVAL

Error retrieving data


Invoicing Errors

The following is a list of errors related to Invoicing. We provide corrective action where available.

VALIDATION_ERROR

Invalid request - see details.

One or more validation errors have occured. Please refer the details for specific validation errors.

MALFORMED_REQUEST_ERROR

Json request malformed.

The Json request is malformed. Please check the request and resend the request.

INTERNAL_SERVICE_ERROR

An internal service error has occurred.

Resend the request at another time. If this error continues, contact PayPal Merchant Technical Support.

USER_BUSINESS_ERROR

User business error.

User business error occured. Please refer the message for a brief description of the error.

UNKNOWN_ERROR

Unknown exception occurred.

An unknown error occured. If this error continues, contact PayPal Merchant Technical Support.

AUTHORIZATION_ERROR

Authorization error occurred.

Authorization error occured. Please check your credentials.

BUSINESS_ERROR

Invoicing business error.

An invoicing business error occured. Please refer the message for a brief description of the error.

RESOURCE_NOT_FOUND_ERROR

Resource not found.

The resource requested is not found in the system.



Validation Issues

The following is a list of validation errors related to the REST API.

Required field missing

Ensure that all required fields are present and resend the request.

Must not be blank

Ensure that fields send in the request are not empty.

Value is invalid (must be visa, mastercard, amex, or discover)

Provide an acceptable card type and resend the request.

Value is invalid (must be credit_card or paypal)

Ensure that the payment_method is either credit_card or paypal.

Value is invalid (must be sale, authorize, or order)

Ensure that the intent is set to sale, authorize, or order.

Value is invalid (must be payer or payee)

Country code must be 2-character ISO 3166-1 value (upper case)

Provide a valid country code in the request in the request.

Currency code must be 3-character ISO 4217 value (upper case)

Provide a valid currency code in the request.

Must be a positive integer

Negative numbers cannot be used for this request.

Value is invalid

Provide a valid value for the request.

This field name is not defined for this resource type

Ensure that all field names in the request are correct.

Email format must be username@domain.com

Ensure that all email addresses in the request use the proper format.

Invalid URL. After ‘protocol://’ in the URL, the valid characters allowed are alphanumericals, ‘.’, and ‘-‘

Provide a valid URL in the request.

Currency amount must be non-negative number, may optionally contain exactly 2 decimal places separated by ‘.’, optional thousands separator ‘,’, limited to 7 digits before the decimal point

Provide a valid currency amount.

Phone number must be in this format: optional leading ‘+’ followed by [0-9], spaces, hyphens, periods, and matching parentheses (not nested)

Provide a valid phone number.

Must start with a letter and contain only letters, hyphens, commas and spaces

Ensure the format of the field, such as a first or last name, is valid.

Must be numeric (YYYY)

Provide the year in a valid format.

Must be numeric

Provide a number in the request.

Must be alphanumeric

Must contain only these characters: a-z, A-Z, 0-9, punctuation(.,#-‘), and embedded spaces

Provide a value that only contains allowable characters.

Must contain only alphanumeric, space, and hyphen characters

Ensure all characters in the field, such as the name, are valid.

Invalid expiration (cannot be in the past)

Provide a valid expiration date for the credit card that occurs in the future.

Value out of range (1-12)

Provide a month that is between 1 (January) through 12 (December).

Value too long (max length 10)

Provide a value that is 10 characters or less.

Value too long (max length 20)

Provide a value that is 20 characters or less.

Value too long (max length 25)

Provide a value that is 25 characters or less.

Value too long (max length 40)

Provide a value that is 40 characters or less.

Value too long (max length 50)

Provide a value that is 50 characters or less.

Value too long (max length 64)

The value for the provided field cannot be longer than 65 characters.

Value too long (max length 100)

Provide a value that is 100 characters or less.

Value too long (max length 127)

Provide a value that is 127 characters or less.

Length is invalid (must be 3 or 4, depending on card type)

Provide a valid CVV.

Value is not supported at this time

You’ve provided a value that we don’t currently support.

This field is not defined for this resource type

You’ve provided a field this isn’t part of this resource type.

Specification of payee by email is not currently supported

You can’t currently use an email to indicate the payee.

Specification of payee by phone is not currently supported

You can’t currently use a phone number to indicate the payee.

Specification of payee other than the API caller is not currently supported

You must currently use a payer other than the API caller.

Only the payment intent value of sale, authorize, or order is currently supported

You can only use sale, authorize, or order as the intent.

Transaction amount details (subtotal, tax, shipping) must add up to specified amount total

Provide amount details that add up to the amount total.

Item amount must add up to specified amount subtotal (or total if amount details not specified)

Ensure that the total amount of all items match the total or subtotal.

Item currency code should be same as the transaction currency code

Ensure that currency code use for the item matches the transaction currency code.

The credit card number is not valid for the specified credit card type

Provide a credit card that matches the credit card type.

The cvv2 length is invalid for the specified credit card type

Provide a CVV2 length that matches the specified credit card type.

The refund amount cannot be zero

Provide a positive refund amount.

The amount object in this resource type must not include amount details

You should not provide an amount object in this resource type.

Must be a non-negative integer

Provide a positive integer.

Must be a date_time string of form yyyy-mm-ddThh:mm:ss(.sss)?Z

Provide a properly formatted date_time.

The date_time, although formatted properly, does not represent a valid date_time

Provide a date_time that is valid.

Invalid to specify both start_id and start_index query params

Provide either start_id or start_index, but not both.

The specified country requires a postal code

Provide a postal code for the provided address.

This field required when payment_method is ‘paypal’

Provide the required field for this PayPal payment.

This field invalid when payment_method is ‘credit_card’

Provide the required field for this credit card payment.

This field currently not supported in this request

Exclude the unsupported field and resend the request.

Not valid to specify this field in a request

This field is only provided as part of a response and cannot be included in a request.

Only single payment transaction currently supported

You can only provide one transaction per request.

Only single funding instrument currently supported

You can only provide one funding instrument per request.

Invalid value

The value for this field must be a valid integer.

Amount cannot be zero

Provide an amount that is not zero (0).

Fraction digits are not allowed with this currency

Fractional digits are not allowed with the currently passed currency.

Value is invalid (must be BBAN or IBAN)

Not valid to specify this field in a request

Value exceeds allowed maximum length

Minimum age limit not met

Field is mandatory. Limit of 127 characters.

Field is mandatory. Limit of 127 characters.

Payment definitions are invalid. Valid parameters are REGULAR or combination of TRIAL and REGULAR.

Template type is either null or invalid. Valid parameters are UNLIMITED or FIXED

Invalid Page size, valid value is positive number less than 21.

Amount passed in regular payment definition should be more than zero.

Currency object of payment definition can’t be null.

Invalid Total required, valid value are yes or no.

Merchant preferences are mandatory.

Field is mandatory. Limit of 127 characters.

Payment Definition type passed is either null/invalid. Valid values are TRIAL or REGULAR.

Payment Definition Frequency type passed is either null/invalid. Valid values are DAY, WEEK, MONTH or YEAR.

Payment Definition Frequency count should be positive numeric

Number of Cycles should be positive numeric and less than 10000

Amount should a positive number greater than 0 with a maximum of 2 decimal places separated by ‘.’, optional thousands separator ‘,’, limited to 7 digits before the decimal point

Charge Models within a payment definition should have distinct ‘Types’.

Amount cannot be blank

Charge Model type is invalid or null. Valid parameters are SHIPPING or TAX

Charge Model amount should be non-negative number with a maximum of 2 decimal places separated by ‘.’, optional thousands separator ‘,’, limited to 7 digits before the decimal point

Charge Model id should not be null or blank

invalid autobill_amount type. Can be yes or no

Invalid init amount action. Valid values are CANCEL, CONTINUE

Sort order is invalid, valid values are asc / desc

Invalid status, valid values are CREATED, ACTIVE, INACTIVE

Incorrect Template Id.

setup_fee is invalid/null.It should be positive number with max value 9999999.

Invalid autobill_amount type. Can be yes or no

Invalid fail_initamt_action. Can be continue or cancel.

max_fail_attempts is invalid/null.It should be positive integer with max value 999.

Missing/Invalid URL entered.Max length is 2048

All amounts with in a plan should have same currency

Invalid Charge Model Id.

Invalid payment def Id.

If payment definition type is REGULAR, no_of_cycles can only be null or 0 for an UNLIMITED plan

no_of_cycles can’t be null or 0 for a FIXED plan.

For TRIAL payment definition, number of cycles can’t be null or 0.

You can’t create template with only TRIAL as payment definition.

You can’t activate an active template.

Invalid template Id.

You can’t deactivate an inactive template.

Updation of a template only allowed in CREATED state.

Remove operation not supported now.

Add operation not supported now.

Invalid Operation nome. Can be add, remove or replace.

Invalid Path provided.

patch is not supported for this field.

Invalid state entered.Valid values are created/deleted/inactive/active.

Requested state change is invalid.

Plan already in same state.

Frequency more than year is not supported

Plan not in active state.

Override Charge Models provided should have different charge_ids

Amount should be non-negative number with a maximum of 2 decimal places separated by ‘.’, optional thousands separator ‘,’, limited to 7 digits before the decimal point

Note is missing from the request or Note length is too long.

Invalid Payment Method provided. Valid values are PAYPAL, CREDIT_CARD

No Funding Instruments need to be passed for payment method as PayPal.

Funding Instrument Details are missing or Funding instrument not supported. Only credit-card is supported.

All amounts with in a agreement should have same currency.

Invalid Payment Token.

start_date and end_date cannot be null.

end_date should be after start_date.

HTTP Status Codes

200 - Request OK
201 - Resource created
401 - Unauthorized request
402 - Failed request
403 - Forbidden
404 - Resource was not found
405 - Method not allowed
415 - Unsupported media type
422 - Unprocessable entity
429 - Too many requests
50x - PayPal server error