# Quickstart

From sandbox credentials to your first account read.

1. Get sandbox credentials. Request access and we register your client and its public signing key. You get a client_id.
2. Get an access token from /oauth2/token with a signed client assertion.
3. Read your merchant account.
4. 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.

**Sign in with a signed client assertion.** In the OpenAPI contract.

Lanes: Your service, insimbi API, Audit record

1. Your service: Sign a client assertion (JWT, RS256) with your registered private key. Audience: the token endpoint.
2. Your service to insimbi API: POST /oauth2/token with grant_type, client_id, client_assertion and optional scope
3. insimbi API: Verify the signature against your registered key, reject replays, check your credential, grants and scopes
4. insimbi API to Audit record: Record token.issued (or security.rejected)
5. insimbi API to Your service: 200: access_token, token_type Bearer, expires_in (60 s at most), scope
6. Your service to insimbi API: GET /v1/merchant-accounts/{id} with Authorization: Bearer
7. insimbi API to Audit record: Record the access decision: authorization.allowed or authorization.denied
8. Audit record to insimbi API: Decision captured
9. 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: sales@insimbi.net

_insimbi is in early access with design partners._