Skip to content

Card payment editor figures for one card

GET
/bills/card-payment-preview
curl --request GET \
--url 'https://api.tovarifinancial.com/bills/card-payment-preview?cardAccountId=2489E9AD-2EE2-8E00-8EC9-32D5F69181C0' \
--header 'Authorization: Bearer <token>'

READ-ONLY (KAN-4134): writes nothing and takes no idempotency key. The card payment editor’s server-computed figures: the current statement, payments since it closed (non-pending inbound transfer legs and unlinked LOAN_PAYMENTS_CREDIT_CARD_PAYMENT rows on the card dated after the closing date and on or before today; refunds and other credits excluded), each amount mode resolved, the usual and due pay dates, the default choice, the target occurrence when editing and any other card payment bill on the card. Requires debt_planning (403). Another household’s id and a nonexistent one both answer 404. KAN-4183: WITHOUT sourceAccountId the answer is the candidates-only shape (status: 'candidates_only', no figures) carrying linkCandidates — the household’s existing recurring expense bills, paid from an active checking or savings account, that already pay this card (destination is the card, or no destination and matched to a Plaid recurring stream whose every live linked row is a transfer into this one card), newest payment first, at most 10, and [] whenever a card payment bill already pays the card. billId, streamId and fixedCents are accepted only beside sourceAccountId (400 on sourceAccountId otherwise). WITH sourceAccountId the answer carries no linkCandidates, and targetOccurrenceDate is null unless billId names a card payment bill.

cardAccountId
required
string format: uuid

The credit card (required)

sourceAccountId
string format: uuid

The checking or savings account it is paid from. OPTIONAL (KAN-4183): omit it for the candidates-only answer.

billId
string format: uuid

The card payment bill being edited (only with sourceAccountId)

streamId
string format: uuid

The card-payment recurring suggestion seeding a new bill (only with sourceAccountId)

fixedCents
integer

The Fixed amount being typed, positive integer cents (only with sourceAccountId)

The preview: the candidates-only answer without sourceAccountId, else the figures

Media typeapplication/json
object
data
required
One of:
object
cardAccountId
required
string format: uuid
sourceAccountId
required

Always null on this shape.

string
nullable
status
required
string
Allowed values: candidates_only
existingCardPaymentBillId
required
string format: uuid
nullable
linkCandidates
required
Array<object>
object
id
required
string format: uuid
name
required

The bill name as stored.

string
sourceAccountId
required
string format: uuid
sourceAccountName
required
string
frequency
required

The bill’s stored frequency; never ‘once’.

string
usualDay
required

Day_of_month when the bill is monthly, else null.

integer
nullable
lastPaidAmountCents
required

The newest payment, positive integer cents; null when never paid.

integer format: int64
nullable
lastPaidDate
required

The newest payment’s register date; null when never paid.

string
nullable
fromBankActivity
required

A Plaid recurring stream in the household is matched to this bill.

boolean
autoEnterMode
required
string
Allowed values: automatic ask_first
message
string
requestId
required
string
timestamp
required
string format: date-time
Example
{
"data": {
"status": "candidates_only",
"linkCandidates": [
{
"autoEnterMode": "automatic"
}
]
}
}

Validation failed — see errorCode / fieldErrors

Media typeapplication/json
object
errorCode
required

Machine-readable error code (AUTH_ERROR_CODES).

string
Allowed values: INVALID_EMAIL_FORMAT USER_ALREADY_EXISTS INVALID_INVITE_CODE WRONG_PASSWORD USER_NOT_FOUND AUTHENTICATION_FAILED EXPIRED_CODE INVALID_CODE INVALID_PASSWORD VALIDATION_ERROR SIGNUP_FAILED DATABASE_ERROR SERVICE_UNAVAILABLE PLAID_ERROR IDEMPOTENCY_CONFLICT ACCOUNT_ALREADY_LINKED NOT_FOUND
message
required
string
fieldErrors

Optional field-level validation errors, keyed by field name.

object
key
additional properties
Array<string>
requestId
required
string
timestamp
required
string format: date-time
Example
{
"errorCode": "INVALID_EMAIL_FORMAT"
}

Missing, invalid, or expired bearer token

Media typeapplication/json
object
errorCode
required

Machine-readable error code (AUTH_ERROR_CODES).

string
Allowed values: INVALID_EMAIL_FORMAT USER_ALREADY_EXISTS INVALID_INVITE_CODE WRONG_PASSWORD USER_NOT_FOUND AUTHENTICATION_FAILED EXPIRED_CODE INVALID_CODE INVALID_PASSWORD VALIDATION_ERROR SIGNUP_FAILED DATABASE_ERROR SERVICE_UNAVAILABLE PLAID_ERROR IDEMPOTENCY_CONFLICT ACCOUNT_ALREADY_LINKED NOT_FOUND
message
required
string
fieldErrors

Optional field-level validation errors, keyed by field name.

object
key
additional properties
Array<string>
requestId
required
string
timestamp
required
string format: date-time
Example
{
"errorCode": "INVALID_EMAIL_FORMAT"
}

