Steps and terms
What a step is
A step is an action that needs a signature the service does not hold. The service checks the action, builds the batch or transaction, adds what it signs itself, and returns the step for one listed key to sign. These are its fields:
| Field | What it holds |
|---|---|
id | The step's id, for steps.get and the submit |
kind | advance, release, repay, withdraw, liquidate, takeover-queue, takeover-cancel, takeover-cancel-po or market |
status | awaiting_signature, submitted, confirmed, failed or expired |
signer | The one key that must sign it |
preimage | The authorisation preimage to sign, on a preimage step |
transaction | The whole transaction to sign as its source, on a release, repay, market or liquidation step |
operation | The operation the step submits, which the SDK checks the preimage against |
expires_ledger | The ledger at which the step's approvals end |
summary | What the step does, in fields: for display |
tx | The transaction hash, once submitted |
steps.sign
line.steps.sign(step, signer, terms) does four things:
- It checks that the step names the signer's address.
- It checks the step against your terms and the line's addresses.
- It signs the preimage or the whole transaction, and verifies the signature locally.
- It submits, and returns the service's result with the transaction hash in
step.tx.
By default the line's addresses come from the testnet registry shipped with the
SDK, a source apart from the service that makes the steps. Pass
lines: linesFromRegistry(registry) to createClient to use your own registry,
or lines: 'service' for a line deployed after the SDK release you run.
The terms check
The terms are your own figures for the step: the face, reference and receiver of an advance, the receiver and amount of a release, the cap on a repayment, the take-over's number. Before any key signs, the SDK checks:
| Check | Refusal |
|---|---|
| The step names the signer's address | SIGNER_MISMATCH |
| The preimage is the batch it claims: the amounts, the asset and the line's own contracts | PREIMAGE_MISMATCH |
The step matches your terms, the advance's split matches the line's advance_bps, and a repayment burns exactly the POT it withdraws | TERMS_MISMATCH |
The approval ends by the step's expiry, and within 120 ledgers of the current ledger when you pass currentLedger | PREIMAGE_MISMATCH |
| A transaction step has the signer as its source, one operation and a fee of at most 10 XLM | TERMS_MISMATCH |
| A liquidation step is the liquidator's own five calls, for the repayment and at least the asset accepted, with its stablecoin transfer under source-account credentials and no other entry but the settlement account's | TERMS_MISMATCH |
| The approval is still live, when the current ledger is known | APPROVAL_EXPIRED |
| The signature verifies against the signer's address | SIGNER_MISMATCH |
The line's network is ready, in steps.sign and again in every signer | MAINNET_NOT_READY |
termsFromSummary(step) reads terms back from the step's own summary. Use it
for display only: a caller that signs with those terms takes the service's word
for them.
Expiry
A prepared step's approvals end 12 ledgers after the prepare, about a minute. A
later submit answers 410 STEP_EXPIRED: make the step again and sign the new
one. Pass { currentLedger } as the last argument of steps.sign and the SDK
also refuses an approval that lasts more than 120 ledgers past it, so the
service cannot hold a signature for later use.
A release stays valid for longer, and lapses on its own: renew it with
payins.renewRelease (Release).
Errors and the envelope
Every failure from the service has the same envelope: a machine-readable code,
a sentence in message, the failed checks in reasons, and the request_id,
also sent as the X-Request-Id header. A refusal from the beta on 18 October
2026, a withdrawal of more XLM than the settlement account held:
{
"error": {
"code": "LIMIT_EXCEEDED",
"message": "taking 100000 XLM leaves less than 20% of the debt covered, or more than the account holds",
"reasons": [
"taking 100000 XLM leaves less than 20% of the debt covered, or more than the account holds"
]
},
"request_id": "req_59e6e39573464118b67c64d2"
}
The SDK turns it into a PayfiError with code, reasons, status and
requestId. Errors lists every code.
Idempotency
Each call that changes state sends an Idempotency-Key and keeps it across the
client's retries, so a retried call does its work once. The service keeps the
key, the route, a hash of the body and the response for 24 hours:
- the same key with the same body returns the stored answer, with the header
Idempotent-Replayed: true; - the same key with another body is refused with 409
IDEMPOTENCY_KEY_REUSED; - a call still running under the key answers 409
IDEMPOTENCY_IN_PROGRESS.
To retry a call made by an earlier process, pass its key as the last argument:
line.payins.renewRelease(ref, { idempotencyKey }). The calls that make a step
take no key: they record nothing, so a repeat does no harm.