API · Response conventions

The acquiring API responses have three details that you cannot infer by reading each operation on its own, and that break typed integrations. They live here because they apply to several operations at once.

For error handling, see how to read an error response.

Amounts come as strings, not numbers#

Any typed deserialization that declares those fields as numbers fails. Declare them as strings and convert them yourself, with your language's decimal type, not with floating point.

It shows up, among others, in get a coupon, list coupons, list plans and subscriber payments.

There is a JSON payload inside a string#

In subscriber payments, the data field of each payment is not an object: it is a string containing JSON.

"data": "{\"first\":1,\"expire\":\"2024-12-28T19:05:29.572648Z\",\"amount\":0,\"activeAmount\":0,\"originalAmount\":0,\"key\":\"XXXX-XXXX-XXXX-XXXX-XXXX\"}"

You have to deserialize twice: first the response, then the contents of data. Treat that second deserialization the way you treat any external input: wrap it and log the raw string when it does not parse.

The same entity changes shape between "get one" and "list"#

This is not a documentation slip: the two operations return different shapes of the same coupon, and each needs its own mapping.

The same happens in subscriber payments, which also uses create with the Y-m-d H:i:s format.

Two ways of saying "not configured"#

In list plans, a plan's webhook fields come as an empty string when they are not configured, while return_url comes as null. Those are two representations of the same state in the same object: when checking whether a webhook is configured, treat the empty string and null as the same case.