Open FredrikMPS opened 8 years ago
Thanks for the great feedback!
My comments in order of yours:
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
Here's some collected feedback from the mobile (s)t(r)eam.
amount
property onPayment
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 whatevercurrency
has been specified, e.g. cents in casecurrency
was 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.paymentType
property ofPayment
is specified as anenum
oftype: 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./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.responses
of the/payments/
path, the200
response is specified for a successful payment. Other that that onlydefault
is further specified, containing one more possible response,402
, in its description for some reason.201
rather than a200
and include a URI for that resource in theLocation
header of the response.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.balance
path specifies a POST operation to retrieve the balance of your Bambora account, this should be a GET.payment
might have astatus
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.