Trolley .Net SDK Major Update (Nov 20, 2023)

With this update we're making some important changes to our C# .Net SDK.
This update covers all the API endpoints our SDK didn't cover before, and makes some important updates to how our packages are organized.

To mark this milestone we're bumping up the MAJOR version 2.0.0.

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

Breaking Changes

1. PaymentRails renamed to Trolley

We have completed our rebranding and now all instances of PaymentRails have been replaced with Trolley accordingly and wherever needed.

This means the classes have been renamed too.

You'll need to optimize imports in your project to adopt to this change.

Here's an example of how it used to be before vs how it is now:

Old Package	New Installation
`using PaymentRails.Types;`	`using Trolley.Types;`
`PaymentRails.Gateway gateway = ...;`	`Trolley.Gateway gateway = ...;`

2. Package reorganization

We have completed our rebranding and now all instances of PaymentRails have been replaced with Trolley accordingly and wherever needed.

This means the classes have been renamed too.

You'll need to optimize imports in your project to adopt to this change.

Here's an example of how it used to be before vs how it is now:

Old Package	New Installation
`using PaymentRails.Types;`	`using Trolley.Types;`
`PaymentRails.Gateway gateway = ...;`	`Trolley.Gateway gateway = ...;`

3. Methods renamed

To comply with .NET naming conventions, all Gateway methods have been renamed, wherever required.

Here's an example:

Old Name	New Name
`Recipient.create()`	`Recipient.Create()`
`Batch.delete()`	`Batch.Delete()`

In most of the cases, you'll just need to rename the methods and reference them by the new names.

There are other specific breaking changes born out of renaming that are discussed below:

1. Method `RecipientGateway.all()` renamed

This method has been renamed to RecipientGateway.ListAllRecipients(). This method also allows you to provide a search term.

...
Gateway gateway = new Trolley.Gateway("<ACCESS_KEY>","<SECRET_KEY>");

int page = 1;
int pageSize = 10;

// Get all recipients with an optional search term and manual pagination
Recipients allRecipients = gateway.recipient.ListAllRecipients("<search_term>", page, pageSize);
List<Recipient> recipients = allRecipients.recipients;

Meta meta = allRecipients.meta;
int nextPage = page < meta.pages ? (meta.page + 1) : -1;

// Or, with auto-pagination with an IEnumerable object
var recipients = gateway.recipient.ListAllRecipients("<search_term>");

foreach(Recipient recipient in recipients){
  Console.WriteLine(recipient.id);
}	
...

2. Method `RecipientGateway.update(Recipient)` updated

This method has been updated to RecipientGateway.Update(string, Recipient). You now have to provide the recipientId separately as a string.

...
Gateway gateway = new Trolley.Gateway("<ACCESS_KEY>","<SECRET_KEY>");

Recipient recipient = getUpdateRecipientBody();
string recipientId = getRecipientIdToUpdate();
bool response = gateway.recipient.Update(recipientId, recipient);
...

3. Method variants of `RecipientGateway.Search()` deleted

All instances of RecipientGateway.Search() method have been deleted, RecipientGateway.ListAllRecipients() has been introduced instead in its place.

This new method works the same way but also is in line with the name of the API it uses, along with allowing you to search.

For more information, refer to our documentation, or the test found at tests/RecipientTest.cs

...
Gateway gateway = new Trolley.Gateway("<ACCESS_KEY>","<SECRET_KEY>");

int page = 1;
int pageSize = 10;

// Get all recipients with an optional search term and manual pagination
Recipients allRecipients = gateway.recipient.ListAllRecipients("<search_term>", page, pageSize);
List<Recipient> recipients = allRecipients.recipients;

Meta meta = allRecipients.meta;
int nextPage = page < meta.pages ? (meta.page + 1) : -1;

// Or, with auto-pagination with an IEnumerable object
var recipients = gateway.recipient.ListAllRecipients("<search_term>");

foreach(Recipient recipient in recipients){
  Console.WriteLine(recipient.id);
}
...

4. Method variants of `RecipientGateway.findLogs()` renamed

The method earlier named RecipientGateway.findLogs() has been renamed to RecipientGateway.GetAllLogs() .

This method lets you access all recipient logs, with either manual or auto-pagination:

