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

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

  • Visual Studio 2008 or higher
  • log4net 1.2.10
  • NuGet 2.2

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

To install the C# SDK as a dependency in your project, please run the following nuget command.

nuget install PayPalRestApiSDK -version 0.5.0

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

API endpoints

The PayPal REST APIs are supported in the Sandbox environment for testing purposes. Use your Test credentials to generate an access token for making calls with the Sandbox endpoints. When you’re set to go live, get your credentials for the Live environment and generate a new access token that you can use with the Live endpoints.

The following URIs form the base for the endpoints in the supported environments:

  • Sandbox, base URI: https://api.sandbox.paypal.com
  • Live, base URI : https://api.paypal.com

A complete endpoint is formed by combining the REST verb with the full URI to the resource you are addressing.

For example, here is the endpoint you would use in a request to to create a new payment:

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

To create a complete request, combine the endpoint with the appropriate HTTP headers and your JSON payload.

Endpoint Summary

Payments: create, execute, and look up payments

GET POST /v1/payments/payment
GET /v1/payments/payment/{paymentId}
POST /v1/payments/payment/{paymentId}/execute/

Sales: look up and refund completed payments

GET /v1/payments/sale/{transactionId}
POST /v1/payments/sale/{transactionId}/refund

Refunds: look up refund details

GET /v1/payments/refund/{refundId}

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

GET /v1/payments/authorization/{authorizationId}
POST /v1/payments/authorization/{authorizationId}/capture
POST /v1/payments/authorization/{authorizationId}/void
POST /v1/payments/authorization/{authorizationId}/reauthorize

Captures: look up and refund captured payments

GET /v1/payments/capture/{captureId}
POST /v1/payments/capture/{captureId}/refund

Vault: Store and look up credit cards

POST /v1/vault/credit-card
DELETE /v1/vault/credit-card/{creditCardId}
GET /v1/vault/credit-card/{creditCardId}

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

POST /v1/identity/openidconnect/tokenservice
GET /v1/identity/openidconnect/userinfo/?{schema}

Invoices: Create and work with invoices

GET POST /v1/invoicing/invoices
GET PUT DELETE /v1/invoicing/invoices/{invoiceId}
GET /v1/invoicing/invoices?{query-string}
POST /v1/invoicing/invoices/{invoiceId}/send
POST /v1/invoicing/invoices/{invoiceId}/remind
POST /v1/invoicing/invoices/{invoiceId}/cancel

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 {accessToken}) 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 .
   

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 clientId: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 "{clientId}:{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_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'));
OAuthTokenCredential tokenCredential =
  new OAuthTokenCredential("<CLIENT_ID>", "<CLIENT_SECRET>");
  
string accessToken = tokenCredential.GetAccessToken();

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 generated 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 generated 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 generated by PayPal.
expires_in integer The lifetime in seconds of the access token.
Value generated 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

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. This redirect URL should match the Return URL registered for your app on the Applications page of the developer site. The URL must at least match the scheme, hostname, and port.
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={clientId}
  &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={authorizationCode}

Paging & Filtering

The following filters can be used for paging and filtering results on GET calls that return multiple results. Currently, these filters apply to /v1/payments/payment.

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

Tip: You can combine filters to further refine results. Example: ?sort_order=asc&sort_by=update_time

Request Sample

curl -v -X GET https://api.sandbox.paypal.com/v1/payments/payment/?count=100 \
-H "Content-Type:application/json" \
-H "Authorization: Bearer {accessToken}"
@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

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

Endpoint

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. Additionally, you can authorize payments to be captured at a later time.

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

When creating a payment, set the intent (sale or authorize), 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 or authorize for a delayed payment to be captured at a later time. 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 {accessToken}" \
-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 or authorize for a delayed payment to be captured at a later time.
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 generated by PayPal.
create_time date_time Payment creation time as defined in RFC 3339 Section 5.6
Value generated by PayPal.
state string Payment state. Must be set to one of the one of the following: created; approved; failed; canceled; expired.
Value generated by PayPal.
update_time date_time Time the resource was last updated.
Value generated by PayPal.
links array of links objects HATEOAS links related to this call.
Value generated 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

Endpoint

