Permissions Service Integration Guide

You can execute PayPal API operations for a PayPal account holder, if you have the account holder's permission. The PayPal Permissions Service provides a way for account holders to grant permission for API operations to be executed on their behalf.

Permissions Service Overview

If you call Permissions Service API operations, the account holder need not set third-party permissions in the Profile, nor explicitly notify you that permission has been granted. Your website or application can incorporate this task seamlessly by calling Permissions Service API operations. In addition to this guide, please see the FAQs.

The Permissions Service API enables you to request and obtain permission from PayPal account holders, such as the merchants or customers. Consider the following examples in which the Permissions Service API can be used:

  • You provide a shopping cart for merchants and need to make calls to the Express Checkout API to complete payments into the merchant's account. As a shopping cart provider, you are a third party to the transaction between PayPal and the merchant and, thus, require permission from the merchant to take actions that affect the merchant's PayPal account. The Permissions Service API enables your cart to request permission to execute Express Checkout APIs on your behalf.
  • You sell an application that provides reports and analyses of your customers' PayPal transactions. Accessing this information requires customers to grant you permission to call the PayPal TransactionSearch and GetTransactionDetails API operations to access their transactions. You can use the Permissions Service API to request permission of each customer to execute TransactionSearch and GetTransactionDetails.

After requesting permission, you redirect the account holder to PayPal to grant the permission:

Once permission has been granted, you can execute the PayPal API operations associated with the permissions on the account holder's behalf. To determine what permissions you need:

  1. Determine the specific PayPal API operations that you will call as part of your application or service.
  2. Identify the groups that contain these API operations.
  3. Request permission to execute the API operations by group.

Permission Groups

Permission groups are the bundles of PayPal APIs that you can request permission to call on behalf of a PayPal account holder. In your request, you specify one or more group IDs that cover the API operations you need to call.

Display description Group ID includes
Use Express Checkout to process payments. EXPRESS_CHECKOUT includes
  • SetExpressCheckout
  • GetExpressCheckout
  • DoExpressCheckout
  • GetPalDetails
Process your customers' credit or debit card payments. DIRECT_PAYMENT includes DoDirectPayment
Consolidate funds from two or more child accounts into a master account. SETTLEMENT_CONSOLIDATION includes Settlement Consolidation; valid for all countries except Indonesia, Turkey, Estonia, and the Russian Federation
Note: You must have prior approval from PayPal to request this permission.
Provide reporting for consolidated funds. SETTLEMENT_REPORTING includes Settlement Reporting; valid for all countries except Indonesia, Turkey, Estonia, and the Russian Federation
Note: You must have prior approval from PayPal to request this permission.
Authorize and capture your PayPal transactions. AUTH_CAPTURE includes
  • DoAuthorization
  • DoCapture
  • DoReauthorization
  • DoVoid
Use Express Checkout to process mobile payments. MOBILE_CHECKOUT includes
  • SetMobileCheckout
  • DoMobileCheckoutPayment
  • CreateMobilePayment
Obtain authorization for pre-approved payments and initiate pre-approved transactions. BILLING_AGREEMENT includes
  • SetCustomerBillingAgreement
  • CreateBillingAgreement
  • BillAgreementUpdate
  • GetBillingAgreementCustomerDetail
    Note: You must have prior approval from PayPal to request this permission.
Process a payment based on a previous transaction. REFERENCE_TRANSACTION includes DoReferenceTransaction
Note: You must have prior approval from PayPal to request this permission.
Authorize transactions with Universal Air Travel Plans. AIR_TRAVEL includes
  • DoUATPAuthorization
  • DoUATPExpressCheckoutPayment
Initiate transactions to multiple recipients in a single batch. MASS_PAY includes MassPay
Note: You must have prior approval from PayPal to request this permission.
Obtain transaction specific information. TRANSACTION_DETAILS includes GetTransactionDetails
Note: You must have prior approval from PayPal to request this permission.
Search your transactions for items that match specific criteria and display the results. TRANSACTION_SEARCH includes TransactionSearch
Create and manage recurring payments. RECURRING_PAYMENTS includes
  • CreateRecurringPaymentsProfile
  • GetRecurringPaymentsProfileDetails
  • ManageRecurringPaymentsProfileStatus
  • UpdateRecurringPaymentsProfile
  • BillOutstandingAmount
Obtain your PayPal account balance. ACCOUNT_BALANCE includes GetBalance
Note: You must have prior approval from PayPal to request this permission.
Dynamically encrypt PayPal payment buttons on your web site. ENCRYPTED_WEBSITE_PAYMENTS includes Encrypted Website Payments
Note: You must have prior approval from PayPal to request this permission.
Refund a transaction on your behalf. REFUND includes
  • RefundTransaction
  • Refund
Issue a credit to a debit or credit card. NON_REFERENCED_CREDIT includes DoNonReferencedCredit
Note: You must have prior approval from PayPal to request this permission.
Create and manage PayPal payment buttons on your behalf. BUTTON_MANAGER includes
  • BMManageButtonStatus
  • BMCreateButton
  • BMUpdateButton
  • BMSetInventory
  • BMGetInventory
  • BMButtonSearch
Obtain basic attributes for specified user, such as first name, last name, and payer ID. ACCESS_BASIC_PERSONAL_DATA required for GetBasicPersonalData
Note: You must have prior approval from PayPal to request this permission.
Obtain advanced attributes for specified user, such as date of birth and phone. ACCESS_ADVANCED_PERSONAL_DATA required for GetAdvancedPersonalData
Note: You must have prior approval from PayPal to request this permission.
Accept or deny a pending transaction. MANAGE_PENDING_TRANSACTION_STATUS includes ManagePendingTransactionStatus
Reporting for recurring payments RECURRING_PAYMENT_REPORT; valid for all countries except Indonesia, Turkey, Estonia, and the Russian Federation
Extended Pro processing EXTENDED_PRO_PROCESSING_REPORT; valid for all countries except Indonesia, Turkey, Estonia, and the Russian Federation
Exception processing EXCEPTION_PROCESSING_REPORT; valid for all countries except Indonesia, Turkey, Estonia, and the Russian Federation
Account Management Permission (MAM) ACCOUNT_MANAGEMENT_PERMISSION; valid for all countries except Indonesia, Turkey, Estonia, and the Russian Federation
Manage invoicing through a third party. INVOICING includes:
  • UpdateInvoice
  • CancelInvoice
  • GetInvoiceDetails
  • MarkInvoiceAsPaid
  • SearchInvoices
  • CreateInvoice
  • SendInvoice
  • CreateAndSendInvoice

Permissions API Operations

The PayPal Permissions API includes operations to request, access, and cancel permissions. It also enables you to obtain the access token needed to determine permissions that an account holder has granted you.

API Operation Description
CancelPermissions Use the CancelPermissions API operation to cancel access to a set of permissions.
GetAccessToken Use the GetAccessToken API operation to obtain an access token for a set of permissions.
GetPermissions Use the GetPermissons API operation to obtain the permissions associated with an access token.
RequestPermissions Use the RequestPermissions API operation to request permissions to execute API operations on a PayPal account holder's behalf.

Additional information