Kobble Transactions API

Introduction

Process transactions in real-time and access detailed transaction histories. Receive real-time updates and notifications.

Overview

Provides endpoints to create, retrieve, and manage transactions.

Key Features

RESTful API with predictable resource-based URLs.

Authentication with secure bearer tokens.

Queue-based processing, with status changes delivered by webhook.

Transaction lifecycle

The API is queue-based, not request and response

POST /customers/v1/transactions returns 201 with the transaction in PENDING and places it on a queue. The response tells you the request was accepted. It does not tell you the money moved.

A failure that can be detected immediately, such as an insufficient balance or an invalid beneficiary, is returned as HTTP 400. A 201 never carries a settled or declined outcome. A real decline arrives later, as a status change and a transaction-decline webhook.

If you reuse an Idempotency-Key, the replay returns HTTP 202 with the original cached body. Treat 202 as success, not failure.

Status is terminal

A transaction is PENDING, then either ACCEPTED or DECLINED. Both outcomes are final. Nothing can move a transaction out of them, and any later attempt is ignored rather than rejected.

Do not build a handler that waits for a status to change after ACCEPTED or DECLINED. Every subsequent event in the life of that money is a new record.

Settlement is your payout reaching ACCEPTED

There is no settlement record to wait for. The SETTLEMENT, SETTLEMENT_REVERSAL, RESERVATION and RESERVATION_REVERSAL values appear in the transaction type enum, but records of those types are internal to Kobble and never appear in your transaction list or your webhooks.

Your payout reaching ACCEPTED, delivered as transaction-accept, is the settlement signal. An integration that waits for a record of type SETTLEMENT waits forever, without an error, while the money moves correctly.

A returned payment arrives as a new REFUND

If a payout is returned or dishonoured after it settled, the original transaction stays ACCEPTED. It is never rewritten. Watching the original record's status will never tell you the money came back.

The return appears as a new transaction of type REFUND, and its external_id is the Kobble transaction id of the original payout. Join on that.

Note that external_id means two different things depending on which record you are looking at. On a transaction you created it is whatever value you supplied. On a REFUND it is Kobble's id for the original. Store the Kobble id for every transaction you create, regardless of whether you set your own reference.

Webhooks tell you what changed, not what it changed to

A webhook carries a pointer, not the transaction. It identifies the entity and the event, and the only enrichment is decline detail on transaction-decline. To learn a transaction's type, amount or external_id, read GET /customers/v1/transactions/{id}.

Your subscription is filtered by client only, so you receive every event type we publish. Ignore event types you do not recognise rather than treating them as errors.

Reading the transaction list

Filters, page bounds and the time-window semantics are documented on the Get all transactions endpoint. Three things are worth knowing before you design against it:

from and to filter on last update, not creation time, so a status change brings a transaction back into a window you have already read. Overlap your windows rather than paging strictly forward.

The row count comes back in the X-Total-Count response header, not the body.

payment_type selects the rail, for example CARD. It is not the transaction type, and there is no filter on transaction type.

Base URLs

Use the appropriate base URL depending on the environment:

Production: https://apikobble.net/

Staging: https://staging.apikobble.net/

Ensure you prepend the base URL to each endpoint while making requests.

Each environment has its own Cognito user pool, so your staging client ID and secret will not authenticate against production. Production credentials are issued separately as part of go-live.

API Endpoints

Get Transactions.

Create a Transaction.

Get Transaction by ID.

Create Manual Credit Transaction

Create Manual Debit Transaction

Authentication

All requests to the Transactions API require an access token. Include the access token in the headers of each request:

To generate an access token, please refer to Authorization.

Error Handling

The API returns standard HTTP status codes for responses. Use the status code to determine the result of your request.

Notes

All responses are returned in JSON format.

Ensure the proper base URL and headers are used in each request.

Transactions API

Kobble Transactions API#

Introduction#

Overview#

Key Features#

Transaction lifecycle#

The API is queue-based, not request and response#

Status is terminal#

Settlement is your payout reaching ACCEPTED#

A returned payment arrives as a new REFUND#

Webhooks tell you what changed, not what it changed to#

Reading the transaction list#

Base URLs#

API Endpoints#

Authentication#

Error Handling#

Notes#