Trolley PHP SDK Major Update (May 1, 2023)

With this update we're making some important changes to our PHP SDK.
This update covers all the API endpoints our SDK didn't cover before. We are also renaming all classes to Trolley to complete our rebranding.

To mark this milestone we're moving to our first major version 3.0.0, and are releasing this version under a new name.

Please read this Update Guide to understand what changed and how to adopt these changes.

Breaking Changes

1. New package on Packagist

Our PHP SDK is now available under a new namespace on Packagist, which is as per our new name 'Trolley' : https://packagist.org/packages/trolley/core

With this update, you'll have to make changes to how Trolley SDK is referenced and used in your code:

The command you used to install the SDK now changes:

Old Installation	New Installation
`composer require paymentrails/php-sdk`	`composer require trolley/core`

If you're adding the package directly in your package.json you'll need to replace it with the new package name:

Old Package	New Package
`"paymentrails/php-sdk": "^2.1"`	`"trolley/core": "^3.0"`

2. All “PaymentRails” classes rebranded to “Trolley”

To complete our rebranding, all the classes called PaymentRails are now called Trolley. You'll need to rename all the class usage in your code.

Old usage

$recipients = PaymentRails\Recipient::all();

New usage

$recipients = Trolley\Recipient::all();

A simple find-and-replace should be helpful in replacing the class names.

3. No need to specify environment now

The SDK now defaults to the production URL i.e. api.trolley.com.
Even while setting up a proxy you no longer need to provide an environment.

Old way

PaymentRails\Configuration::environment('production');
PaymentRails\Configuration::publicKey(ACCESS_KEY);
PaymentRails\Configuration::privateKey(ACCESS_SECRET);

New way

Trolley\Configuration::publicKey(ACCESS_KEY);
Trolley\Configuration::privateKey(SECRET_KEY);

4. Updated `RecipientAccount` attributes

All the attributes of the RecipientAccount class have been updated to match the lates API response as per our documentation.
There were some attributes which were not getting populated because the API response would not contain them.

Please review the lib/Trolley/RecipientAccount.php in PR#42 to see what's changing and update your code accordingly

Deprecated Methods

1. `Payment.all()` deprecated

The function Payment.all() was returning all payments of a recipient. Since it's related to the Recipient model, this functionality is being moved Recipient.getAllPayments() method.

The functionality remains the same, only the class name changes.

Payment.all() currently co-exists with Recipient.getAllPayments() right now, but will be removed by Q3 2023.

Old way

$recipientPayments = PaymentRails\Payment::all($recipientId);

New way

$recipientPayments = Trolley\Recipient::getAllPayments($recipientId);

2. Attribute `Recipient.governmentId` deprecated

The Recipient.governmentId is being deprecated as of version 3.0.0 and will be removed by Q3 2023.
It's being replaced by the new attribute Recipient.governmentIds, which is an array whose each element represents the individual governmentIDs uploaded by the recipient.

Updates to Existing Methods

1. Support for Errors as Arrays

The API returns errors in a JSON array. To support this, we have added a way for you to access the errors as an Array as well.
This should make it easier for you to iterate through the array and process the errors.

The array can be accessed through errorArray variable of the StandardException class, accessible through the function getAllErrorsAsArray().

Example: Consuming error Array

...
catch(Trolley\Exception\Standard $e){
     print_r(count($e->getAllErrorsAsArray()));
 }
...

2. Batch Summary attribute update

The responses sent by the Batch Summary API were not parsed and assigned correctly, so we update it to work correctly.

Example

$summary = Trolley\Batch::summary($batch->id);
print_r($summary->methods);
print_r($summary->methods['bank-transfer']['count']);

You don't need to make any code changes, your old code will still work.
This just gives more options to you to process error messages should you want.

3. Batch index methods now include payments

Any operations (such as Find a Batch) that include payments inside the Batch will now be accessible via the Batch object.

Example

$batch = Trolley\Batch::find($batch->id);
print_r($batch->payments[0]->id);

You don't need to make any code changes, your old code will still work.
This just gives more options to you to process error messages should you want.

New Methods/API Coverage

We have added support for more API endpoints that our PHP SDK wasn't supporting earlier. Here's a rundown of the new API endpoints covered:

Recipient

