Organization transactions

Review transactions across the organization's merchants from the Dashboard — inspect attempts, refund, and void.

These endpoints roll up transactions from every merchant in the organization: filter and open a charge, walk its per-attempt routing timeline, and act on it — refund captured funds or void an authorization.

It is the org-wide window into payment activity. The transaction object and its timeline match the public API; this view aggregates them across merchants for oversight and support.

These endpoints power the Tokeflow Dashboard UI at the organization level. They are session-authenticated (JWT bearer) — the token comes from signing in to the Dashboard, not from an sk_/pk_ API key. Requests also carry the x-organization-id header, and the signed-in user must be a member of that organization.

The transaction object

Returned by the list and retrieve endpoints on this page.

Field	Type	Description
`id`	string	Transaction ID.
`organization_id`	string	Organization ID.
`merchant_id`	string	Merchant ID.
`order_id`	string \| null	Auto-created order ID.
`subscription_id`	string \| null	Subscription created from this CIT, when the underlying offer is recurring. Null for one-time charges and for non-recurring orders.
`external_order_id`	string \| null	External order ID from merchant system.
`customer_id`	string \| null	Customer ID.
`payment_instrument_id`	string \| null	Payment instrument ID used for the transaction.
`amount_authorized`	number	Amount authorized in minor units.
`amount_captured`	number	Amount captured in minor units.
`currency`	string	ISO 4217 currency code.
`payment_method`	string	Payment method. One of `credit_card`, `debit_card`, `pix`, `boleto`, `wallet`.
`charge_type`	string	Type of charge. One of `payment`, `setup_verification`.
`country`	string	ISO 3166-1 alpha-2 country code.
`status`	string	Transaction status. One of `pending`, `pre_authorized`, `authorized`, `failed`, `canceled`, `voided`, `charged_back`, `refund_pending`, `capture_pending`, `refunded`, `partially_refunded`, `expired`.
`applied_routing_rule_id`	string \| null	Routing rule node that produced the successful attempt.
`timeline`	array	Timeline of transaction attempts with routing fallbacks.
`payment_instructions`	object \| null	Payment instructions for async methods (PIX, boleto). Null for synchronous card transactions.
`metadata`	object \| null	Merchant-supplied metadata.
`created_at`	string	Creation timestamp. (ISO 8601 UTC).
`updated_at`	string	Last update timestamp. (ISO 8601 UTC).

Endpoints

GET`/api/v1/org/transactions`

Org

Auth: Dashboard session (JWT bearer). Organization membership required.

List transactions for merchant.

Query parameters

Field	Type	Required	Description
`page`	number	No	Page number (1-indexed). Default `1`, min `1`.
`limit`	number	No	Number of items per page. Default `20`, min `1`, max `100`.
`status`	array	No	Comma-separated list of transaction statuses to filter by
`merchant_id`	string	No	Filter transactions by merchant ID
`customer_reference`	string	No	Filter transactions by customer reference
`order_id`	string	No	Filter transactions by order ID
`date_from`	string	No	Filter transactions created after this date (ISO 8601)
`date_to`	string	No	Filter transactions created before this date (ISO 8601)
`payment_method`	string	No	Filter transactions by payment method
`currency`	string	No	Filter transactions by currency (ISO 4217)

Example request

curl -G https://api.tokeflow.com/api/v1/org/transactions \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-organization-id: org_4b21e7c3" \
  --data-urlencode "page=1" \
  --data-urlencode "limit=20" \
  --data-urlencode "status=pending,authorized,failed" \
  --data-urlencode "merchant_id=mrc_123"

GET`/api/v1/org/transactions/:id`

Org

Auth: Dashboard session (JWT bearer). Organization membership required.

Get transaction by ID.

Path parameters

Field	Type	Required	Description
`id`	string	Yes	—

Example request

curl https://api.tokeflow.com/api/v1/org/transactions/obj_1a2b3c4d \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-organization-id: org_4b21e7c3"

Example response — 200

{
  "id": "tx_777",
  "organization_id": "org_123",
  "merchant_id": "mrc_123",
  "order_id": "ord_001",
  "subscription_id": "sub_001",
  "external_order_id": "order_888",
  "customer_id": "cust_123",
  "payment_instrument_id": "pi_123",
  "amount_authorized": 15000,
  "amount_captured": 15000,
  "currency": "BRL",
  "payment_method": "credit_card",
  "charge_type": "payment",
  "country": "BR",
  "status": "authorized",
  "applied_routing_rule_id": "node_2",
  "timeline": [
    {
      "attempt_number": 1,
      "is_fallback": false,
      "connector_id": "conn_a1b2c3",
      "provider_slug": "provider_b",
      "status": "success",
      "error_category": "TECH_ERROR",
      "error_code": "TIMEOUT",
      "started_at": "2025-11-28T13:00:00Z",
      "finished_at": "2025-11-28T13:00:05Z"
    }
  ],
  "payment_instructions": {
    "type": "pix",
    "qr_code_text": "00020126580014BR.GOV.BCB.PIX...",
    "qr_code_url": "https://psp-url.com/qrcode/image.png",
    "barcode": "string",
    "boleto_url": "https://example.com/webhooks/tokeflow",
    "due_date": "string",
    "expires_at": "2025-11-28T13:30:00Z"
  },
  "metadata": {},
  "created_at": "2025-11-28T13:00:00Z",
  "updated_at": "2025-11-28T13:00:09Z"
}

GET`/api/v1/org/transactions/:id/attempts`

Org

Auth: Dashboard session (JWT bearer). Organization membership required.

List transaction attempts.

Path parameters

