Docs · Quickstart

Quickstart

From sandbox credentials to your first account read.

Get sandbox credentials. Request access and we register your client and its public signing key. You get a client_id.
Get an access token from /oauth2/token with a signed client assertion.
Read your merchant account.
Designed: create a payment, read its ticket and receive its events.

1. Get a token

Sign-in, step by step: your service signs a client assertion, swaps it for a token, then reads with it. Every decision is recorded.

Steps in text

Your service: Sign a client assertion (JWT, RS256) with your registered private key. Audience: the token endpoint.
Your service to insimbi API: POST /oauth2/token with grant_type, client_id, client_assertion and optional scope
insimbi API: Verify the signature against your registered key, reject replays, check your credential, grants and scopes
insimbi API to Audit record: Record token.issued (or security.rejected)
insimbi API to Your service: 200: access_token, token_type Bearer, expires_in (60 s at most), scope
Your service to insimbi API: GET /v1/merchant-accounts/{id} with Authorization: Bearer
insimbi API to Audit record: Record the access decision: authorization.allowed or authorization.denied
Audit record to insimbi API: Decision captured
insimbi API to Your service: 200 merchant account, or 403 insufficient_authority. X-Request-ID on every response.

From the OpenAPI contract

curl https://sandbox.api.insimbi.xyz/oauth2/token \
  -d grant_type=client_credentials \
  -d client_id=$CLIENT_ID \
  -d client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer \
  -d client_assertion=$SIGNED_JWT

The client assertion is a JWT you sign with your registered private key (RS256). Its audience is exactly https://sandbox.api.insimbi.xyz/oauth2/token. Leave out scope to get every scope your client is allowed, or ask for a subset. There are no client secrets.

From the OpenAPI contract

{
  "access_token": "<token>",
  "token_type": "Bearer",
  "expires_in": 60,
  "scope": "organization.read legal_entity.read merchant_account.read"
}

Tokens are short-lived: expires_in is at most 60 seconds. Get a new token when one expires.

2. Read your merchant account

From the OpenAPI contract

curl https://sandbox.api.insimbi.xyz/v1/merchant-accounts/$MERCHANT_ACCOUNT_ID \
  -H "Authorization: Bearer $TOKEN"

From the OpenAPI contract

{
  "id": "<merchant_account_id>",
  "organization_id": "<organization_id>",
  "legal_entity_id": "<legal_entity_id>",
  "environment": "sandbox",
  "environment_id": "<environment_id>",
  "status": "active"
}

3. Create a payment

Designed. Payments, tickets and webhooks are designed endpoints. They are not in the OpenAPI contract yet.

The full payment flow, from the rule check to the record, is on the API reference (/docs/api/#flow-payment).

Illustrative example

curl https://sandbox.api.insimbi.xyz/v1/payments \
  -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: 6f1c2a90-order-1042" \
  -d '{"merchant_account_id":"<uuid>","amount":"182.40","currency":"USD","source":"tok_sandbox_debit"}'

4. Read the ticket

Illustrative example

curl https://sandbox.api.insimbi.xyz/v1/tickets/tkt_01J9 -H "Authorization: Bearer $TOKEN"

Illustrative example

{
  "id": "tkt_01J9",
  "payment_id": "pay_01J9",
  "status": "settled",
  "lines": [
    {
      "label": "interchange",
      "amount": "0.31",
      "rule": "rule:interchange.debit.regulated@v3"
    },
    {
      "label": "network",
      "amount": "0.04",
      "rule": "rule:network.assessment@v7"
    },
    {
      "label": "insimbi",
      "amount": "0.05",
      "rule": "rule:contract.platform_fee@v2"
    }
  ],
  "decisionRefs": [
    "dec_rail_01J9"
  ],
  "eventRefs": [
    "evt_01J9a",
    "evt_01J9b"
  ]
}

Every fee line cites the rule that produced it. Nothing is blended.

Request access

insimbi is in early access with design partners.