POST /v1/payments/payment/{paymentId}/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/{paymentId}/execute/ \
-H "Content-Type:application/json" \
-H "Authorization: Bearer {accessToken}" \
-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 or authorize.
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 generated 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": {
              "total": "7.47",
              "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

Endpoint

GET /v1/payments/payment/{paymentId}

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/{paymentId} \
-H "Content-Type:application/json" \
-H "Authorization: Bearer {accessToken}"
@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 or authorize.
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. Required for PayPal payments.
id string ID of the created payment, the “transaction ID”.
Value generated by PayPal.
create_time date_time Payment creation time as defined in RFC 3339 Section 5.6.
Value generated by PayPal.
state enum payment state, one of the following: created, approved, failed, canceled, or expired.
Value generated by PayPal.
update_time date_time Time that the resource was last updated.
Value generated 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"
            },
            "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"
    }
  ]
}

List payment resources

Endpoint

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 {accessToken}"
@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 or authorize.
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 generated by PayPal.
create_time date_time Payment creation time as defined in RFC 3339 Section 5.6
Value generated by PayPal.
state string Payment state. One of the following: created; approved; failed; canceled; or expired.
Value generated by PayPal.
update_time date_time Time that the resource was last updated.
Value generated by PayPal.
links array of links objects HATEOAS links related to this call.
Value generated 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

Endpoint

GET /v1/payments/sale/{transactionId}

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/{transactionId} \
-H "Content-Type:application/json" \
-H "Authorization: Bearer {accessToken}"
@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 generated by PayPal.
state string State of the sale. One of the following: pending; completed; refunded; or partially_refunded.
Value generated by PayPal.
sale_id string ID of the sale transaction.
Value generated by PayPal.
parent_payment string ID of the payment resource on which this transaction is based.
Value generated by PayPal.
update_time date_time Time that the resource was last updated.
Value generated by PayPal.
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": {
    "total": "7.47",
    "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

Endpoint

POST /v1/payments/sale/{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/{transactionId}/refund \
-H 'Content-Type:application/json'  \
-H 'Authorization: Bearer {accessToken}' \
-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 generated by PayPal.
state string State of the refund. One of the following: pending; completed; or failed.
Value generated by PayPal.
sale_id string ID of the sale transaction.
Value generated by PayPal.
parent_payment string ID of the payment resource on which this transaction is based.
Value generated by PayPal.
update_time date_time Time that the resource was last updated.
Value generated by PayPal.
links array of links objects HATEOAS links related to this call.
Value generated 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"
  },
  "sale_id": "2MU78835H4515710F",
  "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

Endpoint

GET /v1/refund/{transactionId}

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/{transactionId} \
-H "Content-Type:application/json" \
-H "Authorization: Bearer {accessToken}"
@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 generated by PayPal.
state string State of the refund. One of the following: pending; completed; or failed.
Value generated by PayPal.
sale_id string ID of the sale transaction.
Value generated by PayPal.
parent_payment string ID of the payment resource on which this transaction is based.
Value generated by PayPal.
update_time date_time Time that the resource was last updated.
Value generated by PayPal.
links array of links objects HATEOAS links related to this call.
Value generated 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"
  },
  "sale_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

Endpoint

GET /v1/payments/authorization/{authorizationId}

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/{authorizationId} \
-H "Content-Type:application/json" \
-H "Authorization: Bearer {accessToken}"
@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.
create_time date_time Time of authorization as defined in RFC 3339 Section 5.6.
Value generated by PayPal.
update_time date_time Time that the resource was last updated.
Value generated by PayPal.
state enum State of the authorization. Either pending, authorized, captured, partially_captured, expired, or voided.
Value generated by PayPal.
parent_payment string ID of the payment resource on which this transaction is based.
Value generated by PayPal.
id string ID of the authorization transaction.
Value generated by PayPal.
valid_until date_time Authorization expiration time and date as defined in RFC 3339 Section 5.6.
Value generated by PayPal.
links array of links objects HATEOAS links related to this request.
Value generated 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

Endpoint

POST /v1/payments/authorization/{authorizationId}/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/{authorizationId}/capture \
-H "Content-Type:application/json" \
-H "Authorization: Bearer {accessToken}" \
-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 generated by PayPal.
update_time date_time Time that the resource was last updated.
Value generated by PayPal.
state enum State of the capture. Either pending, completed, refunded, or partially_refunded.
Value generated by PayPal.
parent_payment string ID of the payment resource on which this transaction is based.
Value generated by PayPal.
id string ID of the capture transaction.
Value generated by PayPal.
links array of links objects HATEOAS links related to this request.
Value generated 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