...
Gateway gateway = new Trolley.Gateway("<ACCESS_KEY>","<SECRET_KEY>");

int page = 1;
int pageSize = 10;
string recipientId = getRecipientId();

// Get all recipients logs with manual pagination
Logs allLogs = gateway.recipient.GetAllLogs(recipientId, page, pageSize).logs;
List<Log> logs = allRecipients.logs;

Meta meta = allLogs.meta;
int nextPage = page < meta.pages ? (meta.page + 1) : -1;	

// Or, with auto-pagination with an IEnumerable object
var logs = gateway.recipient.GetAllLogs(recipientId);

foreach(Recipient recipient in recipients){
  Console.WriteLine(recipient.id);
}
...

5. Variable `Recipient.TimeZone` removed

The variable Recipient.TimeZone has been removed since it doesn't correspond to our APIs and attributes.

6. Method `PaymentGateway.find()` renamed

This method has been renamed to PaymentGateway.Get()

...
Gateway gateway = new Trolley.Gateway("<ACCESS_KEY>","<SECRET_KEY>");

string recipientId = getRecipientIdToFetch();
Recipient recipient = gateway.recipient.Get(recipientId);

Console.WriteLine(recipient.id);
...

7. Method `PaymentGateway.query()` replaced

The method PaymentGateway.query() has been replaced by PaymentGateway.Search() . It returns a Payments object.

This Payments object helps you manually paginate better by providing you with a List<Payment> object along with a Meta object for pagination information.

For more information, refer to our documentation, or the test found at tests/PaymentTest.cs

...
Gateway gateway = new Trolley.Gateway("<ACCESS_KEY>","<SECRET_KEY>");

int page = 1;
int pageSize = 10;
string recipientId = getRecipientId();

// Search payments with optional search term and batch id, with manual pagination
Payments allPayments = trolley.payment.Search("<search_term>", page, pageSize, "<batch_id>");
List<Payment> payments = allPayments.payments;

foreach (Payment payment in payments){
  Console.WriteLine(payment.id);
}

Meta meta = allPayments.meta;
int nextPage = page < meta.pages ? (meta.page + 1) : -1;
	
...

8. Method `BatchGateway.Delete(Batch)` deleted

Now, in order to delete a batch, you'll have to use the BatchGateway.Delete(string) or its variant BatchGateway.Delete(string[]) to delete multiple batches at once, providing batchId as the parameter.

...
Gateway gateway = new Trolley.Gateway("<ACCESS_KEY>","<SECRET_KEY>");

string batchId = getBatchIdToDelete();
string[] batchIds = getMultipleBatchIdsToDelete();

// Delete a single batch
bool deleteResult = gateway.batch.Delete(batchId);

// Or, Delete multiple batches
bool deleteResult = gateway.batch.Delete(batchIds);
...

9. Method `BatchGateway.query()` replaced

The BatchGateway.query() has been replaced by BatchGateway.ListAllBatches() method which allows you to list and search through all batches, and returns an object of type Batches.

This Batches object helps you manually paginate better by providing you with a List<Batch> object along with a Meta object for pagination information.

For more information, refer to our documentation, or the test found at tests/BatchTest.cs

...
Gateway gateway = new Trolley.Gateway("<ACCESS_KEY>","<SECRET_KEY>");

int page = 1;
int pageSize = 10;

// List all batches with optional search term and manual pagination
Batches allBatches = gateway.batch.ListAllBatches("<search_term>", page, pageSize);
List<Batch> batches = allBatches.batches;

Meta meta = allBatches.meta;
int nextPage = page < meta.pages ? (meta.page + 1) : -1;

// Or, with auto-pagination with an IEnumerable object
var batches = gateway.batch.ListAllBatches("<search_term>");

foreach (Batch batch in batches){
  Console.WriteLine(batch.id);
}
...

10. Method `BatchGateway.generateQuote(Batch)` deleted

To comply with our API behaviour and for consistency, the only version of the above method that remains is the one that takes the batchId as a string argument.

For more information, refer to our documentation, or the test found at tests/BatchTest.cs

...
Gateway gateway = new Trolley.Gateway("<ACCESS_KEY>","<SECRET_KEY>");

string batchId = getBatchId();

Batch batch = gateway.batch.GenerateQuote(batchId);
...

