Requirements
Your server must run the latest PHP version with the native SoapClient class.
You first need to download the generated package from this page. The generated package gathers classes by their type (Service, Struct and Enum) so you can quickly find a class. It includes :
- the sample file: the file that shows you how to start using the generated package
- the autoload file: the file which loads all the generated class with the good path
- the main WsdlClass class: the class from which each generated class inherits in order to inherit usefull methods and generic methods to deal with the SoapClient
- the ClassMap class: the class which defines the mapping between native PayPal SOAP structs and generated classes
- all the classes required to communicate with the PayPal SOAP API
If you have a good IDE, then it should be really easy to navigate trough all these numerous classes.
A simple case: get your account balance
To get your account balance, you need to call the GetBalance operation. This operation is located in the Get service class named PayPalServiceGet. When calling this operation, you'll get the amount available on your account. If you have multiple currencies, you will be able to get your account balance either in only one currency or in each currency.
You can also read the official PayPal GetBalance SOAP operation.
First step: load classes and set configuration
The generated package includes an autoload file which makes easy to load all the generated classes at once.
require_once __DIR__ . '/PayPalAutoload.php';
We suppose your file is located in the root directory of the extracted package you just downloaded.
When all classes are loaded, you can define the configuration to call the SOAP API. This configuration is required to instantiate any PayPal service class.
$wsdl = array();
$wsdl[PayPalWsdlClass::WSDL_URL] = 'https://www.paypalobjects.com/wsdl/PayPalSvc.wsdl';
// no cache so you always get the latest version, slower so you can comment this line if you prefer
$wsdl[PayPalWsdlClass::WSDL_CACHE_WSDL] = WSDL_CACHE_NONE;Second step: instantiate the Get service
As we defined the required configuration as the $wsdl PHP array variable, we now just have to instantiate the Get service object like this:
$get = new PayPalServiceGet($wsdl);At this step, the SoapClient object have been initiated with:
- https://www.paypalobjects.com/wsdl/PayPalSvc.wsdl as the WSDL URL
- no cache for the WSDL content
- a classmap: the array returned by the PayPalClassMap::classMap() method
You can call the PayPalWsdlClass::getSoapClient() method to have access to the SoapClient object. If you are familiar with the SoapClient class, you can even use this object instead of going further. The benefits of using the generated classes is that there is a native error handler while calling operations and so on.
Third step: set the credentials
When you call a PayPal SOAP API operation, you have to send a header in order to be identified. When a header is required, a doc block is defined for the generated method. In our case, the GetBalance operation requires a header named RequesterCredentials in the namespace urn:ebay:api:PayPalAPI. The value of the header must be a PayPalStructCustomSecurityHeaderType object. We use the signature authentication method. To get your signature credentials (username, password, signature), you have to go to your PayPal account and get your API access. When you have them, you set the header like this:
$password = new PayPalStructUserIdPasswordType();
$password->setPassword('your PayPal API access password');
$password->setUsername('your PayPal API access username');
$password->setSignature('your PayPal API access signature');
$get->setSoapHeaderRequesterCredentials(new PayPalStructCustomSecurityHeaderType(null,null,$password));The setSoapHeaderRequesterCredentials method is a method which is automatically generated as soon as a header is detected as required for an operation call. As you can see, we only send one parameter which is the expected header value because this method takes care of setting the namespace and the header name. This method is dedicated to the RequesterCredentials header and set the namespace as urn:ebay:api:PayPalAPI by default. If you wish to customize the header information, here is the generated generic methods signature:
- setSoapHeaderRequesterCredentials(PayPalStructCustomSecurityHeaderType $_payPalStructCustomSecurityHeaderType,$_nameSpace = 'urn:ebay:api:PayPalAPI',$_mustUnderstand = false,$_actor= null)
- $_payPalStructCustomSecurityHeaderType: the header value
- $_nameSpace: the namespace value
- $_mustUnderstand: tells to the SoapClient if the Web service must understand or not the the header
- $_actor: the header actor
If you want to fully understand this method, please refer to the native SoapClient::__setSoapheaders() method and the native SoapHeader class.
Fourth step: set the Web service location
As the operation is not critical for your account integrity (because it only gets your account balance) we are going to set the Web service location to the production environment. Indeed, PayPal provides multiple Web service locations depending on your development process and the protocol you use to call the Web service (SOAP or REST). In our case, the location is then the production environment and is set like this:
$get->setLocation('https://api-3t.paypal.com/2.0/');Access to all PayPal API endpoints.
Last step: call the GetBalance operation
The final step consists in calling the PayPalServiceGet::GetBalance() method. In order to do that, we proceed as following:
// 1: all currencies, 0: your main currency
$requestType = new PayPalStructGetBalanceRequestType(0);
// the latest available version of the PayPal API, indicated in the "ns:version" attribute of the WSDL definitions root tag
$requestType->setVersion(98.0);
$result = $get->GetBalance(new PayPalStructGetBalanceReq($requestType));
if($result)
echo "\r\nYour PayPal account balance amount is: " . $result->getBalance()->get_();
else
print_r($get->getLastError());
If everything goes well, the get_() method returns the numeric amount of your account balance.
Otherwise, you have to analyze the last error catched when the PayPalServiceGet::GetBalance() method has been called by calling the generic PayPalWsdlClass::getLastError() method.
Conclusion
As you can see, getting your account balance is pretty trivial. We saw that each value is OOP and that responses are entirely returned as objects so we can easily manipulate them. The generated classes aim to ease the communication with SOAP Web services at each step. If you have any question, feel free to send me comments on this topic. Now, you can easily call any other PayPal API operation by following this methodology.
This test can easily be done with the intuitive Web interface. In order to do that:
- you first need to log with your account
- generate the package with the WSDL indicated at the top
- then follow these steps using the interface
For more information, read the dedicated article to get your PayPal account balance with the intuitive Web interface.