Field	Type	Required	Description
`id`	string	Yes	—

Example request

curl https://api.tokeflow.com/api/v1/org/transactions/obj_1a2b3c4d/attempts \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-organization-id: org_4b21e7c3"

POST`/api/v1/org/transactions/:id/capture`

Org

Auth: Dashboard session (JWT bearer). Organization membership required.

Capture an authorized transaction.

Path parameters

Field	Type	Required	Description
`id`	string	Yes	—

Request fields

Field	Type	Required	Description
`amount`	number	No	Optional amount to capture in cents/minor unit. If not provided, the full authorized amount will be captured. For partial capture, must be less than or equal to amount_authorized.

Example request

curl -X POST https://api.tokeflow.com/api/v1/org/transactions/obj_1a2b3c4d/capture \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-organization-id: org_4b21e7c3" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 15000
  }'

Example response — 200

{
  "id": "tx_777",
  "organization_id": "org_123",
  "merchant_id": "mrc_123",
  "order_id": "ord_001",
  "subscription_id": "sub_001",
  "external_order_id": "order_888",
  "customer_id": "cust_123",
  "payment_instrument_id": "pi_123",
  "amount_authorized": 15000,
  "amount_captured": 15000,
  "currency": "BRL",
  "payment_method": "credit_card",
  "charge_type": "payment",
  "country": "BR",
  "status": "authorized",
  "applied_routing_rule_id": "node_2",
  "timeline": [
    {
      "attempt_number": 1,
      "is_fallback": false,
      "connector_id": "conn_a1b2c3",
      "provider_slug": "provider_b",
      "status": "success",
      "error_category": "TECH_ERROR",
      "error_code": "TIMEOUT",
      "started_at": "2025-11-28T13:00:00Z",
      "finished_at": "2025-11-28T13:00:05Z"
    }
  ],
  "payment_instructions": {
    "type": "pix",
    "qr_code_text": "00020126580014BR.GOV.BCB.PIX...",
    "qr_code_url": "https://psp-url.com/qrcode/image.png",
    "barcode": "string",
    "boleto_url": "https://example.com/webhooks/tokeflow",
    "due_date": "string",
    "expires_at": "2025-11-28T13:30:00Z"
  },
  "metadata": {},
  "created_at": "2025-11-28T13:00:00Z",
  "updated_at": "2025-11-28T13:00:09Z"
}

POST`/api/v1/org/transactions/:id/refund`

Org

Auth: Dashboard session (JWT bearer). Organization membership required.

Refund a captured transaction.

Path parameters

Field	Type	Required	Description
`id`	string	Yes	—

Request fields

Field	Type	Required	Description
`amount`	number	No	Amount to refund in cents/minor unit. If not provided, full amount will be refunded.
`reason`	string	No	Reason for the refund. One of `duplicate`, `fraudulent`, `requested_by_customer`.

Example request

curl -X POST https://api.tokeflow.com/api/v1/org/transactions/obj_1a2b3c4d/refund \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-organization-id: org_4b21e7c3" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5000,
    "reason": "requested_by_customer"
  }'

Example response — 200

{
  "id": "tx_777",
  "refund_id": "ref_abc123",
  "status": "refund_pending",
  "amount_captured": 15000,
  "amount_refunded": 5000,
  "total_refunded": 5000,
  "updated_at": "2025-11-28T13:07:00Z"
}

GET`/api/v1/org/transactions/:id/refunds`

Org

Auth: Dashboard session (JWT bearer). Organization membership required.

List refunds for a transaction.

Path parameters

Field	Type	Required	Description
`id`	string	Yes	—

Query parameters

Field	Type	Required	Description
`page`	number	No	Page number (1-indexed). Default `1`, min `1`.
`limit`	number	No	Number of items per page. Default `20`, min `1`, max `100`.

Example request

curl -G https://api.tokeflow.com/api/v1/org/transactions/obj_1a2b3c4d/refunds \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-organization-id: org_4b21e7c3" \
  --data-urlencode "page=1" \
  --data-urlencode "limit=20"

POST`/api/v1/org/transactions/:id/void`

Org

Auth: Dashboard session (JWT bearer). Organization membership required.

Void an authorized transaction.

Path parameters

Field	Type	Required	Description
`id`	string	Yes	—

Example request

curl -X POST https://api.tokeflow.com/api/v1/org/transactions/obj_1a2b3c4d/void \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-organization-id: org_4b21e7c3"

Example response — 200

{
  "id": "tx_777",
  "status": "voided",
  "updated_at": "2025-11-28T13:06:00Z"
}

Errors

Errors use the standard envelope. The most common cases here:

HTTP	Meaning
`400`	Invalid parameters or a state that does not allow this operation.
`401`	Missing, expired, or invalid Dashboard session token.
`403`	Authenticated, but the signed-in user lacks access to this entity.
`404`	The record does not exist or is not visible to this entity.

Organization transactions

The transaction object

Endpoints

GET/api/v1/org/transactions

GET/api/v1/org/transactions/:id

GET/api/v1/org/transactions/:id/attempts

POST/api/v1/org/transactions/:id/capture

POST/api/v1/org/transactions/:id/refund

GET/api/v1/org/transactions/:id/refunds

POST/api/v1/org/transactions/:id/void

Errors

Related

On this page

GET`/api/v1/org/transactions`

GET`/api/v1/org/transactions/:id`

GET`/api/v1/org/transactions/:id/attempts`

POST`/api/v1/org/transactions/:id/capture`

POST`/api/v1/org/transactions/:id/refund`

GET`/api/v1/org/transactions/:id/refunds`

POST`/api/v1/org/transactions/:id/void`