11. Method `BatchGateway.processBatch(Batch)` deleted

To comply with our API behaviour and for consistency, the only version of the above method that remains is the one that takes the batchId as a string argument.

For more information, refer to our documentation, or the test found at tests/BatchTest.cs

...
Gateway gateway = new Trolley.Gateway("<ACCESS_KEY>","<SECRET_KEY>");

string batchId = getBatchId();

Batch batch = gateway.batch.ProcessBatch(batchId);
...

12. Method `BalancesGateway.all()` replaced

The method BalancesGateway.all() has been replaced by BalancesGateway.GetAllBalances() and it returns balances in all the accounts you hold with Trolley:

...
Gateway gateway = new Trolley.Gateway("<ACCESS_KEY>","<SECRET_KEY>");

List<Balance> balances = gateway.balances.GetAllBalances();

foreach(Balance balance in balances){
  Console.WriteLine($"{balance.type} : {balance.amount}");
}
...

Update to existing Methods

1. 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.

If you're running from the source and need to specify a server url, you now have to create a .env file in the project root and specify the BASE_URL there. Then, specify the environment as development for the SDK to start picking up the API url from .env file.

Old way

...
	Gateway gateway = new Gateway(new Configuration("<ACCESS_KEY>","<SECRET_KEY>","production"));
...

New way

...
	Gateway gateway = new Gateway(new Configuration("<ACCESS_KEY>","<SECRET_KEY>"));
...

New Methods/API Coverage

We have added support for more API endpoints that our SDK wasn't supporting earlier.

Here's a rundown of the new API endpoints covered:

Recipient

1. Delete Multiple Recipients

An overloaded version of RecipientGateway.Delete() now allows you to delete multiple recipients at once:

...
Gateway gateway = new Trolley.Gateway("<ACCESS_KEY>","<SECRET_KEY>");

bool delResult = gateway.recipient.Delete(recipient1.id, recipient2.id, ...);
...

2. List All Recipients with manual or auto pagination

Instead of using RecipientGateway.all(), now you can use two versions of RecipientGateway.ListAllRecipients() to get or search for recipients, and paginate through the result set either manually or automatically:

...
Gateway gateway = new Trolley.Gateway("<ACCESS_KEY>","<SECRET_KEY>");

int page = 1;
int pageSize = 10;

// Get all recipients with an optional search term and manual pagination
Recipients allRecipients = gateway.recipient.ListAllRecipients("<search_term>", page, pageSize);
List<Recipient> recipients = allRecipients.recipients;

Meta meta = allRecipients.meta;
int nextPage = page < meta.pages ? (meta.page + 1) : -1;

// Or, with auto-pagination with an IEnumerable object
var recipients = gateway.recipient.ListAllRecipients("<search_term>");

foreach(Recipient recipient in recipients){
  Console.WriteLine(recipient.id);
}
...

3. Get all Offline Payments

A new method RecipientGateway.GetAllOfflinePayments() lets you access all offline payments of the recipient with either manual or auto-pagination:

...
Gateway gateway = new Trolley.Gateway("<ACCESS_KEY>","<SECRET_KEY>");

int page = 1;
int pageSize = 10;
string recipientId = getRecipientId();

// Get all offline payments with an optional search term and manual pagination.
OfflinePayments allOfflinePayments =  gateway.recipient.GetAllOfflinePayments(recipientId, "<search_term>", page, pageSize);
List<OfflinePayment> offlinePayments = allOfflinePayments.offlinePayments;

Meta meta = allOfflinePayments.meta;
int nextPage = page < meta.pages ? (meta.page + 1) : -1;

// Or, with auto-pagination with an IEnumerable object
var offlinePayments = gateway.recipient.GetAllOfflinePayments(recipientId, "<search_term>");
foreach(OfflinePayment offlinePayment in offlinePayments){
    Console.WriteLine(offlinePayment.id);
}
...

Payment

1. List All Payments

A new method PaymentGateway.ListAllBatches() lets you list and search through all the payments inside a batch whose ID you provide. You can pagiante through this method manually or automatically:

...
Gateway gateway = new Trolley.Gateway("<ACCESS_KEY>","<SECRET_KEY>");

