Developer Quick Start

Everything you need to integrate with the Bultra API: authentication, request handling, webhooks, and best practices.

Authentication

Bultra uses OAuth2 with the client credentials grant type for API authentication. During registration, you'll receive a client ID and secret that must be housed securely.

Token Generation

To create access tokens:

  1. Combine your credentials: {clientID}:{secret}
  2. Base64 encode the combined string
  3. Submit a POST request to the authentication endpoint with the encoded value in the Authorization header using the Basic scheme
POST /oauth2/token HTTP/1.1
Host: auth.bultra.com
Authorization: Basic {base64(clientID:secret)}
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials

Token Expiration

Token lifespan varies by environment:

Environment Token TTL
Production 15 minutes
App 15 minutes
Development 12 hours

Best Practice: Implement token refresh capability in your integration to handle the 15-minute TTL in production environments.

Access Control via Scopes

Bultra implements granular permission control through scopes covering:

Security: Request only the scopes needed for your specific function. Following the principle of least privilege reduces security risk.

Idempotence

Idempotence allows you to safely retry API requests without duplicating operations. This is particularly useful when network issues prevent you from receiving a response.

How It Works

Certain Bultra endpoints support idempotent requests through an optional x-bultra-idempotency-id header:

POST /v1/transfers HTTP/1.1
Host: api.bultra.com
Authorization: Bearer {access_token}
x-bultra-idempotency-id: 550e8400-e29b-41d4-a716-446655440000
Content-Type: application/json

{
  "source_account_id": "acc_123",
  "destination_account_id": "acc_456",
  "amount": "1000.00"
}

Practical Application

A common scenario: if you request a transfer acceptance but don't receive a response due to connectivity problems, you can confidently retry using the original idempotency ID. Bultra ensures only one transfer executes, even with multiple attempts.

Note: Not all endpoints support idempotency. Check the specific endpoint documentation to confirm support before implementing this pattern.

Webhooks & Subscriptions

Subscriptions enable asynchronous event-based notifications. They allow you to receive real-time updates when specific events occur in the Bultra system.

Registration Process

Management of subscriptions happens through the Subscriptions API. You can:

Important: Production webhook URLs must be explicitly whitelisted by Bultra before receiving callbacks. Contact your implementation engineer or account manager for approval.

Event Structure

All subscription events follow a consistent format with four key components:

Field Description
event_id A unique, idempotent UUID that remains unchanged during event replays
event_date Timestamp indicating when the event was generated
event_type Classification of the event with type-specific details
event_data Business information relevant to that particular event

Example Event Payload

{
  "event_id": "evt_550e8400-e29b-41d4-a716-446655440000",
  "event_date": "2024-01-15T10:30:00Z",
  "event_type": "PAYMENT_EXECUTED",
  "event_data": {
    "payment_id": "pay_123456",
    "status": "EXECUTED",
    "amount": "5000.00",
    "currency": "USD"
  }
}

Available Event Types

Common subscription events include:

Design Note: Events are intentionally minimal, containing only essential decision-making information. For additional context, use the event IDs to call the appropriate GET endpoints for enriched data.

Environments

Bultra provides multiple environments for different stages of development:

Environment Purpose Token TTL
Development Initial integration and testing 12 hours
App Full testing with simulated data 15 minutes
Production Live transactions 15 minutes

App Testing

The app.bultra.com environment allows you to test all API functionality with simulated data. Special behaviors include: