File: documentation/API.txt

+----------------------------+
|---------+ INTRO +----------|
+----------------------------+

The paypal api class is very easy to use, and should work without modification providing the constants in SnPayPalConfig (.class.php) are set correctly,
you can obtain the information from paypal.com, see the comments in the file.

The API for the package is available in /phpdoc/ but i will explain how certain aspects of the classes are used here. 
Note, if you are going to use a function check the source comments also, they may contain more up-to-date information.

Even if you do not intent to use the CLI classes associated with this package it is also worth reading CLI.txt 
as some aspects of the main classes are explain there also.


Basic usage boils down to calling a function of SnPayPalAPi,
<?php

$paypal = new SnPayPalApi();

$balanceResponse = $paypal->getBalance()->getResponse('GetBalanceResponse');

echo $balanceResponse->Balance;

?>

This is a stadard format for all requests,

<?php

$response = $payapl->apiMethod()->getResponse('PayPal_SOAP_ELEMENT');

?>

If you want to obtain the raw xml use ->getXml(), which will return the SOAP BODY, if you want the FULL SOAP RESPONSE (which is unlikely)
you can set SnPayPalApi->rtnSoapBody to false,

<?php

$paypal = new SnPayPalApi();
$paypal->rtnSoapBody = false;
$response = $paypal->...->getXml();

?>

This will give you the entire soap packet as a string, you can also get the entire soap packet parsed into objects with ->getResponse().
In almost all cases you do not want the entire packet, which contains meta irrelevant to your request, you do not even want the body,
but a subsection of the body, you can find out which subsection using the PayPal API Ref provided, or a newer version from there site.

Page 102 outlines the response from a refundTransaction request, which has been implemented in SnPayPalApi

<?php
$transId = 'transaction_id';
$response = $paypal->refundTransaction($transId);
?>

We can find out what subsection we're after, and the fields assocaiated with  it on p102,

"TABLE 8.2 RefundTransactionResponse Fields
RefundTransactionID
...
GrossRefundAmount
...etc."

so we could access GrossRefundAmount by,


<?php
$transId = 'transaction_id';
$response = $paypal->refundTransaction($transId)->getResponse('RefundTransactionResponse');
echo $response->GrossRefundAmount;
?>

At this point i should note that SnPayPalApi->getBalance uses an undocumented API, so i will provide the current API here,

the soap body contains,
<GetBalanceResponse>
<Timestamp/>
<Ack>Success</Ack>
<Version />
<Build />
<Balance currencyID="" />
<BalanceTimeStamp/>
</GetBalanceResponse>

(with actual values removed)

The CLI function checkBalance() shows how to access some of these,

        if ($response = $paypal->getBalance()->getResponse('GetBalanceResponse')) 
        {
            $cli->write('Balance: ' . $response->Balance . ' ' . $response->Balance['currencyID']);
            $cli->write('Read on: ' . date('F dS Y - H:i', strtotime($response->BalanceTimeStamp)));
            return true;
        }

You can see the SOAP packet sent for any request using $paypal->getSoapSent(), the soap packet is nicely formated with newlines.

+------------------------------------+
|---------+ ADDING AN API +----------|
+------------------------------------+

Opening SnPayPalApi.class.php reveals the simiplicity of adding a PayPalApi Function, for example,

    public function transactionSearchByDate($startDate, $endDate)
    {
        return $this->callAPI('TransactionSearch', array(new SnPayPalApiParameter('StartDate', $startDate,'xs:dateTime'),
                                                         new SnPayPalApiParameter('EndDate',   $endDate,  'xs:dateTime')));
    }

The title of the API (in the reference, e.g. TransactionSearch API p105) is the first parameter, 
the second is an array containing the required fields for the request, on p106 TBL 9.1, the reference states you can supply a Payer field,
with type 'ebl:EmailAddress' adding that is as simple as adding a new SnPayPalApiParameter with the appropriate name and a new function param,

public function transactionSearchByDate($startDate, $endDate, $payer)...

        return $this->callAPI('TransactionSearch', array(new SnPayPalApiParameter('StartDate', $startDate,'xs:dateTime'),
                                                         new SnPayPalApiParameter('EndDate',   $endDate,  'xs:dateTime'),
                                                         new SnPayPalApiParameter('Payer',     $payer,  'ebl:EmailAddress')));

You could then call this via $paypal->transactionSearchByDate(date('c'), date('c', (time() - (24*3600))), 'email@example.com');

adding ->getResponse('RefundTransactionResponse') to access the body contents, see p102 for details on the fields contained within.

Note all paypal dates are in ISO "date('c')" format, above i supplied today and yesterday as the dates.


The basic TransactionSearchResponse contains only a select number of fiends, you can perform a comprehensive 'GetTransactionDetails'
search if you have a transactionId, fullTransactionSearchByDate() combines these two apis to perform a comprehensive search by date,

    public function fullTransactionSearchByDate($startDate, $endDate)...
        
        $transactionResponse = $this->transactionSearchByDate($startDate, $endDate)->getResponse('TransactionSearchResponse');
        return $this->getTransactionDetails($transactionResponse->PaymentTransactions->TransactionID);

Note: when PayPalSoapResponse objects (those returned by ->getResponse()) contain arrays, such as having multiple transactions,
some operations such as casting to a string (performed by more functions that is initially realised) can destroy those arrays,
see the getTransactions() method of SnCliPayPalMethods for an implementation of SnPayPalApi->transactionSearchByType().