Using the API

Deprecation notice

This feature is scheduled for deprecation. If you are currently using it, we recommend contacting Mambu Support to discuss your transition options. Alternatively, you can explore our latest payments module here.

Authentication

To access the Payments API, you must create an API consumer that has the Manage Payments (MANAGE_PAYMENTS) permission assigned to it and create API keys using this API consumer.

API keys inherit the scope of access settings from the API consumer that creates them. You must authenticate every request to the Payments API using an API key in the request header.

You may create and manage API consumers and keys either through the Mambu UI or using the API Consumers endpoint provided by Mambu API v2. For more information, see API Consumers in our User Guide.

note

API consumers and keys is currently an Early Access feature. If you would like to request early access to this feature, please get in touch with your Mambu Customer Success Manager to discuss your requirements. For more information, see Mambu Release Cycle - Feature Release Status.

Example authenticated request using cURL

curl  --request GET 'https://TENANT_NAME.mambu.com/api/v1/collections/d45a34ed341321bca4d89e42452dc074' \
--header 'apikey: i9TCzwUBwyTVQrfPEAhk0oEpOUCt0O2M'

Content types

Depending on the endpoint, the Payments API will accept one of two content types: JSON and XML. The format should be specified in the Content-Type header with either the value application/json or application/xml. Check the parameters table for each request for the required value for the Content-Type header.

For certain requests, including some POST requests, there is no need to supply a request body. For these requests, the Content-Type header can be omitted.

Idempotency

Many POST requests take an optional Idempotency-Key header. The value of this header should be a randomly generated string, unique to the request. We recommend using a UUID generator or library to create idempotency keys in the UUID v4 format. The following example shows a typical UUID: c2f53453-439c-4efa-9e27-58877160638b.

Using an idempotency key helps avoid duplicate requests. When an idempotent request is processed, the status code and body of the response is associated with the idempotency key and stored in a cache. If the request is duplicated for any reason, the duplicate request is not processed, and the response is re-sent to the client.