RFC-002: Nexus UCP Payment Standard (NUPS)

Metadata	Value
Title	Nexus UCP Payment Standard (NUPS)
Version	2.0.0
Status	Final Draft
Author	Cipher & Nexus Architect Team
Created	2026-01-20
Updated	2026-04-01
Integrations	Google UCP, AP2 Agent Protocol, EVM Chains, ISO 20022 Financial Rails

1. Architecture Overview

This protocol adopts a "Quote-to-Transaction" model. The data flow is divided into two strict phases, ensuring lightweight merchant integration and rigorous settlement logic.

Quote Phase (Merchant Side): The merchant generates a "quote" containing the business order number and ISO metadata. The merchant does not generate a Nexus ID, nor does it generate on-chain Calldata.
Orchestration Phase (Core Side): Nexus Core receives the quote, assigns a nexus_payment_id, resolves DID routing, and generates settlement instructions.
Settlement Phase (On-chain): The Escrow contract locks funds, releases them after merchant fulfillment, and emits Events with ISO 20022-compatible semantics.

New in v2.0.0:

AP2 Protocol Support: Operates as a Credential Provider, receiving CartMandate / IntentMandate VCs and issuing PaymentMandate VCs
Multi-Token: Supports ERC-3009-compatible tokens such as XSGD and USDC
Gasless Settlement: Users only sign; the Relayer pays all gas fees

2. Phase I: Merchant Quote Payload

This is the standard JSON returned by the Merchant Agent via UCP.

Generation Tool: @nexus/ucp-adapter SDK.
Design Goal: Minimal integration effort while carrying ISO metadata required by financial institutions.

2.1 JSON Schema

json

{
"payment_methods": [
{
"type": "urn:ucp:payment:nexus_v1",
"display_name": "Nexus (USDC)",
"payload": {
// --- A. Business Intent ---
"merchant_did": "did:nexus:20250407:trip_com",
"merchant_order_ref": "TRIP-2026-888", // [KEY] Unique order number in merchant ERP
"amount": "530000000", // Integer (6-decimal precision)
"currency": "USDC", // Nexus internal asset identifier
"chain_id": 20250407,
"expiry": 1768809600,
// --- B. Context (User View) ---
// Used by User Agent to display itemized details to the user
"context": {
"summary": "Flight SQ638 (SIN-NRT)",
"ucp_offer_id": "OFFER-XYZ-999",
"line_items": [
{ "name": "Flight Ticket", "qty": 1, "amount": "500000000" },
{ "name": "Tax", "qty": 1, "amount": "30000000" }
]
},
// --- C. ISO Financial Metadata (Bank View) --- [OPTIONAL]
// Semantic mapping for bank systems/ERP automatic reconciliation
// This field is optional in MVP phase; mandatory in future Enterprise edition
"iso_metadata": {  // OPTIONAL in MVP
// Value Anchor Layer: Maps to ISO 4217 (e.g. USD)
// Purpose: Enables SAP/Oracle ERP to recognize this as a "USD" transaction
"account_currency": "USD",
// Settlement Asset Layer: Maps to ISO 24165 (DTI)
// Purpose: Specifies the exact digital asset ID
"asset_identifier": {
"scheme": "ISO24165",
"dti_code": "4H95J0R2X", // USDC DTI Code
"contract": "0xA0b8..."
},
// Creditor Information (ISO 20022)
"creditor": {
"name": "Trip.com International",
"bic": "TRIPCNBJ" // SWIFT BIC code if available
}
},
// --- D. Security Credentials ---
// Signature covers all fields above (including context hash and iso hash)
"signature": "0xMerchantSig..."
}
}
]
}

3. Phase II: Settlement Manifest

When the User Agent executes an aggregated payment (nexus/orchestrateBatch), Nexus Core returns this object. This is the content that the User Agent ultimately signs.

3.1 JSON Schema

json

{
"type": "urn:ucp:payment:nexus_batch_v1",
"batch_id": "BATCH-ROOT-20260120-001",
"total_amount": "630000000",
// --- A. ID Mapping & Aggregation Manifest (The Manifest) ---
// Used for UI rendering and user verification
"manifest": [
{
"index": 0,
"merchant_name": "Trip.com",
// [ID Bridge] Nexus Payment ID <---> Merchant Order Ref
"nexus_payment_id": "NEX-UUID-001", // [NEW] End-to-end ID generated by Core
"merchant_order_ref": "TRIP-2026-888", // [OLD] From merchant Quote
"amount": "530000000",
"summary": "Flight SQ638",
"iso_currency": "USD" // UI display: $530.00 USD (USDC Settlement)
},
{
"index": 1,
"merchant_name": "Nexus OTC",
"nexus_payment_id": "NEX-UUID-002",
"merchant_order_ref": "OTC-BTC-05",
"amount": "100000000",
"summary": "0.03 ETH"
}
],
// --- B. On-chain Transaction Data ---
"tx_data": {
"to": "0xNexusRouter...",
"chain_id": 20250407,
"data": "0x...", // Encoded batchPay
"value": "0"
}
}