Endpoint

POST /v1/payments/authorization/{authorizationId}/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/{authorizationId}/void \
-H "Content-Type:application/json" \
-H "Authorization: Bearer {accessToken}"
@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 Authorized amount.
create_time date_time Time of authorization as defined in RFC 3339 Section 5.6.
Value generated by PayPal.
update_time date_time Time that the resource was last updated.
Value generated by PayPal.
state enum State of the authorization. When voiding, the returned value is normally set to voided.
Value generated by PayPal.
parent_payment string ID of the payment resource on which this transaction is based.
Value generated by PayPal.
id string ID of the authorization.
Value generated by PayPal.
valid_until date_time Authorization expiration time and date as defined in RFC 3339 Section 5.6.
Value generated by PayPal.
links array of links objects HATEOAS links related to this request.
Value generated 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

Endpoint

POST /v1/payments/authorization/{authorizationId}/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/{authorizationId}/reauthorize \
-H "Content-Type:application/json"  \
-H "Authorization: Bearer {accessToken}"  \
-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 generated by PayPal.
update_time date_time Time that the resource was last updated.
Value generated by PayPal.
state enum State of the authorization. Either pending or authorized.
Value generated by PayPal.
parent_payment string ID of the payment resource on which this transaction is based.
Value generated by PayPal.
id string ID of the authorization transaction.
Value generated by PayPal.
valid_until date_time Authorization expiration time and date as defined in RFC 3339 Section 5.6.
Value generated by PayPal.
links array of links objects HATEOAS links related to this request.
Value generated 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

Endpoint

GET /v1/payments/capture/{captureId}

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/{captureId} \
-H "Content-Type:application/json" \
-H "Authorization: Bearer {accessToken}"
@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 generated by PayPal.
update_time date_time Time that the resource was last updated.
Value generated by PayPal.
state enum State of the capture. Either pending, completed, refunded, or partially_refunded.
Value generated by PayPal.
parent_payment string ID of the payment resource on which this transaction is based.
Value generated by PayPal.
id string ID of the capture transaction.
Value generated by PayPal.
links array of links objects HATEOAS links related to this request.
Value generated 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",
  "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

Endpoint

POST /v1/payments/capture/{captureId}/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/{captureId}/refund  \
-H 'Content-Type:application/json'  \
-H 'Authorization: Bearer {accessToken}'  \
-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.
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 generated by PayPal.
state enum State of the refund. Either pending, completed, or failed.
Value generated by PayPal.
sale_id string ID of the sale transaction.
Value generated by PayPal.
parent_payment string ID of the payment resource on which this transaction is based.
Value generated by PayPal.
update_time date_time Time that the resource was last updated.
Value generated by PayPal.
links array of links objects HATEOAS links related to this call.
Value generated 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"
    }
  ]
}

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

Endpoint

POST /v1/vault/credit-card

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 a payer_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. Recommended when storing the credit card in vault.
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.
     

Request Sample

curl -v https://api.sandbox.paypal.com/v1/vault/credit-card \
-H 'Content-Type:application/json' \
-H 'Authorization: Bearer {accessToken}' \
-d '{
 "payer_id":"user12345",
 "type":"visa",
 "number":"4417119669820331",
 "expire_month":"11",
 "expire_year":"2018",
 "first_name":"Betsy",
 "last_name":"Buyer"
}'
@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 generated 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.
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.
state string State of the credit card funding instrument. Must be either expired or ok.
Value supplied by PayPal.
valid_until string Funding instrument expiration date.
Value supplied by PayPal.
links array of links objects HATEOAS links related to this call.
Value generated 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-card/CARD-1MD19612EW4364010KGFNJQI",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://api.sandbox.paypal.com/v1/vault/credit-card/CARD-1MD19612EW4364010KGFNJQI",
      "rel": "delete",
      "method": "DELETE"
    }
  ]
}

Delete a stored credit card

Endpoint

