Receive an Inbound Payment to a Wallet
An inbound payment is a Tesser Payment resource with direction = "inbound". It represents funds sent on-chain from an external wallet to one of your managed accounts at Tesser. This guide covers the wallet-recipient flow: inbound payments credited to a managed wallet at Tesser. Before reading further, review the Funds Movement Lifecycle and Data Model for the shared data shape, lifecycle phases, and status taxonomy that apply to inbound payments along with Tesser's other funds-movement resources, and Compliance and Risk Management for the two compliance checks — Travel Rule data exchange and wallet risk screening — that shape the inbound lifecycle.
What's Different About Inbound Payments
Inbound payments share the Payment resource shape with outbound payments but diverge in several ways. Note these before you begin your integration:
- Two entry paths. An inbound payment either begins with a Travel Rule authorization request from the originator VASP, in which case the payment record is created before funds move, or arrives as a direct on-chain transfer, in which case the record is created when Tesser sees the transaction in a block. See How an Inbound Payment Begins.
- No customer-side planning. The
desiredoverlay does not populate.estimatedpopulates when Tesser records the inbound payment;actualpopulates only when the block finalizes (atstep.completed/payment.updated). There is no quote, nopayment.quote_createdwebhook, and noPATCHstep. - No balance check.
balance_statusisnullfor the life of an inbound payment. Funds are being credited to the wallet's balance, not debited from it, so there is no balance to reserve and nounreserved→reservedtransition to report. - No signing. Your integration never calls a sign endpoint for an inbound payment. The on-chain transaction was signed by the external sender, not by you.
- Exactly one step. The payment contains exactly one step, of type
transfer. Inbound payments get created with stepstatusascreatedwhen the record predates the transaction (a Travel Rule authorization flow) and with stepstatusasconfirmedwhen the record is created from a direct on-chain transfer without the Travel Rule flow. Stepstatuswill beconfirmedonce the transaction is in a block,completedonce the block finalizes, andfailedif the block never finalizes. Stepstatusfollows the money only: the outcome of a Travel Rule authorization request is recorded in the step'sstatus_reasons[]and never changes itsstatus. - No expiration.
expires_atis alwaysnullon an inbound payment. You are receiving funds on-chain rather than instructing a payment, so there is nothing to expire. - The originator is identified through
participants[], not supplied by you. Tesser reconciles the originating participant, and the VASP hosting the sending wallet, if there is one, against the records of the tenant that owns the receiving account (or your workspace-level records when the account has no tenant), and records the outcome in the payment'sparticipants[]array.participants[]stays empty untilpayment.participants_updatedpublishes it. See How the Sending Wallet Is Identified and Inbound Payment Participants. funding_account_idis the originator's account at their VASP, when Travel Rule data names one. It points at a generic account owned by theORIGINATOR. Otherwise it isnull, and the sending wallet is identified throughestimated.from.account_idandparticipants[]. See The Originator's Funding Account.- Risk screening targets the sender and is advisory. Because the recipient is your managed wallet, Tesser screens the external sending wallet against your organization's risk policy and notifies you of the outcome via
payment.risk_updated. Screening runs in parallel with the on-chain lifecycle and does not gate the credit — the receiving wallet's balance updates when the transaction is confirmed in a block, regardless of the risk outcome.
How an Inbound Payment Begins
An inbound payment can begin one of two ways:
- Through a Travel Rule authorization flow. The sending (originator) VASP requests authorization through a Travel Rule data-exchange provider before broadcasting the transaction on-chain, and exchanges identity information as part of that request. Tesser creates a payment record and populates it with the data available from the Travel Rule provider.
- As a direct on-chain transfer. A sending wallet pushes funds to the wallet with no prior authorization request. No Travel Rule data accompanies the transfer, so Tesser creates the payment record when it sees the transaction in a block and infers what it can about the sender from screening the sending wallet through a blockchain analytics provider.
A note on settlement
For inbound payments, funds are credited to your available balance regardless of the screening outcome. Tesser's risk_status is an advisory signal you consume to decide whether to credit your end user; it is not a hold on funds Tesser has already credited. See Why Availability Isn't Gated on the Screening Outcome.
Continuous Monitoring of Wallets for Inbound Payments
You do not need to pre-register inbound payments in order to receive funds on-chain. Tesser monitors wallets for on-chain activity and when an inbound transaction is detected, will create a payment record, counterparties and accounts (if needed), and notify your integration via webhooks. Tesser will first become aware of an on-chain transaction when that transaction is confirmed in a block.
When funds arrive on-chain, Tesser checks whether Travel Rule data already names the transaction. If it does, the transfer is reconciled to the payment record created from that flow rather than creating a second record, even when the amount differs from the declared one (for example, when the sending VASP deducts a fee). Only the transaction named in the Travel Rule data links the two: a transfer to the same wallet with the same amount is not enough. When the Travel Rule data never names the transaction, the funds and the Travel Rule data stay two separate payment records. When it names the transaction only after both records exist, Tesser moves the Travel Rule data onto the payment that received the funds, and records transfers-9217 on the other record's step, naming that payment. The other record received no funds and stays in created.
Travel Rule Workspaces Wait for Travel Rule Data
In a workspace with Travel Rule enabled, the originator VASP often names the transaction a few seconds after the funds land. So that those funds reconcile to the Travel Rule payment record instead of creating a second one, Tesser waits before it records an inbound payment on an EVM network (such as Ethereum, Base or Polygon):
- The wait ends when Travel Rule data names the transaction. The funds reconcile to that payment record, its step moves to
confirmed, and the wallet is credited. - Otherwise it ends about 5 minutes after Tesser detects the transaction on-chain. Tesser then creates the payment record from the on-chain transfer, as for any direct transfer, and credits the wallet. In rare cases, such as an internal retry, the wait can stretch to about 12 minutes; it never lasts indefinitely.
- Nothing is recorded or credited during the wait. No
payment.createdfires, and the wallet's balance does not include the funds until the wait ends. - Solana and Stellar deposits don't wait, and neither do deposits to workspaces without Travel Rule enabled. Solana and Stellar deposits are also never reconciled to Travel Rule data: each becomes its own payment.
When two transfers to the same wallet travel in one transaction and Travel Rule data can't tell them apart, Tesser reconciles neither: each becomes its own payment, and the Travel Rule payment record keeps its step in created. This holds whether the Travel Rule data arrives before or after the funds.
How the Sending Wallet Is Identified
Tesser identifies the participant(s) on the other side of an inbound payment in the payment's top-level participants[] array. For an inbound payment, the array can identify the ORIGINATOR, the ORIGINATOR_VASP, a CUSTODY_SERVICE and/or INTERMEDIARY_VASP, the BENEFICIARY (the counterparty or tenant that owns the receiving wallet), or a CONTRACT when the sending address is a contract rather than an end-user wallet.
Which roles populate, where each one's identity data comes from, and how each is reconciled to your records depends on whether Travel Rule data accompanied the transfer and whether the sending wallet is VASP-hosted or self-hosted.
See Payment Participants for the per-role tables, the resource object's fields, and the full set of resolution values.
Four points matter most for an inbound integration:
- Names are matched fuzzily. Provider-supplied names are scored 0–100 against your counterparty and tenant records, and a score of 85 or above matches — so a typo or a different word order still resolves to the record you already hold. Where a non-beneficiary participant does not reach the threshold, Tesser creates a new counterparty for it and the entry carries
resolution: "COUNTERPARTY_CREATED". See Payment Participants for what the scorer does and does not tolerate. - Your beneficiary record is canonical. Tesser never creates a new beneficiary record from provider data. If an originator VASP supplies a beneficiary name that does not match your record, the
BENEFICIARYentry carriesresolution: "DID_NOT_MATCH". An inbound payment withresolution: "DID_NOT_MATCH"for theBENEFICIARYrole is how you know a Travel Rule authorization was received but rejected prior to funds movement. Where no provider-supplied beneficiary name existed to match at all, the entry carriesresolution: "USER_SUPPLIED_ID". For this rejection, the step remainscreatedand itsstatus_reasons[]carriestransfers-9215; a rejection because the Travel Rule data was incomplete under your data-completeness setting carriestransfers-9323, and a rejection Tesser did not make (e.g. one by the originator's VASP or the Travel Rule provider) carriestransfers-9218. Older payments carrytransfers-9203for either of the last two. - One sending wallet can produce more than one array entry. A hot wallet used to send funds out of an exchange, for example, may be attributed both to the exchange itself (
ORIGINATOR_VASP) and to the third-party custodian that holds its wallets (CUSTODY_SERVICE). - Travel Rule data takes precedence for entity attribution. Where a Travel Rule authorization flow supplied the identity data, Tesser treats it as the source of truth for the roles it covers. Wallet screening attribution still fills in roles the Travel Rule payload does not describe, e.g. a custody service or an intermediary VASP the originator VASP did not declare.
Recording the Sending Wallet on the Payment
When Tesser records an inbound payment from a wallet address it has not seen before, it automatically creates an unmanaged wallet account (is_managed: false) for the sending wallet and assigns it to the counterparty the sender reconciled to. If Tesser recognizes the wallet address — because the sender is a repeat sender, or because an outbound payment previously sent funds to this address — Tesser identifies the existing account by looking up the wallet address.
estimated.from.account_id populates as soon as Tesser has the transaction, because the sending address is on the transaction itself — it does not wait for the screening outcome. For a direct on-chain transfer it is present from record creation; for a Travel Rule flow it fills in when funds land on-chain. The participants[] entry that identifies who that wallet belongs to arrives later, in payment.participants_updated once screening resolves. See When Each Field Populates.
The auto-created account follows this shape:
Code
The account is assigned to whichever record the sender reconciled to. Read the corresponding participants[] entry's resource.resource_type to know which: for a COUNTERPARTY the account carries counterparty_id, and looking that counterparty up returns its tenant_id for tenanted integrations; for a TENANT the sender resolved to the tenant that owns the receiving account, a transfer from that tenant's own wallet; WORKSPACE means the funds came from one of your own treasury wallets. Subsequent inbound payments from the same wallet address reuse this account.
The sending account's assets[].available_balance stays "0". Tesser does not monitor balances on unmanaged accounts — the record exists to identify where the funds came from, not to track what that wallet holds.
Wallet Clusters for Unattributed Sending Wallets
Where the sender cannot be identified by name, Tesser still creates a counterparty so the payment has something to reconcile to. This happens when there was no Travel Rule data and the wallet screening provider does not attribute the sending address to a named entity. That counterparty has classification: "wallet_cluster".
A wallet cluster groups the address(es) the screening provider believes are controlled by the same owner. It means "we know these addresses belong to one owner, but not who that owner is." When the screening provider labels the cluster, repeat sends from any address in it reconcile to the same counterparty. An unlabelled cluster is named after the sending address, so each address reconciles to its own counterparty.
A wallet cluster's name is a label for that group of addresses, not a legal name:
- When the screening provider labels the cluster, the counterparty takes that label.
- Otherwise it is named after the sending address: the words "Wallet Cluster" followed by the full wallet address, for example
Wallet Cluster 0x742d35Cc6634C0532925a3b844Bc9e7595f8fE0B.
Code
Three points matter when you work with wallet clusters:
- Only Tesser creates them. You cannot create a counterparty with
classification: "wallet_cluster", and you cannot yet reclassify a wallet cluster as abusinessorindividualonce you learn who owns the addresses. - List them with the
classificationfilter.GET /v1/entities/counterparties?classification=wallet_clusterreturns only wallet clusters, andsearchmatches their names. - They cannot be a party to a payout. A wallet cluster has no identity to share, so a payout or off-ramp that sends the originator's or beneficiary's details to a provider rejects it with
counterparties-3016. A wallet cluster can still be an inboundORIGINATOR, and it can own the unmanaged account that represents the sending wallet.
When Each Field Populates
An inbound payment record is created at the earliest point Tesser has something to record, and its remaining fields fill in as the compliance checks resolve.
| Stage | What has happened | What populates |
|---|---|---|
| Travel Rule authorization request received (Travel Rule flows only) | Tesser runs the beneficiary-name match and authorizes or rejects the request, then creates the payment record and its single transfer step in created status, with the outcome in the step's status_reasons[]. Funds have not yet moved. If the funds already landed and the Travel Rule data names their transaction, Tesser attaches the request and its outcome to the existing payment instead of creating a second one; see The Originator's Funding Account for what changes then. Otherwise it creates its own record. | estimated.to.account_id, and the estimated amount, currency, and network at both the top level and the step level; participants[], published right after payment.created in payment.participants_updated; the TRAVEL_RULE entry in provider_metadata[]; and funding_account_id when the originator VASP sent an account number. estimated.from.account_id is left blank. risk_status is unchecked and risk_status_reasons[] is empty. |
| Funds land on-chain | In a workspace with Travel Rule enabled, an EVM transfer first waits about 5 minutes for Travel Rule data; this stage happens when the wait ends. For a Travel Rule record, Tesser reconciles the transfer to it and now knows which wallet sent the funds; the step moves from created to confirmed. When no record matches, Tesser creates one now, with its step already in confirmed. Either way, wallet screening kicks off and the receiving wallet is credited. | The step's status, transaction_hash, and confirmed_at; and estimated.from.account_id. The receiving wallet's available and total balance are credited. For records created at this stage: estimated.to.account_id, network, and estimated amounts are also populated, with participants[] empty, risk_status unchecked, and risk_status_reasons[] empty. |
| Screening resolves | The wallet screen completes and Tesser determines whether the sender's identity reconciles to existing records or requires new counterparties. | risk_status and risk_status_reasons[]; the WALLET_RISK_SCREENING entry in provider_metadata[]; and, for records created at the funds-landing stage, participants[], published in payment.participants_updated. |
| Block finalizes | The transaction is final and can no longer be reorganized away. | The step moves to completed; the step-level and top-level actual overlays populate. The balance does not change here — it was credited at confirmation, and finalization makes that credit permanent. |
Manual review (only when risk_status is awaiting_decision) | Your reviewer records a decision. | risk_status moves to manually_approved or manually_rejected; risk_reviewed_by and risk_reviewed_at populate. risk_status_reasons[] is unchanged from the automatic outcome. |
participants[] is first published in payment.participants_updated, which is delivered at least once. Data that arrives later is appended, and payment.participants_updated fires again. Until the first one it is an empty array in GET /v1/payments/{id} and in every payment webhook. For the timing across all payment directions, see When participants[] Populates.
Inbound Payment Creation (payment.created)
payment.created fires when Tesser creates the payment record. When that happens depends on the entry path.
About the payload examples on this page
The webhook payloads below are abridged to the fields that matter at each stage — // ... marks fields present on the wire but omitted here. Every payload carries the complete payment resource, wrapped in the standard { id, type, created_at, data: { object } } envelope. For the full field list see the Payments API reference; for the envelope, see Webhooks.
Travel Rule Authorization Flow
For a payment that begins with a Travel Rule authorization request, payment.created fires before funds move. The payload records the destination account, the raw transfer record in provider_metadata[], and the single transfer step in created status — the step exists to hold the money movement the authorization anticipates, but nothing has happened on-chain yet, so transaction_hash and confirmed_at are both null.
participants[] is still empty: the reconciled participants follow right after, in payment.participants_updated. The sending account is necessarily absent at this point because the transaction has not happened yet:
estimated.from.account_idisnull. The originator VASP tells Tesser who is sending, not which wallet they will send from, so there is no sending account to reference until funds land. It is never pre-filled with a stand-in.estimated.*.networkis populated. Tesser only authorizes supported CAIP-19 assets, so the declared token identifies the network before funds move.
expires_at is null, as it is on every inbound payment.
Early Payment Records
Tesser can create the payment record as soon as the originator VASP opens the Travel Rule transfer, before Tesser has authorized or rejected it. This is turned on per organization; contact Tesser support to enable it. With it on, for a transfer on an EVM network:
payment.createdfires when the transfer is opened, with the step increated, the declared amount, currency, network and destination, and aTRAVEL_RULEentry inprovider_metadata[]that does not yet hold the originator's or beneficiary's details.funding_account_idisnull, andparticipants[]is empty. Nothing else is sent until Tesser decides or the funds land.- The decision lands on the same payment.
step.updatedcarries the outcome instatus_reasons[], andpayment.participants_updatedpublishes the participants. TheTRAVEL_RULEentry andfunding_account_idfill in at the same time. - When the originator VASP reports the transaction before Tesser decides, the payment gets the originator's details then, and the funds credit it when they land.
payment.participants_updatedfollows the screening of the funds, and the decision arrives later asstep.updated. - A payment whose funds never arrive stays
created, with no expiry. A transfer the originator VASP never follows up keeps a payment with no decision. Ignore payments whose step stayscreatedwith notransaction_hash.
If the transfer was already decided when Tesser first hears of it, the payment is created as it would be without early records. If only its transaction was reported, the payment already holds the originator's details, and payment.created still fires at once.
The Originator's Funding Account
The originator VASP usually sends the originator's account number with its own records (IVMS101 accountNumber): a customer id, an IBAN, or any other identifier the VASP uses. Tesser records it as the payment's funding_account_id, pointing at a generic account owned by the record in the ORIGINATOR entry of participants[]:
- Tesser reuses the owner's account for that number when one exists, whoever created it. If you registered the originator's account yourself with
POST /v1/accounts/generic, the payment points at that account. Repeat payments from the same originator and number share one account. - Otherwise Tesser creates one, with
created_by: "SYSTEM", the originator's account number asgeneric_account_number, and the name"<originator VASP name> Unique Identifier", or"Unique Identifier"when the Travel Rule data doesn't name the originator VASP. You can rename it withPATCH /v1/accounts/{account_id}. - Tesser uses the first non-empty account number the VASP sent and doesn't interpret it. It is never matched against wallet addresses, so it never points at the sending wallet's account, even when the number looks like one. The raw value stays in the
TRAVEL_RULEentry inprovider_metadata[]. funding_account_idisnullwhen the VASP sent no account number or named no originator. Nothing else about the payment changes.- When the funds land before Travel Rule data that names their transaction, and the wait for Travel Rule data ends first, Tesser has already created the payment from the on-chain transfer and sent
payment.created. The Travel Rule data then attaches to that payment and setsfunding_account_idby the rules above, and apayment.updateddelivers it. When the Travel Rule data names the originator VASP, wallet screening runs again instead, and itspayment.risk_updatedcarries the same fields, unless a risk review decision is already recorded on the payment: screening doesn't run again then, andpayment.updateddelivers them. Travel Rule participants that arrive before the participants are published are part ofpayment.participants_updated; those that arrive after are appended, asORIGINATOR_UPDATED,ORIGINATOR_VASP_UPDATEDorBENEFICIARY_UPDATEDfor a role already published, in anotherpayment.participants_updated. - Once set, it doesn't change. A redelivered Travel Rule authorization leaves the payment as it is, and Travel Rule data arriving after the funds never replaces a funding account the payment already has.
A generic account has no network, currency, or balance. It identifies the originator. It can't send or receive funds.
Beneficiary Name Match
Once Tesser receives the Travel Rule data from the Originator VASP, it will check whether the Beneficiary name sent by the Originator matches the name your organization recorded for the counterparty owner of the destination wallet account. In other words, does your organization and the Originator VASP agree that "John Smith" owns the destination wallet, or does the Originator VASP think a different entity owns the destination wallet?
If the check passes, Tesser will return an "authorization" response to the Travel Rule data provider. If the check fails, Tesser will instruct the Travel Rule provider to reject the inbound payment. Either way, the outcome does not change the step's status: the originator may still send the funds, and if they arrive the payment moves through confirmed and completed as usual.
The result of the check is visible on the participants[] once payment.participants_updated publishes them. When the Travel Rule data arrives after the participants were published, the result is on a BENEFICIARY_UPDATED entry appended after them, and the earlier BENEFICIARY entry stays as it was. Read the result from the last entry at BENEFICIARY or BENEFICIARY_UPDATED whose resource_type is not ACCOUNT: its resolution is EXACT_MATCH or PARTIAL_MATCH for an authorized request, DID_NOT_MATCH for one Tesser rejected on the beneficiary-name match. The outcome is also recorded on the step's status_reasons[] and announced with step.updated: transfers-9216 for an authorized request, transfers-9215 for one Tesser rejected on the beneficiary-name match, transfers-9323 for one Tesser rejected because the Travel Rule data was incomplete under your data-completeness setting, and transfers-9218 for other Travel Rule rejections (transfers-9203 on older payments for either of the last two). Outcomes are appended, never replaced: a later decision on the same transfer adds a new entry. The current decision is the last entry with one of these codes; an earlier transfers-9216 stays in the list after a later rejection, so don't treat its presence alone as authorized.
Code
Until the funds arrive, the step's transaction_hash is null. When the sending VASP reports the transaction it sent, the payment's NOTABENE entry in provider_metadata carries it as settlementId, the CAIP-220 id Notabene reports (for example eip155:84532:tx/0x…). No webhook announces it; read it with GET /v1/payments/{id}. Payments recorded before this change may have no settlementId, and a step still created may show the settlement transaction in transaction_hash until Tesser migrates it.
When funds subsequently land on-chain, Tesser matches the on-chain transaction to the payment record and moves the step from created to confirmed status. That transition fires step.confirmed followed by payment.updated webhooks, which carry the step's new status, transaction_hash, confirmed_at, and the now-known estimated.from.account_id. From that point the payment follows the same path as a direct on-chain transfer.
step.confirmed is specific to this entry path. A direct on-chain transfer never fires it, because its step is already confirmed when the record is created — there is no transition to report.
Direct On-Chain Transfer
For a transfer that arrives with no Travel Rule data, payment.created fires when Tesser sees the transaction in a block. The step is already in confirmed and the estimated overlay is fully populated at both the top level and the step level, estimated.from.account_id included — the sending address is on the transaction, so the sending account is known from the outset. participants[] and provider_metadata[] are empty, because both depend on the screening result, and the actual overlay is present with all sub-fields still null.
Code
Inbound Payment Participants (payment.participants_updated)
payment.participants_updated fires when Tesser publishes the payment's participants[], normally after payment.created, and again, at least once, after it appends data that arrives after publication. Delivery is at least once, so you may receive it more than once, and it normally arrives after payment.created without that order being guaranteed: key on the payment id rather than on the order of events. It is sent:
- Travel Rule authorization flow. Right after
payment.created, before funds move, with the participants the Travel Rule data names. - Direct on-chain transfer. Once the wallet screen of the sending wallet completes, with the participants screening identified.
- Data after publication. When Travel Rule data, or a later screening, identifies parties after the participants were published. The published entries stay as they were, in the same order, and the new ones follow: a role already published comes back as
ORIGINATOR_UPDATED,ORIGINATOR_VASP_UPDATEDorBENEFICIARY_UPDATED, an absent role plainly. Data that adds nothing new fires nothing. See Data That Arrives After Publication.
Until this event first fires, participants[] is an empty array in GET /v1/payments/{id} and in every payment webhook, including payment.created and payment.risk_updated. Every later read and payment webhook carries the published entries.
Example payload for a direct on-chain transfer. The sending wallet was attributed to a VASP whose name did not exactly match an existing counterparty, so a new counterparty was created for it; the beneficiary carries USER_SUPPLIED_ID because no Travel Rule data accompanied the transfer and there was no supplied name to match:
Code
Inbound Payment Risk Review (payment.risk_updated)
Tesser screens the sending wallet against your organization's risk policy and reports the outcome on the payment as risk_status via a payment.risk_updated webhook. Screening runs on every inbound payment, whether or not a Travel Rule authorization flow preceded it. See Wallet Risk Screening Data for how to read risk_status_reasons[], and Wallet Screening Risk Categories for the category values.
payment.risk_updated does not publish participants[]. For a payment that arrived as a direct on-chain transfer, the participants follow once screening resolves, in payment.participants_updated. See Inbound Payment Participants.
Risk screening runs in parallel with on-chain finalization, so payment.risk_updated and step.completed can fire in either order.
If your policy requires manual review, an initial payment.risk_updated fires with risk_status: "awaiting_decision". Optionally submit a decision via the risk review decision API or in the Tesser dashboard. If a decision is recorded, risk_reviewed_by and risk_reviewed_at are populated and a second payment.risk_updated fires with risk_status transitioned to manually_approved or manually_rejected.
Test each risk outcome
In sandbox you can simulate an inbound payment at a chosen risk outcome on demand with POST /v1/payments/simulate-inbound. See Test Compliance Risk Checks.
Example webhook payload when the sending wallet is automatically approved per your organization's policy. participants[] is empty until payment.participants_updated publishes it:
Code
Inbound Payment Completion (step.completed and payment.updated)
When the block finalizes, several things occur:
- The step status transitions from
confirmedtocompleted. - The step-level and top-level
actualoverlays populate. - Tesser fires
step.completedfollowed bypayment.updatedwebhooks.
Finalization does not move the balance. The receiving wallet was credited earlier, when the transaction was confirmed in a block — see Spending the Inbound Funds. What finalization changes is that the credit can no longer be reversed.
The payment.updated payload below shows a terminal state in which risk was manually approved before the block finalized. Because screening and finalization are independent, step.completed can fire first — in that case this payload's risk_status will still be "unchecked" or "awaiting_decision", and participants[] will still be empty for a direct on-chain transfer, because payment.participants_updated has not fired yet. The actual overlay is unaffected either way: it mirrors the settled transaction, including actual.from.account_id, and does not wait on the screen.
Code
Spending the Inbound Funds
The receiving wallet's available and total balance are credited when the step reaches confirmed — that is, as soon as the transaction is in a block, not when the block finalizes. In a workspace with Travel Rule enabled, an EVM deposit reaches confirmed when the wait for Travel Rule data ends.
We nevertheless recommend waiting for the step to reach completed before spending inbound funds. Do not attempt on-chain transfers, rebalances, payouts, or off-ramps to fiat against a credit that is only confirmed. Until the block finalizes the transaction can still be reorganized away, and if that happens Tesser reverses the credit — leaving you having spent against funds that no longer exist. Finalization is what makes the credit permanent.
The credit lands on the receiving managed wallet's matching asset — the entry whose currency and network match the payment. Fetch it with GET /v1/accounts/{estimated.to.account_id}:
Code
Balances are returned in major units, the same convention the payment's estimated and actual amounts use, so a balance and a payment amount are directly comparable.
The balance is credited regardless of the risk outcome — risk screening does not hold the funds. We recommend, separately from the finality point above, that you wait for an approving risk_status (automatically_approved or manually_approved) before spending inbound funds, and reconcile any automatically_rejected or manually_rejected outcome against your own compliance policy before putting the funds to use.
Why Availability Isn't Gated on the Screening Outcome
The credit tracks the chain, not the screening outcome. Tesser credits the wallet when the transaction lands and reverses that credit only if the chain itself takes the transaction back; risk_status never holds funds. That is a deliberate choice: if Tesser withheld a rejected payment from available balance, the funds would be stranded in the receiving wallet with no way to act on them, because an on-chain transfer cannot be sent back automatically. Crediting the balance preserves your ability to respond to a rejection — returning the funds to the originator, say, or moving them to a dedicated wallet to quarantine them. Your organization's compliance policy should determine what to do with the funds after rejection.
Do not naively return funds to the sender's address
The sending wallet may not be a self-hosted wallet under the original sender's control. It could be an exchange hot wallet, a smart-contract address, or any other on-chain address — the participants[] array will tell you when the sender was attributed to a hosting VASP (ORIGINATOR_VASP) or to a contract (CONTRACT). Returning funds to such an address could deposit them into a pooled exchange account or a contract from which they cannot be recovered. If you need to return funds, coordinate the return address with the sender out of band rather than reusing the sender account's crypto_wallet_address (retrievable by looking up estimated.from.account_id via GET /v1/accounts/{account_id} — use estimated, not actual, since you may be acting on a rejection before the block finalizes).
Failure Modes for Inbound Payments
An inbound payment fails only when the chain takes the transaction back: the step transitions from confirmed to failed, step.failed fires, payment.updated follows with the failed step, and the credit is reversed. A rejected Travel Rule authorization request is not a failure: it is recorded on the step's status_reasons[] and the step keeps its status (see below).
Chain Reorganization
If the block containing the on-chain transaction does not finalize — most commonly because a chain reorganization removes the transaction from the canonical chain — the inbound payment terminates and the credit made at confirmation is reversed. This is the case the "wait for completed" recommendation exists for: the funds were in the wallet's available balance, and then they were not.
If the transaction is reorganized away during the wait for Travel Rule data, no payment is recorded and nothing is credited. If the chain includes the same transfer again in another block, the wait starts again from that block and ends as described above: the transfer is recorded and credited once, from the new block. If a Travel Rule payment record already exists and Travel Rule data names the transaction, the transfer reconciles to that record instead of creating a new payment.
What you will observe:
step.failedfires. The step transitions fromconfirmedtofailed,failed_atpopulates, and step-levelstatus_reasonscarries the failure detail.payment.updatedfires alongside, carrying the full updated payment with the failed step.- Top-level
actual.*stays all-null because nothing settled.estimated.*remains populated from record creation, preserving the original observation;desired.*is all-null as always for inbound. - Risk screening is unaffected. A reorganization fails the step; it does not cancel a screen in progress or suppress its result. A screen that was still running completes normally and
payment.risk_updatedfires as usual, and a screen that had already completed keeps itsrisk_status,risk_status_reasons[], andWALLET_RISK_SCREENINGentry inprovider_metadata[]on the failed payment. The screening outcome describes the sending wallet, which does not become less true because the transaction was undone. For a payment that came through a Travel Rule authorization flow,participants[]and theTRAVEL_RULEentry inprovider_metadata[]were written at record creation and are likewise preserved. - The credit is reversed. The receiving wallet's available and total balance return to what they were before the transaction was confirmed.
Example payment.updated webhook payload at the terminal failed state, for a payment that arrived as a direct on-chain transfer whose screening had not yet completed when the reorganization was detected. risk_status is unchecked and participants[] is empty at this moment only — the screen is still running, and a later payment.risk_updated will carry its outcome:
Code
Rejected or Never-Funded Travel Rule Records
A payment record created from a Travel Rule authorization request that Tesser rejected on the beneficiary-name match, or one whose funds never arrive, records the authorization outcome and the supplied identity data. Its step stays in created until funds move it.
- The step stays
created. A rejection is recorded on the step'sstatus_reasons[](transfers-9215for the beneficiary-name match,transfers-9323for incomplete data under your data-completeness setting,transfers-9218for a rejection Tesser did not make;transfers-9203on older payments for either of the last two) and announced withstep.updated. Nostep.failedfires. - Rejected funds can still arrive. Rejecting the request asks the originator not to send, but some originators send anyway. If they do, and the Travel Rule data names their transaction, Tesser matches the transaction to this record as usual: the step moves to
confirmedand thencompleted, the receiving wallet is credited, wallet screening runs, and the rejection stays onstatus_reasons[]. - The data can move to the payment that received the funds. When the funds were already recorded as their own payment before the Travel Rule data named their transaction, Tesser moves the data onto that payment. Its participants are appended to that payment's published
participants[], as_UPDATEDentries for roles already there, and announced by anotherpayment.participants_updated. This record then getstransfers-9217on itsstatus_reasons[], naming that payment, and astep.updated. - Until funds arrive,
estimated.from.account_id, the step'stransaction_hash,confirmed_at, and everyactual.*field staynull. The declared amount, currency, network, and destination remain onestimated. participants[],funding_account_id, and theTRAVEL_RULEentry inprovider_metadata[]are preserved as written at record creation. A rejected authorization is identifiable from theBENEFICIARYentry'sresolution: "DID_NOT_MATCH".risk_statusremainsuncheckeduntil funds arrive. Wallet screening runs against the sending wallet, which is only known once funds land.- The receiving wallet's balance is untouched until funds arrive, because the credit happens at
confirmed.
Inbound Payment Event Sequence
The happy path for an inbound payment fires the following webhook events. payment.risk_updated and step.completed run on independent clocks and can fire in either order; the receiving wallet's balance is credited at confirmed, before either of them, regardless of the risk outcome.
| Event | Fires when |
|---|---|
payment.created | Tesser creates the payment record, always with one transfer step and the estimated overlay populated at the top level and the step level. Travel Rule flow: fires when the authorization request is handled, before funds move; the step is in created, estimated.from.account_id is null, and the declared amount, currency, network, destination, and TRAVEL_RULE metadata are present, and participants[] is empty. Direct on-chain transfer: fires when the transaction is included in a block, or when the wait for Travel Rule data ends in a workspace with Travel Rule enabled; the step is already in confirmed, estimated.from.account_id is populated, and participants[] and provider_metadata[] are still empty. |
payment.participants_updated | Tesser publishes participants[], delivered at least once, normally after payment.created. Travel Rule flow: right after payment.created, before funds move. Direct on-chain transfer: once the risk screening of the sending wallet completes. Fires again, at least once, after an addition after publication, such as Travel Rule data that arrives after the funds, with _UPDATED roles for roles already published. |
step.updated | (Travel Rule flow only.) The outcome of the authorization request is recorded on the step's status_reasons[]. The step's status is unchanged. Fires after payment.created, or on the existing payment when the funds landed first and the Travel Rule data names their transaction. After a late move it fires on both payments: the decision on the payment that received the funds, and transfers-9217 on the Travel Rule record. |
step.confirmed | (Travel Rule flow only.) Funds land on-chain and Tesser matches the transaction to the record created from the authorization request, moving the step from created to confirmed. A direct on-chain transfer does not fire this event — its step is already confirmed at payment.created, so there is no transition. |
payment.updated | (Travel Rule flow only.) Fires alongside step.confirmed, carrying the step's new status, transaction_hash, confirmed_at, and the now-known estimated.from.account_id. |
payment.risk_updated | The risk screening of the sending wallet completes. risk_status transitions to automatically_approved, automatically_rejected, or awaiting_decision. For a direct on-chain transfer the same payload carries the WALLET_RISK_SCREENING entry in provider_metadata[]. For the manual-review path, a second payment.risk_updated fires once a reviewer records a decision via the risk review decision API or in the Tesser dashboard, transitioning risk_status to manually_approved or manually_rejected and populating risk_reviewed_by and risk_reviewed_at. |
step.completed | The block finalizes. The step transitions to completed and the step-level actual overlay populates. |
payment.updated | Fires alongside step.completed. The top-level actual overlay populates to reflect the finalized amounts. For a Travel Rule flow this is the second payment.updated on the payment. |
The step's status is the shortest summary of where the money stands: created (recorded, nothing on-chain yet) → confirmed (in a block) → completed (finalized), or failed when a chain reorganization takes the transaction back. The Travel Rule outcome is not part of the status; read it from the step's status_reasons[]. See Failure Modes for Inbound Payments.
Reconciliation via the API
If your integration misses a webhook or needs to reconcile state on a schedule, fetch inbound payments via the Payments API:
Code
Auto-created unmanaged wallet accounts are also retrievable via GET /v1/accounts with the is_managed=false filter, and the counterparties they belong to via GET /v1/entities/counterparties. See the Payments API reference, Accounts API reference, and Counterparties API reference for the full set of query parameters.