> For the complete documentation index, see [llms.txt](https://docs.tylt.money/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tylt.money/tylt-crossramp-fiat-crypto-solutions/eu-open-banking/open-banking-payin-eur-gbp-usdc/event-status-reference.md). # Event Status Reference Each Open Banking Pay-In transaction progresses through a payment lifecycle. For transactions configured with **external settlement**, successful payment is followed by a separate crypto-settlement lifecycle. For transactions configured with **internal settlement**, the transaction completes at `Payment Completed` (`eventId: 5`) and no separate settlement events are generated. The `eventId` identifies the current state of the transaction. Merchants should use the `eventId` received through webhooks or returned by the transaction-status endpoint as the primary transaction-status indicator. *** ### Event IDs
eventIdStatus KeyDisplay TextDescriptionTerminal State
1createdInstance CreatedThe Pay-In instance has been created but the payment flow has not yet started.No
2initiatedOrder CreatedThe order has been created and the end user can proceed with the Open Banking payment flow.No
3orderProcessingOrder ProcessingThe order is being processed and the Open Banking payment instruction is being prepared.No
4paymentProcessingPayment ProcessingThe end user has initiated the Open Banking payment and Tylt is waiting for confirmation from the payment provider.No
5paymentCompletedPayment CompletedThe fiat payment has been successfully completed. For internal settlement this is the final transaction state. For external settlement the transaction proceeds to crypto settlement.Yes — Internal / No — External
6refundProcessingRefund ProcessingA refund or return of the fiat payment has been initiated and is awaiting completion.No
7paymentRefundedPayment RefundedThe fiat payment has been successfully returned to the sender.Yes
8paymentFailedPayment FailedThe payment failed because of a bank, payment-provider or processing error.Yes
9expiredOrder Cancelled or ExpiredThe order expired or was cancelled before successful payment completion.Yes
10kycFailedKYC FailedThe required identity verification failed, expired or was not completed within the permitted period.Yes
11awaitingApprovaelawaiting payout approvalWhen autoMerchantApproval is set to 0, the payout pending approval is denoted by eventId 11 No
12settlementInitiatedSettlement InitiatedExternal crypto settlement has been initiated following successful fiat payment.No — External only
13settlementCompletedSettlement CompletedExternal crypto settlement has been successfully completed.Yes — External only
14holdHoldAn error has occured during the external settlement process. The case will be manually reviewed for resolution. If resolved settlement will reinitiate else refund will be initiated.No
*** ## Transaction Lifecycle The lifecycle depends on the transaction's `settlementType`. ### Internal Settlement Where: ```json { "settlementType": "internal" } ``` the successful lifecycle is: ``` Instance Created ↓ Order Created ↓ Order Processing ↓ Payment Processing ↓ Payment Completed ↓ COMPLETE ``` For an internal-settlement transaction: * `eventId: 5` is the final successful state. * No `Settlement Initiated` event is generated. * No `Settlement Completed` event is generated. * `eventId: 11` and `eventId: 12` do not apply. * The corresponding crypto amount is credited internally according to the merchant's configured Tylt settlement arrangement. *** ### External Settlement Where: ```json { "settlementType": "external" } ``` the successful lifecycle is: ``` PAYMENT Instance Created ↓ Order Created ↓ Order Processing ↓ Payment Processing ↓ Payment Completed ↓ EXTERNAL CRYPTO SETTLEMENT Settlement Initiated ↓ Settlement Completed ↓ COMPLETE ``` For an external-settlement transaction: * `eventId: 5` confirms completion of the fiat payment. * `eventId: 5` is not the final transaction state. * External crypto settlement is processed separately. * `eventId: 11` confirms that external settlement has started. * `eventId: 12` confirms final completion of the transaction. *** ## Payment Lifecycle ### 1 — Instance Created `eventId: 1` The Open Banking Pay-In instance has been successfully created. At this stage: * The transaction exists within Tylt. * The fiat payment amount has been defined. * The applicable crypto quote may have been calculated. * The Open Banking payment has not yet been initiated. * Settlement has not started. No fulfilment should occur at this stage. *** ### 2 — Order Created `eventId: 2` The Pay-In order has been successfully created. The end user can proceed with the Open Banking payment flow. Depending on the payment flow, the end user may now be redirected to or presented with the relevant Open Banking payment interface. The transaction remains pending. *** ### 3 — Order Processing `eventId: 3` The order is currently being processed. At this stage, Tylt and/or the payment provider may be: * Preparing the Open Banking payment instruction. * Establishing the payment session. * Preparing the bank-selection or authorization flow. * Performing processing required before the payment can proceed. The transaction remains pending. The merchant should continue waiting for the transaction to progress to `Payment Processing`, `Payment Completed` or another applicable event. *** ### 4 — Payment Processing `eventId: 4` The end user has initiated the Open Banking payment. Tylt is waiting for confirmation from the payment provider that the payment has been successfully processed. The transaction should continue to be treated as pending. The merchant should not treat the transaction as successfully paid until `Payment Completed` has been received. *** ### 5 — Payment Completed `eventId: 5` The fiat payment has been successfully completed. The meaning of this event depends on the transaction's `settlementType`. #### Internal Settlement Where: ```json { "settlementType": "internal" } ``` `Payment Completed` represents final successful completion of the transaction. At this stage: * The Open Banking payment has been successfully completed. * Payment-side processing has completed. * The applicable crypto amount has been determined. * The corresponding crypto amount has been credited internally according to the configured settlement arrangement. * No separate external blockchain settlement is required. * No `Settlement Initiated` or `Settlement Completed` events will follow. For internal settlement, merchants should treat `eventId: 5` as the authoritative final successful status. *** #### External Settlement Where: ```json { "settlementType": "external" } ``` `Payment Completed` confirms completion of the fiat-payment lifecycle only. At this stage: * The Open Banking payment has been successfully completed. * Payment-side processing has completed. * The applicable crypto amount has been determined. * The transaction can proceed to external crypto settlement. * The merchant should not yet treat the complete fiat-to-crypto transaction as settled. The transaction will subsequently progress to: ``` Settlement Initiated ↓ Settlement Completed ``` For external settlement, merchants should wait for `eventId: 12` before treating the full transaction as complete. *** ## Amount and Conversion Information Where returned by the API, transaction amount and conversion information is available under the `accounts` object. | Field | Description | | ----------------- | ------------------------------------------------------------------------- | | `fiatCurrency` | Fiat currency used for the transaction, such as `EUR` or `GBP`. | | `fiatAmount` | Fiat amount paid by the end user. | | `cryptoCurrency` | Crypto asset applicable to the transaction, such as `USDT` or `USDC`. | | `cryptoAmount` | Gross crypto amount calculated for the transaction. | | `toReleaseAmount` | Net crypto amount to be credited or externally settled. | | `rate` | Base conversion rate used for the transaction. | | `effectiveRate` | Effective transaction rate after applicable commercial pricing. | | `fees` | Fees applied to the transaction, where applicable. | | `MDR` | Commercial spread or MDR applicable to the transaction, where applicable. | The interpretation of `toReleaseAmount` depends on the settlement type: ``` internal → Amount credited internally external → Amount to be transferred through external crypto settlement ``` *** ## External Settlement Lifecycle The settlement lifecycle applies **only** where: ```json { "settlementType": "external" } ``` Following `Payment Completed`, Tylt processes the external transfer of the corresponding USDT or USDC. The external settlement lifecycle is: ``` Payment Completed ↓ Settlement Initiated ↓ Settlement Completed ``` *** ### 11 — Settlement Initiated `eventId: 11` The fiat payment has been successfully completed and external crypto settlement has been initiated. This state indicates that Tylt has started the external settlement process but settlement has not yet completed. At this stage: * The fiat payment is complete. * The crypto amount to be settled has been determined. * The external settlement instruction has been initiated. * The external transfer has not yet reached its final completed state. The merchant should continue waiting for `Settlement Completed`. This event does not apply to transactions where: ```json { "settlementType": "internal" } ``` *** ### 12 — Settlement Completed `eventId: 12` The external crypto settlement has been successfully completed. This represents final successful completion of an **external Open Banking Pay-In transaction**. The USDT or USDC has been transferred to the external wallet address configured for the transaction. Where applicable, settlement details may include: | Field | Description | | --------- | ------------------------------------------------------ | | `Status` | Current crypto-settlement status. | | `hash` | Blockchain transaction hash for the external transfer. | | `address` | Destination external wallet address. | | `Network` | Blockchain network used for settlement. | | `type` | Settlement type. | Merchants should use `eventId: 12` as the authoritative confirmation that external settlement has completed rather than relying solely on the presence of a blockchain transaction hash. This event does not apply to transactions where: ```json { "settlementType": "internal" } ``` *** ## Settlement Model The final successful event depends on `settlementType`. | Settlement Type | Final Successful Event | Final `eventId` | | --------------- | ---------------------- | --------------: | | `internal` | Payment Completed | `5` | | `external` | Settlement Completed | `12` | Accordingly: ``` INTERNAL Payment Completed ↓ COMPLETE ``` and: ``` EXTERNAL Payment Completed ↓ Settlement Initiated ↓ Settlement Completed ↓ COMPLETE ``` *** ## Refund Lifecycle Where a fiat payment needs to be returned, the transaction enters the refund lifecycle. ``` Refund Processing ↓ Payment Refunded ``` A refund may be initiated after payment activity has started or after the payment has completed, depending on the reason for the return and the capabilities of the underlying payment rail. *** ### 6 — Refund Processing `eventId: 6` A refund or return of the fiat payment has been initiated and is awaiting completion. This is not a terminal state. The merchant should suspend any pending fulfilment and continue monitoring the transaction until the refund has completed. Where external settlement has not yet occurred, settlement should not proceed. Where settlement has already occurred, additional reconciliation or recovery procedures may be required separately. *** ### 7 — Payment Refunded `eventId: 7` The fiat funds have been successfully returned to the sender. This is a terminal unsuccessful state for the original Pay-In transaction. The transaction should not be treated as successfully completed. *** ## Other Terminal States ### 8 — Payment Failed `eventId: 8` The Open Banking payment failed because of a bank-side, payment-provider or processing error. Possible causes may include: * Bank rejection. * Payment authorization failure. * Payment-provider rejection. * Technical failure. * Payment-session failure. * Payment-processing failure. The transaction should not be fulfilled or settled. If the end user wishes to try again, a new Pay-In transaction may be required depending on the integration flow. *** ### 9 — Order Cancelled or Expired `eventId: 9` The Pay-In order expired or was cancelled before successful payment completion. This may occur where: * The end user does not complete the payment within the permitted time. * The Open Banking payment session expires. * The end user cancels the transaction. * The merchant cancels the transaction. * The payment provider cancels or expires the payment flow. The transaction should not be fulfilled or settled. If the end user wishes to try again, a new Pay-In instance should generally be created. *** ### 10 — KYC Failed `eventId: 10` The required identity verification failed, expired or was not completed within the permitted period. The transaction cannot proceed while the required KYC requirements remain unsatisfied. The transaction should not proceed to payment or settlement unless the end user subsequently completes an approved verification flow and the transaction is permitted to continue. *** ## Hold ### 13 — Hold `eventId: 13` The external wallet settlement has been temporarily placed on hold. A hold may be applied where additional processing, review or information is required before the external wallet settlement can continue. Examples may include: * Compliance review. * Transaction-monitoring review. * Additional KYC requirements. * Customer-information requirements. * Payment investigation. * Bank or payment-provider review. * Operational review. * Settlement review. `Hold` is **not a terminal state**. While a transaction is on hold: * The merchant should not treat the transaction as completed unless it had already reached its applicable final successful state. * Any pending fulfilment should remain suspended. * The merchant should continue monitoring webhook updates or query the latest transaction status. * The transaction may subsequently resume from the appropriate lifecycle stage once the hold is released. *** ## Processing Event Updates Tylt sends webhook notifications as the transaction progresses through its lifecycle. The current event is returned under: ```json { "eventDetails": { "eventId": 5, "description": "Payment Completed" } } ``` Merchants should identify transactions using both the Tylt transaction identifier and the merchant's own order identifier. For example: ``` data.instanceId ``` and: ``` data.merchantOrderId ``` For external-settlement transactions, settlement-specific information may be returned separately under: ``` data.cryptoSettlementDetails ``` *** ## Recommended Merchant Handling Merchants should: * Use `eventId` as the primary transaction-status indicator. * Process webhook notifications idempotently. * Maintain the latest state for each transaction. * Match the Tylt transaction identifier and `merchantOrderId` against the merchant's records. * Treat `Instance Created` as confirmation that the Pay-In transaction has been created only. * Treat `Order Created` as confirmation that the Open Banking payment flow is available to the end user. * Treat `Order Processing` as an intermediate processing state. * Treat `Payment Processing` as confirmation that payment activity is underway but has not yet been finally confirmed. * Read `settlementType` when determining whether `Payment Completed` is terminal. * For `settlementType: internal`, treat `Payment Completed` (`eventId: 5`) as final successful completion of the transaction. * For `settlementType: internal`, do not expect `eventId: 11` or `eventId: 12`. * For `settlementType: external`, treat `Payment Completed` (`eventId: 5`) as completion of the fiat-payment lifecycle only. * For `settlementType: external`, wait for `Settlement Completed` (`eventId: 12`) before treating the full transaction as complete. * Treat `Settlement Initiated` as confirmation that external crypto settlement is underway. * Treat `Settlement Completed` as final successful completion of an external-settlement transaction. * Treat `Refund Processing` as a pending return of the fiat funds. * Treat `Payment Refunded` as final confirmation that the fiat payment has been returned. * Treat `Payment Failed`, `Order Cancelled or Expired`, `KYC Failed`, and `Payment Refunded` as terminal unsuccessful outcomes. * Treat `Hold` as a temporary non-terminal state. * Where applicable, use `accounts.toReleaseAmount` as the net crypto amount to be credited or settled. * Use `accounts.cryptoCurrency` to identify the applicable crypto asset. * Use `cryptoSettlementDetails` for external settlement metadata where returned. * Query the transaction-status endpoint when the latest state needs to be independently verified. *** ## Successful Transaction Summary ### Internal Settlement For: ```json { "settlementType": "internal" } ``` the complete successful lifecycle is: ``` OPEN BANKING PAYMENT Instance Created ↓ Order Created ↓ Order Processing ↓ Payment Processing ↓ Payment Completed ↓ COMPLETE ``` Accordingly: ``` Fiat Payment Completed + Internal Crypto Credit Completed = Open Banking Pay-In Complete ``` The final successful event is: ``` eventId: 5 Payment Completed ``` *** ### External Settlement For: ```json { "settlementType": "external" } ``` the complete successful lifecycle is: ``` OPEN BANKING PAYMENT Instance Created ↓ Order Created ↓ Order Processing ↓ Payment Processing ↓ Payment Completed ──────────────────────── EXTERNAL CRYPTO SETTLEMENT Settlement Initiated ↓ Settlement Completed ↓ COMPLETE ``` Accordingly: ``` Fiat Payment Completed + External USDT / USDC Settlement Completed = Open Banking Pay-In Complete ``` The final successful event is: ``` eventId: 12 Settlement Completed ``` *** ## Final Status Logic Merchants can determine successful completion using the following logic: ``` IF settlementType = internal AND eventId = 5 THEN Transaction = Complete ``` ``` IF settlementType = external AND eventId = 12 THEN Transaction = Complete ``` For external transactions: ``` eventId = 5 ``` means: ``` Payment Complete Settlement Pending ``` For internal transactions: ``` eventId = 5 ``` means: ``` Payment Complete Transaction Complete ```