Create subscription

To create relay subscription by passing a client url

Registers a synchronous transaction-authorization relay.

Operational contract. For each in-scope transaction, Kobble POSTs to your relay URL a JSON body {id, entity_id, entity_type, entity} (where entity is the transaction). Your endpoint must respond with {"status": "ACCEPTED" | "DECLINED", "remarks"?: string} and an x-client-signature header containing the signature of the response, created with the privateKey returned below; Kobble verifies it against your stored public key.

Signature. Sign the JSON-serialized response body with RSA-SHA256 using the privateKey from this response, and send the signature base64-encoded in the x-client-signature header. Kobble verifies it against your stored 2048-bit RSA public key.

The relay fails closed: any error — timeout, non-2xx, missing or invalid signature, malformed body — DECLINES the transaction. A broken relay integration silently declines your customers' payments. If a client has NO relay registered, transactions proceed without a relay check (they are not declined).

The privateKey in the response is returned exactly once and never stored by Kobble.

Request Code Samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

Responses

🟢201Created

application/json

Bodyapplication/json

Example

{
    "id": "d18efff5-f8c0-4e15-a683-fe7e8a1a8f2f",
    "owner": "5cad242e-4291-4905-8849-a6f09f4e6d4a",
    "url": "https://basic-wallaby.biz",
    "created_at": "2025-01-14T16:59:07.432Z",
    "updated_at": "2025-01-14T16:59:07.433Z",
    "public_key": "-----BEGIN PUBLIC KEY-----\n...base64...\n-----END PUBLIC KEY-----\n",
    "privateKey": "-----BEGIN PRIVATE KEY-----\n...base64 (shown only once)...\n-----END PRIVATE KEY-----\n"
}

🟠400Bad Request

🟠401Unauthorized

🟠403Forbidden