State Lifecycles

Understanding resource state transitions is essential for building robust integrations. This guide documents the lifecycle of key resources in the Dakota API.

Application Lifecycle

Applications go through a defined lifecycle from creation to decision. Understanding these states helps you build proper status handling and user feedback.

Application-Level States

Status	Description	Allowed Actions
`pending`	Draft state. Application created but not yet submitted.	Add/edit entities, upload documents, submit
`submitted`	Application submitted; awaiting review.	View only
`under_review`	Review in progress.	View only
`request_for_information`	Additional information has been requested. Fires `customer.rfi.requested` with the list of `requirements`; `kyb_status` does not change. See RFI events.	Provide the requested information
`admin_revision`	The application is under revision.	View only
`approved`	Approved. The customer can transact once `kyb_status` is `active`.	View only (individuals may still upload a Proof of Address via the original onboarding link, moving to `compliance_review`)
`declined`	Declined. See compliance notes for details. `application_status` changes but no webhook is fired — poll to detect it.	View only
`compliance_review`	An individual customer has uploaded a Proof of Address document and is awaiting compliance review of that PoA. Reached only when the PoA-optional flow is enabled and an approved customer crosses the $3,000 / 7-day rolling transaction threshold (or uploads a PoA via the original onboarding link). Returns to `approved` once the PoA is reviewed.	View documents; compliance approves / rejects PoA

completed is a legacy status retained for backward compatibility; new integrations should read approved / declined. The application_decision field below is also still populated.

Application Decisions

Once an application reaches completed status, the application_decision field contains the outcome:

Decision	Description
`approved`	Application approved. Customer can transact.
`declined`	Application declined. See compliance notes for details.
`withdrawn`	Application was withdrawn before a decision was made.

Proof of Address State (Individuals)

For individual applications, the application-level poa_status field exposes the review state of the customer’s Proof of Address document. It is null for business applications.

`poa_status` value	Meaning
`missing`	No PoA on file. The customer has crossed the $3,000 / 7-day rolling threshold and any inbound transactions over the limit are being held until compliance approves a submitted PoA.
`submitted_pending_review`	PoA uploaded; awaiting compliance review.
`approved`	PoA approved by compliance. Customer is exempt from the threshold.
`rejected`	PoA rejected by compliance. Customer must upload a new document; the threshold continues to apply.

The customer.kyb_status.updated webhook event surfaces these transitions via its reason_code field — see Webhook events.

Applicant-Level States (Business & Individuals)

Within an application, each entity (business or individual) has its own status:

Status	Description
`pending`	Entity data incomplete or not yet submitted
`submitted`	Entity submitted for review
`completed`	Review complete for this entity

Transaction Lifecycle

Transactions progress through multiple states from initiation to completion.

Transaction States

Transaction Status Reference

Status	Terminal	Description
`not_started`	No	Transaction created but processing not begun
`pending`	No	Transaction is queued for processing. Auto transactions only; it reads `not_started` in `status_code`
`processing`	No	Transaction is actively being processed. Auto transactions only; it reads `in_progress` in `status_code`
`in_progress`	No	Transaction is being processed
`awaiting_confirmation`	No	Waiting for blockchain confirmation
`waiting_for_signature`	No	Waiting for the required signatures before it can be sent
`broadcasted`	No	Submitted to blockchain, awaiting confirmation
`needs_manual_input`	No	Waiting for manual action from Dakota or from you
`completed`	Yes	Transaction completed successfully
`invalid`	Yes	Transaction parameters were invalid
`failed`	Yes	Transaction failed during processing
`cancelled`	Yes	Transaction was cancelled
`reversed`	Yes	Transaction was reversed after completion. On a wallet transaction: its execution reverted on the blockchain and no funds moved
`rejected`	Yes	Transaction was rejected by compliance or provider
`timed_out`	No	Timed out with an uncertain outcome; it may still confirm. Don’t send the payment again
`pending_return`	No	A return is in flight; the transaction may still settle
`returned`	Yes	The receiving bank returned the funds
`pending_reversal`	No	A reversal is in flight; the transaction may still complete
`unknown`	No	The status could not be determined. Don’t act on it as a failure; read the transaction again or contact Dakota

A cancelled transaction has the status cancelled (two Ls). Earlier versions of this page said canceled. The API has always sent cancelled, so check your handlers for cancelled.

Wallet and auto-account transactions on GET /transactions and GET /transactions/{transaction_id} (resource_type wallet, auto_account or fx_auto_account), and wallet.transaction.* webhooks, return two status fields. status is a display label, such as Broadcasted or Success. status_code is the code from this table; the label Success has the code completed. Branch on status_code, and treat a code you don’t recognise like unknown. One-off transactions (resource_type one_off) and transaction.* webhooks have no status_code: their status is already a code from this table. See Wallet Transaction Events.

