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

eventId	Status Key	Display Text	Description	Terminal State
1	created	Instance Created	The Pay-In instance has been created but the payment flow has not yet started.	No
2	initiated	Order Created	The order has been created and the end user can proceed with the Open Banking payment flow.	No
3	orderProcessing	Order Processing	The order is being processed and the Open Banking payment instruction is being prepared.	No
4	paymentProcessing	Payment Processing	The end user has initiated the Open Banking payment and Tylt is waiting for confirmation from the payment provider.	No
5	paymentCompleted	Payment Completed	The 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
6	refundProcessing	Refund Processing	A refund or return of the fiat payment has been initiated and is awaiting completion.	No
7	paymentRefunded	Payment Refunded	The fiat payment has been successfully returned to the sender.	Yes
8	paymentFailed	Payment Failed	The payment failed because of a bank, payment-provider or processing error.	Yes
9	expired	Order Cancelled or Expired	The order expired or was cancelled before successful payment completion.	Yes
10	kycFailed	KYC Failed	The required identity verification failed, expired or was not completed within the permitted period.	Yes
11	awaitingApprovael	awaiting payout approval	When autoMerchantApproval is set to 0, the payout pending approval is denoted by eventId 11	No
12	settlementInitiated	Settlement Initiated	External crypto settlement has been initiated following successful fiat payment.	No — External only
13	settlementCompleted	Settlement Completed	External crypto settlement has been successfully completed.	Yes — External only
14	hold	Hold	An 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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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