DELETE /v1/vault/credit-card/{creditCardId}

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 https://api.sandbox.paypal.com/v1/vault/credit-card/{creditCardId} \
-H "Content-Type:application/json" \
-H "Authorization: Bearer {accessToken}"
@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

Endpoint

GET /v1/vault/credit-card/{creditCardId}

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 https://api.sandbox.paypal.com/v1/vault/credit-card/{creditCardId} \
-H "Content-Type:application/json" \
-H "Authorization: Bearer {accessToken}"
@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.
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.
state string State of the credit card funding instrument. Either expired or ok.
Value generated by PayPal.
valid_until string Funding instrument expiration date.
Value generated by PayPal.
links array of links objects HATEOAS links related to this call.
Value generated 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-card/CARD-1MD19612EW4364010KGFNJQI",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://api.sandbox.paypal.com/v1/vault/credit-card/CARD-1MD19612EW4364010KGFNJQI",
      "rel": "delete",
      "method": "DELETE"
    }
  ]
}

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

Endpoint

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 Redirection endpoint that must match the one provided during the authorization request that ended in receiving the authorization code.
     

Request Sample

curl -v https://api.sandbox.paypal.com/v1/identity/openidconnect/tokenservice \
-u "{clientId}:{secret}" \
-d "grant_type=authorization_code
    &code={authorizationCode}
    &redirect_uri=http://example.com/myapp/return.php"

s

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": "{refreshToken}",
  "access_token": "{accessToken}"
}

Grant token from refresh token

Endpoint

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 "{clientId}:{secret}" \
-d "grant_type=refresh_token
    &refresh_token={refreshToken}"
@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

Endpoint