pending_return, returned, and pending_reversal appear on the transaction object, but they are not distinct webhook lifecycle stages. Read them from data.object.status on a *.updated event, or from GET /transactions/{transaction_id} (status_code where the transaction has one, otherwise status) — no separate event fires for them. See Webhooks.

Terminal vs Non-Terminal States

Terminal states indicate the transaction has reached an outcome:

completed, invalid, failed, cancelled, reversed, returned, rejected

Whether a terminal state can still change depends on the transaction:

Wallet transactions: completed, failed and reversed never change. Only a repeat of the same status, such as a hash backfill, can follow.
Auto and one-off transactions: completed can still move to pending_return, returned, pending_reversal or reversed, for example after an ACH or wire return. failed and returned can move again when Dakota retries, resumes or re-sends the payment, so keep handling updates after them.
The other terminal states (cancelled, invalid and rejected, and reversed outside wallet transactions) don’t move in the normal flow, but Dakota can still correct a status that was reported out of order. Apply every update you receive, even after a terminal state.

Non-terminal states indicate the transaction is still in progress:

not_started, pending, processing, in_progress, waiting_for_signature, awaiting_confirmation, broadcasted, needs_manual_input, pending_return, pending_reversal, timed_out, unknown

Auto Transaction Lifecycle

Auto transactions have their own lifecycle:

Status	Terminal	Description
`pending`	No	Scheduled but not yet processed
`processing`	No	Currently being executed
`completed`	Yes	Successfully completed
`failed`	Yes	Failed during processing
`cancelled`	Yes	Cancelled before processing
`reversed`	Yes	Reversed after completion

Handling State Changes

Polling for Status Updates

For non-terminal states, poll periodically to check for updates:

// Returns the auto transaction once it reaches an outcome, or null if it is
// still in flight after maxAttempts. completed, failed and returned can still
// change afterwards, so keep handling transaction.auto.updated webhooks.
async function waitForOutcome(transactionId, maxAttempts = 30) {
  const outcomeStates = ['completed', 'failed', 'cancelled', 'reversed', 'returned'];

  for (let i = 0; i < maxAttempts; i++) {
    const response = await fetch(`https://api.platform.dakota.xyz/auto-transactions/${transactionId}`, {
      headers: { 'x-api-key': API_KEY }
    });
    const transaction = await response.json();

    if (outcomeStates.includes(transaction.status)) {
      return transaction;
    }

    // Wait before next poll (exponential backoff)
    await new Promise(r => setTimeout(r, Math.min(1000 * Math.pow(2, i), 30000)));
  }

  // Still in flight, not failed: don't send the payment again. Check it later
  // or wait for its next webhook.
  return null;
}

Using Webhooks for State Changes

Instead of polling, configure webhooks to receive real-time notifications:

// Webhook handler for transaction status changes
app.post('/webhooks/dakota', (req, res) => {
  const event = req.body;

  if (event.type === 'transaction.one_off.updated' || event.type === 'transaction.auto.updated') {
    const { id: transaction_id, status: new_status } = event.data.object;

    console.log(`Transaction ${transaction_id}: ${new_status}`);

    // Handle outcomes. A completed transaction can still move to
    // pending_return / returned / pending_reversal / reversed later, and a
    // failed one can still move when Dakota retries or resumes it.
    if (['completed', 'failed', 'cancelled'].includes(new_status)) {
      // Update your database, notify user, etc.
    }
  }

  res.status(200).send('OK');
});

See Webhook Integration for complete webhook setup.

State Transition Rules

Valid Transitions

Not all state transitions are valid. The API enforces these rules: Applications:

pending → submitted (via submit endpoint)
submitted → completed (automatic after review)

Transactions:

A wallet transaction never leaves completed, failed or reversed
On auto and one-off transactions, completed can move to pending_return, returned, pending_reversal or reversed, and failed and returned can move again when Dakota retries, resumes or re-sends the payment
cancelled can only be triggered while in non-terminal state
reversed usually follows completed (a return or an originator reversal). An auto or one-off transaction that Dakota stops or refunds before it completes can also end reversed, and a wallet transaction reaches reversed without completing when its execution reverts on the blockchain

Error Handling

See Error Codes for all error types and handling best practices.

​Application Lifecycle

​Application-Level States

​Application Decisions

​Proof of Address State (Individuals)

​Applicant-Level States (Business & Individuals)

​Transaction Lifecycle

​Transaction States

​Transaction Status Reference

​Terminal vs Non-Terminal States

​Auto Transaction Lifecycle

​Handling State Changes

​Polling for Status Updates

​Using Webhooks for State Changes

​State Transition Rules

​Valid Transitions

​Error Handling

Application Lifecycle

Application-Level States

Application Decisions

Proof of Address State (Individuals)

Applicant-Level States (Business & Individuals)

Transaction Lifecycle

Transaction States

Transaction Status Reference

Terminal vs Non-Terminal States

Auto Transaction Lifecycle

Handling State Changes

Polling for Status Updates

Using Webhooks for State Changes

State Transition Rules

Valid Transitions

Error Handling