Using the createPayment() API method with foreign currencies

Problem reported by Richard Cooper 10 years ago

I'm trying to use the createPayment() API method to add a payment to a US dollar bank account.

In my testing I've found a few problems

  1. The documentation says amount="The total amount paid in pounds". That's not correct. It's actually the total amount in the currency of the bank account being used.
  2. The documentation doesn't mention the fxRate parameter which is important when creating foreign currency payments
  3. createPayment() will happily accept a payment to a foreign currencies bank account without requiring fxRate to be supplied. That creates a payment with a NULL fxRate, which would be impossible to create via the website.

file

That broken payment creates all sorts of problems in the website. For example in the customer's full statement the "total" doesn't equal the sum of the individual payments.

file

And in the running balance the broken payment is treated as if it had an exchange rate of £1 = $1

file

Solved
Write reply4

4 Replies

Hi Richard,

Unfortunately the FX functionality was added to the createPayment relatively recently. To prevent breaking old applications the behaviour to allow createPayment without an FX rate on a multi-currency bank account is allowed.

I'm sorry if this is causing you some pain.

Regards, Adrian.

10 years ago

Richard,

We first brought this up before fxRate was added (point to note it is called fxrate for Invoices and fxRate for payments!). It now works for us but we have to use getExchangeRate.

The documentation also doesn't include the getExchangeRate call which allows you to ask Clearbooks for the current exchange rate on a given day. We call this then pass the result with the payment.

Example

$request = new \Clearbooks_Soap_1_0_ExchangeRateRequest(); $request->baseCurrency = 'GBP'; // default $request->targetCurrency = 'USD'; $request->date = date( 'Y-m-d' , time() - 60 60 24); $usdrate = $client->getExchangeRate( $request );

Gives us the USD Exchange rate for yesterday.

10 years ago

I understand the need to maintain backwards compatibility when designing APIs. However, I don't see how that changes this problem.

My first 2 points are documentation problems. Fixing them just requires correcting the documentation.

My third point is is basically "If you use createPayment() on a non-sterling account with no fxRate then clearbooks interprets $1 as £1 in some contexts and as £0 in other contexts." That is clearly a bug and not useful behaviour, even for older applications which don't know about fxRate.

IMO the best fix would be to make fxRate a required parameter if createPayment() is used with a non-sterling account. If you can't do that for backwards compatibility reasons then you should at least give fxRate a default value which isn't NULL. The appropriate exchange rate as returned by getExchangeRate() would be the most obvious default but even just setting the default to 1 would be an improvement. The sterling value would be wrong but at least your data would not be corrupt.

To be clear: I'm reporting this problem to try to help you improve your documentation and API for future customers, not because I need help with my use-case. Once I found the undocumented fxRate I was all set.

10 years ago

I suggested this initially when the fxRate was added that if blank it should at least be the current dates rate. So I completely agree.

10 years ago

Reply to this problem

Attach images by dragging and dropping or upload
 

Your comments will be public and can be answered by anyone in the Clear Books community.

Find out what we do and who we are

Apps

Company

Social