Intents - identiPay

Overview

The intents endpoint allows wallets to resolve a proposal by transaction ID. This is used when a buyer scans a QR code or clicks a payment link.

This endpoint is public and does not require authentication.

Endpoints

Get Proposal by Transaction ID

Resolve a proposal by its transaction ID.

GET /api/identipay/v1/intents/:txId

Per the whitepaper (section 6), this endpoint is available at:

https://<hostname>/api/identipay/v1/intents/<transaction-id>

Path Parameters

txId

string

required

Transaction ID (UUID) from the payment URI or QR code

Response

Returns the full CommerceProposal JSON-LD object (see Proposals for schema).

@context

string

JSON-LD context (https://schema.identipay.net/v1)

@type

string

Type (CommerceProposal)

transactionId

string

UUID for this transaction

merchant

object

Merchant information

Show Merchant Schema

did

string

Merchant DID

name

string

Merchant name

suiAddress

string

Merchant Sui address

publicKey

string

Merchant public key

items

array

Array of line items

amount

object

Total amount and currency

deliverables

object

Receipt and warranty information

constraints

object

Age gate or region restrictions

expiresAt

string

ISO 8601 expiry timestamp

intentHash

string

Hash for on-chain verification

settlementChain

string

Blockchain name (sui)

settlementModule

string

On-chain settlement module address

Example Request

curl https://api.identipay.com/api/identipay/v1/intents/550e8400-e29b-41d4-a716-446655440000

Example Response

{
  "@context": "https://schema.identipay.net/v1",
  "@type": "CommerceProposal",
  "transactionId": "550e8400-e29b-41d4-a716-446655440000",
  "merchant": {
    "did": "did:identipay:acme.com:...",
    "name": "Acme Store",
    "suiAddress": "0xabc123...",
    "publicKey": "a1b2c3d4..."
  },
  "items": [
    {
      "name": "Coffee",
      "quantity": 2,
      "unitPrice": "5.00"
    }
  ],
  "amount": {
    "value": "10.00",
    "currency": "USDC"
  },
  "deliverables": {
    "receipt": true,
    "warranty": {
      "durationDays": 30,
      "transferable": false
    }
  },
  "constraints": {
    "ageGate": 21
  },
  "expiresAt": "2026-03-09T21:15:00.000Z",
  "intentHash": "a1b2c3d4e5f6...",
  "settlementChain": "sui",
  "settlementModule": "0x123abc::settlement"
}

Error Responses

Show 404 Not Found

Proposal with the specified transaction ID does not exist.

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Proposal not found"
  }
}

Show 400 Expired

Proposal has expired.

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Proposal has expired"
  }
}

When a proposal expires, the backend automatically updates its status to expired.

Show 400 Cancelled

Proposal has been cancelled.

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Proposal has been cancelled"
  }
}

Implementation Details

Resolution Flow

When a wallet resolves an intent (see routes/intents.ts:12-42):

Lookup Proposal: Query database by transaction ID
Check Existence: Return 404 if not found
Check Expiry: If expired, update status and return error
Check Status: Return error if cancelled
Return Proposal: Return full proposal JSON

Automatic Expiry Detection

The endpoint checks expiry on every request:

if (new Date(proposal.expiresAt) < new Date()) {
  if (proposal.status === "pending") {
    await db
      .update(proposals)
      .set({ status: "expired" })
      .where(eq(proposals.transactionId, txId));
  }
  throw new ValidationError("Proposal has expired");
}

This ensures proposals cannot be settled after expiry, even if the background expiry task hasn’t run yet.

Payment URI Format

Wallets typically extract the transaction ID from a payment URI:

identipay://{merchant-hostname}/{transaction-id}

Example:

identipay://acme.com/550e8400-e29b-41d4-a716-446655440000

The wallet:

Extracts the hostname (acme.com)
Extracts the transaction ID (550e8400-...)
Constructs the intent URL: https://acme.com/api/identipay/v1/intents/550e8400-...
Fetches the proposal
Displays it to the user for approval

Privacy Considerations

The proposal includes the merchant’s Sui address and public key, but:

Does NOT include the buyer’s information (added during settlement)
Does NOT reveal which addresses are scanning the proposal
Can be fetched anonymously (no authentication required)

Settlement Workflow

After resolving the proposal, the wallet:

Display Proposal: Show merchant, items, amount, constraints
Check Constraints: Verify age gate (generate ZK proof if needed)
Build Settlement: Create settlement transaction via /transactions/gas-sponsor
Sign & Submit: Sign transaction and submit via /transactions/submit
Monitor Status: Watch for settlement confirmation via WebSocket

See Transactions for settlement details.

Proposals - Create proposals (merchant endpoint)
Transactions - Submit settlements
WebSocket - Monitor settlement status

Overview

Endpoints

WebSocket

​Overview

​Endpoints

​Get Proposal by Transaction ID

​Path Parameters

​Response

​Example Request

​Example Response

​Error Responses

​Implementation Details

​Resolution Flow

​Automatic Expiry Detection

​Payment URI Format

​Privacy Considerations

​Settlement Workflow

​Related Endpoints

Build docs developers (and LLMs) love

Overview

Endpoints

Get Proposal by Transaction ID

Path Parameters

Response

Example Request

Example Response

Error Responses

Implementation Details

Resolution Flow

Automatic Expiry Detection

Payment URI Format

Privacy Considerations

Settlement Workflow

Related Endpoints