Start here

0.15.9 Migration Guide

Review hook calls for rejected transactions, queued create errors, atomic bulk rollback, and two database migrations before you upgrade to Blnk v0.15.9.

This guide covers the changes you need to review when upgrading to Blnk v0.15.9.

Review this guide before you upgrade if your app uses POST_TRANSACTION hooks, creates queued or bulk transactions, matches bulk failure messages, or reads historical balances. Each section links to the Core 0.15.9 code or test that shows the behavior.

At a glance

ChangeWho is affected?What changed
Database migrationsEveryoneTwo migrations run with blnk migrate up.
Hooks for rejected transactionsApps with POST_TRANSACTION hooksHooks now also run when a transaction is rejected.
Queued create errorsApps that create queued transactionsA used reference or unknown balance now returns an error instead of 201.
Atomic bulk rollbackApps that send atomic bulk requestsQueued atomic batches now roll back when a worker rejects an item. Handle the new batch failure event idempotently.
Monitor updatesApps that update balance monitorsA PUT changes only the fields you send.
Negative split distributionsApps that send split transactionsA negative distribution is rejected.
Balance historyApps that read historical balancesBackdated transactions are now counted correctly.

Database migrations

0.15.9 adds a column that balance history uses, and drops four database triggers that Blnk no longer uses.

What to do:

  1. Pause transaction submissions and let queued jobs finish.
  2. Stop the old API and every old worker. A 0.15.8 worker does not check whether a queued atomic batch has failed, so it can apply items that 0.15.9 would reject.
  3. Back up the database and run blnk migrate up. The bundled Docker Compose file runs it on start.
  4. Start the 0.15.9 API and workers.

The trigger migration sets a 3-second lock timeout so it fails instead of blocking writes. If it times out, wait for long-running queries to finish and run it again.

Both migrations have down steps. The trigger down step recreates the triggers. The snapshot down step drops last_tx_seq, so snapshots taken on 0.15.9 lose it. Test a rollback on a copy of your database first.

Hooks for rejected transactions

From 0.15.9, a rejected transaction calls your POST_TRANSACTION hooks. data.status is REJECTED, and data.meta_data.blnk_rejection_reason says why.

{
  "transaction_id": "txn_aa13b549-c278-47ee-87d7-2e2cfcad99ce",
  "hook_type": "POST_TRANSACTION",
  "data": {
    "status": "REJECTED",
    "meta_data": {
      "blnk_rejection_reason": "failed to apply transaction to balances: insufficient funds in source balance"
    }
  }
}

What to do: Check data.status before your hook acts on the call. See Transaction hooks.

Queued create errors

Blnk now saves a queued transaction before it answers. A used reference returns 409 TXN_DUPLICATE_REFERENCE, and an unknown balance returns 404 BAL_NOT_FOUND. Before, both returned 201 and the transaction was never recorded.

What is saved depends on the request:

RequestWhat Blnk keeps after the error
Single transactionNothing. The new attempt has no transaction or REJECTED record. On 409, the original transaction with that reference is unchanged.
Bulk requestThe items before the failing one. They were already queued and still process, even with atomic: true. Items after it are not saved.
Split transactionThe legs before the failing one, saved as QUEUED. Queue recovery picks up QUEUED rows after about 2 hours and can apply them.

What to do: On 409, look up the original reference instead of retrying. On 404, fix the balance ID before retrying. After a failed bulk request or split, check each reference before you resend anything. See Reconcile a queued batch after a duplicate reference.

Atomic bulk rollback

From 0.15.9, when a worker rejects an item in a queued atomic: true batch, Blnk refunds applied items or voids inflight items and emits one bulk_transaction.failed event for the batch. Blnk records the items still waiting in the queue as REJECTED when it reaches them. Before, only skip_queue: true rolled back.

If Blnk finds a duplicate reference while adding items to the queue, items already queued may still process, even in an atomic batch. Reconcile by batch ID and reference before resubmitting any items. See Reconcile a queued batch after a duplicate reference.

The failure message now says how many items were refunded, instead of All transactions in this batch have been refunded.

What to do: Listen for bulk_transaction.failed and deduplicate it on data.batch_id. Blnk queues one event per batch, but webhook delivery can repeat. If your code matches the old message text, match the event instead. See Bulk transactions.

Monitor updates

From 0.15.9, PUT /balance-monitors/{monitor_id} changes only the fields you send. A partial body used to fail with 500.

What to do: If your app sends precision without value, include value in the same request to change the scale. If your app does not send precision alone, no change is required. See Update balance monitor.

Negative split distributions

A negative distribution used to be accepted, and the "left" leg received the difference. From 0.15.9, negative distribution and precise_distribution values return 400 TXN_VALIDATION_ERROR; no balance moves.

What to do: Send 0 or a positive value for each leg. See Split transactions.

Balance history

Balance history could miss a backdated transaction or count a future-dated one twice. From 0.15.9, each transaction is counted once, at its effective_date.

Snapshots taken before the upgrade are skipped until new ones replace them. from_source=true results do not change.

What to do: Expect some past balances to change. If you store history results, read them again, and take a snapshot after you upgrade. See Historical balances.

Core release references