bambora / api.bambora.com

Bambora API designs

api.bambora.com

Bambora API designs

Most of the designs are written in Swagger. You can view the designs in the nice interactive swagger editor:

Batch Payments

http://editor.swagger.io/#/?import=https://raw.githubusercontent.com/bambora/api.bambora.com/master/batchpayments-swagger.yaml

Card information

http://editor.swagger.io/#/?import=https://raw.githubusercontent.com/bambora/api.bambora.com/master/cardinformation-swagger.yaml

Payments

http://editor.swagger.io/#/?import=https://raw.githubusercontent.com/bambora/api.bambora.com/master/payments-swagger.yaml

api.bambora.com's Issues

Feedback

Here's some collected feedback from the mobile (s)t(r)eam.

• There is no specification for how authentication is handled, I'm guessing because it hasn't been decided on, but still 😄
• The amount property on Payment should be specified as an integer rather than a float to avoid rounding errors in the float representation in many languages. It would be in the lowest denomination of whatever currency has been specified, e.g. cents in case currencywas set to 'EUR'. This would automatically prevent someone from trying to charge a fraction of the smallest denomination as well, e.g. 3.437843 EUR.
• The paymentTypeproperty of Payment is specified as an enum of type: object, which is not supported by the swagger specification. This leads to weirdness in the generated documentation where parts of the api spec is included as if it was part of the input data to the endpoint.
• Having the /payments/ endpoint accept three distinct inputs doesn't feel all that RESTful, more like RPC. We suggest adding several endpoints /payments/creditcard/, /payments/token/ and /payments/encryptedcard/ each accepting just one format of input.
• When it comes to responses of the /payments/ path, the 200 response is specified for a successful payment. Other that that only default is further specified, containing one more possible response, 402, in its description for some reason.
• Any POST that creates a new resource that can be further operated on should return a 201 rather than a 200 and include a URI for that resource in the Location header of the response.
• The definition of the Error model very closely resembles https://tools.ietf.org/html/draft-ietf-appsawg-http-problem-00 in semantics with mostly some differences in the naming of properties, so we could reuse that specification instead of rolling our own.
• The balance path specifies a POST operation to retrieve the balance of your Bambora account, this should be a GET.
• To make the API more RESTful we could try to work more with resources and vary the data on those, rather than returning messages as responses to operations.
  A payment might have a status property, to represent it's current state. This could then be set to 'declined' if a payment didn't go through or 'captured' after a successful capture.
• A lot more validation could be added in the spec for the different properties, but this is fine for a draft.
• What does it mean for the payment to be run "as a pre-authorization"? 😄

add end-point to payment API for adding payments later in the process

In order to allow payments from elixir, pay, samport, etc to be added to the payment service, even if the initial payment request wasn't made through the payment api, we need an additional method + end-point.

My suggestion is that we add POST /payments/{operation}, which similar to POST /payments/{id}/{operation}, would add an operation to a payment.

The difference is that we don't know when we add e.g. the acquisition operation if the parent payment object exist or not. The end-point would try to match the operation to an existing payment, and if it exist, would add it to that payment. If it does not exist, it would create a new parent object and add the operation to that object.

Take the card_token out of the url when creating a new payment authorization using a tokenized payment card.

I was looking at the api with my colleague @frodeaa and he pointed out that it might not be a good idea to have the card_token as a GET variable, since urls for requests are commonly logged, and then we end up with card_tokens that can be used for payments in our (or our customers) logs.

Paging in bambora APIs

So, I see that we currently don't have any endpoints here returning lists, but I wonder if you have any thoughts on how to handle paging of elements in responses.

I think we should find one way to do it, and use that consistently accross all our services.

Card data in the payments response?

From the GET /{payment} endpoint, is there a way to get information about the customer card, like if it is a visa or a master card, and a masked card number or an id/toke (preferably one that can not be used for a payment)?