Money Movement

Learn how to move funds using Bultra: receive payments, send withdrawals, transfer between accounts, and exchange currencies.

Payments (Collections)

Collections are payments received from external entities into Bultra accounts. The process involves establishing a counterparty, generating a payment, and managing any information requests.

Creating a Payment

Creating a payment involves four sequential steps:

1. Establish a Counterparty: Create an external fund source and obtain approval through AML screening
2. Generate Payment: Create a payment using the approved counterparty ID
3. Accept Payment: Authorize the transaction to obtain deposit instructions
4. Handle RFIs: Upload required documents if Bultra requests additional information

Payment Status Tracking

Monitor payment progression using the Retrieve Payment Status endpoint. Payment states include:

Payment Lifecycle Scenarios

Three common patterns exist:

• Happy Path: No RFI involvement—payment progresses smoothly from acceptance to execution
• Upfront RFI: Information requested before acceptance
• Post-Acceptance RFI: Documentation required during AML review after initial authorization

Withdrawals

Withdrawals enable sending fiat or cryptocurrency to external entities (counterparties). The process is similar to payments but in the opposite direction.

Creating a Withdrawal

1. Create a Counterparty: Establish an external recipient and obtain approval
2. Create Withdrawal: Initiate the withdrawal using the counterparty
3. Accept Withdrawal: Authorize the transaction
4. Upload Documents: Provide documentation if Bultra requests additional information

Withdrawal Status Lifecycle

Withdrawals progress through similar states as payments:

• REQUESTED → ACCEPTED → IN_PROGRESS → EXECUTED
• May enter CHANGES_REQUESTED if RFI is triggered

App Testing

In app.bultra.com environments, all fiat withdrawals exceeding $100 USD automatically trigger pre-acceptance RFI scenarios for testing purposes.

Transfers

Transfers move funds between any two accounts within the Bultra platform. Both accounts must hold the same asset type.

Key Constraints

• Both source and destination accounts must hold the same asset type
• Accounts can belong to different customers
• For cross-asset transfers, use the Exchange functionality instead

Three-Step Process

1. Setup the Transfer: Use the transfers endpoint to create the transfer and receive a transfer_id
2. Execute the Transfer: Accept the transfer via the transfers/{transfer_id}/accept endpoint
3. Retrieve Details: Query transfer information using the transfers/{transfer_id} endpoint

POST /v1/transfers HTTP/1.1
Host: api.bultra.com
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "source_account_id": "acc_source_123",
  "destination_account_id": "acc_dest_456",
  "amount": "1000.00",
  "reference": "Monthly settlement"
}

Exchanges

Exchanges enable currency trades by moving assets between accounts with different asset types. Currently, one side of every exchange must be a stablecoin.

Trade Types

Exchange Actions

The action field specifies which account has the fixed amount:

• FIX_SOURCE: Debits a set amount from the source account; the quote shows destination credit amount. Think of this as "selling."
• FIX_DESTINATION: Credits a fixed amount to the destination account; the quote shows source debit amount. This is like "buying" the destination amount.

Slippage Management

Slippage applies only to market exchanges with FIX_DESTINATION action. It protects against price fluctuations between quote and execution.

• Default: Maximum slippage is 100 basis points (1%)
• If actual price variance exceeds this, the trade cancels
• Any unused slippage buffer is credited back as a MARKET_ADJUSTMENT transaction

Requests for Information (RFIs)

Bultra may request supporting documentation (such as invoices) to process payments or withdrawals. All RFIs require a response to proceed.

Managing RFI Workflow

1. Detection: Subscribe to PAYMENT_CHANGES_REQUESTED or WITHDRAWAL_CHANGES_REQUESTED webhook events for notifications
2. Investigation: Use Retrieve Status endpoint to identify required documents and their IDs
3. Response: Upload documents via the Upload Document API using the provided document ID
4. Resolution: Processing resumes once Bultra approves submitted documentation

Common RFI Triggers

• Large transaction amounts
• Unusual transaction patterns
• New counterparty relationships
• Cross-border transactions
• Certain high-risk jurisdictions

RFI Lifecycle Example

// 1. Webhook notification received
{
  "event_type": "PAYMENT_CHANGES_REQUESTED",
  "event_data": {
    "payment_id": "pay_123456",
    "status": "CHANGES_REQUESTED"
  }
}

// 2. Retrieve payment status to get document requirements
GET /v1/payments/pay_123456/status

// 3. Upload required document
POST /v1/documents/{document_id}/upload
Content-Type: multipart/form-data

// 4. Payment processing resumes automatically