// Get all payments with an optional search term or batch id
var allPayments = trolley.payment.ListAllPayments("<search_term>", "<batch_id>");
foreach(Payment payment in allPayments){
  Console.WriteLine(payment.id);
}
...

Invoice

1. Create an Invoice

...
Gateway gateway = new Trolley.Gateway("<ACCESS_KEY>","<SECRET_KEY>");

string recipientId = getRecipientId();

Invoice invoiceRequest = new Invoice();
invoiceRequest.recipientId = recipientId;
invoiceRequest.description = "Created with .Net SDK";
Invoice invoice = gateway.invoice.Create(invoiceRequest);

Console.WriteLine(invoice.id);
...

2. Get an Invoice

...
Gateway gateway = new Trolley.Gateway("<ACCESS_KEY>","<SECRET_KEY>");

string invoiceId = getInvoiceId();

Invoice invoice = gateway.invoice.Get(invoiceId);

Console.WriteLine(invoice.id);
...

3. Update an Invoice

...
Gateway gateway = new Trolley.Gateway("<ACCESS_KEY>","<SECRET_KEY>");

string invoiceId = getInvoiceId();

Invoice invoiceRequest = new Invoice();
invoiceRequest.invoiceId = invoiceId;
invoiceRequest.description = "Updated description";
Invoice invoice = gateway.invoice.Update(invoiceRequest);

Console.WriteLine(invoice.id);
...

4. Delete an Invoice

...
Gateway gateway = new Trolley.Gateway("<ACCESS_KEY>","<SECRET_KEY>");

string invoiceId = getInvoiceId();

bool delResult = gateway.invoice.Delete(invoiceId);
...

5. Search for an Invoice

...
Gateway gateway = new Trolley.Gateway("<ACCESS_KEY>","<SECRET_KEY>");

int page = 1;
int pageSize = 10;
string recipientId = getRecipientId();

// Search for invoices with optional search term and manual pagination
Invoices allInvoices = gateway.invoice.Search(SearchBy.RecipientId, page, pageSize, "<search_term>", recipientId);
List<Invoice> invoices = allInvoices.invoices;

Meta meta = allInvoices.meta;
int nextPage = page < meta.pages ? (meta.page + 1) : -1;

// Or, with auto-pagination with an IEnumerable object
var invoices = gateway.invoice.Search(SearchBy.RecipientId, "<search_term>", recipientId);
foreach (Invoice invoice in invoices)
{
  Console.WriteLine(invoice.id);
}
...

Invoice Line

1. Create an Invoice Line

...
Gateway gateway = new Trolley.Gateway("<ACCESS_KEY>","<SECRET_KEY>");

string invoiceId = getInvoiceId();

InvoiceLine invoiceLineRequest = new InvoiceLine();
invoiceLineRequest.description = "Invoice Line created from .Net SDK";
invoiceLineRequest.unitAmount = new Amount("120.00", "CAD");
Invoice invoice = gateway.invoiceLine.Create(invoiceId, invoiceLineRequest);

Console.WriteLine(invoice.lines.Count);
...

2. Update an Invoice Line

...
Gateway gateway = new Trolley.Gateway("<ACCESS_KEY>","<SECRET_KEY>");

string invoiceLineId = getInvoiceLineId();

InvoiceLine invoiceLineRequest = new InvoiceLine();
invoiceLineRequest.invoiceLineId = invoiceLineId;
invoiceLineRequest.unitAmount = new Amount("150.00", "CAD");
Invoice invoice = gateway.invoiceLine.Update(invoiceLineId, invoiceLineRequest);

Console.WriteLine(invoice.lines.Count);
...

3. Delete an Invoice Line

...
Gateway gateway = new Trolley.Gateway("<ACCESS_KEY>","<SECRET_KEY>");

string invoiceId = getInvoiceId();
string[] invoiceLineIds = getInvoiceLineIds();

Invoice invoice = gateway.invoiceLine.Delete(invoiceId, invoiceLineIds);

Console.WriteLine(invoice.lines.Count);
...

Invoice Payment

1. Create an Invoice Payment

...
Gateway gateway = new Trolley.Gateway("<ACCESS_KEY>","<SECRET_KEY>");

string invoiceId = getInvoiceId();
string invoiceLineId = getInvoiceLineId();

