Settings

List merchant accounts

GET

/v1/merchant-accounts

const url = 'https://api.timbro.do/v1/merchant-accounts?limit=20';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url 'https://api.timbro.do/v1/merchant-accounts?limit=20' \
  --header 'Authorization: Bearer <token>'

Authentication

secretKey
adminKey

Parameters

Query parameters

limit

integer

default: 20 >= 1 <= 100

Rows on one page.

cursor

string

>= 1 characters <= 512 characters

The nextCursor of the previous page. A cursor belongs to the list, tenant, mode, and filter set that minted it.

Responses

200

One page of Merchant Accounts, newest first.

application/json

Response fields and codes

One page of Merchant Accounts, newest first.

object

object

required

string

Allowed value: list

data

required

Array<object>

A merchant-owned provider account.

object

required

Merchant Account identifier.

string

/^merchant_account_[0-9a-hjkmnp-tv-z]{24,}$/

object

required

string

Allowed value: merchant_account

provider

required

Any of:

string
string

string

Allowed value: azul

mode

required

Any of:

string
string

string

Allowed value: test

lifecycle

required

Any of:

string
string

string

Allowed value: active

readiness

required

object

status

required

Any of:

string
string

string

Allowed value: ready

blockers

required

Array<object>

object

code

required

Any of:

string

Allowed value: merchant_account_disabled

owner

required

Any of:

string

Allowed value: merchant

detail

string

>= 1 characters <= 256 characters

checks

required

Array<object>

object

check

required

string

>= 1 characters <= 64 characters

status

required

Any of:

string

Allowed value: passed

detail

string

>= 1 characters <= 256 characters

capabilities

required

Array<object>

unique items

Readiness for one merchant-facing account operation. Provider credentials and protocol details are never returned.

object

purpose

required

Any of:

string

Allowed value: payment

TEST only. The acquirer’s own payment page, present while the account has one enabled. A Payment uses it only when it sets checkoutPreferences.paymentPage.

string

Allowed value: payment_page

readiness

required

object

status

required

Any of:

string
string

string

Allowed value: ready

blockers

required

Array<object>

object

code

required

Any of:

string

Allowed value: merchant_account_disabled

owner

required

Any of:

string

Allowed value: merchant

detail

string

>= 1 characters <= 256 characters

checks

required

Array<object>

object

check

required

string

>= 1 characters <= 64 characters

status

required

Any of:

string

Allowed value: passed

detail

string

>= 1 characters <= 256 characters

credentialVersion

integer

>= 1

checkoutCapabilities

required

Safe effective Checkout capabilities for one Merchant Account and mode.

object

splits

required

boolean

wallets

required

Array

<= 2 items unique items

threeDsModes

required

Array

<= 2 items unique items

createdAt

required

string format: date-time

venueReference

string

>= 1 characters <= 256 characters

credentialVersion

integer

>= 1

hasMore

required

True when a further page follows this one.

boolean

nextCursor

required

Any of:

string
null

string

>= 1 characters

Headers

request-id

required

string

Identifies this request. Quote it when you contact support.

400

The request could not be understood.

application/problem+json

Example

{
  "type": "about:blank",
  "title": "The request could not be understood.",
  "status": 400,
  "code": "parameter_invalid",
  "requestId": "request_000000000000000000000001"
}

Response fields and codes

RFC 9457 problem details. Every failure of this API is one of these, and each operation narrows code to the subset it can emit.

object

code

required

Stable machine-readable code. Branch on this, never on title.

string

Allowed values: parameter_invalid collection_cursor_invalid

requestId

required

string

status

required

integer format: int32

>= 400 <= 599

Allowed value: 400

title

required

string

type

required

string

Allowed values: about:blank

Optional fields

detail

string

invoiceId

Present only when the rejected request produced a Fiscal operation.

string

issuanceBlockers

Present only when the authoritative issuance rules refused to issue.

Array<string>

