Feedback

[FredrikMPS]

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"? 😄

[bowens-bambora]

Thanks for the great feedback!

My comments in order of yours:

• yep no auth scheme has been decided yet. We will nail this down in the January meeting.
• float vs. int, this will be highly debated. Generally floating point precision shouldn't be a huge issue for most currencies (except for maybe Zimbabwe). The issue people run into is not doing the conversion to cents. A 64bit float (double precision) should cover almost all currency ranges.
• enum of any type is supported in v2 of the spec. However some of the ui tools have bugs in rendering.
• I'm on board for having the more explicit URLs for the different payment types. It would also resolve the ui tool bugs (not that that should be a deciding factor). It does feel nicer putting the payment types in the URL. Let me see how the object model will look this way.
• The response types are not fully expanded out yet, mostly just for brevity while we discuss the API. We will have 400, 401, 402, 404, 415, and 500. For the final design I will explicitly define these responses in each of the API calls. I'm of course open to other response types, but we should keep them to as few as we need (< 8).
• Yes we can return a 201 for POST requests creating a new object, such as a purchase that can be returned or voided (and note that both of those calls are missing at the moment). Unfortunately some tools and libraries handle non-200 results as an error, hence it just being 200 right now. A solution around that will be to add a querystring parameter to the request that tells the API to return 200 for all requests, and include the actual status code in the response object. This can be for V2 of the API though, which we should have out before year's end.
• Good idea, we can use https://tools.ietf.org/html/draft-ietf-appsawg-http-problem-00 for the error model
• Good catch. I will probably remove Balance from the API for V1 anyways. This will depend on the product team deciding what features we want for the first release. Right now it is not needed.
• Status in responses: I like this idea. Since a payment will have a status anyways, we can return it back instead of just a message.
• Yep minimal validation for now. We will have to get the BAs to dig deeper into the requirements in each PSP for those values and align them.
• A pre-auth (aka "auth") here in north america holds a $ amount on the card. The auth can then be captured/completed at a later time to consume some or all of the amount.

[bowens-bambora]

I created a branch and updated the model. It is not complete, the error model hasn't been updated. But the URL paths have been changed. I also added in Returns and Voids:
https://github.com/bambora/api.bambora.com/blob/expanded/payments-swagger.yaml