InvoicePaymentPart invoicePaymentPartRequest = new InvoicePaymentPart();
invoicePaymentPartRequest.invoiceId = invoiceId;
invoicePaymentPartRequest.invoiceLineId = invocieLineId;
invoicePaymentPartRequest.amount = new Amount("100.00", "CAD");
InvoicePayment invoicePayment = gateway.invoicePayment.Create("<batch_id>", invoicePaymentPartRequest);

Console.WriteLine(invoicePayment.paymentId);
...

2. Update an Invoice Payment

...
Gateway gateway = new Trolley.Gateway("<ACCESS_KEY>","<SECRET_KEY>");

string invoiceId = getInvoiceId();
string invoiceLineId = getInvoiceLineId();
string invoicePaymentId = getInvoicePaymentId();

InvoicePaymentPart invoicePaymentPartRequest = new InvoicePaymentPart();
invoicePaymentPartRequest.paymentId = invoicePaymentId;
invoicePaymentPartRequest.invoiceId = invoiceId;
invoicePaymentPartRequest.invoiceLineId = invoiceLineId;
invoicePaymentPartRequest.amount = new Amount("100.00", "CAD");
InvoicePayment invoicePayment = gateway.invoicePayment.Update(invoicePaymentPartRequest);

Console.WriteLine(invoicePayment.paymentId);
...

3. Delete an Invoice Payment

...
Gateway gateway = new Trolley.Gateway("<ACCESS_KEY>","<SECRET_KEY>");

string invoiceId = getInvoiceId();
string[] invoiceLineIds = getInvoiceLineIds();
string invoicePaymentId = getInvoicePaymentId();

bool paymentDelResult = gateway.invoicePayment.Delete(invoicePaymentId, invoiceLineIds);
...

4. Search an Invoice Payment

...
Gateway gateway = new Trolley.Gateway("<ACCESS_KEY>","<SECRET_KEY>");

int page = 1;
int pageSize = 10;

string[] invoiceIds = getInvoiceIds();
string[] paymentIds = getInvoicePaymentIds();

// Search either via single or multiple invoiceIds, or invoicePaymentIds and manual pagination
InvoicePayments allInvoicePayments = gateway.invoicePayment.Search(invoiceIds, invoicePaymentIds, page, pageSize);
List<InvoicePayment> invoicePayments = allInvoicePayments.invoicePayments;

Meta meta = allInvoicePayments.meta;
int nextPage = page < meta.pages ? (meta.page + 1) : -1;

// Or, with auto-pagination with an IEnumerable object
var invoicePayments = gateway.invoicePayment.Search(invoiceIds, invoicePaymentIds);
foreach(InvoicePayment invoicePayment in invoicePayments){
  Console.WriteLine(invoicePayment.id);
}
...

Balances

1. Get Trolley Account's Balances

...
Gateway gateway = new Trolley.Gateway("<ACCESS_KEY>","<SECRET_KEY>");

List<Balance> balances = gateway.balances.GetTrolleyBalances();

foreach(Balance balance in balances){
  Console.WriteLine($"{balance.type} : {balance.amount}");
}
...

2. Get PayPal Account's Balances

...
Gateway gateway = new Trolley.Gateway("<ACCESS_KEY>","<SECRET_KEY>");

List<Balance> balances = gateway.balances.GetPaypalBalances();

foreach(Balance balance in balances){
  Console.WriteLine($"{balance.type} : {balance.amount}");
}
...

3. Get All Accounts' Balances

...
Gateway gateway = new Trolley.Gateway("<ACCESS_KEY>","<SECRET_KEY>");

List<Balance> balances = gateway.balances.GetAllBalances();

foreach(Balance balance in balances){
  Console.WriteLine($"{balance.type} : {balance.amount}");
}
...

Offline Payment

1. Create an Offline Payment

...
Gateway gateway = new Trolley.Gateway("<ACCESS_KEY>","<SECRET_KEY>");

string recipientId = getRecipientId();

OfflinePayment opRequest = new OfflinePayment();
opRequest.amount = 20;
opRequest.currency = "CAD";
opRequest.memo = "Created from .Net SDK";
OfflinePayment offlinePayment = gateway.offlinePayment.Create(recipientId, opRequest);

Console.WriteLine(offlinePayment.id);
...

