Skip to main content

​
Transfer Lifecycle

Each partner transfer moves through a series of states from creation to completion.

​
States

StatusDescription
CREATEDTransfer created, points deducted from user. Webhook pending delivery.
SENTWebhook successfully dispatched to partner.
ACCEPTEDPartner confirmed acceptance. Payout to partner wallet will be initiated.
REFUSEDPartner refused the transfer. User’s points are refunded.

​
State Diagram

  User initiates transfer
           │
           ▼
       ┌────────┐
       │CREATED │
       └───┬────┘
           │  Webhook dispatched
           ▼
       ┌────────┐
       │  SENT  │
       └───┬────┘
           │  Partner processes webhook
           │  and sends confirmation
           │
     ┌─────┴─────┐
     ▼           ▼
┌────────┐  ┌────────┐
│ACCEPTED│  │REFUSED │
└────────┘  └────────┘
     │           │
     │           └── Points refunded to user
     │
     └── Payout initiated to partner wallet

​
Terminal States

  • ACCEPTED — the transfer is complete. Bankroll initiates a payout to your partner wallet address.
  • REFUSED — the transfer is rolled back. The original points deduction is cancelled and a reversal transaction refunds the user.
Once a transfer reaches a terminal state, it cannot change. Attempting to accept a refused transfer (or vice versa) returns a 409 Conflict.

​
Reconciliation

Bankroll runs a periodic reconciliation job that handles edge cases:
  • Stale CREATED transfers — if a transfer remains in CREATED for more than 30 seconds, the webhook is redispatched. This handles cases where the initial delivery failed silently.
  • Accepted transfers without payout — if an ACCEPTED transfer doesn’t have a corresponding payout, the reconciliation job initiates one.

​
Event Log

Every state transition is recorded as a PartnerTransferEvent with a timestamp and optional metadata. This provides a full audit trail for each transfer:
Event TypeDescription
CREATETransfer created
SENDWebhook dispatched
ACCEPTTransfer accepted by partner
REFUSETransfer refused by partner (includes reason)