Home

PayPal Permissions Service - 2012 User's Guide

1. 63 PersonalAttributeList Fields o 64 RequestEnvelope Fields 64 GetAdvancedPersonalDataResponse Message 64 GetAdvancedPersonalData Response Fields 65 PersonalDataListFields 65 PersonalData Fields 65 ResponseEnvelope Fields 66 PPFault Message taa taneria daen e a 67 FaultMessage Fields 67 ErrorData Fields soaa e w e a e A a a a a a 68 ResponseEnvelope Fields 68 GetAdvancedPersonalData Errors 69 Chapter 9 Permission Commands 71 _grant permission Command 71 Past Releases r 73 Release 84 0 Features 4 444444 a 73 PayPal Permissions Service May 2012 5 Contents Addition of Two New Groups 73 Addition of Two New APIS 73 Release 74 0 Features 74 Changes to Permission Categories 74 Changes to RequestPermissionRequest Fields for Release 74 0 75 Changes to GetAccessTokenRespone and GetPermissionsResponse Fields for Rel
2. PPFault Message FaultMessage Fields ErrorData Fields o ResponseEnvelope Fields CancelPermissions Errors 4 May 2012 PayPal Permissions Service Contents Chapter7 GetBasicPersonalData API Operation 55 GetBasicPersonalDataRequest Message 55 GetBasicPersonalDataRequest Fields 55 PersonalAttributeList Fields o 56 RequestEnvelope Fields 56 GetBasicPersonalDataResponse Message 56 GetBasicPersonalData Response Fields 57 PersonalDataList Fields 57 PersonalData Fields 58 ResponseEnvelope Fields 58 PPFault Message 59 FaultMessage Fields 59 ErrorData Fields Oa ara i a Da e TE T a S a a a 60 ResponseEnvelope Fields 60 GetBasicPersonalData Errors 61 Chapter 8 GetAdvancedPersonalData API Operation 63 GetAdvancedPersonalDataRequest Message 63 GetAdvancedPersonalDataRequest Fields
3. CancelPermissionsRequest Fields Field Description token xs string Required The access token that identifies a set of permissions to cancel requestEnvelope common requestEnvelope Required Information common to each API operation such as the language in which an error message is returned RequestEnvelope Fields Field Description detailLevel common DetailLevelCode Optional Level of detail required by the client application for components It is one of the following values e ReturnAll This value provides the maximum level of detail default errorLanguage xs string Required RFC 3066 language in which error messages are returned by default it is en_US which is the only language currently supported PayPal Permissions Service May 2012 49 j CancelPermissions API Operation CancelPermissionsResponse Message CancelPermissionsResponse Message CancelPermissionsResponse e responseEnvelope ResponseEnvelope ResponseEnvelope e timestamp 1 1 dateTime e ack 0 1 AckCode e correlationId 1 1 string e build 1 1 string 7 any CancelPermissions Response Fields Field Description responseEnvelope common ResponseEnvelope Common response information including a timestamp and the response acknowledgement status ResponseEnvelope Fields Field Description ack build correlationId timestamp common
4. Use the GetBasicPersonalData API operation to obtain basic personal data for an account holder GetBasicPersonalDataRequest Message E GetBasicPersonalDataRequest RequestEnvelope Gi requestEnvelope 0 1 RequestEnvelope e errorLanguage 1 1 string ses E attributeList 1 1 PersonalAttributeList FE any 0 FE any 0 PersonalattributeList eee e attribute 0 Personal ttribute GetBasicPersonalDataRequest Fields Field Description attributeList tns PersonalAttributeList Required The list of personal attributes requested for this account requestEnvelope common requestEnvelope Required Information common to each API operation such as the language in which an error message is returned PayPal Permissions Service May 2012 55 56 GetBasicPersonalData API Operation GetBasicPersonalDataResponse Message PersonalAttributeList Fields Field Description attribute tns PersonalAttribute The attributes whose values you are requesting You specify one or more of the following URIs http http http http http http axschema org namePerson first First name axschema org namePerson 1 axschema org contact emai ast last name Email schema openid net contact fullname Full name openid net schema company name Business name axschema org contact country home Country https www paypal com webapps auth schema payer
5. AUTHORIZATION When you call PayPal API operations the authentication header specifies whether you have permission to make the call on behalf of the account holder Generating Signatures for the Authentication Header After you have an access token and associated secret you can create an authentication header X PAYPAL AUTHORL AT ION and use it in calls to PayPal APIs You use either the API signature or certificate from the account holder s profile when you create the header The X PAYPAL AUT e A timestamp HORI AT ION header contains e The access token from the GetAccessToken response e A signature generated from the following information Your API username Your API password The access token from the GetAccessToken response The token secret from the GetAccessToken response The endpoint for the PayPal API operation s request such as https api paypal com nvp The HTTPS delivery method such as POST Request parameters associated with the request NOTE You can use a certificate instead of the API username and API signature PayPal provides SDKs that you can use to generate authentication header signatures for Java PHP and NET When you use the SDK you will get two values such as the following 20 May 2012 PayPal Permissions Service Using the Permissions Service Generating Signatures for the Authentication Header Signature tL
6. category ErrorCategory e message string e exceptionId 0 1 token e parameter 0 ErrorParameter FaultMessage Fields Field Description error common ErrorData Detailed error information responseEnvelope common ResponseEnvelope Common response information including a timestamp and the response acknowledgement status PayPal Permissions Service May 2012 45 Le GetPermissions API Operation PPFault Message ErrorData Fields Field Description category common ErrorCategory The location where the error occurred Possible values are e System The system encountered errors try again e Application The application encountered errors try again e Request The request was incorrect domain The domain to which this service belongs errorld A number that uniquely identifies a particular error exceptionID This field is not used message A description of the error parameter common ErrorParameter Represents contextual information about the error severity common ErrorSeverity The severity of the error encountered Possible values are e Error Processing of the request was interrupted e Warning Processing of the request was completed subdomain This field is not used ResponseEnvelope Fields Field Description ack build correlationId common AckCode Acknowledgement code It is one of the following values e Success The operation completed suc
7. 50 57 ResponseEnvelope response fields 28 30 36 38 44 46 50 52 58 60 66 68 S scope request field 26 scope response field 35 43 severity field 30 38 46 52 60 68 signatures 20 subdomain field 30 38 46 52 60 68 subjectAlias request field 33 T timestamp response field 28 31 36 39 44 47 50 53 58 61 66 69 token request field 33 41 49 token response field 27 35 tokenSecret response field 35 May 2012 PayPal Permissions Service
8. Cart Software w You are in the process of authorizing platform sdk s Test Store access to your account information Required Permissions Y Use Express Checkout to process payments What s this Y Authorize and capture your PayPal transactions what s this For more information about the permissions you are granting see Third Party Permissions To revoke permissions at any time log in to your PayPal account and choose Profile then API Access and then choose Manage API Permissions m renipemmissions _ Cancel 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 e SetExpressCheckout e GetExpressCheckout e DoExpressCheckout e GetPalDetails Process your customers credit or debit card payments DIRECT_PAYMENT includes DoDi
9. GetAdvancedPersonalData API Operation Use the GetAdvancedPersonalData API operation to obtain sensitive personal data for an account holder GetAdvancedPersonalDataRequest Message E Get dyancedPersonalDataRequest RequestEnvelope Gi requestEnvelope 0 1 RequestEnvelope e errorLanguage 1 1 string seo E attributeList 1 1 PersonalAttributeList FE any 0 F any 0 PersonalattributeList cee e attribute 0 PersonalAttribute GetAdvancedPersonalDataRequest Fields Field Description attributeList tns PersonalAttributeList Required The list of personal attributes requested for the account requestEnvelope common requestEnvelope Required Information common to each API operation such as the language in which an error message is returned PayPal Permissions Service May 2012 63 _ GetAdvancedPersonalData API Operation GetAdvancedPersonalDataResponse Message PersonalAttributeList Fields Field Description PersonalAttribute The attributes whose value you are requesting You specify one or more of the following URIs e http axschema org birthDate Date of birth http axschema org contact postalCode home Postcode http schema openid net contact street1 Street http schema openid net contact street2 Street2 http axschema org contact city home City http axschema org contact state home State http axschema org contact phone de
10. of the following values e ReturnAll This value provides the maximum level of detail default errorLanguage xs string Required RFC 3066 language in which error messages are returned by default it is en_US which is the only language currently supported PayPal Permissions Service May 2012 41 GetPermissions API Operation GetPermissionsResponse Message GetPermissionsResponse Message Ea GetPermissionsResponse i ResponseEnvelope e responseEnvelope ResponseEnvelope e timestamp 1 1 dateTime e scope 0 string e ack 0 1 AckCode e correlationId 1 1 string e build 1 1 string 7j any 0 42 May 2012 PayPal Permissions Service GetPermissions API Operation p GetPermissionsResponse Message GetPermissionsResponse Fields Field Description scope xs string Any number of permission categories from the following list EXPRESS_CHECKOUT Express Checkout DIRECT_PAYMENT Direct payment by debit or credit card SETTLEMENT_CONSOLIDATION Settlement consolidation SETTLEMENT_REPORTING Settlement reporting AUTH_CAPTURE Payment authorization and capture OBILE_CHECKOUT Mobile checkout BILLING_AGREEMENT Billing agreements REFERENCE_TRANSACTION Reference transactions AIR_TRAVEL Express Checkout for UTAP ASS_PAY Mass pay TRANSACTION_DETAILS Transaction details TRANSACTION_SEARCH Transaction search RECURRING_PAYMENTS Recurring payments ACCOUNT_BALANCE Account bala
11. payments REFUND Refunds NON_REFERENCED_ CREDIT Non referenced credit BUTTON_MANAGER Button Manager T T ANAGE_PENDING_TRANSACTION_ STATUS includes anagePendingTransactionStatus RECURRING_PAYMENT_REPORT Reporting for recurring payments EXTENDED_PRO_PROCESSING_REPORT Extended Pro processing EXCEPTION_PROCESSING_REPORT Exception processing ACCOUNT_MANAGEMENT_PERMISSION Account Management Permission MAM ACCESS_BASIC_PERSONAL_DATA User attributes e ACCESS ADVANCED PERSONAL DATA User attributes e INVOICING Invoicing T callback xs string Required Your callback function that specifies actions to take after the account holder grants or denies the request requestEnvelop common requestEnvelop Required Information common to each API operation such as the language in which an error message is returned 26 May 2012 PayPal Permissions Service RequestPermissions API Operation x RequestPermissionsResponse Message RequestEnvelope Fields Field Description detaillevel common DetailLevelCode Optional Level of detail required by the client application for components It is one of the following values e ReturnAll This value provides the maximum lev
12. required for Obtain basic attributes for specified user such as firstname GetBasicPersonalData last name and payer ID New NOTE You must have prior approval from PayPal to request this permission ACCESS_ADVANCED_PERSONAL_DATA required Obtain advanced attributes for specified user such as date of for GetAdvancedPersonalData birth and phone NOTE You must have prior approval from PayPal to request this permission Addition of Two New APIs API Description New GetBasicPersonalData New GetAdvancedPersonalData Request to retrieve basic personal data for an account holder Accepts PersonalAttributeList as request and responds with PersonalDataList This call will accept only Basic attributes and ignore others Request to retrieve more sensitive personal data for an account holder Accepts PersonalAttributeList as request and responds with PersonalDataList This call will accept both Basic and Advanced attributes PayPal Permissions Service May 2012 73 Release 74 0 Features Release 74 0 Features Release 74 0 of the Permissions API introduces several new permission categories and language support and redirect response parameters NOTE Changes to API operations are backward compatible Changes to Permission Categories Display description Group ID includes Consolidate funds from two or more child accounts into a SETTLEMENT CONSOLIDATION inc
13. AckCode Acknowledgement code It is one of the following values Success The operation completed successfully Failure The operation failed Warning Warning SuccessWithWarning The operation completed successfully however there is a warning message e FailureWithWarning The operation failed with a warning message Build number it is used only by Developer Technical Support Correlation ID it is used only by Developer Technical Support NOTE You must log and store this data for every response you receive PayPal Technical Support uses the information to assist with reported issues Date on which the response was sent The time is currently not supported NOTE You must log and store this data for every response you receive PayPal Technical Support uses the information to assist with reported issues 50 May 2012 PayPal Permissions Service CancelPermissions API Operation s PPFault Message PPFault Message The PPFaultMessage returns ErrorData and the ResponseEnvelope information to your application if an error occurs ResponseEnvelope E FaultMessage e timestamp 1 1 dateTime e ack 1 1 AckCode e correlationId 1 1 string e build 1 1 string T l any o e responseEnvelope 1 1 ResponseEnvelope e error 0 ErrorData ErrorData e errorld long e domain string e subdomain 0 1 string e severity ErrorSeverity e category ErrorCatego
14. ID Payer ID RequestEnvelope Fields Field Description detailLevel common DetailLevelCod Optional Level of detail required by the client application for components It is one of the following values e ReturnA11 This value provides the maximum level of detail default errorLanguage xs string Required RFC 3066 language in which error messages are returned by default it is en_US which is the only language currently supported GetBasicPersonalDataResponse Message GetAdvancedPersonalDataResponse e responseEnvelope ResponseEnvelope e response PersonalDataList sea ResponseEnvelope e ack e build FE any e timestamp 1 1 dateTime 0 1 AckCode e correlationId 1 1 string 1 1 string 0 PersonalDataList s e personalData 0 PersonalData May 2012 PayPal Permissions Service GetBasicPersonalData API Operation GetBasicPersonalDataResponse Message PersonalDataList PersonalData ses e personalData 0 PersonalData personalDataKey 1 1 PersonalAttribute personalDataYalue 1 1 string GetBasicPersonalData Response Fields Field Description response tns PersonalDataList The attributes for which you have been granted permission to access one or more of the following URIs http axschema org namePerson first First name http axschema org namePerson last last name http ax
15. May 2012 PayPal Permissions Service GetAccessToken API Operation 4 GetAccessToken Errors Field Description timestamp Date on which the response was sent The time is currently not supported NOTE You must log and store this data for every response you receive PayPal Technical Support uses the information to assist with reported Issues GetAccessToken Errors Code Message Additional Information 579058 Request token is Expired 580022 Invalid Request token or Verifier Code PayPal Permissions Service May 2012 39 GetAccessToken API Operation GetAccess Token Errors 40 May 2012 PayPal Permissions Service GetPermissions API Operation Use the GetPermissions API operation to obtain the permissions associated with an access token GetPermissionsRequest Message GetPermissionsRequest RequestEnvelope e requestEnvelope 0 1 RequestEnvelope e errorLanguage 1 1 string ses e token 1 1 string FE any 0 Ej any 0 GetPermissionsRequest Fields Field Description token xs string Required The access token that identifies a set of permissions requestEnvelope common requestEnvelope Required Information common to each API operation such as the language in which an error message is returned RequestEnvelope Fields Field Description detailLevel common DetailLevelCode Optional Level of detail required by the client application for components It is one
16. PayPal PayPal Permissions Service PayPal Permissions Service Document Number 10125 en_US 201205 2010 2012 PayPal Inc All rights reserved PayPal is a registered trademark of PayPal Inc The PayPal logo is a trademark of PayPal Inc Other trademarks and brands are the property of their respective owners The information in this document belongs to PayPal Inc It may not be used reproduced or disclosed without the written approval of PayPal Inc Copyright PayPal All rights reserved PayPal S r l et Cie S C A Soci t en Commandite par Actions Registered office 22 24 Boulevard Royal L 2449 Luxembourg R C S Luxembourg B 118 349 Consumer advisory The PayPal payment service is regarded as a stored value facility under Singapore law As such it does not require the approval of the Monetary Authority of Singapore You are advised to read the terms and conditions carefully Notice of non liability PayPal Inc is providing the information in this document to you AS IS with all faults PayPal Inc makes no warranties of any kind whether express implied or statutory with respect to the information contained herein PayPal Inc assumes no liability for damages whether direct or indirect caused by errors or omissions or resulting from the use of this document or the information contained in this document or resulting from the application or use of the product or service described herein PayPal Inc reserves
17. WUfZU9Np 7qgPqWF1LMIWjY1s Timestamp 1285744515 Use the values to construct the header as follows X PAYPAL AUTHORIZATION timestamp 1285744515 token 5wZptMaHXQfihLKzFscuGjeKOPqQrlfHFPaRcIiQOlItX3vYi6 signature tLWU ZU9Np 7qgPaWF1LMIWjY1s Java Example The PayPal Java SDK provides a method for creating the X PAYPAL AUTHORIZATION header See the get AuthHeader method in the OauthSignature java file of the com paypal sdk util package in paypal_base jar import java util lterator import java util Map import com paypal sdk util OAuthSignature import com paypal sdk util OAuthSignature HTTPMethod public class TestOauthSignature private static String apiUserName biz apil gmail com private static String apiPassword 1255077037 private static String accessToken 2WhQDDM4 private static String tokenSecret JjOYhbTgcy K5VjpQa7Ru80M private static HTTPMethod httpMethod OAuthSignature HTTPMethod POST private static String scriptURI https api sandbox paypal com nvp private static Map queryParams null public static void main String args try Map map OAuthSignature getAuthHeader apiUserName apiPassword accessToken tokenSecret httpMethod scriptURI queryParams Display Signature and Timestamp to console Iterator itr map entrySet iterator while itr hasNext Map Entry entry Map Entry itr next System ou
18. al Permissions Service May 2012 23 Le Using the Permissions Service Granting Permission to Access Account Holder Information 24 May 2012 PayPal Permissions Service RequestPermissions API Operation Use the RequestPermissions API operation to request permissions to execute API operations on a PayPal account holder s behalf RequestPermissionsRequest Message RequestPermissiorisRequest y RequestEnvelope e requestEnvelope 0 1 RequestEnvelope e errorLanguage 1 1 string e scope 1 string FE any 0 e callback 1 1 string Fl any o PayPal Permissions Service May 2012 me RequestPermissions API Operation RequestPermissionsRequest Message RequestPermissions Request Fields Field Description scope xs string Required At least 1 of the following permission categories e EXPRESS _CHECKOUT Express Checkout DIRECT_PAYMENT Direct payment by debit or credit card SETTLEMENT_ CONSOLIDATION Settlement consolidation SETTLEMENT_ REPORTING Settlement reporting AUTH_CAPTURE Payment authorization and capture OBILE_CHECKOUT Mobile checkout BILLING_AGREEMENT Billing agreements REFERENCE_TRANSACTION Reference transactions AIR_TRAVEL Express Checkout for UTAP ASS_PAY Mass pay TRANSACTION_DETAILS Transaction details TRANSACTION_SEARCH Transaction search RECURRING_PAYMENTS Recurring payments ACCOUNT_BALANCE Account balance ENCRYPTED_WEBSITE_PAYMENTS Encrypted website
19. as interrupted e Warning Processing of the request was completed subdomain This field is not used ResponseEnvelope Fields Field Description ack build correlationId common AckCode Acknowledgement code It is one of the following values e Success The operation completed successfully e Failure The operation failed e Warning Warning e SuccessWithWarning The operation completed successfully however there is a warning message e FailureWithWarning The operation failed with a warning message Build number it is used only by Developer Technical Support Correlation ID it is used only by Developer Technical Support NOTE You must log and store this data for every response you receive PayPal Technical Support uses the information to assist with reported Issues 60 May 2012 PayPal Permissions Service GetBasicPersonalData API Operation GetBasicPersonalData Errors Field Description timestamp Date on which the response was sent The time is currently not supported NOTE You must log and store this data for every response you receive PayPal Technical Support uses the information to assist with reported issues GetBasicPersonalData Errors Code Message Additional Information 580022 Invalid Access Token PayPal Permissions Service May 2012 61 GetBasicPersonalData API Operation GetBasicPersonalData Errors 62 May 2012 PayPal Permissions Service
20. butes e ACCESS ADVANCED PERSONAL DATA User attributes e INVOICING Invoicing T token xs string The access token that identifies a set of permissions tokenSecret xs string The secret associated with the access token responseEnvelop common ResponseEnvelop Common response information including a timestamp and the response acknowledgement status PayPal Permissions Service May 2012 35 4 GetAccessToken API Operation GetAccessToken Response Message ResponseEnvelope Fields Field Description ack common AckCode Acknowledgement code It is one of the following values Success The operation completed successfully Failure The operation failed Warning Warning SuccessWithWarning The operation completed successfully however there is a warning message e FailureWithWarning The operation failed with a warning message build Build number it is used only by Developer Technical Support correlationld Correlation ID it is used only by Developer Technical Support NOTE You must log and store this data for every response you receive PayPal Technical Support uses the information to assist with reported issues timestamp Date on which the response was sent The time is currently not supported NOTE You must log and store this data for every response you receive PayPal Technical Support uses the info
21. cessToken API Operation ES GetAccess Token Response Message GetAccessTokenResponse Fields Field Description scope xs string The group IDs of the permission categories associated with the access token e EXPRESS_CHECKOUT Express Checkout DIRECT_PAYMENT Direct payment by debit or credit card SETTLEMENT_CONSOLIDATION Settlement consolidation SETTLEMENT_R AUTH_CAPTURE Payment authorization and capture OBILE_CHECKOUT Mobile checkout BILLING_AGREEMENT Billing agreements REFERENCE_TRANSACTION Reference transactions AIR_TRAVEL Express Checkout for UTAP ASS_PAY Mass pay TRANSACTION_DETAILS Transaction details TRANSACTION_SEARCH Transaction search RECURRING_PAYMENTS Recurring payments ACCOUNT_BALANCE Account balance ENCRYPTED_WEBSITE_PAYMENTS Encrypted website payments REFUND Refunds NON_REFERENCED_ CREDIT Non referenced credit BUTTON_MANAGER Button Manager EPORT ING Settlement reporting T T ANAGE_PENDING_TRANSACTION_ STATUS includes anagePendingTransactionStatus RECURRING_PAYMENT_REPORT Reporting for recurring payments EXTENDED_PRO_PROCESSING_REPORT Extended Pro processing EXCEPTION_PROCESSING_REPORT Exception processing ACCOUNT_MANAGEMENT_PERMISSION Account Management Permission MAM ACCESS_BASIC_PERSONAL_DATA User attri
22. cessfully e Failure The operation failed e Warning Warning e SuccessWithWarning The operation completed successfully however there is a warning message e FailureWithWarning The operation failed with a warning message Build number it is used only by Developer Technical Support Correlation ID it is used only by Developer Technical Support NOTE You must log and store this data for every response you receive PayPal Technical Support uses the information to assist with reported Issues 46 May 2012 PayPal Permissions Service GetPermissions API Operation GetPermissions Errors Field Description timestamp Date on which the response was sent The time is currently not supported NOTE You must log and store this data for every response you receive PayPal Technical Support uses the information to assist with reported Issues GetPermissions Errors Code Message Additional Information 580022 Invalid Access Token PayPal Permissions Service May 2012 47 ae GetPermissions API Operation GetPermissions Errors 48 May 2012 PayPal Permissions Service CancelPermissions API Operation Use the CancelPermissions API operation to cancel access to a set of permissions CancelPermissionsRequest Message CancelPermissionsRequest RequestEnvelope e requestEnvelope 0 1 RequestEnvelope e errorLanguage 1 1 string ses e token 1 1 string FE any 0 Fl any o
23. d Pro processing e EXCEPTION PROCESSING _ REPORT Exception processing e ACCOUNT _MANAGEMENT_ PERMISSION Account Management Permission MAM Changes to GetAccessTokenRespone and GetPermissionsResponse Fields for Release 74 0 Field Description scope xs string New values RECURRING_PAYMENT_ REPORT Reporting for recurring payments EXTENDED_PRO_PROCESSING_REPORT Extended Pro processing EXCEPTION_PROCESSING_REPORT Exception processing ACCOUNT_MANAGEMENT_PERMISSION Account Management Permission MAM PayPal Permissions Service May 2012 75 a Release 74 0 Features 76 May 2012 PayPal Permissions Service Permissions Service Revision History The revision history identifies changes to Permissions Service documentation at a high level Date Description 05 02 12 Maintenance release 02 09 12 Maintenance release 10 09 11 Added new groups and APIs for getting personal data This version of the guide corresponds to release version 84 05 24 11 Added new permission groups and information about return parameters for the redirect This version of the guide corresponds to release version 74 04 05 11 Initial release draft which corresponds to release version 71 This guide replaces the earlier Permissions Service guide last published in October 2009 which was based on a non platform API 10 22 10 Initial draft for version 1 6 0 PayPal Permissions Service May 2012 78 May 2012 PayPal Per
24. ease TAO pe 75 Permissions Service Revision History 77 Index 9 6 May 2012 PayPal Permissions Service What s New Permissions Service is intended for developers implementing solutions that require executing a PayPal API operation on behalf of an account holder Check out what s new in the current release Release 89 Changes Maintenance release PayPal Permissions Service May 2012 a Release 89 Changes 8 May 2012 PayPal Permissions Service Preface With the Permissions Service you can ask your customers for permission to make API calls on their behalf programmatically Documentation Feedback Help us improve this guide by sending feedback to documentat ionfeedback paypal com PayPal Permissions Service May 2012 a Documentation Feedback 10 May 2012 PayPal Permissions Service About the PayPal Permissions Service With permission you can execute PayPal API operations for a PayPal account holder The PayPal Permissions Service provides a way for account holders to grant permission to execute API operations on their behalf programmatically Permissions Service Overview Granting of permissions is handled by the Permissions Service API If you call these API operations the account holder need not set third party permissions in the Profile and then explicitly notify you that permission has been granted Your website or applicatio
25. ed error information responseEnvelop common ResponseEnvelope Common response information including a timestamp and the response acknowledgement status PayPal Permissions Service May 2012 29 La RequestPermissions API Operation PPFault Message ErrorData Fields Field Description category common ErrorCategory The location where the error occurred Possible values are e System The system encountered errors try again e Application The application encountered errors try again e Request The request was incorrect domain The domain to which this service belongs errorld A number that uniquely identifies a particular error exceptionID This field is not used message A description of the error parameter common ErrorParameter Represents contextual information about the error severity common ErrorSeverity The severity of the error encountered Possible values are e Error Processing of the request was interrupted e Warning Processing of the request was completed subdomain This field is not used ResponseEnvelope Fields Field Description ack build correlationId common AckCode Acknowledgement code It is one of the following values e Success The operation completed successfully e Failure The operation failed e Warning Warning e SuccessWithWarning The operation completed successfully however there is a warning message e FailureWithWarning The o
26. el of detail default errorLanguage xs string Required REC 3066 language in which error messages are returned by default it is en_US which is the only language currently supported RequestPermissionsResponse Message RequestPermissionsResponse ResponseEnvelope e timestamp 1 1 dateTime e ack 0 1 AckCode e correlationId 1 1 string e build 1 1 string Fl any 0 e responseEnvelope ResponseEnvelope e token string RequestPermissions Response Fields Field Description token xs string Required A token from PayPal that enables the request to obtain permissions responseEnvelope common ResponseEnvelope Common response information including a timestamp and the response acknowledgement status PayPal Permissions Service May 2012 27 me RequestPermissions API Operation RequestPermissionsResponse Message ResponseEnvelope Fields Field Description ack common AckCode Acknowledgement code It is one of the following values Success The operation completed successfully Failure The operation failed Warning Warning SuccessWithWarning The operation completed successfully however there is a warning message e FailureWithWarning The operation failed with a warning message build Build number it is used only by Developer Technical Support correlationId Correlation ID it is used only by Developer Technical Support NOTE You must log a
27. email timestamp attributeList attribute 1 http schema openid net contact ful amp requestEnvelop errorLanguage en_US https svcs paypal com Permissions GetBasicPersonalData May 2012 lname PayPal Permissions Service Using the Permissions Service Granting Permission to Access Account Holder Information responseEnvelope timestamp 2011 10 24T01 3A37 3A26 565 07 3A00 amp responseEnvelope ack Success amp responseEnvelope correlationId 5d8bfl9 13be028responseEnvelope build 22103018response personalData 0 personalData Key http 3A 2FS2Faxschema org 2Fcontact 2Femail amp response personalData 0 pe rsonalDataValue jdoe 40someisp com response personalData 1 personalDataKey http53A52F 2Fschema openid nets2Fcontact 2Ffullnamesresponse personalData 1 personalDataValue John Doe Notes 1 The X PAYPAL AUTHORIZATION header was generated with URL https svces paypal com Permissions GetBasicPersonalData 2 ACCESS_BASIC_PERSONAL_DATA and ACCESS_ADVANCED_PERSONAL_ DATA access permissions have been previously granted to the API caller 3 This example illustrates use of the GetBasicPersonalData API A request to GetAdvancedPersonalData would be the same except for the URL and the response fields would differ 4 The URL used in cur1 and the URL used to generate X PAYPAL AUTHORIZATION must be identical PayP
28. eveloper Technical Support Correlation ID it is used only by Developer Technical Support NOTE You must log and store this data for every response you receive PayPal Technical Support uses the information to assist with reported Issues 68 May 2012 PayPal Permissions Service GetAdvancedPersonalData API Operation ESE GetAdvancedPersonalData Errors Field Description timestamp Date on which the response was sent The time is currently not supported NOTE You must log and store this data for every response you receive PayPal Technical Support uses the information to assist with reported Issues GetAdvancedPersonalData Errors Code Message Additional Information 580022 Invalid Access Token PayPal Permissions Service May 2012 69 L GetAdvancedPersonalData API Operation GetAdvancedPersonalData Errors 70 May 2012 PayPal Permissions Service Permission Commands The web flows associated with Permissions Service require you to redirect the account holder s browser to PayPal When you redirect to the webscr endpoint you must send a command that identifies the flow and associated parameters _grant permission Command The account holder can log in to paypal com and grant permissions to you when you redirect the account holder s browser to paypal com with the _grant permission command Redirect to PayPal using the _grant permission command Redirect to PayPal https www paypal co
29. fault Phone RequestEnvelope Fields Field Description detailLevel common DetailLevelCod Optional Level of detail required by the client application for components It is one of the following values e ReturnA11 This value provides the maximum level of detail default errorLanguage xs string Required RFC 3066 language in which error messages are returned by default it is en_US which is the only language currently supported GetAdvancedPersonalDataResponse Message GetAdvancedPersonalDataResponse ResponseEnvelope e responseEnvelope ResponseEnvelope e timestamp 1 1 dateTime e response PersonalDataList e ack 0 1 AckCode se e correlationId 1 1 string e build 1 1 string any 0 PersonalDataList s e personalData 0 PersonalData 64 May 2012 PayPal Permissions Service GetAdvancedPersonalData API Operation 8 GetAdvancedPersonalDataResponse Message PersonalDataList PersonalData e personalData 0 PersonalData personalDataKey 1 1 PersonalAttribute personalDataYalue 1 1 string GetAdvancedPersonalData Response Fields Field Description responseEnvelope common ResponseEnvelope Common response information including a timestamp and the response acknowledgement status PersonalDataListFields Field Description personalData tns PersonalData The list of name value pairs of personal data in t
30. g Processing of the request was completed subdomain This field is not used ResponseEnvelope Fields Field Description ack build correlationId common AckCode Acknowledgement code It is one of the following values e Success The operation completed successfully e Failure The operation failed e Warning Warning e SuccessWithWarning The operation completed successfully however there is a warning message e FailureWithWarning The operation failed with a warning message Build number it is used only by Developer Technical Support Correlation ID it is used only by Developer Technical Support NOTE You must log and store this data for every response you receive PayPal Technical Support uses the information to assist with reported Issues 52 May 2012 PayPal Permissions Service CancelPermissions API Operation CancelPermissions Errors Field Description timestamp Date on which the response was sent The time is currently not supported NOTE You must log and store this data for every response you receive PayPal Technical Support uses the information to assist with reported issues CancelPermissions Errors Code Message Additional Information 580022 Invalid Access Token PayPal Permissions Service May 2012 53 j CancelPermissions API Operation CancelPermissions Errors 54 May 2012 PayPal Permissions Service GetBasicPersonalData API Operation
31. he response PersonalData Fields Field Description personalDataKey tns PersonalAttribute The attributes whose values you are requesting You specify one or more of the following URIs e http axschema org namePerson first First name http axschema org namePerson last last name http axschema org contact email Email http schema openid net contact fullname Full name http openid net schema company name Business name http axschema org contact count ry home Country https www paypal com webapps auth schema payerlID Payer ID personalDataValue xs String The value associated with the key PayPal Permissions Service May 2012 65 8 GetAdvancedPersonalData API Operation GetAdvancedPersonalDataResponse Message ResponseEnvelope Fields Field Description ack common AckCode Acknowledgement code It is one of the following values Success The operation completed successfully Failure The operation failed Warning Warning SuccessWithWarning The operation completed successfully however there is a warning message e FailureWithWarning The operation failed with a warning message build Build number it is used only by Developer Technical Support correlationId Correlation ID it is used only by Developer Technical Support NOTE You must log and store this data for every response you receive PayPal Technical Support uses the informa
32. ile o o e ManageRecurringPaymentsProfileStatus o e BillOutstandingAmount ACCOUNT_BALANCE includes GetBalance NOTE You must have prior approval from PayPal to request this permission ENCRYPTED_WEBSITE_PAYMENTS includes Encrypted Website Payments NOTE You must have prior approval from PayPal to request this permission REFUND includes e RefundTransaction e Refund NON_REFERENCED_CREDIT includes DoNonReferencedCredit NOTE You must have prior approval from PayPal to request this permission BUTTON_MANAGER includes e BMManageButtonStatus BMCreateButton BMUpdateButton BMSet Inventory BMGet Inventory BMButtonSearch ACCESS _ BASIC PERSONAL DATA required for GetBasicPersonalData NOTE You must have prior approval from PayPal to request this permission May 2012 PayPal Permissions Service About the PayPal Permissions Service Permissions API Operations Display description Group ID includes Obtain advanced attributes for specified user such as date of ACCESS ADVANCED PERSONAL DATA required birth and phone for GetAdvancedPersonalData NOTE You must have prior approval from PayPal to request this permission includes ManagePendingTransactionStatus Accept or deny a pending transaction MANAGE_PENDING_ TRANSACTION STATUS Reporting for recurring payments RECURRING_PAYMENT_ REPORT valid for all co
33. kCode Acknowledgement code It is one of the following values e Success The operation completed successfully e Failure The operation failed e Warning Warning e SuccessWithWarning The operation completed successfully however there is a warning message e FailureWithWarning The operation failed with a warning message Build number it is used only by Developer Technical Support Correlation ID it is used only by Developer Technical Support NOTE You must log and store this data for every response you receive PayPal Technical Support uses the information to assist with reported issues Date on which the response was sent The time is currently not supported NOTE You must log and store this data for every response you receive PayPal Technical Support uses the information to assist with reported issues 58 May 2012 PayPal Permissions Service GetBasicPersonalData API Operation 7 PPFault Message PPFault Message The PPFaultMessage returns ErrorData and the ResponseEnvelope information to your application if an error occurs E FaultMessage e responseEnvelope 1 1 ResponseEnvelope e error 0 ErrorData ErrorData e errorld long e domain string e subdomain 0 1 string e severity ErrorSeverity ErrorCategory e category e message string e exceptionId 0 1 token e parameter 0 ErrorParameter FaultMessage Fields ResponseEnve
34. lope e timestamp 1 1 dateTime e ack 1 1 AckCode e correlationId 1 1 string e build 1 1 string T any o ErrorData e errorld long e domain string e subdomain 0 1 string e severity ErrorSeverity e category ErrorCategory e message string e exceptionId 0 1 token e parameter 0 ErrorParameter ErrorSeverity E ErrorCategory ErrorParameter name string Field Description error common ErrorData Detailed error information responseEnvelop common ResponseEnvelope Common response information including a timestamp and the response acknowledgement status PayPal Permissions Service May 2012 59 GetBasicPersonalData API Operation PPFault Message ErrorData Fields Field Description category common ErrorCategory The location where the error occurred Possible values are e System The system encountered errors try again e Application The application encountered errors try again e Request The request was incorrect domain The domain to which this service belongs errorld A number that uniquely identifies a particular error exceptionID This field is not used message A description of the error parameter common ErrorParameter Represents contextual information about the error severity common ErrorSeverity The severity of the error encountered Possible values are e Error Processing of the request w
35. ludes master account 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 New RECURRING_ PAYMENT REPORT valid for all Reporting for recurring payments countries except Indonesia Turkey Estonia and the Russian Federation New EXTENDED PRO PROCESSING REPORT valid for Extended Pro processing all countries except Indonesia Turkey Estonia and the Russian Federation New EXCEPTION PROCESSING _ REPORT valid for all Exception processing countries except Indonesia Turkey Estonia and the Russian Federation New ACCOUNT MANAGEMENT _PERMISSION valid for Account Management Permission MAM all countries except Indonesia Turkey Estonia and the Russian Federation 74 May 2012 PayPal Permissions Service Release 74 0 Features as Changes to RequestPermissionRequest Fields for Release 74 0 Field Description scope xs string Required New values e RECURRING_PAYMENT_ REPORT Reporting for recurring payments e EXTENDED_ PRO PROCESSING REPORT Extende
36. m cgi bin webscr cmd grant permission amp request_token oken Parameter Description cmd Required _grant permission request_token Required The token from the RequestPermissions response message Response to _grant permission command from PayPal PayPal redirects to the callback URL you set in the RequestPermissions request It may include the following parameters Parameter Description verification_code Verification code returned if the account holder agreed to grant permissions Expires after 15 minutes request_token The token from the RequestPermissions response message returned if the account holder agreed to grant permissions Error An error code which is equal to Internal Error if an error occurred If the account holder canceled no parameters are returned PayPal Permissions Service May 2012 71 Permission Commands _grant permission Command 72 May 2012 PayPal Permissions Service Past Releases Permissions Service is intended for developers implementing solutions that require executing a PayPal API operation on behalf of an account holder Enhancements introduced in past releases are described here Release 84 0 Features Release 84 0 of the Permissions API introduces two new permission groups and two new APIs NoTE Changes to API operations are backward compatible Addition of Two New Groups Display description Group ID includes New ACCESS_BASIC_PERSONAL_DATA
37. missions Service Index Symbols _ap payment flow command 71 A ack response field 28 30 36 38 44 46 50 52 58 60 66 68 attributeList request field 55 56 63 build response field 28 30 36 38 44 46 50 52 58 60 66 68 C callbackrequest field 26 CancelPermissions API operation 49 CancelPermissions errors 53 CancelPermissionsRequest fields 49 CancelPermissionsRequest message 49 CancelPermissionsResponse fields 50 CancelPermissionsResponse message 50 category field 30 38 46 52 60 68 correlationId response field 28 30 36 38 44 46 50 52 58 60 66 68 D detailLevel request field 27 34 41 49 56 64 domain field 30 38 46 52 60 68 E error PPFault field 29 37 45 51 59 67 ErrorData fields 30 38 46 52 60 68 errorld field 30 38 46 52 60 68 errorLanguage request field 27 34 41 49 56 64 exceptionID field 30 38 46 52 60 68 PayPal Permissions Service F FaultMessage PPFault fields 29 37 45 51 59 67 G generating signatures 20 GetAccessToken API operation 33 GetAccessToken errors 39 GetAccessTokenRequest fields 33 GetAccessTokenRequest message 33 GetAccessTokenResponse fields 35 GetAccessTokenResponse message 34 GetAdvancedPersonalData APT operation 63 GetAdvancedPersonalData errors 69 GetAdvancedPersonalDataRequest fields 63 GetAdvancedPersonalDataRequest Message 63 GetAdvancedPersonalDataResponse fields 65 GetAdvancedPersonalDataResp
38. n ErrorCategory The location where the error occurred Possible values are e System The system encountered errors try again e Application The application encountered errors try again e Request The request was incorrect domain The domain to which this service belongs errorld A number that uniquely identifies a particular error exceptionID This field is not used message A description of the error parameter common ErrorParameter Represents contextual information about the error severity common ErrorSeverity The severity of the error encountered Possible values are e Error Processing of the request was interrupted e Warning Processing of the request was completed subdomain This field is not used ResponseEnvelope Fields Field Description ack build correlationId common AckCode Acknowledgement code It is one of the following values e Success The operation completed successfully e Failure The operation failed e Warning Warning e SuccessWithWarning The operation completed successfully however there is a warning message e FailureWithWarning The operation failed with a warning message Build number it is used only by Developer Technical Support Correlation ID it is used only by Developer Technical Support NOTE You must log and store this data for every response you receive PayPal Technical Support uses the information to assist with reported Issues 38
39. n can Incorporate this task seamlessly by calling Permissions Service API operations 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 e 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 e 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 PayPal Permissions Service May 2012 11 E About the PayPal Permissions Service Permission Groups LoaQu Securty Center Search PayPal Grant Permission to Shopping
40. nce ENCRYPTED_WEBSITE_PAYMENTS Encrypted website payments REFUND Refunds NON_REFERENCED_ CREDIT Non referenced credit BUTTON_MANAGER Button Manager T T ANAGE_PENDING_TRANSACTION_ STATUS includes anagePendingTransactionStatus RECURRING_PAYMENT_REPORT Reporting for recurring payments EXTENDED_PRO_PROCESSING_REPORT Extended Pro processing EXCEPTION_PROCESSING_REPORT Exception processing ACCOUNT_MANAGEMENT_PERMISSION Account Management Permission MAM ACCESS_BASIC_PERSONAL_DATA User attributes e ACCESS ADVANCED PERSONAL DATA User attributes e INVOICING Invoicing T responseEnvelop common ResponseEnvelop Common response information including a timestamp and the response acknowledgement status PayPal Permissions Service May 2012 43 Les GetPermissions API Operation GetPermissionsResponse Message ResponseEnvelope Fields Field Description ack common AckCode Acknowledgement code It is one of the following values Success The operation completed successfully Failure The operation failed Warning Warning SuccessWithWarning The operation completed successfully however there is a warning message e FailureWithWarning The ope
41. nd store this data for every response you receive PayPal Technical Support uses the information to assist with reported issues timestamp Date on which the response was sent The time is currently not supported NOTE You must log and store this data for every response you receive PayPal Technical Support uses the information to assist with reported issues 28 May 2012 PayPal Permissions Service RequestPermissions API Operation PPFault Message PPFault Message The PPFaultMessage returns ErrorData and the ResponseEnvelope information to your application if an error occurs ResponseEnvelope E FaultMessage e timestamp 1 1 dateTime e ack 1 1 AckCode e correlationId 1 1 string e build 1 1 string T l any o e responseEnvelope 1 1 ResponseEnvelope e error 0 ErrorData ErrorData e errorld long e domain string e subdomain 0 1 string e severity ErrorSeverity e category ErrorCategory e message string e exceptionId 0 1 token e parameter 0 ErrorParameter ErrorData E ErrorSeverity e errorld long e domain string E ErrorCategory e subdomain 0 1 string e severity ErrorSeverity ErrorParameter name string e category ErrorCategory e message string e exceptionId 0 1 token e parameter 0 ErrorParameter FaultMessage Fields Field Description error common ErrorData Detail
42. ns 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 16 May 2012 PayPal Permissions Service Using the Permissions Service Use the Permissions Service API to obtain permission to execute PayPal API operations on behalf of PayPal account holders You can use PayPal SDKSs to generate authentication headers for PayPal Adaptive Payment and Adaptive Accounts APIs Obtaining Permissions To obtain permissions from an account holder you call RequestPermissions to make the request redirect to PayPal to enable the account holder to approve the request and call GetAccessToken to obtain the permissions and an access token The access token enables you to create a signature for calling APT operations as a third party determine the permissions you can access and cancel access to the permissions The following diagram shows the basic execution flow for obtaining permission as a third party to PayPal and an account holder PayPal Permissions Service May 2012 17 Using the Permissions Service Obtaining Permissions Legend mp Web Flow D API Call Request Token gt Access Token VW Verifier Code A Request RequestPermissions PayPal Response API Server L HTTP Redirect ma y Grant Permissions HTTP Redirect mmm YV mE a PayPar l
43. nse information including a timestamp and the response acknowledgement status PayPal Permissions Service May 2012 67 8 GetAdvancedPersonalData API Operation PPFault Message ErrorData Fields Field Description category common ErrorCategory The location where the error occurred Possible values are e System The system encountered errors try again e Application The application encountered errors try again e Request The request was incorrect domain The domain to which this service belongs errorId A number that uniquely identifies a particular error exceptionID This field is not used message A description of the error parameter common ErrorParameter Represents contextual information about the error severity common ErrorSeverity The severity of the error encountered Possible values are e Error Processing of the request was interrupted e Warning Processing of the request was completed subdomain This field is not used ResponseEnvelope Fields Field Description ack build correlationId common AckCode Acknowledgement code It is one of the following values e Success The operation completed successfully e Failure The operation failed e Warning Warning e SuccessWithWarning The operation completed successfully however there is a warning message e FailureWithWarning The operation failed with a warning message Build number it is used only by D
44. onse message 64 GetBasicPersonalData API operation 55 GetBasicPersonalData errors 61 GetBasicPersonalDataRequest fields 55 GetBasicPersonalDataRequest message 55 GetBasicPersonalDataResponse fields 57 GetBasicPersonalDataResponse message 56 GetPermissions APT operation 41 GetPermissions errors 47 GetPermissionsRequest fields 41 GetPermissionsRequest message 41 GetPermissionsResponse fields 43 GetPermissionsResponse message 42 message field 30 38 46 52 60 68 O obtaining permissions 17 overview 11 May 2012 79 80 P U parameter field 30 38 46 52 60 68 using Permissions Service 17 Permission API operations 15 PersonalAttribute request field 64 PersonalAttributeList request fields 64 V personalData response field 57 65 verifier request field 33 PersonalData response fields 58 65 personalDataKey response field 58 65 PersonalDataList response fields 57 65 personalDataValue response field 58 65 PPFault message 29 37 45 51 59 67 R requestEnvelope request field 26 33 41 49 55 63 RequestEnvelope request fields 27 34 41 49 56 64 RequestPermission API operation 25 RequestPermission request fields 26 RequestPermission request message 25 RequestPermission response fields 27 RequestPermission response message 27 RequestPermissions errors 31 response response field 57 responseEnvelope PPFault field 29 37 45 51 59 67 responseEnvelope request field 65 responseEnvelope response field 27 35 43
45. peration failed with a warning message Build number it is used only by Developer Technical Support Correlation ID it is used only by Developer Technical Support NOTE You must log and store this data for every response you receive PayPal Technical Support uses the information to assist with reported Issues 30 May 2012 PayPal Permissions Service RequestPermissions API Operation EN RequestPermission Errors Field Description timestamp Date on which the response was sent The time is currently not supported NOTE You must log and store this data for every response you receive PayPal Technical Support uses the information to assist with reported Issues RequestPermission Errors Code Message Additional Information 520002 Internal error 550001 User is not allowed to perform this action 560022 Invalid API Caller Account 580022 Transaction refused because of an invalid argument See additional error messages for details 580028 Invalid Redirect URL PayPal Permissions Service May 2012 31 RequestPermissions API Operation RequestPermission Errors 32 May 2012 PayPal Permissions Service GetAccessToken API Operation Use the GetAccessToken API operation to obtain an access token for a set of permissions GetAccessTokenRequest Message GetAccessTokenRequest RequestEnvelope e requestEnvelope 0 e token ses e verifier e subjectAlias Fl any 1 RequestEn
46. ration failed with a warning message build Build number it is used only by Developer Technical Support correlationld Correlation ID it is used only by Developer Technical Support NOTE You must log and store this data for every response you receive PayPal Technical Support uses the information to assist with reported issues timestamp Date on which the response was sent The time is currently not supported NOTE You must log and store this data for every response you receive PayPal Technical Support uses the information to assist with reported issues 44 May 2012 PayPal Permissions Service GetPermissions API Operation s PPFault Message PPFault Message The PPFaultMessage returns ErrorData and the ResponseEnvelope information to your application if an error occurs ResponseEnvelope FaultMessage e timestamp 1 1 dateTime e ack 1 1 AckCode e correlationId 1 1 string e build 1 1 string T any o e responseEnvelope 1 1 ResponseEnvelope e error 0 ErrorData ErrorData e errorld long e domain string e subdomain 0 1 string e severity ErrorSeverity e category ErrorCategory e message string e exceptionId 0 1 token e parameter 0 ErrorParameter ErrorData E ErrorSeverity e errorld long e domain string E ErrorCategory e subdomain 0 1 string e severity ErrorSeverity ErrorParameter name string e
47. rectPayment 12 May 2012 PayPal Permissions Service About the PayPal Permissions Service Permission Groups Display description Group ID includes Consolidate funds from two or more child accounts into a master account Provide reporting for consolidated funds Authorize and capture your PayPal transactions Use Express Checkout to process mobile payments Obtain authorization for pre approved payments and initiate pre approved transactions Process a payment based on a previous transaction Authorize transactions with Universal Air Travel Plans Initiate transactions to multiple recipients in a single batch 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 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 AUTH_CAPTURE includes e DoAuthorization e DoCapture e DoReauthorization e DoVoid MOBILE_ CHECKOUT includes e SetMobileCheckout e DoMobileCheckoutPayment e CreateMobilePayment BILLING_AGREEMENT includes e SetCustomerBillingAgreement E H CreateBil1 ngAgreement o e BillAg
48. reementUpdate e GetBillingAgreementCustomerDetail NOTE You must have prior approval from PayPal to request this permission REFERENCE_TRANSACTION includes DoReferenceTransaction NOTE You must have prior approval from PayPal to request this permission AIR TRAVEL includes e DOUATPAuthorization e DOUATPExpressCheckoutPayment MASS_PAY includes MassPay NOTE You must have prior approval from PayPal to request this permission PayPal Permissions Service May 2012 13 About the PayPal Permissions Service Permission Groups Display description Group ID includes Obtain transaction specific information Search your transactions for items that match specific criteria and display the results Create and manage recurring payments Obtain your PayPal account balance Dynamically encrypt PayPal payment buttons on your web site Refund a transaction on your behalf Issue a credit to a debit or credit card Create and manage PayPal payment buttons on your behalf Obtain basic attributes for specified user such as first name last name and payer ID TRANSACTION DETAILS includes GetTransactionDetails NOTE You must have prior approval from PayPal to request this permission RANSACTION_ SEARCH includes TransactionSearch RECURRING_PAYMENTS includes CreateRecurringPaymentsProfile GetRecurringPaymentsProfileDetails UpdateRecurringPaymentsProf
49. rmation to assist with reported issues 36 May 2012 PayPal Permissions Service GetAccessToken API Operation ES PPFault Message PPFault Message The PPFaultMessage returns ErrorData and the ResponseEnvel ope information to your application if an error occurs ResponseEnvelope E FaultMessage e timestamp 1 1 dateTime e ack 1 1 AckCode e correlationId 1 1 string e build 1 1 string T l any o e responseEnvelope 1 1 ResponseEnvelope e error 0 ErrorData ErrorData e errorld long e domain string e subdomain 0 1 string e severity ErrorSeverity e category ErrorCategory e message string e exceptionId 0 1 token e parameter 0 ErrorParameter ErrorData E ErrorSeverity e errorld long e domain string E ErrorCategory e subdomain 0 1 string e severity ErrorSeverity ErrorParameter name string e category ErrorCategory e message string e exceptionId 0 1 token e parameter 0 ErrorParameter FaultMessage Fields Field Description error common ErrorData Detailed error information responseEnvelop common ResponseEnvelope Common response information including a timestamp and the response acknowledgement status PayPal Permissions Service May 2012 37 4 GetAccessToken API Operation PPFault Message ErrorData Fields Field Description category commo
50. ry e message string e exceptionId 0 1 token e parameter 0 ErrorParameter ErrorData E ErrorSeverity e errorld long e domain string E ErrorCategory e subdomain 0 1 string e severity ErrorSeverity ErrorParameter name string e category ErrorCategory e message string e exceptionId 0 1 token e parameter 0 ErrorParameter FaultMessage Fields Field Description error common ErrorData Detailed error information responseEnvelop common ResponseEnvelope Common response information including a timestamp and the response acknowledgement status PayPal Permissions Service May 2012 51 j CancelPermissions API Operation PPFault Message ErrorData Fields Field Description category common ErrorCategory The location where the error occurred Possible values are e System The system encountered errors try again e Application The application encountered errors try again e Request The request was incorrect domain The domain to which this service belongs errorld A number that uniquely identifies a particular error exceptionID This field is not used message A description of the error parameter common ErrorParameter Represents contextual information about the error severity common ErrorSeverity The severity of the error encountered Possible values are e Error Processing of the request was interrupted e Warnin
51. schema org contact email Email http schema openid net contact fullname Full name http openid net schema company name Business name http axschema org contact count ry home Country https www paypal com webapps auth schema payerID Payer ID responseEnvelope common ResponseEnvelope Common response information including a timestamp and the response acknowledgement status PersonalDataList Fields Field Description personalData tns PersonalData The list of name value pairs of personal data in the response PayPal Permissions Service May 2012 57 GetBasicPersonalData API Operation GetBasicPersonalDataResponse Message PersonalData Fields Field Description personalDataKey personalDataValue tns PersonalAttribute The attributes whose values you are requesting You specify one or more of the following URIs e http axschema org namePerson first First name ttp axschema org namePerson last last name ttp axschema org contact email Email ttp schema openid net contact fullname Full name ttp openid net schema company name Business name ttp axschema org contact count ry home Country ttps www paypal com webapps auth schema payerID Payer ID N nN N N A A xs String The value associated with the key ResponseEnvelope Fields Field Description ack build correlationId timestamp common Ac
52. ssToken API Operation 33 GetAccessTokenRequest Message 33 PayPal Permissions Service May 2012 Contents GetAccessTokenRequest Fields RequestEnvelope Fields GetAccessToken Response Message GetAccessTokenResponse Fields ResponseEnvelope Fields PPFault Message FaultMessage Fields ErrorData Fields ResponseEnvelope Fields GetAccessToken Errors Chapter 5 GetPermissions API Operation GetPermissionsRequest Message GetPermissionsRequest Fields RequestEnvelope Fields GetPermissionsResponse Message GetPermissionsResponse Fields ResponseEnvelope Fields PPFault Message FaultMessage Fields ErrorData Fields ResponseEnvelope Fields GetPermissions Errors Chapter 6 CancelPermissions API Operation CancelPermissionsRequest Message CancelPermissionsRequest Fields RequestEnvelope Fields CancelPermissionsResponse Message CancelPermissions Response Fields ResponseEnvelope Fields
53. t Response gt Permissions AP Server To obtain permissions from an account holder follow these steps 1 Setup your request and call the RequestPermissions API operation Specify the return URL in the callback field Specify one or more group IDs such as EXPRESS_CHECKOUT in the scope field one string per group ID Send the request to the https svcs paypal com Permissions RequestPermission endpoint NOTE Use https svcs sandbox paypal com Permissions for the Sandbox 18 May 2012 PayPal Permissions Service ht Wr amp S amp C Using the Permissions Service Obtaining Permissions ERID api username SECURITY PASSWORD api password ECURITY SIGNATURE api signature T tps svcs sandbox paypal com Permissions RequestPermissions d rl s insecure X PAYPAL SECURITY US X PAYPA K X PAYPAL SE X PAYPAL REQUEST DATA FORMAT NV K X PAYPAL RESPONSE DATA FORMAT NV X PAYPAL APPLICATION ID app id questEnvelope errorLanguage en_US cope EXPRESS_CHECKOUT allback http your retum url PayPal responds with a request token that you use in following steps to obtain an access token NOTE The request token from this step is different than the access token which you use to access permissions that already have been granted 2 Redirect the account holder s browser to PayPal and include the request token in the req
54. t println entry getKey entry getValue catch Exception e handle exceptio D PayPal Permissions Service May 2012 21 22 Using the Permissions Service Granting Permission to Access Account Holder Information Granting Permission to Access Account Holder Information After you have created an authentication header as described above you can call Get information about the account holder Basic information includes the following e First Name e Last Name Email Full Name Business Name Country PayerID Advanced information includes the following Date of birth e e Postcode e Street Street2 City State Phone BasicPersonalData and GetAdvancedPersonalData to obtain basic and advanced These two API calls work like all other APIs in PayPal if you have permission the call will succeed if not the call will fail For both APIs if the account holder has not given consent to access the requested data the service will return an error indicating that you do not have permission to perform the action on behalf of another user The form of the call is as follows A curl s insecure ZATION token signature DATA FORMAT NV F DATA FORMAT NV H X PAYPAL AUTHORI H X PAYPAL REQUEST H X PAYPAL RESPONS H d attributeList at K X PAYPAL APPLICATION ID APP 1JE4291016473214C tribute 0 http axschema org contact
55. the right to make changes to any information herein without further notice Contents What s New 7 Release 89 Changes 7 Preface 9 Documentation Feedback 9 Chapter 1 About the PayPal Permissions Service 11 Permissions Service Overview 11 Permission Groups 12 Permissions API Operations 15 Chapter 2 Using the Permissions Service 17 Obtaining Permissions ooo a 17 Generating Signatures for the Authentication Header 20 Granting Permission to Access Account Holder Information 22 Chapter 3 RequestPermissions API Operation 25 RequestPermissionsRequest Message 25 RequestPermissions Request Fields 26 RequestEnvelope Fields 27 RequestPermissionsResponse Message 27 RequestPermissions Response Fields 27 ResponseEnvelope Fields 28 PPFault Message 24 424 22 Be ee ds DE at ae EAS Be ed S kS 29 FaultMessage Fields a aa a 29 ErrorData Fields u ss s a b k a k a 30 ResponseEnvelope Fields 30 RequestPermission Errors 31 Chapter 4 GetAcce
56. tion to assist with reported issues timestamp Date on which the response was sent The time is currently not supported NOTE You must log and store this data for every response you receive PayPal Technical Support uses the information to assist with reported issues 66 May 2012 PayPal Permissions Service GetAdvancedPersonalData API Operation ESE PPFault Message PPFault Message The PPFaultMessage returns ErrorData and the ResponseEnvel ope information to your application if an error occurs ResponseEnvelope E FaultMessage e timestamp 1 1 dateTime e ack 1 1 AckCode e correlationId 1 1 string e build 1 1 string T l any o e responseEnvelope 1 1 ResponseEnvelope e error 0 ErrorData ErrorData e errorld long e domain string e subdomain 0 1 string e severity ErrorSeverity e category ErrorCategory e message string e exceptionId 0 1 token e parameter 0 ErrorParameter ErrorData E ErrorSeverity e errorld long e domain string E ErrorCategory e subdomain 0 1 string e severity ErrorSeverity ErrorParameter name string e category ErrorCategory e message string e exceptionId 0 1 token e parameter 0 ErrorParameter FaultMessage Fields Field Description error common ErrorData Detailed error information responseEnvelop common ResponseEnvelope Common respo
57. uest_token parameter https www paypal com cgi bin webscr cmd _grant permission amp request_token loken PayPal initiates granting permissions When the account holder grants permissions PayPal returns a verification code which you use in the next step NOTE The verification code expires in about 15 minutes 3 Set up your request and call the GetAccessToken API operation Specify the request token in the token field Specify the verification code in the verifier field Send the request to https svcs paypal com Permissions GetAccessToken PayPal Permissions Service May 2012 19 ze Using the Permissions Service Generating Signatures for the Authentication Header curl s insecur H X PAYPAL SECURITY USI H X PAYPAL SECURITY PASSWORD api password H X PAYPAL SECURITY SIGNATURE api signature H X PAYPAL REQUEST DATA FORMAT NV E H X PAYPAL RESP ERID api username ONSE DATA FORMAT NV K requestEnvelope amp token token s amp verifier code H X PAYPAL APPLICATION ID appi id https svcs sandbox paypal com Permissions GetAccessToken d rrorLanguage en_US PayPal responds with the scope which is a list of the permissions granted by the account holder and an access token and associated secret After Completing This Task You use the access token and associated secret to create an authentication header X PAYPAL
58. untries 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 Manager your invoicing through a third party INVOICING includes UpdateInvoice CancelInvoice GetInvoiceDetails MarkInvoiceAsPaid SearchInvoices Createlnvoice 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 PayPal Permissions Service May 2012 15 E About the PayPal Permissions Service Permissions API Operations API Operation Description GetPermissions Use the GetPermissons API operation to obtain the permissio
59. velope e errorLanguage 1 1 string string f any 0 string string GetAccessTokenRequest Fields Field Description token xs string Required The request token from the response to RequestPermissions verifier xs string Required The verification code returned in the redirect from PayPal to the return URL subjectAlias xs string Do not use requestEnvelope common requestEnvelope Required Information common to each API operation such as the language in which an error message is returned PayPal Permissions Service May 2012 33 4 GetAccessToken API Operation GetAccess Token Response Message RequestEnvelope Fields Field Description detailLevel common DetailLevelCode Optional Level of detail required by the client application for components It is one of the following values e ReturnAll This value provides the maximum level of detail default errorLanguage xs string Required RFC 3066 language in which error messages are returned by default it is en_US which is the only language currently supported GetAccessToken Response Message E GetAccessTokenResponse ResponseEnvelope e timestamp 1 1 dateTime e responseEnvelope ResponseEnvelope e ack 0 1 AckCode e correlationId 1 1 string e build 1 1 string any 0 e scope 0 string e token string e tokenSecret string 34 May 2012 PayPal Permissions Service GetAc

PayPal Permissions Service - 2012 User's Guide

Contents

Download Pdf Manuals

Related Search

Related Contents