2. Update an Offline Payment

...
Gateway gateway = new Trolley.Gateway("<ACCESS_KEY>","<SECRET_KEY>");

string recipientId = getRecipientId();
string offlinePaymentId = getOfflinePaymentId();

OfflinePayment opRequest = new OfflinePayment();
opRequest.amount = 50;
bool updateResult = gateway.offlinePayment.Update(recipientId, offlinePaymentId, opRequest);
...

3. Delete an Offline Payment

...
Gateway gateway = new Trolley.Gateway("<ACCESS_KEY>","<SECRET_KEY>");

string recipientId = getRecipientId();
string offlinePaymentId = getOfflinePaymentId();

bool delResult = gateway.offlinePayment.Delete(recipientId, offlinePaymentId);
...

4. List Offline Payments

...
Gateway gateway = new Trolley.Gateway("<ACCESS_KEY>","<SECRET_KEY>");

int page = 1;
int pageSize = 10;

// Get all offline payments with an optional search term, with manual pagination.
OfflinePayments allOfflinePayments = gateway.offlinePayment.ListAllOfflinePayments("<search_term>", page, pageSize);
List<OfflinePayment> offlinePayments = allOfflinePayments.offlinePayments;

Meta meta = allOfflinePayments.meta;
int nextPage = page < meta.pages ? (meta.page + 1) : -1;

// Or, with auto-pagination with an IEnumerable object
var offlinePayments = gateway.offlinePayment.ListAllOfflinePayments("<search_term>");
foreach (OfflinePayment offlinePayment in offlinePayments){
  Console.WriteLine(offlinePayment.id);
}
...

Housekeeping updates

Apart from covering new APIs, we also updated the dependencies to improve the functionality and security of the SDK.

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 developers@trolley.com
Collaborations and PRs are welcome.

v2.0.0

Trolley .Net SDK Major Update (Nov 20, 2023)

Breaking Changes

1. PaymentRails renamed to Trolley

2. Package reorganization

3. Methods renamed

1. Method RecipientGateway.all() renamed

2. Method RecipientGateway.update(Recipient) updated

3. Method variants of RecipientGateway.Search() deleted

4. Method variants of RecipientGateway.findLogs() renamed

5. Variable Recipient.TimeZone removed

6. Method PaymentGateway.find() renamed

7. Method PaymentGateway.query() replaced

8. Method BatchGateway.Delete(Batch) deleted

9. Method BatchGateway.query() replaced

10. Method BatchGateway.generateQuote(Batch) deleted

11. Method BatchGateway.processBatch(Batch) deleted

12. Method BalancesGateway.all() replaced

Update to existing Methods

1. No need to specify environment now

Old way

New way

New Methods/API Coverage

Recipient

1. Delete Multiple Recipients

2. List All Recipients with manual or auto pagination

3. Get all Offline Payments

Payment

1. List All Payments

Invoice

1. Create an Invoice

2. Get an Invoice

3. Update an Invoice

4. Delete an Invoice

5. Search for an Invoice

Invoice Line

1. Create an Invoice Line

2. Update an Invoice Line

3. Delete an Invoice Line

Invoice Payment

1. Create an Invoice Payment

2. Update an Invoice Payment

3. Delete an Invoice Payment

4. Search an Invoice Payment

Balances

1. Get Trolley Account's Balances

2. Get PayPal Account's Balances

3. Get All Accounts' Balances

Offline Payment

1. Create an Offline Payment

2. Update an Offline Payment

3. Delete an Offline Payment

4. List Offline Payments

Housekeeping updates

Uh oh!

1. Method `RecipientGateway.all()` renamed

2. Method `RecipientGateway.update(Recipient)` updated

3. Method variants of `RecipientGateway.Search()` deleted

4. Method variants of `RecipientGateway.findLogs()` renamed

5. Variable `Recipient.TimeZone` removed

6. Method `PaymentGateway.find()` renamed

7. Method `PaymentGateway.query()` replaced

8. Method `BatchGateway.Delete(Batch)` deleted

9. Method `BatchGateway.query()` replaced

10. Method `BatchGateway.generateQuote(Batch)` deleted

11. Method `BatchGateway.processBatch(Batch)` deleted

12. Method `BalancesGateway.all()` replaced