Skip to main content
GET
Get a payin

Authorizations

Authorization
string
header
required

Session JWT (from register/login) or API key (pk_...). X-API-Key: <token> is accepted as an alternative header.

Path Parameters

payinID
string<uuid>
required

Response

The payin.

payin_id
string<uuid>
instrument_id
string<uuid>

Dedicated deposit instrument that received the payin; omitted for generic collections and historical payins.

instrument
object

Dedicated instrument metadata, returned when the instrument row is available.

account_id
string
kind
enum<string>
Available options:
qr,
collect,
push,
card,
checkout,
pos
country
string
currency
string
method
string
local_amount
string

Amount in the local currency, as a plain decimal string (for example "5000000"). Never scientific notation.

settlement_asset
enum<string>

The virtual balance the payin settles into. Checkout and POS payins denominate the charge in this per-link asset (no currency/local_amount until a local payment method is used; the charge amount is asset_amount in this asset). Other credited payins carry it when the settlement asset differs from the credited asset (accounts with a default_payin_asset other than the credited asset; direct USD credits and fiat-local holds do not convert).

Available options:
USD,
USDT,
USDC,
BTC,
GOLD,
SILVER,
PLATINUM
asset_amount
string

Checkout and POS payins only — the charge amount denominated in settlement_asset (present in every status, including pending and expired).

conversion_status
enum<string>

Auto-conversion state — for checkout/POS payins when the payment arrived in a different asset than settlement_asset, and for other payins when the account configured a default_payin_asset other than the credited asset. pending_retry is retried automatically. Omitted when no conversion applies.

Available options:
pending_retry,
done
status
enum<string>
Available options:
pending,
credited,
unassigned,
expired,
failed
reference
string
idempotency_key
string

Your idempotency key from the create request, echoed back. Absent when the payin was created without one (or by the platform itself — internal keys are never exposed).

created_at
string<date-time>
updated_at
string<date-time>
settle_at
string<date-time>

Card-paid collections with a configured settlement delay only — direct card payins and checkout/POS charges paid by card — when this payin's balance becomes available (created_at plus the payin_card fee config's settlement_hours). The payin itself is confirmed right away: the status is credited and the payin_credited webhook fires at payment time; what waits until settle_at is the BALANCE credit (and the auto-conversion, when configured). A payin whose delay has already elapsed when it is approved or assigned settles immediately. Absent when the balance settles on confirmation.

settlement_pending
boolean

Present (true) while a credited card-paid payin's balance is still scheduled for settle_at — covers direct card payins and checkout/POS charges paid by card. While set, the payin cannot be refunded (422 settlement_pending) — the funds are not in your balance yet. Absent once the balance lands.

settled_at
string<date-time>

When the balance of this credited payin actually landed in your ledger — right at confirmation for payins without a settlement delay, or when the scheduled settlement ran (or was released early by your org admin) for delayed card payins.

fx_rate
string

Your payin rate at credit time (present once the payment was received and converted).

rate_source
enum<string>

Payin quote provenance when a USDT payin quote was loaded; omitted for historical rows without a quote.

Available options:
lot,
spot
usdt_gross
string
fee
string
usdt_credited
string

Amount credited to the balance. Also present WITHOUT fx_rate on checkout/POS charges settled in crypto or via a CBPay transfer (no FX quote applies).

credit_asset
enum<string>

Asset actually credited (USDT or retained local fiat).

Available options:
USD,
USDT,
BOB,
MXN,
ARS
fiat_credited
string

Local fiat amount; present only when credit_asset is fiat.

refund_status
enum<string>

Present only once the payin has refunds or a chargeback. Derived from the accumulated amounts — the payin status is never rewritten.

Available options:
partial,
full
refunded_amount
string

Accumulated USDT debited by refunds and chargebacks on this payin.

refunded_local
string

Accumulated amount refunded in the original local currency.

failure
object

Present only when the payin is failed on active collections: where the rejection originated (provider = the payer's bank, core = pre-charge validation) plus the concrete code and message.

payer_source
enum<string>

Announced transfers and deposits — where the payer identity came from. declared you sent it, account_identity the account holder's verified tax id was used as the default, none no identity was available (only the reference can match), bank_event is reported by the bank, including for a paid QR charge bound through charge_link; if the rail does not report a value, the corresponding field is omitted.

Available options:
declared,
account_identity,
none,
bank_event
payer
object

Payer identity attached to the payin, when known.

deposit_instructions
object

Frozen snapshot of the destination bank account announced to the payer (announced bank_transfer payins on corridors with configured instructions — today CL, PY and US). The text never changes after creation; the QR image is regenerated on read with your current branding. On the US/USD corridor this block is the domestic rail (ABA routing number).

deposit_instructions_swift
object

Frozen snapshot of the international SWIFT rail (BIC + correspondent bank), present only on the US/USD corridor when your organization has the swift variant configured. The payer picks either rail; both share the same reference.

match_method
enum<string>

How the arriving transfer was matched to this payin (audit trail). charge_link means the deposit settled the charge created for this payin (QR, checkout link or card) and was linked one-to-one by that charge - the strongest signal, no heuristics involved. manual_assign means an org admin routed the deposit by hand.

Available options:
charge_link,
reference,
payer_document,
payer_account,
payer_name,
amount_single_candidate,
dedicated_clabe,
collect_settlement,
manual_assign
match_reason
string

Why the deposit could NOT be matched automatically, on unassigned payins — no_match, ambiguous_amount (two or more announcements share the amount), ambiguous_payer, claim_lost (another event claimed the announcement first), checkout_link_expired (the checkout link had expired) or assigned_to:<payin_id>.

candidate_count
integer

Number of pending announcements that matched the amount and currency of an unassigned deposit (2 or more means the deposit was ambiguous).