1. `Recipient.deleteMultiple()` - Delete Multiple Recipients

$deleteResult = Trolley\Recipient::deleteMultiple([$recipientAlpha->id, $recipientBeta->id]);

2. `Recipient.getAllLogs()` - Get all logs of a Recipient

$allLogs = Trolley\Recipient::getAllLogs($recipient->id);

3. `Recipient.getAllPayments()` - Get all payments of a Recipient

$all = Trolley\Recipient::getAllPayments($recipient->id);

Batch

4. `Batch.deleteMultiple()` - Delete Multiple Batches

$response = Trolley\Batch::deleteMultiple([$batchAlpha->id, $batchBeta->id]);

Offline Payment

5. `OfflinePayment.all()` - Fetch All Offline Paymenta

$allOfflinePayments = Trolley\OfflinePayment::all(1,10);

Invoices

6. `Invoice.create()` - Create a new Invoice

$newInvoice = Trolley\Invoice::create([
      "recipientId" 	=> $recipient->id,
      "description" 	=> "May Invoice",
      "externalId"	=> "May-Invoice-".($recipientId)
    ]);

7. `Invoice.fetch()` - Fetch details of a single Invoice

$invoice = Trolley\Invoice::fetch($invoice->id);

8. `Invoice.listAll()` - List all Invoices in your merchant account

$allInvoices = Trolley\Invoice::listAll();

9. `Invoice.search()` - Search for Invoices

$searchResults = Trolley\Invoice::search([
	  "recipientId" => [$recipient->id],
	  "page" => 1,
	  "pageSize" => 5
	]);

10. `Invoice.update()` - Update details of an Invoice

$updateInvoice = Trolley\Invoice::update([
	"invoiceId" 	=> $invoice->id,
    "description" 	=> "Updated Invoice Description",
    ]);

11. `Invoice.delete()` - Delete an Invoice

$deleteInvoice = Trolley\Invoice::delete($invoice->id);

12. `Invoice.deleteMultiple()` - Delete Multiple Invoices

$deleteInvoices = Trolley\Invoice::deleteMultiple([
		$firstInvoice->id,
		$secondInvoice->id
	]);

Invoice Line

13. `InvoiceLine.create()` - Create an Invoice Line

$invoiceWithLines = Trolley\InvoiceLine::create($invoice->id, [
		[
			"unitAmount" =>[
				"value" => "50.00",
			 	"currency" => "EUR"
			],
			"description" 	=> "first line",
			"category"		=> Trolley\InvoiceLine::$categories["services"]
		],
		...
	]);

14. `InvoiceLine.update()` - Update an Invoice Line

$updatedInvoice = Trolley\InvoiceLine::update($newInvoice->id, [
		[
			"invoiceLineId" => $invoice->lines[0]->id,
			"description"	=> "updated first line"
		],
		...
	]);

15. `InvoiceLine.delete()` - Delete an Invoice Line

$deleteInvoice = Trolley\Invoice::delete($invoice->id);

Invoice Payment

16. `InvoicePayment.create()` - Create an Invoice Payment

$invoicePayment = Trolley\InvoicePayment::create([
    [
        "invoiceId" => $invoice->id,
        "invoiceLineId" => $invoice->lines[0]->id,
        "amount" => [
            "value" => $invoice->lines[0]->unitAmount["value"],
            "currency" => $invoice->lines[0]->unitAmount["currency"]
        ]
    ],
    ...
]);

17. `InvoicePayment.update()` - Update an Invoice Payment

$updatedInvoicePayment = Trolley\InvoicePayment::update([
    "invoiceLineId" => $invoice->lines[0]->id,
    "paymentId" => $invoicePayment[0]->paymentId,
    "amount" => [
        "value" => "102.10",
        "currency" => $invoice->lines[0]->unitAmount["currency"]
    ]
]);

18. `InvoicePayment.search()` - Search for an Invoice Payment

$searchInvoicePayment = Trolley\InvoicePayment::search([$invoicePayment[0]->paymentId], [$invoice->id]);

19. `InvoicePayment.delete()` - Delete an Invoice Payment

$deleteInvoicePayments = Trolley\InvoicePayment::delete($invoicePayment[0]->paymentId, [
    $invoice->lines[0]->id,
    $invoice->lines[1]->id
]);

