Off-chain sale (bank transfer)

In an off-chain primary sale, the buyer commits to a quantity, pays the issuer's configured receiving account using a unique reference, and receives the asset after payment reconciliation and delivery.

Flow

Prerequisites

The buyer must be signed in, currently eligible for the action, have an allowed delivery wallet, and select an active registered payment account. The instrument must be active, open for primary sale, entitled to the partner tenant, and linked to an active receiving account in the sale currency.

The API enforces these prerequisites. Frontend checks improve the journey but do not authorize the purchase.

Create a purchase

Your BFF forwards the body and the signed-in user's server-held access token to POST /offchain-purchases.

{
  "pairId": 42,
  "quantity": "10",
  "walletAddress": "0x1111111111111111111111111111111111111111",
  "bankAccountId": "11111111-1111-4111-8111-111111111111"
}

{
  "reference": "AB12EXAMPLE",
  "status": "awaiting_payment",
  "phase": "pending",
  "pairId": 42,
  "quantity": "10",
  "unitPrice": "100.00",
  "amount": "1000.00",
  "currency": "EUR",
  "bankAccount": {
    "beneficiary": "Example Issuer",
    "iban": "DE00000000000000000000",
    "bic": "EXAMPLEBIC",
    "bankName": "Example Bank"
  },
  "payerAccount": {
    "id": "11111111-1111-4111-8111-111111111111",
    "ibanLast4": "1234",
    "holderName": "Example Customer"
  },
  "qr": "<EPC QR payload>"
}

Quantities and money are decimal strings. Preserve them as strings or use a decimal library. The exact response schema and nullable fields are defined in the Marketplace OpenAPI contract.

The create operation is idempotent for the same active purchase intent. The selected payment account is part of that intent, so changing it creates a different purchase and reference.

Show the payment instruction

Display the returned beneficiary, IBAN, amount, currency, reference, and QR. Do not hardcode, rewrite, or cache receiving-account details in the frontend.

Track status

Use GET /offchain-purchases/:reference for one caller-owned purchase or GET /offchain-purchases for the caller's list. The detailed lifecycle is:

For customer-facing UI, use the coarse phase returned by the API (pending, review, success, failed, cancelled, or expired). Keep the detailed status in support diagnostics and do not infer additional transitions.

Reconciliation boundaries

Issuer users can perform only the transitions allowed for their role and issuer assignment. A payment-account mismatch cannot be overridden in the issuer portal. It follows the Compliance escalation route, where any permitted override is officer-only and audited.

On-chain delivery can be performed or observed by Assetera's operational flow. The buyer integration tracks the purchase response rather than trying to advance operational states itself.

Security requirements

• Keep the Assetera bearer token in the BFF.
• Read the buyer subject from the validated user session.
• Use only the returned receiving account and reference.
• Treat 400, 403, and permanent 409 responses as business failures, not blind retry candidates.
• Redact IBANs, customer names, access tokens, and QR payloads from application logs.
• Re-fetch the purchase after reconnecting or resuming a session.