4. ISO 20022 Data Mapping

To ensure compatibility with financial institution systems, we map JSON fields to ISO 20022 XML tags (pacs.008 / pain.001).

Nexus JSON Field	ISO 20022 XML Tag	Business Meaning
`nexus_payment_id`	`<EndToEndId>`	End-to-End Identifier. A unique transaction reference that persists across the entire payment chain.
`merchant_order_ref`	`<RmtInf>/<Ustrd>`	Remittance Information. The order number used by the merchant ERP for automatic write-off.
`amount` (converted)	`<InstdAmt>`	Instructed Amount. Uses `iso_metadata.account_currency`.
`iso_metadata.dti`	`<SplmtryData>/<Envlp>`	Additional Information. e.g. "Settled via DTI:4H95J0R2X".
`merchant_did`	`<Cdtr>/<Id>/<OrgId>/<Othr>`	Creditor Identifier.

5. Reconciliation & Events

After successful execution, the smart contract must emit Events with ISO-compatible semantics.

5.1 Solidity Event Definition

solidity

event PaymentProcessed(
// Indexed fields (for fast filtering)
string indexed merchant_did,
string indexed nexus_payment_id, // Corresponds to ISO
// Data fields (for business processing)
string merchant_order_ref, // Corresponds to ISO
uint256 amount,
address token_address, // Corresponds to DTI/Contract
string iso_currency_code // e.g. "USD"
);

5.2 Merchant/Bank Reconciliation Logic

Listen: Listen for PaymentProcessed events.
Convert: (Optional) Convert Event data to ISO 20022 XML format for ERP import.
Match: * Match merchant_did.

Use merchant_order_ref to look up accounts receivable in the ERP.
Verify amount.

Write Off: Mark the order as PAID.

6. Security Specification

6.1 EIP-712 TypedData

The merchant SDK must sign the Quote.

javascript

const types = {
NexusQuote: [
{ name: 'merchant_did', type: 'string' },
{ name: 'merchant_order_ref', type: 'string' },
{ name: 'amount', type: 'uint256' },
{ name: 'currency', type: 'string' },
{ name: 'expiry', type: 'uint256' },
{ name: 'context_hash', type: 'bytes32' }, // Hash(context)
// iso_hash is OPTIONAL — omit when iso_metadata is not provided (MVP)
// { name: 'iso_hash', type: 'bytes32' } // Hash(iso_metadata) [Enterprise only]
]
};

6.2 DID Resolution

Nexus Core must never trust the recipient address passed from the frontend. It must use merchant_did to call the on-chain Registry contract (or a trusted cache) to obtain the authentic payment_address.

7. AP2 Protocol Extension (new in v2.0.0)

7.1 Overview

Nexus supports both the native NUPS protocol and Google AP2 (Agent Protocol 2). When an AP2 request is detected, Core operates as a Credential Provider, processing payment credentials in the W3C Verifiable Credential format.

7.2 Protocol Detection

typescript

function detectProtocol(body): "ap2" | "nups" {
  if (body.protocol === "ap2") return "ap2";
  if (body.cart_mandates) return "ap2";
  return "nups";  // default: native NUPS
}

7.3 AP2 Verifiable Credential Types

CartMandate VC (Merchant Agent -> Nexus)

A shopping cart authorization credential issued by the Merchant Agent, containing the item list and amounts:

json

{
  "@context": ["https://www.w3.org/ns/credentials/v2"],
  "type": ["VerifiableCredential", "CartMandate"],
  "issuer": "did:nexus:20250407:demo_flight",
  "credentialSubject": {
    "merchant_did": "did:nexus:20250407:demo_flight",
    "cart_id": "CART-001",
    "total": "530000000",
    "currency": "XSGD",
    "line_items": [
      { "name": "Flight SQ638", "qty": 1, "amount": "500000000" },
      { "name": "Tax", "qty": 1, "amount": "30000000" }
    ],
    "expires_at": "2026-04-01T12:00:00Z",
    "payment_request": {
      "method_data": [
        {
          "supported_methods": "urn:ucp:payment:nexus_v1",
          "data": {
            "credential_provider_did": "did:nexus:20250407:nexuspay-core",
            "display_name": "Nexus (XSGD)"
          }
        }
      ]
    }
  },
  "proof": { "type": "DataIntegrityProof", "cryptosuite": "ecdsa-jcs-2022", "..." : "..." }
}

payment_request.method_data: Follows the AP2 CartMandate supported_methods pattern. The merchant declares Nexus as an accepted payment method using the same urn:ucp:payment:nexus_v1 identifier used in UCP Checkout Sessions (Section 2.1). The data.credential_provider_did identifies Nexus Core as the Credential Provider that processes this CartMandate.

IntentMandate VC (User Agent -> Nexus)

A payment intent credential issued by the User Agent, containing the budget and merchant whitelist:

json

