Skip to main content

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:

FieldWhat it holds
idThe step's id, for steps.get and the submit
kindadvance, release, repay, withdraw, liquidate, takeover-queue, takeover-cancel, takeover-cancel-po or market
statusawaiting_signature, submitted, confirmed, failed or expired
signerThe one key that must sign it
preimageThe authorisation preimage to sign, on a preimage step
transactionThe whole transaction to sign as its source, on a release, repay, market or liquidation step
operationThe operation the step submits, which the SDK checks the preimage against
expires_ledgerThe ledger at which the step's approvals end
summaryWhat the step does, in fields: for display
txThe transaction hash, once submitted

steps.sign​

line.steps.sign(step, signer, terms) does four things:

  1. It checks that the step names the signer's address.
  2. It checks the step against your terms and the line's addresses.
  3. It signs the preimage or the whole transaction, and verifies the signature locally.
  4. 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:

CheckRefusal
The step names the signer's addressSIGNER_MISMATCH
The preimage is the batch it claims: the amounts, the asset and the line's own contractsPREIMAGE_MISMATCH
The step matches your terms, the advance's split matches the line's advance_bps, and a repayment burns exactly the POT it withdrawsTERMS_MISMATCH
The approval ends by the step's expiry, and within 120 ledgers of the current ledger when you pass currentLedgerPREIMAGE_MISMATCH
A transaction step has the signer as its source, one operation and a fee of at most 10 XLMTERMS_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'sTERMS_MISMATCH
The approval is still live, when the current ledger is knownAPPROVAL_EXPIRED
The signature verifies against the signer's addressSIGNER_MISMATCH
The line's network is ready, in steps.sign and again in every signerMAINNET_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:

409 response
{
"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.