Understanding the Trip Timeline
In every payout, Bitnob generates a Trip object that builds a complete timeline of the transaction's lifecycle.
The Trip allows you to see exactly:
When the payout was submitted,
When asset funding was detected and confirmed,
When fiat processing started,
When the transaction completed (success or failure),
Total time taken from start to final state.
This gives you a full operational view per transaction — Essential for reconciliation, monitoring, SLAs, and dispute handling.
Trip Fields Explained
| FIELD | TYPE | MEANING |
|---|---|---|
quoteAt | Timestamp | Time the quote for this transaction was generated. |
expiredAt | Timestamp | Time the quote expired (if no payment was made). |
submittedAt | Timestamp | Time the payout request was submitted to Bitnob. |
initializedAt | Timestamp | Time the payout was internally initialized after submission. |
assetReceivedAt | Timestamp | Time Bitnob first detected incoming asset funding on blockchain or Lightning. |
assetConfirmedAt | Timestamp | Time the funding was fully confirmed and considered spendable by Bitnob. |
processingAt | Timestamp | Time the payout started processing to the beneficiary. |
settlementAt | Timestamp | Time Bitnob started processing the fiat side of the payout. |
settlementFailedAt | Timestamp | Time when the fiat side of the payout failed. |
completionTime | Timestamp | Time the transaction reached a final state — success, failure, or expiry. |
timeToFinish | Integer (seconds) | Total time taken between submittedAt and completionTime. |
Visual Timeline of a Successful Trip
Submitted -> Funding Detected -> Funding Confirmed -> Processing Started -> Settlement Completed
(submittedAt) (assetReceivedAt) (assetConfirmedAt) (processingAt) (settlementAt + completionTime)
Visual Timeline of a Failed Trip
Submitted -> Funding Detected -> Funding Confirmed -> Processing Started -> Settlement Failed
(submittedAt) (assetReceivedAt) (assetConfirmedAt) (processingAt) (settlementFailedAt + completionTime)
Example Trip Object (JSON)
Developer Notes on Trip
Every Trip field is timestamped in Unix Epoch Seconds.
If a field is Webhooks are sent via HTTPS null, to your specified that stage has not yet been reached.
completionTime always indicates when the trip reached a terminal state (either settlementAt for success or settlementFailedAt for failure).
timeToFinish, = completionTime - submittedAt (measured in seconds).
Webhooks will reflect Trip status changes but developers can always query Trip directly to get timeline snapshots.
Why Trip Matters
| Benefit | Impact |
|---|---|
Transparency | You can see exactly where a payout is stuck (e.g., funding received but payout delayed). |
SLA Tracking | Time to finish allows you to measure system efficiency and promise payout timelines to users. |
Dispute Resolution | You can show proof: "We received your Bitcoin at 12:00, confirmed at 12:05, payout started at 12:10, delivered at 12:13." |
Monitoring and Alerting | You can trigger alerts if trips take too long at certain stages. |
Trip = truth timeline of your payout transaction.
Summary
Every payout has an associated Trip object.
Trip shows timestamps for submission, funding detection, funding confirmation, processing, completion (or failure).
TimeToFinish gives real operational speed metrics per transaction.
Trip allows perfect traceability and transparency end-to-end.
You can use Trip for:
Real-time status dashboards,
SLA reporting,
User notification systems,
Internal troubleshooting and audits.
