PayPal REST API Release Notes
- Updates for August 12, 2015
- Updates for July 29, 2015
- Updates for June 18, 2015
- Updates for May 19, 2015
- Updates for May 5, 2015
- Updates for April 23, 2015
- Updates for April 5, 2015
- Updates for March 25, 2015
- Updates for March 12, 2015
- Updates for February 26, 2015
- Updates for February 13, 2015
- Updates for January 29, 2015
- Updates for January 22, 2015
- Updates for December 17, 2014
- Updates for December 10, 2014
- Updates for December 3, 2014
- Updates for November 5, 2014
- Updates for October 23, 2014
- Updates for October 15, 2014
- Updates for October 1, 2014
- Updates for September 17, 2014
- Updates for August 13, 2014
- Updates for July 23, 2014
- Updates for July 7, 2014
- Updates for March 7, 2014
- Updates for July 30, 2013
- Updates for May 28, 2013
- Updates for May 22, 2013
- Updates for May 15, 2013
- Updates for April 24, 2013
Updates for August 12, 2015
This release contains the following updates.
API Changes
No changes.
New Features
No changes.
Documentation Update
Added information to the Create an agreement and Execute an agreement sections of the REST API Reference to explain that executing a billing agreement is only necessary when the agreement is for PayPal payment.
Updates for July 29, 2015
This release contains the following updates.
API Changes
No changes.
New Features
No changes.
Documentation Update
Added information to more clearly describe how to use an asterisk (*) as a wildcard to subscribe to all event types when you Create a webhook.
Updates for June 18, 2015
This release contains the following updates.
API Changes
No changes.
New Features
No changes.
Documentation Update
Updated the Webhooks overview page to include information about the asymmetric algorithm used for event signatures.
Updates for May 19, 2015
This release contains the following updates.
API Changes
No changes.
New Features
New features can include new resources, new fields, and other additions.
New Webhooks Event Types
Support for several new event types has been added, including:
PAYMENT.CAPTURE.COMPLETED: This event gets triggered when a capture is completed.PAYMENT.CAPTURE.PENDING: This event gets triggered when a capture goes into pending state.PAYMENT.SALE.PENDING: This event gets triggered when a sale goes into pending state.RISK.DISPUTE.CREATED: This event gets triggered when a dispute is created.
For more information, see the Webhooks Overview.
Documentation Updates
No changes.
Updates for May 5, 2015
This release contains the following updates.
API Changes
No changes.
New Features
No changes.
Documentation Updates
The following corrections were made to the REST API documentation:
- Changed the
filter_identifierproperty tofilter_idinfmf_detailsobject. - Removed the
pending_reasonproperty from the sale object. - Corrected the response for the Look up an authorization operation by adding the
reason_code,payment_mode, andfmf_detailsproperties.
The following updates have also been made to the REST API documentation:
- Noted event data generated by the webhooks simulator cannot be manipulated using other webhook API operations in the Wehooks overview and the introduction for the Simulate a webhook event operation.
- Added the authorization object
payment_modeandfmf_detailsproperties. - Added response information for List plans operation, noting that partial plan resources are returned.
Updates for April 23, 2015
This release contains the following updates.
API Changes
No changes.
New Feature
New features can include new resources, new fields, and other additions.
Wildcards for Webhook Events
Wildcard capability has been introduced for Webhook events. You can now subscribe to all event types by using an asterisk (*) as an event name in the event_types field. To learn more about this capability, see the Create a webhook section of the REST API Reference.
Documentation Update
Updated the webhooks sample code for obtaining a signature algorithm on the Webhooks integration overview page.
Updates for April 5, 2015
This release contains the following updates.
API Changes
| Method | Name | Type of Change |
|---|---|---|
POST |
v1/notifications/simulate-event/ |
New Endpoint |
New Features
New features can include new resources, new fields, and other additions.
Simulate a Webhook Event
Use this call to simulate a webhook event using a sample payload. For more information, see the REST API Reference.
Webhooks Simulator
The newly available Webhooks Simulator provides an interactive interface that enables you to test webhook URLs to verify that they are able to receive event data as expected, without firewall or other connectivity issues. For more information, see Webhooks Simulator.
Documentation Updates
The following updates were made to the REST API documentation:
- Added the possible values of the
statusproperty to the agreement_transaction object. - The description of the response for the Get user information operation has been updated to clarify that the attributes returned depend on the scopes configured for the user's REST app.
- Fixed the capture object to include the
transaction_feeproperty that was previously missing
Updates for March 25, 2015
This release contains the following updates.
API Changes
No changes.
New Features
No changes.
Documentation Update
Emphasized, in the Log In with PayPal Obtain user's consent and Grant token from authorization code sections of the REST API reference, the importance of passing a redirect_uri that matches the app's info provided in the application registration page of the developer site.
Updates for March 12, 2015
This release contains the following updates.
API Changes
| Method | Name | Type of Change |
|---|---|---|
GET |
/v1/vault/credit-cards |
New Endpoint |
| Name | Type of Change | Capability |
|---|---|---|
fmf_details within sale object |
New Property | Payments |
transaction_fee within sale object |
New Field | Payments |
receivable_amount within sale object |
New Property | Payments |
exchange_rate within sale object |
New Property | Payments |
receipt_id within sale object |
New Property | Payments |
salutation within payer_info object |
New Property | Payments |
suffix within payer_info object |
New Property | Payments |
middle_name within payer_info object |
New Property | Payments |
country_code within payer_info object |
New Property | Payments |
status within address object |
New Property | Payments |
in_progress possible value for state property |
New State | Payments |
fmf_details object |
New Object | Payments |
New Features
New features can include new resources, new fields, and other additions.
List Credit Cards
Added the List credit cards operation for the Vault API. Use this call to retrieve a list of credit card resources according to the parameters specified.
New Object
Added the fmf_details object to the Payments common objects.
New Properties
- Added the
fmf_details,transaction_fee,receivable_amount,exchange_rate, andreceipt_idproperties to sale object as part of Payments API enhancements. - Added the
salutation,suffix,middle_nameandcountry_codeproperties to the payer_info object as part of Payments API enhancements. - Added the
statusproperty to the address object as part of Payments API enhancements. - Added a possible state of
in progressto the state property for thepaymentobject as part of Payments API enhancements.
Documentation Updates
No changes.
Updates for February 26, 2015
This release contains the following updates.
API Changes
| Name | Type of Change | Capability |
|---|---|---|
fee within details object |
Removed | Payments |
New Features
New features can include new resources, new fields, and other additions.
Two new errors have been added to the Billing Agreements API:
Documentation Updates
The following updates have been made to the REST API documentation:
- Changed the C# SDK prerequisites and other requirements in the REST API reference to reflect current dependencies.
- Enhanced the description of the
amountproperty in theagreement_state_descriptorobject to clarify that this property is required to bill outstanding amounts, but not required when suspending, cancelling, or reactivating an agreement. - Corrected the listed properties for the billing agreement object to include the
stateandagreement_detailsproperties that were previously missing. - Enhanced the description of the
notify_urlproperty in the merchant_preferences object to clarify that this property is read-only and reserved for future use.
Updates for February 13, 2015
This release contains the following updates.
API Changes
No changes.
New Features
No changes.
Documentation Updates
The following updates have been made to the REST API documentation:
- Corrected the name of the
time_updatedproperty in the agreement_transaction object for the Billing Agreements API. This property was previously incorrectly namedtime_stampin the Rest API Reference. - Enhanced the description of the
item_listproperty in the Payments transaction object to clarify that this property includes the related shipping address for a transaction. - Corrected the response description for the Cancel an unclaimed payout item operation. If successful, this call returns a
payout_item_detailsobject with atransaction_statusof RETURNED, which was previously incorrectly documented as apayout_item_status.
Updates for January 22, 2015
This release contains the following updates.
API Changes
| Method | Name | Type of Change |
|---|---|---|
POST |
/v1/payments/payouts-item/<Payout-Item-Id>/cancel |
New Endpoint |
New Features
New features can include new resources, new fields, and other additions.
Cancel an unclaimed payout item
Use this call to cancel an existing, unclaimed transaction. If an unclaimed item is not claimed within 30 days, the funds will be automatically returned to the sender. This call can be used to cancel the unclaimed item prior to the automatic 30-day return.
For further information, see the REST API Reference.
Demo Portal
Added a link to the Demo Portal from the Payments Button page.
Updates for December 17, 2014
This release contains the following updates.
API Changes
| Method | Name | Type of Change |
|---|---|---|
POST |
/v1/vault/credit-cards |
Updated Endpoint |
DELETE GET PATCH |
/v1/vault/credit-cards/<Credit-Card-Id> |
Updated Endpoint |
New Features
New features can include new resources, new fields, and other additions.
Vault
Vault operations with credit-card in the endpoint are being deprecated in favor of credit-cards. Both are currently still valid at this time.
For further information, see the REST API Reference
HTTP error codes
Updated the list of standard HTTP error codes
Updates for December 10, 2014
This release contains the following updates.
API Changes
| Method | Name | Type of Change |
|---|---|---|
POST |
/v1/payments/payouts |
New Endpoint |
GET |
/v1/payments/payouts/<Payout-Batch-Id> |
New Endpoint |
GET |
/v1/payments/payouts-item/<Payout-Item-Id> |
New Endpoint |
New Features
New features can include new resources, new fields, and other additions.
Create and Manage Payouts
The Payments namespace now includes a Payouts Feature that enables you to send up to 500 disbursements in one API call to any email address or US mobile phone number. The Payout APIs let you easily send, track, and search for your previously made payouts.
For further information, see the REST API Reference
Updates for December 3, 2014
This release contains the following updates.
API Changes
No changes.
New Features
New features can include new resources, new fields, and other additions.
Web checkout guide
Revamped the Web checkout guide.
Authentication and headers
Added the PayPal-Client-Metadata-Id header in Authentication and headers, which replaces the Paypal-Application-Correlation-Id header. See Future Payments for details.
Updates for November 5, 2014
This release contains the following updates.
API Changes
No changes.
New Features
New features can include new resources, new fields, and other additions.
Event types
The following event types are now available for use with Webhooks:
- PAYMENT.SALE.REVERSED
- PAYMENT.CAPTURE.REVERSED
The following event type has been removed:
- PAYMENT.CAPTURE.COMPLETED
For further information, see the REST API Reference.
Updates for October 23, 2014
This release contains the following updates.
API Changes
| Method | Name | Type of Change |
|---|---|---|
PATCH |
/v1/payments/payment/<Payment-Id> |
New Method |
New Features
New features can include new resources, new fields, and other additions.
Update a payment resource
PATCH can now be used to update the shipping address and the transaction amount of a payment.
For further information, see the REST API Reference.
Updates for October 15, 2014
This release contains the following updates.
API Changes
| Method | Name | Type of Change |
|---|---|---|
GET |
/v1/payments/billing-plans?page_size=<page_size>&page=<page>&total_required=<total_required> |
Revised Pagination |
New Features
New features can include new resources, new fields, and other additions.
Pagination
The following can now be used for pagination when listing billing plans.
| Filter | Description |
|---|---|
page_size |
To indicate the maximum number of results to return at one time. The page_size is a non-negative, non-zero integer with a default value of 10. |
page |
To indicate the page to return. The default value is 0. |
total_required |
To indicate that the total number of items (total_items) and pages (total_pages) are expected to be returned in the response. |
For further information, see the REST API Reference.
Updates for October 1, 2014
This release contains the following updates.
API Changes
| Method | Name | Type of Change |
|---|---|---|
GET POST |
/v1/notifications/webhooks |
New Endpoint |
GET PATCH DELETE |
/v1/notifications/webhooks/<Webhook-Id> |
New Endpoint |
GET |
v1/notifications/webhooks/<Webhook-Id>/event-types |
New Endpoint |
GET |
/v1/notifications/webhooks-events |
New Endpoint |
GET |
/v1/notifications/webhooks-events/<Event-Id> |
New Endpoint |
POST |
/v1/notifications/webhooks-events/<Event-Id>/resend |
New Endpoint |
GET |
/v1/notifications/webhooks-event-types |
New Endpoint |
New Features
New features can include new resources, new fields, and other additions.
Create and Manage Webhooks
The Notification namespace contains resources for listing event types; creating, listing, updating, and deleting webhooks; and searching and resending events.
A webhook is a callback that occurs when something of interest happens. A web application providing support for webhooks will POST a message to a specified URL when certain triggers happen. For the merchant, a webhook provides a way to receive useful information about an event when it happens, rather than polling for it at random. For the resources available, see the REST API Reference.
Updates for September 17, 2014
This release contains the following updates.
API Changes
| Method | Name | Type of Change | Capability |
|---|---|---|---|
POST GET |
/v1/payment-experience/web-profiles |
New Endpoint | Experience |
GET PUT PATCH DELETE |
/v1/payment-experience/web-profiles/<id> |
New Endpoint | Experience |
New Features
New features can include new resources, new fields, and other additions.
Create and Manage Payment Experience Profiles
The REST Payment Experience API allows merchants to provide a customized experience to consumers from the merchant’s website to the PayPal payment. For the resources available, see the REST API Reference.
Updates for August 13, 2014
This release contains the following updates.
API Changes
| Name | Type of Change | Capability |
|---|---|---|
clearing_time within authorization, order, and sale objects |
New Field | Payments |
custom within transaction object |
New Field | Payments |
description within item object |
New Field | Payments |
handling_fee within details object |
New Field | Payments |
insurance within details object |
New Field | Payments |
invoice_number within transaction object |
New Field | Payments |
middle_name within userinfo object |
Removed Field | Payments |
payment_mode within sale object |
New Field | Payments |
pending_reason within sale object |
New Field | Payments |
protection_eligibility within authorization, order, and sale objects |
New Field | Payments |
protection_eligibility_type within authorization, order, and sale objects |
New Field | Payments |
reason_code within order and sale objects |
New Field | Payments |
shipping_discount within details object |
New Field | Payments |
soft_descriptor within transaction object |
New Field | Payments |
status within payer object |
New Field | Payments |
tax within item object |
New Field | Payments |
tax_id within payer_info object |
New Field | Payments |
tax_id_type within payer_info object |
New Field | Payments |
New Features
New features can include new resources, new fields, and other additions.
New Fields
The new fields allow for further capabilities in payment transactions.
For more information, see explore payment capabilities.
Updates for July 23, 2014
This release contains the following updates.
API Changes
| Method | Name | Type of Change | Capability |
|---|---|---|---|
GET POST |
/v1/payments/orders |
New Endpoint | Orders |
POST |
/v1/payments/payment |
New Property | Orders |
GET |
/v1/invoicing/invoices/<invoice-id>/qr-code?<Query-String> |
New Endpoint | Invoicing |
POST |
/v1/invoicing/invoices/<invoice-id>/<invoice-id>/record-payment |
New Endpoint | Invoicing |
POST |
/v1/invoicing/invoices/<invoice-id>/<invoice-id>/record-refund |
New Endpoint | Invoicing |
New Features
New features can include new resources, new fields, and other additions.
Manage Orders
The REST Orders API allows merchants to accept orders for items that may not yet be available for shipment. For the resources available, see the REST API Reference.
Additionally, the payment object properties have been updated. The intent can now be set to order, in addition to sale or authorize.
Get a QR Code for an Invoice
After you retrieve a QR code (image) for an invoice, it can be added to a paper or PDF invoice. When a customer uses their mobile device to scan the QR code, the customer is redirected to the PayPal mobile payment flow, where they can pay online with PayPal or a credit card.
For more information, see Retrieve a QR code.
Record a Payment
You can record a payment on an invoice (that is, mark an invoice as paid). For more information, see Record a payment. Planned functionality for the future includes the recording of multiple payments per invoice.
Record a Refund
You can record a refund related to an invoice (that is, mark an invoice as refunded). For more information, see Record a refund.
Updates for July 7, 2014
This release contains the following updates.
API Changes
| Method | Name | Type of Change | Capability |
|---|---|---|---|
POST |
/v1/payments/billing-plans |
New Endpoint | Subscriptions |
POST |
/v1/payments/billing-agreements |
New Endpoint | Subscriptions |
New Features
New features can include new resources, new fields, and other additions.
Create and Manage Subscriptions
The REST Subscription API billing plans allow automated recurring payments at regularly scheduled intervals. Billing agreements are contracts between a payer and a payee or between payer and facilitator to send payments according to a plan which consists of payment amount, billing cycle, number of billing cycles, etc. For the resources available, see the REST API Reference.
Updates for March 7, 2014
These release notes describe the changes to the PayPal REST API and related documentation.
Announcements
This section provides announcements related to the PayPal REST API.
None for this release.
API Changes
This section provides specific API changes for this release.
| Method | Name | Type of Change | Capability |
|---|---|---|---|
POST |
/v1/invoicing/ |
New Endpoint | Invoicing |
New Features
This section describes new features that have been added as of this release. New features can involve new capabilities, new resources, and/or new fields added to existing resources.
Create and Manage Invoices
The REST Invoicing API enables you to create, send, and manage invoices. For the resources available, see the REST API Reference.
Changed Functionality
Logical or functional changes that have been made to existing functionality, including new code list values and/or changes in validation rules.
None for this release.
Additional Documentation Updates
This section lists additional documentation changes and corrections that were made with this release and that are not already mentioned in New Features or Changed Functionality.
None for this release.
Updates for July 30, 2013
These release notes describe the changes to the PayPal REST API and related documentation.
Announcements
This section provides announcements related to the PayPal REST API.
No announcements.
API Changes
This section provides specific API changes for this release.
| Method | Name | Type of Change | Capability |
|---|---|---|---|
POST |
/v1/payments/authorization/{authorization_id}/reauthorize/ |
New Endpoint | Payments |
New Features
This section describes new features that have been added as of this release. New features can involve new capabilities, new resources, and/or new fields added to existing resources.
Reauthorize PayPal Payments
The REST Payment API now allows you 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.
Changed Functionality
Logical or functional changes that have been made to existing functionality, including new code list values and/or changes in validation rules.
Support for Additional Countries and Currencies
The PayPal REST Payment API now supports additional currencies and countries for PayPal account payments and direct credit card payments. Refer to the REST Payment FAQs for more information.
Additional Documentation Updates
This section lists additional documentation changes and corrections that were made with this release and that are not already mentioned in New Features or Changed Functionality.
API reference updated to clarify transactions object for /execute
The /execute section of the API reference guide has been updated to clarify that the transactions object uses only amount when used with the /execute call.
Updates for May 28, 2013
These release notes describe the changes to the PayPal REST API and related documentation.
Announcements
This section provides announcements related to the PayPal REST API.
No announcements.
API Changes
This section provides specific API changes for this release.
| Method | Name | Type of Change | Capability |
|---|---|---|---|
GET |
/v1/payments/authorization/{authorization_id} |
New Endpoint | Payments |
POST |
/v1/payments/authorization/{authorization_id}/capture |
New Endpoint | Payments |
POST |
/v1/payments/authorization/{authorization_id}/void |
New Endpoint | Payments |
GET |
/v1/payments/capture/{capture_id} |
New Endpoint | Payments |
POST |
/v1/payments/capture/{capture_id}/refund |
New Endpoint | Payments |
DELETE |
/v1/vault/credit-card/{credit-card-id} |
New Endpoint | Payments |
POST |
payer_id within /v1/vault/credit-card/ |
New Field | Payments |
New Features
This section describes new features that have been added as of this release. New features can involve new capabilities, new resources, and/or new fields added to existing resources.
Authorization and Capture
The REST Payment API now allows you to authorize payments to be captured later.
Delete Stored Credit Cards in Vault
The REST Payment API now allows you delete stored credit cards.
New Payer ID for Stored Credit Cards in Vault
When you store a credit card using the Vault API, you can now pass an optional payer_id field. This field distinguishes a credit card from others and helps to prevent potential misuse of the card. If this field is passed when storing the credit card, it must be provided when using the credit card.
Changed Functionality
Logical or functional changes that have been made to existing functionality, including new code list values and/or changes in validation rules.
No changes.
Additional Documentation Updates
This section lists additional documentation changes and corrections that were made with this release and that are not already mentioned in New Features or Changed Functionality.
No changes.
Updates for May 22, 2013
These release notes describe the changes to the PayPal REST API and related documentation.
Announcements
This section provides announcements related to the PayPal REST API.
Create and manage REST API apps and capabilities
You can use the My Apps & Credentials page to create and manage one or more REST API apps and/or capabilities.
API Changes
This section provides specific API changes for this release.
No changes.
New Features
This section describes new features that have been added as of this release. New features can involve new capabilities, new resources, and/or new fields added to existing resources.
No new features.
Changed Functionality
Logical or functional changes that have been made to existing functionality, including new code list values and/or changes in validation rules.
No changes.
Additional Documentation Updates
This section lists additional documentation changes and corrections that were made with this release and that are not already mentioned in New Features or Changed Functionality.
No changes.
Updates for May 15, 2013
These release notes describe the changes to the PayPal REST API and related documentation.
Announcements
This section provides announcements related to the PayPal REST API.
PayPal Android SDK
In addition to the PayPal iOS SDK, Paypal now offers a PayPal Android SDK.
The PayPal Android SDK provides a native Android library that simplifies accepting credit card and PayPal payments in your mobile app. Visit the PayPal Android SDK page on GitHub for more information.
API Changes
This section provides specific API changes for this release.
No changes.
New Features
This section describes new features that have been added as of this release. New features can involve new capabilities, new resources, and/or new fields added to existing resources.
No new features.
Changed Functionality
Logical or functional changes that have been made to existing functionality, including new code list values and/or changes in validation rules.
No changes.
Additional Documentation Updates
This section lists additional documentation changes and corrections that were made with this release and that are not already mentioned in New Features or Changed Functionality.
New documentation on handling common errors in the REST Payment API
A new document is available for handling common error related to the REST Payment API, such as validation and authentication errors.
Updates for April 24, 2013
These release notes describe the changes to the PayPal REST API and related documentation.
Announcements
No announcements.
API Changes
The following table lists the specific API changes for this release:
| Name| Type of Change| Capability|
|---|---|---| |
| /v1/identity/openidconnect/token | New | Identity |
| /v1/identity/openidconnect/userinfo/?{schema} | New | Identity |
| tokeninfo | New | Identity |
| userinfo | New | Identity |
| address | New | Identity |
| error | New | Identity |
| cvv2 | Modified | Payments |
New Features
This section describes new features that have been added as of this release. New features can involve new capabilities, new resources, and/or new fields added to existing resources.
Log In with PayPal REST APIs
Identity resource URIs and resource models added for Log In with PayPal.
New Python and Node.js SDKs
Python and Node.js SDKs have been released to support the PayPal REST APIs. Visit the PayPal on GitHub page to see the complete PayPal SDK offering. The API reference incorporates request samples from the SDKs.
Changed Functionality
Logical or functional changes that have been made to existing functionality, including new code list values and/or changes in validation rules.
Data type change for cvv2
The data type for the cvv2 field has been changed from integer to string. The cvv2 field is in the CreditCard object used by payment resources. This change is backward compatible. If you pass cvv2 values as integers, PayPal will process them as strings. We recommend you update your integration to handle cvv2 values as strings only.
Additional Documentation Updates
This section lists additional documentation changes and corrections that were made with this release and that are not already mentioned in New Features or Changed Functionality.
No updates.