{
  "@context": ["https://www.w3.org/ns/credentials/v2"],
  "type": ["VerifiableCredential", "IntentMandate"],
  "issuer": "did:key:z6Mk...",
  "credentialSubject": {
    "agent_did": "did:key:z6Mk...",
    "budget": "600000000",
    "currency": "XSGD",
    "merchant_whitelist": ["did:nexus:20250407:demo_flight"],
    "ttl": 3600
  }
}

PaymentMandate VC (Nexus -> All Agents)

A payment proof credential issued by Nexus acting as a Credential Provider, automatically generated after funds enter the Escrow:

json

{
  "@context": ["https://www.w3.org/ns/credentials/v2"],
  "type": ["VerifiableCredential", "PaymentMandate"],
  "issuer": "did:nexus:20250407:nexuspay-core",
  "credentialSubject": {
    "credential_provider_did": "did:nexus:20250407:nexuspay-core",
    "nexus_payment_id": "PAY-01JAXYZ-0001",
    "group_id": "GRP-001",
    "payer": "0x1234...abcd",
    "total_amount": "530000000",
    "currency": "XSGD",
    "chain_id": 20250407,
    "escrow_contract": "0xeB33a9C2b4c7D3F44Fd5514F90C355AF6bb79236",
    "deposit_tx_hash": "0xabc123...def456"
  },
  "proof": {
    "type": "DataIntegrityProof",
    "cryptosuite": "ecdsa-jcs-2022",
    "verificationMethod": "did:nexus:20250407:nexuspay-core#key-1",
    "proofPurpose": "assertionMethod",
    "created": "2026-04-01T10:35:00Z",
    "proofValue": "..."
  }
}

7.4 Relationship Between NUPS and AP2

Dimension	NUPS (Native)	AP2
Quote Format	NUPS JSON + EIP-712 Signature	CartMandate VC + Data Integrity Proof
Payment Credential	HTTP 402 + BatchDepositInstruction	PaymentMandate VC
On-chain Settlement	Identical (Escrow Contract)	Identical
Use Case	MCP Tool Invocation	Google Agent Ecosystem

Both protocols share the same Escrow contract and settlement flow; they differ only in quote verification and credential format.

8. Multi-Token Support (new in v2.0.0)

8.1 Supported Tokens

Token	Contract Address	EIP-712 name	EIP-712 version	Status
XSGD	`0x0Fd437613dE3d14F4dDaB8331DC0f2C0C543BdD0`	"XSGD"	"2"	Active
USDC	`0xFF8dEe9983768D0399673014cf77826896F97e4d`	"USD Coin"	"1"	Legacy

8.2 Token Switching

The Escrow contract manages the active token via the setToken() admin function. After a token switch:

New deposits use the new token
Existing escrows are unaffected (they settle with their original token)

8.3 The currency Field in Quotes

The currency field in a merchant Quote identifies the token symbol (e.g. "XSGD", "USDC"). Core resolves the corresponding contract address and EIP-712 domain parameters based on the currency value.

RFC-002: Nexus UCP Payment Standard (NUPS) ​

1. Architecture Overview ​

2. Phase I: Merchant Quote Payload ​

2.1 JSON Schema ​

3. Phase II: Settlement Manifest ​

3.1 JSON Schema ​

4. ISO 20022 Data Mapping ​

5. Reconciliation & Events ​

5.1 Solidity Event Definition ​

5.2 Merchant/Bank Reconciliation Logic ​

6. Security Specification ​

6.1 EIP-712 TypedData ​

6.2 DID Resolution ​

7. AP2 Protocol Extension (new in v2.0.0) ​

7.1 Overview ​

7.2 Protocol Detection ​

7.3 AP2 Verifiable Credential Types ​

CartMandate VC (Merchant Agent -> Nexus) ​

IntentMandate VC (User Agent -> Nexus) ​

PaymentMandate VC (Nexus -> All Agents) ​

7.4 Relationship Between NUPS and AP2 ​

8. Multi-Token Support (new in v2.0.0) ​

8.1 Supported Tokens ​

8.2 Token Switching ​

8.3 The currency Field in Quotes ​

RFC-002: Nexus UCP Payment Standard (NUPS)

1. Architecture Overview

2. Phase I: Merchant Quote Payload

2.1 JSON Schema

3. Phase II: Settlement Manifest

3.1 JSON Schema

4. ISO 20022 Data Mapping

5. Reconciliation & Events

5.1 Solidity Event Definition

5.2 Merchant/Bank Reconciliation Logic

6. Security Specification

6.1 EIP-712 TypedData

6.2 DID Resolution

7. AP2 Protocol Extension (new in v2.0.0)

7.1 Overview

7.2 Protocol Detection

7.3 AP2 Verifiable Credential Types

CartMandate VC (Merchant Agent -> Nexus)

IntentMandate VC (User Agent -> Nexus)

PaymentMandate VC (Nexus -> All Agents)

7.4 Relationship Between NUPS and AP2

8. Multi-Token Support (new in v2.0.0)

8.1 Supported Tokens

8.2 Token Switching

8.3 The currency Field in Quotes