Authenticated, but the tenant gate refuses the request until the caller resolves a precondition. errorCode is one of EMAIL_NOT_VERIFIED, POLICY_ACCEPTANCE_REQUIRED, or SUBSCRIPTION_REQUIRED, evaluated in exactly that order (contract term CCR-1: email verification first, then policy acceptance, then subscription — so a subscriber who has merely not re-accepted the current policies always sees POLICY_ACCEPTANCE_REQUIRED). A POLICY_ACCEPTANCE_REQUIRED body additionally carries details.outstanding (the policy versions still to accept) and details.firstAcceptance. The SUBSCRIPTION_REQUIRED arm is INERT unless the server-side BILLING_ENABLED flag is exactly the string true; while it is off, only the first two codes are reachable. Not retryable as sent — resolve the named condition, then resend. This operation can ALSO answer 403 with errorCode CAPABILITY_REQUIRED and no details, a refusal by the HANDLER rather than by the tenant gate: the request needs the debt_planning capability (the Premier plan or Founder access) — turning statement details on (enabled: true; turning it off needs no capability), or (KAN-4134) saving a non-null card payment field on a bill (clearing the mode needs none) or reading the card payment preview. It fails closed: a capability read that errors is refused the same way. Nothing is written, nothing is queued and no idempotency record is kept. It does NOT depend on CAPABILITY_FENCE_ENABLED or BILLING_ENABLED. The errorCode enum on this operation’s response schema is the complete, machine-readable list.

Media typeapplication/json
object
errorCode
required

Which condition refused the request, evaluated in this order (CCR-1). SUBSCRIPTION_REQUIRED is unreachable while BILLING_ENABLED is not exactly true; CAPABILITY_REQUIRED is unreachable while CAPABILITY_FENCE_ENABLED is not exactly true. The two switches are independent, so CAPABILITY_REQUIRED is reachable with the subscription paywall off. CAPABILITY_REQUIRED carries no details.

string
Allowed values: EMAIL_NOT_VERIFIED POLICY_ACCEPTANCE_REQUIRED SUBSCRIPTION_REQUIRED CAPABILITY_REQUIRED
message
required
string
details
object
outstanding
required

Active policy versions the user has not yet accepted.

Array<object>
object
id
required
string format: uuid
policyType
required
string
version
required
integer
title
required
string
firstAcceptance
required

True when the user has accepted no policy before — the client renders the new-signup screen rather than the re-acceptance one.

boolean
requestId
required
string
timestamp
required
string format: date-time
Example
{
"errorCode": "EMAIL_NOT_VERIFIED"
}

Resource not found or not owned by the caller org

Media typeapplication/json
object
errorCode
required

Machine-readable error code (AUTH_ERROR_CODES).

string
Allowed values: INVALID_EMAIL_FORMAT USER_ALREADY_EXISTS INVALID_INVITE_CODE WRONG_PASSWORD USER_NOT_FOUND AUTHENTICATION_FAILED EXPIRED_CODE INVALID_CODE INVALID_PASSWORD VALIDATION_ERROR SIGNUP_FAILED DATABASE_ERROR SERVICE_UNAVAILABLE PLAID_ERROR IDEMPOTENCY_CONFLICT ACCOUNT_ALREADY_LINKED NOT_FOUND
message
required
string
fieldErrors

Optional field-level validation errors, keyed by field name.

object
key
additional properties
Array<string>
requestId
required
string
timestamp
required
string format: date-time
Example
{
"errorCode": "INVALID_EMAIL_FORMAT"
}

Internal error (no internal detail leaked)

Media typeapplication/json
object
errorCode
required

Machine-readable error code (AUTH_ERROR_CODES).

string
Allowed values: INVALID_EMAIL_FORMAT USER_ALREADY_EXISTS INVALID_INVITE_CODE WRONG_PASSWORD USER_NOT_FOUND AUTHENTICATION_FAILED EXPIRED_CODE INVALID_CODE INVALID_PASSWORD VALIDATION_ERROR SIGNUP_FAILED DATABASE_ERROR SERVICE_UNAVAILABLE PLAID_ERROR IDEMPOTENCY_CONFLICT ACCOUNT_ALREADY_LINKED NOT_FOUND
message
required
string
fieldErrors

Optional field-level validation errors, keyed by field name.

object
key
additional properties
Array<string>
requestId
required
string
timestamp
required
string format: date-time
Example
{
"errorCode": "INVALID_EMAIL_FORMAT"
}

Service temporarily unavailable — errorCode is SERVICE_UNAVAILABLE. A TRANSIENT, RETRYABLE condition rather than a defect in the request: a query that exceeded its time budget, a lost or refused database connection, a saturated connection pool, or an outage at an upstream provider the request depends on (the authentication provider, or the bank data provider on a bank-connection operation). The identical request may succeed on retry — back off briefly and, on a write, resend the same X-Idempotency-Key where the operation accepts one.

Media typeapplication/json
object
errorCode
required

Machine-readable error code (AUTH_ERROR_CODES).

string
Allowed values: INVALID_EMAIL_FORMAT USER_ALREADY_EXISTS INVALID_INVITE_CODE WRONG_PASSWORD USER_NOT_FOUND AUTHENTICATION_FAILED EXPIRED_CODE INVALID_CODE INVALID_PASSWORD VALIDATION_ERROR SIGNUP_FAILED DATABASE_ERROR SERVICE_UNAVAILABLE PLAID_ERROR IDEMPOTENCY_CONFLICT ACCOUNT_ALREADY_LINKED NOT_FOUND
message
required
string
fieldErrors

Optional field-level validation errors, keyed by field name.

object
key
additional properties
Array<string>
requestId
required
string
timestamp
required
string format: date-time
Example
{
"errorCode": "INVALID_EMAIL_FORMAT"
}