Integration Questions

This guide covers API connectivity, authentication, request handling, financial operations, and recommended integration practices.

For endpoint-specific details, refer to the relevant API Reference.

---

API access and authentication

How do I connect to Senmo APIs?

For products exposing HTTP APIs, applications communicate with the platform using authenticated requests.

A typical integration involves:

1. Obtaining the appropriate API credentials.
2. Configuring the correct API environment.
3. Sending HTTPS requests to supported endpoints.
4. Processing API responses and errors.
5. Implementing appropriate retry and monitoring mechanisms.

The exact connection process depends on the product.

How does InfraRails authentication work?

InfraRails distinguishes between two authentication contexts.

Both use the x-api-key HTTP header in the current API design.

The API Gateway validates management keys through its configured usage plan, while the Lambda application validates ledger-specific credentials.

Management authorization must also enforce the appropriate ledger ownership checks.

Can I use the same API key for every ledger?

Ledger API keys are associated with individual ledgers.

Applications should use the credential belonging to the ledger they intend to access.

Do not assume a credential provides access to other ledgers.

Where should API keys be stored?

Store credentials in trusted server-side infrastructure.

Recommended options include:

• AWS Secrets Manager.
• Secure environment configuration.
• An appropriately protected secret-management service.

Never expose privileged API credentials in browser-side JavaScript, mobile application bundles, or public repositories.

Can API keys be rotated?

The InfraRails development API includes operations for rotating and revoking ledger API keys.

Rotation invalidates the previous key in the current implementation.

Applications should coordinate credential updates to avoid interrupting active integrations.

Consult the deployed API Reference for availability and exact behavior.

Environments and API requests

Is there a separate testing environment?

Environment availability depends on the platform and deployment.

Use the endpoint and credentials provided for your authorized environment.

Production and non-production environments should be configured separately.

Which HTTP methods are supported?

InfraRails currently uses standard HTTP methods.

Not every method is available for every resource.

What format should API requests use?

For operations accepting JSON request bodies, use:

Content-Type: application/json

Request fields and data types must match the relevant endpoint specification.

How are API responses structured?

Response structures depend on the endpoint.

For example, InfraRails listing operations can return paginated results containing a data array and a nextToken field.

Individual resource operations return the corresponding resource information or a documented error.

Always follow the response schema for the specific endpoint.

Pagination and filtering

How do I retrieve large lists of resources?

InfraRails development endpoints support cursor-based pagination for ledger, account, and transaction listings.

A paginated request may look like:

GET /transactions?ledger_id=LEDGER_ID&limit=25
x-api-key: YOUR_LEDGER_API_KEY

An illustrative response structure is:

{
  "data": [],
  "nextToken": "CONTINUATION_TOKEN"
}

Use the returned token to request the next page.

How do I request the next page?

Include the original filters and the returned nextToken.

GET /transactions?ledger_id=LEDGER_ID&limit=25&nextToken=CONTINUATION_TOKEN

Continue until the response contains:

{
  "data": [],
  "nextToken": null
}

A page may contain fewer records than the requested limit, even when additional results remain.

Can I reuse a pagination token with different filters?

No.

InfraRails pagination tokens are designed to be associated with the original resource scope and filtering parameters.

Use the token with the same query context.

Start a new pagination sequence when changing filters.

Which filters are supported?

The current development implementation includes:

Refer to the API Reference for exact parameter names and supported values.

InfraRails transactions

How do I create a financial transaction?

A transaction is created using the supported InfraRails transaction operation.

The request must satisfy the applicable requirements for:

• Ledger identification.
• Transaction type.
• Accounting entries.
• Monetary amounts.
• Idempotency.
• Additional transaction metadata.

Use the documented request schema rather than constructing transaction payloads from examples intended only to explain accounting concepts.

What transaction types are available?

The core ledger model includes:

Each type has its own accounting requirements.

How are monetary amounts represented?

InfraRails uses integer minor units.

For example, an EUR account with currency exponent 2 represents €25.50 as:

{
  "amount": 2550
}

This example illustrates monetary representation, not a complete transaction request.

Can transactions be processed asynchronously?

The InfraRails transaction lifecycle includes processing states such as PENDING and INFLIGHT.

Applications should inspect the returned transaction status rather than assuming every successful HTTP request represents final completion.

What should I do if a transaction request times out?

Do not immediately create another transaction.

A network timeout does not prove that the original operation failed.

Instead:

1. Preserve the original idempotency key.
2. Check whether the transaction was created.
3. Retrieve its current status.
4. Retry only when the operation's outcome and API rules permit it.

How does idempotency work?

Idempotency helps prevent duplicate execution of the same logical financial operation.

InfraRails associates eligible transaction operations with an idempotency key scoped to the ledger.

When retrying the same operation, preserve the original key and transaction parameters.

Can I search for a transaction by reference?

The current InfraRails development implementation includes:

GET /transactions/lookup

This operation supports lookup by an idempotency key or business reference.

Reference-based searches may return multiple matching transactions.

Accounts and balances

How do I retrieve an account balance?