Allowed values: invalid_request unsupported_protocol unsupported_rules_version invalid_resolved_facts numbering_verifier_missing numbering_mode_not_enabled document_type_not_recognized sequence_missing sequence_not_observed_on_effective_date sequence_suspended sequence_cancelled sequence_superseded sequence_exhausted sequence_conflicting sequence_document_type_mismatch sequence_rejected_by_dgii sequence_expired sequence_range_overlap fiscal_number_capacity_exhausted invalid_fiscal_number fiscal_number_outside_authorized_range fiscal_number_before_verified_floor sequence_expiration_mismatch

problems

Present only when the rejection points at a value the request carried.

Array<object>

One stable public document problem retained for a rejected admission.

object

code

required

string

message

required

string

path

required

string

Headers

request-id

required

string

Identifies this request. Quote it when you contact support.

401

The credential is missing, malformed, or no longer valid.

application/problem+json

Example

{
  "type": "about:blank",
  "title": "The credential is missing, malformed, or no longer valid.",
  "status": 401,
  "code": "api_key_missing",
  "requestId": "request_000000000000000000000001"
}

Response fields and codes

RFC 9457 problem details. Every failure of this API is one of these, and each operation narrows code to the subset it can emit.

object

code

required

Stable machine-readable code. Branch on this, never on title.

string

Allowed values: api_key_missing api_key_invalid checkout_token_invalid checkout_token_expired

requestId

required

string

status

required

integer format: int32

>= 400 <= 599

Allowed value: 401

title

required

string

type

required

string

Allowed values: about:blank

Optional fields

detail

string

invoiceId

Present only when the rejected request produced a Fiscal operation.

string

issuanceBlockers

Present only when the authoritative issuance rules refused to issue.

Array<string>

problems

Present only when the rejection points at a value the request carried.

Array<object>

One stable public document problem retained for a rejected admission.

object

code

required

string

message

required

string

path

required

string

Headers

request-id

required

string

Identifies this request. Quote it when you contact support.

403

The credential is valid but not permitted to perform this operation.

application/problem+json

Example

{
  "type": "about:blank",
  "title": "The credential is valid but not permitted to perform this operation.",
  "status": 403,
  "code": "operation_not_permitted",
  "requestId": "request_000000000000000000000001"
}

Response fields and codes

RFC 9457 problem details. Every failure of this API is one of these, and each operation narrows code to the subset it can emit.

object

code

required

Stable machine-readable code. Branch on this, never on title.

string

Allowed values: operation_not_permitted

requestId

required

string

status

required

integer format: int32

>= 400 <= 599

Allowed value: 403

title

required

string

type

required

string

Allowed values: about:blank

Optional fields

detail

string

invoiceId

Present only when the rejected request produced a Fiscal operation.

string

issuanceBlockers

Present only when the authoritative issuance rules refused to issue.

Array<string>

problems

Present only when the rejection points at a value the request carried.

Array<object>

One stable public document problem retained for a rejected admission.

object

code

required

string

message

required

string

path

required

string

Headers

request-id

required

string

Identifies this request. Quote it when you contact support.

500

The request could not complete. Recover by the retained resource reference or retry with the same command identity.

application/problem+json

Example

{
  "type": "about:blank",
  "title": "The request could not complete. Recover by the retained resource reference or retry with the same command identity.",
  "status": 500,
  "code": "internal_error",
  "requestId": "request_000000000000000000000001"
}

Response fields and codes

RFC 9457 problem details. Every failure of this API is one of these, and each operation narrows code to the subset it can emit.

object

code

required

Stable machine-readable code. Branch on this, never on title.

string

Allowed values: internal_error

requestId

required

string

status

required

integer format: int32

>= 400 <= 599

Allowed value: 500

title

required

string

type

required

string

Allowed values: about:blank

Optional fields

detail

string

invoiceId

Present only when the rejected request produced a Fiscal operation.

string

issuanceBlockers

Present only when the authoritative issuance rules refused to issue.

Array<string>

problems

Present only when the rejection points at a value the request carried.

Array<object>

One stable public document problem retained for a rejected admission.

object

code

required

string

message

required

string

path

required

string

Headers

request-id

required

string

Identifies this request. Quote it when you contact support.