Status mapping reference
A single reference for deal, payout, dispute, withdrawal, and whitelist pass statuses on the Syncra V2 platform
Status reference and mapping
This section gives the canonical table of every entity state on the Syncra V2 platform. The V1 compat column is provided for reference only — for merchants migrating from the V1 platform.
All string values are case-sensitive (transmitted as
UPPER_SNAKE_CASE), except amount_match_status, which is always
lowercase (full / partial / overpaid).
Requisite types
The platform is not tied to a specific country or payment infrastructure: the choice of market (Russia, CIS, Turkey, EU, ...) is determined by the tenant configuration. Any payment instrument is a requisite of one of five types:
| Requisite type | Description | Key field in CheckoutView |
|---|---|---|
BANK_CARD | Transfer by bank card number (Card2Card, P2P). The basic method for RU/CIS. | card_number, holder_name |
E_WALLET | Transfer to an electronic wallet (a digital identifier). | card_number (wallet identifier), holder_name |
SBP | Transfer by phone number through SBP, the Russian faster payment system. | phone_number, holder_name |
SIM | Transfer tied to a SIM number (mobile channels). | phone_number |
BANK_TRANSFER | International bank transfer by IBAN (ISO 13616). Havale (TR), SEPA (EU), and analogues. The IBAN is encrypted the same way as the PAN. | iban, holder_name |
The requisite type is not passed in the CreateMerchantPayIn
request. It is determined by the merchant → payment_method_id →
currency configuration and returned to the client on the payment page
via the CheckoutView fields.
Amount match status
Transmitted only in PayIn webhook events (the amount_match_status field
of CallbackEventPayload) and in CheckoutView. Always lowercase.
| Value | Description |
|---|---|
full | The received amount exactly matched the declared one. |
partial | Less than declared was received. |
overpaid | More than declared was received. |
amount_match_status is not an OrderStatus; it is a derived
attribute of a deal in COMPLETED / PAYMENT_VERIFIED. Display
priority: overpaid > partial (a deal cannot be in both at once).
Incoming payments (PayIn OrderStatus)
The canonical PayIn deal lifecycle has 11 values. Status transitions are managed by the system automatically.
| Canonical V2 status | Final? | State description | V1 compat (reference) |
|---|---|---|---|
INITIALIZED | No | The deal is created, waiting for the escrow lock and payment. | 1 WaitingPayment / 31 WaitingPaymentChannel |
ESCROW_LOCKED | No | The escrow hold is reserved, payment details issued to the client. | 1 WaitingPayment |
PAYMENT_NOTIFIED | No | The client pressed "I paid", waiting for the trader's check. | 2 ConfirmedByPayer |
PAYMENT_VERIFIED | No | The incoming funds are confirmed by the trader, the amount is reconciled. | 11 Paid |
COMPLETED | Yes (success) | The deal is finally completed successfully. amount_match_status=full/partial/overpaid refines the outcome. | 11 Paid / 14 OverPaid / 15 PartiallyPaid |
EXPIRED | Yes (timeout) | The deal expired by payment_timeout_at before verification. | 13 Timeout |
APPEALED | No | An appeal is open on the deal — handed to arbitration. | 21 Disput |
REFUND_PENDING | No | An internal transit state on the way to CANCELLED: the deal is recognized as third-party (a rejected appeal, a third-party flag). Externally it shows up as the webhook pair deal.refund_pending → deal.cancelled; there is no money movement — holds are released idempotently. Requires no merchant action. | 32 RollingBack / 16 Returned |
SPAM_REJECTED | Yes (rejection) | The deal is rejected by the antifraud system. | 12 Cancelled |
SOFT_DISPUTED | No | A soft dispute: a data discrepancy without a full appeal. | 21 Disput |
CANCELLED | Yes (rejection) | The client or the merchant explicitly canceled the deal before payment confirmation. PayIn only; escrow holds are released automatically. | 12 Cancelled |
The V1 codes 14 (OverPaid) and 15 (PartiallyPaid) are not
separate OrderStatus values in V2. The deal stays in COMPLETED, and
the overpayment/underpayment is signaled by the amount_match_status
field = overpaid / partial. When working through the V1 protocol, the
callback translates these values back into codes 14/15.
PayIn transition diagram:
SPAM_REJECTED is assigned by the antifraud system outside the
transition map and has no incoming edges. CANCELLED is the terminal
cancellation status: reachable from INITIALIZED, ESCROW_LOCKED, and
PAYMENT_NOTIFIED (explicit cancellation, see
PayIn → Canceling a deal)
and from REFUND_PENDING (transit finalization); after the transition,
escrow holds are released automatically, fee_breakdown is zeroed, and
matches move to FAILED. REFUND_PENDING is a transit: the webhook
pair deal.refund_pending → deal.cancelled is always emitted, and the
deal does not return to the payment cycle.
Deal amount fields (deal-amount)
| Field | Type | Description |
|---|---|---|
amount | int64 | The declared fiat amount (minor units). Can be changed by an operator before PAYMENT_VERIFIED (see amend). |
amount_version | int64 | Monotonic counter of amount edits. A new deal starts at 1; each amend adds 1. Delivered in the deal.amount_changed webhook together with the old/new amount; used in the amend request as an optimistic lock (If-Match). |
amount_usdt | int64 | USDT equivalent at the deal's rate (exchange_rate_micro); on amend it is recomputed at the same rate. |
received_amount | int64 | The amount actually received (provider/reconciliation). Stored forever, including on EXPIRED deals — the source of the settlement amount. |
amount_match_status | string | full / partial / overpaid — the match result (received_amount vs amount). |
parent_deal_id | string(UUID) | Settlement deals only: the expired original (see settle-as-received). |
origin_appeal_id | string(UUID) | Settlement deals only: the appeal whose resolution created it (one appeal → one settlement). |
Outgoing payouts (PayOut Status)
The canonical PayOut lifecycle has 7 values. PayOut uses a separate status domain from PayIn.
| Canonical V2 status | Final? | State description | V1 compat (reference) |
|---|---|---|---|
INITIALIZED | No | The starting status: the payout is created, the balance is put on hold. Observed only in edge cases (the provider branch, races) — with synchronous auto-matching, the create response arrives already in MATCHED/UNASSIGNED. | 1 WaitingProcessing |
MATCHED | No | A trader/team is assigned. The typical status right after creation under synchronous auto-matching (a free trader exists). | 1 WaitingProcessing |
UNASSIGNED | No | No free trader at creation time (no cascade capacity). The system keeps matching automatically: on success → MATCHED; when the assignment SLA expires → EXPIRED. Manual assignment remains available to the operator. | 1 WaitingProcessing |
PROCESSING | No | The trader is transferring the funds to the recipient. | 40 InProgress / 50 PayingRightNow |
COMPLETED | Yes (success) | The funds are sent to the recipient, the escrow hold is debited. | 10 Paid |
FAILED | Yes (rejection) | The payout is rejected (invalid payment details, cancellation by the trader). The hold is returned to the merchant's balance. | 30 Failed |
EXPIRED | Yes (timeout) | The PayOut expired before the transfer completed (including by the assignment SLA from UNASSIGNED); the hold is returned to the merchant. | 30 Failed |
PayOut transition diagram:
PayOut does not use the PayIn statuses (PAYMENT_NOTIFIED,
PAYMENT_VERIFIED, APPEALED, ...). These are different lifecycles.
Appeals / Disputes (Appeal Status)
The canonical appeal lifecycle has 5 values.
| Canonical V2 status | Final? | State description | V1 compat (reference) |
|---|---|---|---|
OPEN | No | The appeal is created, waiting for an arbitrator to be assigned. | 1 |
IN_PROGRESS | No | The arbitrator is reviewing the dispute, the chat is running. | 2 IN_REVIEW |
REOPENED | No | The appeal is reopened for further investigation. | 6 |
SATISFIED | Yes | The dispute is resolved in the initiator's favor (the merchant's). | 3 RESOLVED_MERCHANT / 5 REFUNDED |
REJECTED | Yes | The dispute is rejected (insufficient evidence). | 4 RESOLVED_TRADER |
The V1 values IN_REVIEW, RESOLVED_MERCHANT, RESOLVED_TRADER,
REFUNDED, CLOSED do not exist in V2. The mapping exists only on
the V1 protocol side for migrating merchants.
Cryptocurrency withdrawals (Withdrawal Status)
The lifecycle of a USDT withdrawal to an external wallet has 3 values. A withdrawal is a separate entity from a PayOut.
| Canonical V2 status | Final? | State description | V1 compat (reference) |
|---|---|---|---|
PENDING | No | The request is created, the funds are reserved, waiting for the on-chain broadcast. | 1 |
APPROVED | Yes (success) | The on-chain tx is sent, the ledger is debited. V1 sees this as COMPLETED. | 3 COMPLETED |
CANCELLED | Yes (rejection) | Rejected by an admin or canceled before broadcast. Refunded to the balance. | 4 FAILED |
This is the domain status of the request
(p2p.finance.withdrawal_* webhooks). A withdrawal has two other status
surfaces: the synchronous POST /wallet/withdraw response returns
COMPLETED/PENDING_MANUAL, and the GET /wallet/withdrawals listing
additionally distinguishes PENDING (awaiting approval) from
COMPLETED (the broadcast went through) — all three are described in
Wallet → Withdrawal request statuses.
PROCESSING is reserved for a future block-confirmation step between
APPROVED and the final confirmation — the current API version never
returns it.
Whitelist pass status
The lifecycle of a pre-approved whitelist pass has 4 values. A pass is a two-phase mechanism: reservation at deal creation, confirmation at completion.
| Canonical V2 status | Final? | State description |
|---|---|---|
ACTIVE | No | The pass is available for matching. |
RESERVED | No | A deal has reserved the pass; another deal cannot take it. |
USED | Yes | The deal that owns the pass completed successfully. Terminal. |
EXPIRED | Yes | The pass TTL expired before use. Terminal. |
Pass transition diagram:
RESERVED → ACTIVE happens automatically when the owning deal expires
or is canceled — the pass returns to the pool.
Full registry of V1 numeric codes (compat surface)
This is the exhaustive registry of numeric statuses that the V1
protocol (/v1/payments/incoming|outgoing, /v1/merchant/withdraw,
/v1/disputs) returns in the status field — both in REST responses
and in webhook bodies. The code set follows the platform's V1 spec
(MerchantApiPaymentProfile.status / MerchantApiWithdrawProfile.status).
Integrators working over the V1 protocol should register all of the listed codes — this prevents operations from hanging on unfamiliar statuses.
Outgoing payouts (outgoing — /v1/payments/outgoing)
| Code | Name | Final? | When it is returned (internal V2 statuses) |
|---|---|---|---|
1 | WaitingProcessing | No | created / waiting for a handler (INITIALIZED, MATCHED, UNASSIGNED, PENDING) |
40 | InProgress | No | the trader took the job (PROCESSING, ESCROW_LOCKED, PAYMENT_NOTIFIED) |
50 | PayingRightNow | No | the transfer is executing (EXECUTING, TRADER_SENT, PAYMENT_VERIFIED); the outcome is code 10 or 30; sentAt/sentAmount are filled in the final status |
10 | Paid | Yes (success) | the payout is executed (COMPLETED, PAID) |
20 | PaidPartially | Yes | reserved for compatibility; not returned by the current API version — V2 does not support partial payouts |
30 | Failed | Yes (rejection) | rejection: cancellation, invalid payment details, timeout (EXPIRED), dispute (DISPUTED) — the V1 protocol has no separate codes for payout timeouts and disputes, everything is returned as 30; the hold is returned |
On outgoing payments: the codes 2, 13, 14, 16, 21 are
never returned by /v1/payments/outgoing — they are not part of
the payout code set. The actual set of outgoing codes: 1, 40, 50
(intermediate) → 10, 30 (final).
PayOut webhooks use the codes of this same registry: PROCESSING →
40 (InProgress), FAILED/EXPIRED → 30 (Failed), COMPLETED →
10 (Paid).
Incoming payments (incoming — /v1/payments/incoming)
| Code | Name | Final? | When it is returned (internal V2 statuses) |
|---|---|---|---|
1 | WaitingPayment | No | awaiting payment (PENDING, WAITING_PAYMENT, ESCROW_LOCKED) |
31 | WaitingPaymentChannel | No | the channel/method is not determined (AWAITING_METHOD, PROCESSING, EXECUTING) |
2 | ConfirmedByPayer | No | the payer confirmed the payment (CUSTOMER_CONFIRMED, TRADER_RECEIVED) |
32 | RollingBack | No | the refund is in progress (transit): the GET request /v1/payments/incoming/{id} returns 32 on the REFUND_PENDING status; the webhook at the same stage returns 16. The transit outcome is guaranteed — 12 Cancelled |
21 | Disput | No | dispute (DISPUTED, APPEALED, SOFT_DISPUTED) |
11 | Paid | Yes (success) | paid (COMPLETED, PAID, PAYMENT_VERIFIED) |
12 | Cancelled | Yes | canceled, including by the protection system (CANCELLED, SPAM_REJECTED) |
13 | Timeout | Yes | expired by the payment window (EXPIRED) |
14 | OverPaid | Yes | overpaid (OVERPAID) |
15 | PartiallyPaid | Yes | underpaid (UNDERPAID) |
16 | Returned | No | transit: the refund is initiated (REFUND_PENDING); the 16 webhook is reliably followed by 12 Cancelled — the deal ends in a cancellation and does not return to the payment cycle. The webhook surface returns 16 at the REFUND_PENDING stage, the GET surface returns 32 at the same stage |
1000 | Unknown | — | fallback code (UNKNOWN) |
Crypto withdrawals (withdraw — /v1/merchant/withdraw)
| Code | Name | Final? |
|---|---|---|
1 | Created | No |
2 | InProgress | No |
3 | Completed | Yes (success) |
4 | Failed | Yes (rejection) |
Handling rule: treat any unregistered code as intermediate and keep polling — only the codes listed above are final.