Balances

20. `Balance.getTrolleyAccountBalance()` - Get Balance of all Trolley Accounts

$trolleyBalances = Trolley\Balance::getTrolleyAccountBalance();

21. `Balance.getPaypalAccountBalance()` - Get Balance of all Trolley Accounts

$paypalBalances = Trolley\Balance::getPaypalAccountBalance();

We hope these new updates help you build Trolley integration faster and more reliably.
If you have any questions or find any bugs, please open an issue or reach out to us at [email protected]
Collaborations and PRs are welcome.

v3.0.0

Trolley PHP SDK Major Update (May 1, 2023)

Breaking Changes

1. New package on Packagist

2. All “PaymentRails” classes rebranded to “Trolley”

Old usage

New usage

3. No need to specify environment now

Old way

New way

4. Updated RecipientAccount attributes

Deprecated Methods

1. Payment.all() deprecated

Old way

New way

2. Attribute Recipient.governmentId deprecated

Updates to Existing Methods

1. Support for Errors as Arrays

Example: Consuming error Array

2. Batch Summary attribute update

Example

3. Batch index methods now include payments

Example

New Methods/API Coverage

Recipient

1. Recipient.deleteMultiple() - Delete Multiple Recipients

2. Recipient.getAllLogs() - Get all logs of a Recipient

3. Recipient.getAllPayments() - Get all payments of a Recipient

Batch

4. Batch.deleteMultiple() - Delete Multiple Batches

Offline Payment

5. OfflinePayment.all() - Fetch All Offline Paymenta

Invoices

6. Invoice.create() - Create a new Invoice

7. Invoice.fetch() - Fetch details of a single Invoice

8. Invoice.listAll() - List all Invoices in your merchant account

9. Invoice.search() - Search for Invoices

10. Invoice.update() - Update details of an Invoice

11. Invoice.delete() - Delete an Invoice

12. Invoice.deleteMultiple() - Delete Multiple Invoices

Invoice Line

13. InvoiceLine.create() - Create an Invoice Line

14. InvoiceLine.update() - Update an Invoice Line

15. InvoiceLine.delete() - Delete an Invoice Line

Invoice Payment

16. InvoicePayment.create() - Create an Invoice Payment

17. InvoicePayment.update() - Update an Invoice Payment

18. InvoicePayment.search() - Search for an Invoice Payment

19. InvoicePayment.delete() - Delete an Invoice Payment

Balances

20. Balance.getTrolleyAccountBalance() - Get Balance of all Trolley Accounts

21. Balance.getPaypalAccountBalance() - Get Balance of all Trolley Accounts

Uh oh!

4. Updated `RecipientAccount` attributes

1. `Payment.all()` deprecated

2. Attribute `Recipient.governmentId` deprecated

1. `Recipient.deleteMultiple()` - Delete Multiple Recipients

2. `Recipient.getAllLogs()` - Get all logs of a Recipient

3. `Recipient.getAllPayments()` - Get all payments of a Recipient

4. `Batch.deleteMultiple()` - Delete Multiple Batches

5. `OfflinePayment.all()` - Fetch All Offline Paymenta

6. `Invoice.create()` - Create a new Invoice

7. `Invoice.fetch()` - Fetch details of a single Invoice

8. `Invoice.listAll()` - List all Invoices in your merchant account

9. `Invoice.search()` - Search for Invoices

10. `Invoice.update()` - Update details of an Invoice

11. `Invoice.delete()` - Delete an Invoice

12. `Invoice.deleteMultiple()` - Delete Multiple Invoices

13. `InvoiceLine.create()` - Create an Invoice Line

14. `InvoiceLine.update()` - Update an Invoice Line

15. `InvoiceLine.delete()` - Delete an Invoice Line

16. `InvoicePayment.create()` - Create an Invoice Payment

17. `InvoicePayment.update()` - Update an Invoice Payment

18. `InvoicePayment.search()` - Search for an Invoice Payment

19. `InvoicePayment.delete()` - Delete an Invoice Payment

20. `Balance.getTrolleyAccountBalance()` - Get Balance of all Trolley Accounts

21. `Balance.getPaypalAccountBalance()` - Get Balance of all Trolley Accounts