GET /v1/identity/openidconnect/userinfo/?{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 {accessToken}"
@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.

Property Type Description
user_id string Identifier for the end-user at the issuer.
sub 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.
middle_name string Middle name(s) of the end-user.
picture string URL of the End-User’s profile picture.
email string End-user’s preferred email address.
email_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

Endpoint

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.

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. For example, 2014-02-27 PST
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 {accessToken}' \
-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.

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. For example, 2014-02-27 PST
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.
payment_details array of payment_detail List of payment details for the invoice.
refund_details 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

Endpoint

POST /v1/invoicing/invoices/{invoiceId}/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/{invoiceId}/send' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {accessToken}'

Response

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

Update an invoice

Endpoint

PUT /v1/invoicing/invoices/{invoiceId}

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.

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. For example, 2014-02-27 PST
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/{invoiceId}' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {accessToken}' \
-d '{
  "id": "{invoiceId}",
  "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.

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. For example, 2014-02-27 PST
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.
payment_details array of payment_detail List of payment details for the invoice.
refund_details 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

Endpoint

GET /v1/invoicing/invoices/{invoiceId}

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/{invoiceId}' \
-H 'Authorization: Bearer {accessToken}'

Response

Returns an invoice object containing the specified invoice.

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. For example, 2014-02-27 PST
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.
payment_details array of payment_detail List of payment details for the invoice.
refund_details 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

Endpoint

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 {accessToken}'

Response

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

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. For example, 2014-02-27 PST
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.
payment_details array of payment_detail List of payment details for the invoice.
refund_details 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

Endpoint

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.

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.
end_invoice_date string End invoice date.
start_due_date string Start invoice due date.
end_due_date string End invoice due date.
start_payment_date string Start invoice payment date.
end_payment_date string End invoice payment date.
start_creation_date string Start invoice creation date.
end_creation_date string End invoice creation date.
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 {accessToken}' \
-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.

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. For example, 2014-02-27 PST
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.
payment_details array of payment_detail List of payment details for the invoice.
refund_details 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

Endpoint

POST /v1/invoicing/invoices/{invoiceId}/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.

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/{invoiceId}/remind' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {accessToken}' \
-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

Endpoint

POST /v1/invoicing/invoices/{invoiceId}/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.

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/{invoiceId}/cancel' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {accessToken} \'
-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

Endpoint

DELETE /v1/invoicing/invoices/{invoiceId}

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/{invoiceId}' \
-H 'Authorization: Bearer {accessToken}'

Response

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

Common Payments Objects

These are common objects used by payments resources.

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; set to sale or authorize. 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. Required for PayPal payments.
id string ID of the created payment
Value generated by PayPal.
create_time date_time Payment creation time as defined in RFC 3339 Section 5.6.
Value generated by PayPal.
state string Payment state. Must be one of the following: created; approved; failed; pending; canceled; or expired.
Value generated by PayPal.
update_time date_time Time that the resource was last updated.
Value generated by PayPal.
     

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.
     

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.

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.

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 generated 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 generated by PayPal.
expire_year integer 4-digit expiration year.
Value generated by PayPal.
expire_month integer Expiration month with no leading zero. Acceptable values are 1 through 12.
Value generated by PayPal.
     

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. Required when using a stored credit card if a payer_id was originally provided when storing the credit card in vault.
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 Billing address associated with card.
state string State of the credit card funding instrument: expired or ok.
Value generated by PayPal.
valid_until string Funding instrument expiration date.
Value generated 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.

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.
first_name string First name of the payer.
Value generated by PayPal.
last_name string Last name of the payer.
Value generated by PayPal.
payer_id string PayPal assigned Payer ID.
Value generated by PayPal.
phone string Phone number representing the payer. 20 characters max.
shipping_address shipping_address Shipping address of payer PayPal account.
Value generated by PayPal.

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.
     

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.
item_list item_list Items within a transaction.
related_resources array of sale, authorization, capture, or refund, objects Financial transactions related to a payment.

item_list object

This object provides a list of items and related shipping addresses 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.

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.

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 generated by PayPal.
state string State of the refund. One of the following: pending; completed; or failed.
Value generated by PayPal.
sale_id string ID of the sale transaction being refunded.
Value generated by PayPal.
parent_payment string ID of the payment resource on which this transaction is based.
Value generated by PayPal.
update_time date_time Time that the resource was last updated.
Value generated 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 generated by PayPal.
state string State of the sale. One of the following: pending; completed; refunded; or partially_refunded.
Value generated by PayPal.
sale_id string ID of the sale transaction being refunded.
Value generated by PayPal.
parent_payment string ID of the payment resource on which this transaction is based.
Value generated by PayPal.
update_time date_time Time that the resource was last updated.
Value generated by PayPal.
     

authorization object

This object defines 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 generated by PayPal.
update_time date_time Time that the resource was last updated.
Value generated by PayPal.
state enum State of the authorization. Either pending, authorized, captured, partially_captured, expired, or voided.
Value generated by PayPal.
parent_payment string ID of the payment resource on which this transaction is based.
Value generated by PayPal.
id string ID of the authorization transaction.
Value generated by PayPal.
valid_until date_time Authorization expiration time and date as defined in RFC 3339 Section 5.6.
Value generated by PayPal.
links array of links objects HATEOAS links related to this request.
Value generated 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 generated by PayPal.
update_time date_time Time that the resource was last updated.
Value generated by PayPal.
state enum State of the sale. Either pending, completed, refunded, or partially_refunded.
Value generated by PayPal.
parent_payment string ID of the payment resource on which this transaction is based.
Value generated by PayPal.
id string ID of the capture transaction.
Value generated by PayPal.
links array of links objects HATEOAS links related to this request.
Value generated by PayPal.
     

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.
     

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 Sub-total (amount) of items being paid for. 10 characters max with support for 2 decimal places.
tax string Amount charged for tax. 10 characters max with support for 2 decimal places.
fee string Fee charged by PayPal. In case of a refund, this is the fee amount refunded to the original recipient of the payment. 10 characters max.
Value generated by 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.
     

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.
sub 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.
middle_name string Middle name(s) of the End-User.
picture string URL of the End-User’s profile picture.
email string End-User’s preferred e-mail address.
email_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.

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. For example, 2014-02-27 PST
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.
payment_details array of payment_detail List of payment details for the invoice. Assigned in response.
refund_details 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.

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. For example, 2014-02-27 PST
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.
payment_details array of payment_detail List of payment details for the invoice. Assigned in response.
refund_details 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.

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. For example, 2014-02-27 PST.
discount cost Item discount in percent or amount.

merchant_info object

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

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

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.

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.

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. For example, 2014-02-27 PST

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.

percent number Cost in percent. Range of 0 to 100.
amount string ~

shipping_cost object

Shipping cost in percent or amount.

amount Currency Shipping cost in amount. Range of 0 to 999999.99.
tax tax Tax percentage on shipping amount.

tax object

Tax information.

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.

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.

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. For example, 2014-02-27 PST.
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.

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.
note string Optional note associated with the refund.

metadata object

Audit information of the resource.

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.

phone object

Representation of a phone number.

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.

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.

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.
end_invoice_date string End invoice date.
start_due_date string Start invoice due date.
end_due_date string End invoice due date.
start_payment_date string Start invoice payment date.
end_payment_date string End invoice payment date.
start_creation_date string Start invoice creation date.
end_creation_date string End invoice creation date.
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.

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.

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

Error List

The following is a list of errors related to the REST API. 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.

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.

INVALID_ACCOUNT_NUMBER

Account number does not exist

Provide a valid account number and resend the request.

INVALID_RESOURCE_ID

The requested resource ID was not found.

Provide a valid resource ID and resent the request.

DUPLICATE_REQUEST_ID

The value of PayPal-Request-Id header has already been used.

Resend the request using a unique PayPal-Request-Id.

TRANSACTION_LIMIT_EXCEEDED

Total payment amount exceeded transaction limit

The amount sent must be within PayPal transaction limits.

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.

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.

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.

CAPTURE_AMOUNT_LIMIT_EXCEEDED

Capture amount specified exceeded allowable limit.

AUTHORIZATION_ALREADY_COMPLETED

Capture refused - this authorization has already been completed.

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.

TOO_MANY_REAUTHORIZATIONS

Maximum number of reauthorizations for this authorization has been reached.

You can only reauthorize a payment once.

PERMISSION_DENIED

No permission for the requested operation.

You don’t have the proper permissions to perform this request.

AUTHORIZATION_VOIDED

Authorization has been voided

AUTHORIZATION_ID_DOES_NOT_EXIST

The requested authorization ID does not exist.

VALIDATION_ERROR

Invalid request - see details.

There was a validation issue with your request - see details.

CREDIT_CARD_REFUSED

Credit card was refused.

The credit card used for payment was refused. Resend the request using another 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.

PAYEE_ACCOUNT_RESTRICTED

Refused - payee account is restricted.

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

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.

INVALID_PAYER_ID

Payer ID is invalid

The provided payer_id is invalid. Resend the request using a valid payer_id.

PAYEE_ACCOUNT_LOCKED_OR_CLOSED

Payee account is locked or closed

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

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.

DATA_RETRIEVAL

Error retrieving data

There was a problem getting data. Resend the request. If this error continues, contact PayPal Merchant Technical Support.

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.

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.

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.

AMOUNT_MISMATCH

The totals of the cart item amounts do not match sale amounts

The amount total does not match the item amount totals.

CURRENCY_NOT_ALLOWED

Currency is not supported

You are using a currency that is not currently supported.

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.

AUTHORIZATION_EXPIRED

Authorization has expired

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

INVALID_ARGUMENT

Transaction refused because of an invalid argument

An invalid argument has been passed in this request.

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.

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.

AUTHORIZATION_CANNOT_BE_VOIDED

Authorization is in {0} 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.

UNSUPPORTED_SEPA_BANK

Bank is from a country outside Single Euro Payments Area.

BANK_MRN_MISMATCH

Bank and Mandate Reference Number mismatch

BANK_ACCOUNT_VALIDATION_FAILED

Bank account validation failed

SENDING_LIMIT_EXCEEDED

The transaction exceeds the buyer’s sending limit.

FAILED_TO_CHARGE_CC

Failed to charge credit card.

CANNOT_PAY_SELF

Payer cannot pay to himself/herself.

SELECTED_PLAN_NOT_AVAILABLE

Selected plan is not available.

NEED_CREDIT_CARD

Need Credit card to complete the payment.

NEED_CREDIT_CARD_OR_BANK_ACCOUNT

Need bank or credit card to complete the payment.

BUYER_NOT_SET

Buyer is not yet set for this purchase.

MALFORMED_REQUEST_ERROR

Json request malformed.

The Json request is malformed. Please check the request and resend the request.

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 or authorize)

Ensure that the intent is set to sale or authorize.

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

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 payment intent value sale is currently supported

You can only use sale 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

HTTP Status Codes

200 - Request OK
201 - Resource created
401 - Unauthorized request
402 - Failed request
403 - Forbidden
404 - Resource was not found
50x - PayPal server error