---
name: nexus-rest-integration
version: "1.0.0"
description: Integrate your merchant agent with NexusPay via HTTP REST API
protocol: NUPS/1.5
category: finance.payment.integration
interface: rest
currencies: [XSGD]
chain_id: 20250407
---

# NexusPay Merchant Integration — REST API

Connect your merchant service to NexusPay using **standard HTTP REST endpoints**. Best for traditional web services, backends, and agents that don't support MCP.

## When to Use REST API

- Your service is a standard web backend (Node.js, Python, Go, etc.)
- You don't run inside an MCP host
- You want simple HTTP request/response patterns
- You need webhook-driven payment notifications

## Prerequisites

1. An EVM signer key for request authentication (EIP-712 signed headers)
2. A payment address for receiving XSGD
3. A publicly accessible webhook endpoint (recommended)

**Base URL:** `https://api.nexus.platon.network`

## Step 1 — Register Your Agent

```bash
curl -X POST https://api.nexus.platon.network/api/market/register \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_did": "did:nexus:20250407:my_agent",
    "name": "My Agent",
    "description": "What your agent does",
    "category": "travel.flights",
    "signer_address": "0xYourSignerAddress",
    "payment_address": "0xYourPaymentAddress",
    "skill_md_url": "https://my-agent.example.com/skill.md",
    "health_url": "https://my-agent.example.com/health",
    "webhook_url": "https://my-agent.example.com/webhooks/nexus"
  }'
```

## Step 2 — Generate Quotes

Your agent signs NexusQuote payloads using EIP-712 and returns them in responses.

Quote structure:
```json
{
  "merchant_did": "did:nexus:20250407:my_agent",
  "merchant_order_ref": "ORD-001",
  "amount": "5000000",
  "currency": "XSGD",
  "chain_id": 20250407,
  "expiry": 1711900000,
  "context": {
    "summary": "Flight SFO → LAX",
    "line_items": [{ "description": "Economy seat", "amount": "5000000" }]
  },
  "signature": "0x..."
}
```

## Step 3 — Payment Orchestration (User Side)

The user's agent submits quotes to NexusPay:

```bash
curl -X POST https://api.nexus.platon.network/api/orchestrate \
  -H "Content-Type: application/json" \
  -d '{
    "quotes": [<quote_from_your_agent>],
    "payer_wallet": "0xPayerAddress"
  }'
```

Response: HTTP 402 with `checkout_url` for the user to complete payment.

## Step 4 — Handle Payment Lifecycle

### Signed Request Authentication

All merchant API calls require EIP-712 signed headers:

| Header | Value |
|--------|-------|
| `x-nexus-signature` | EIP-712 signature of request |
| `x-nexus-signer` | Signer address (0x...) |
| `x-nexus-timestamp` | Unix timestamp |
| `x-nexus-nonce` | Unique nonce (replay protection) |

### Confirm Fulfillment

```bash
curl -X POST https://api.nexus.platon.network/api/merchant/confirm-fulfillment \
  -H "Content-Type: application/json" \
  -H "x-nexus-signature: 0x..." \
  -H "x-nexus-signer: 0x..." \
  -H "x-nexus-timestamp: 1711900000" \
  -H "x-nexus-nonce: abc123" \
  -d '{"nexus_payment_id": "PAY-xxx"}'
```

### Cancel Payment

```bash
curl -X POST https://api.nexus.platon.network/api/merchant/cancel-payment \
  -H "Content-Type: application/json" \
  -H "x-nexus-signature: 0x..." \
  -H "x-nexus-signer: 0x..." \
  -H "x-nexus-timestamp: 1711900000" \
  -H "x-nexus-nonce: abc123" \
  -d '{"nexus_payment_id": "PAY-xxx", "cancel_reason": "out of stock"}'
```

### Webhook Events

Configure `webhook_url` to receive POST notifications:

```json
{
  "event": "payment.escrowed",
  "payment": {
    "nexus_payment_id": "PAY-xxx",
    "status": "ESCROWED",
    "amount": "5000000",
    "merchant_did": "did:nexus:20250407:my_agent"
  }
}
```

| Event | Action Required |
|-------|-----------------|
| `payment.escrowed` | Deliver service, then call confirm-fulfillment |
| `payment.settled` | Funds released — call confirm-fulfillment again for COMPLETED |
| `payment.cancelled` | Cancel the order on your side |
| `payment.completed` | End-to-end done, no action needed |

## API Endpoints Reference

| Method | Path | Purpose | Auth |
|--------|------|---------|------|
| POST | `/api/orchestrate` | Create payment | Open |
| GET | `/api/payments?group_id=...` | Query status | Open |
| GET | `/api/payments/{PAY-...}` | Payment detail | Open |
| POST | `/api/merchant/confirm-fulfillment` | Trigger release | Signed |
| POST | `/api/merchant/cancel-payment` | Cancel payment | Signed |
| POST | `/api/merchant/cancel-order` | Cancel order group | Signed |
| POST | `/api/merchant/dispute` | Open dispute | Signed |
| POST | `/api/merchant/resolve` | Resolve dispute | Signed |
| GET | `/api/merchant/payments?merchant_did=...` | Merchant payments | Open |
| GET | `/api/agents` | Search marketplace | Open |
| GET | `/api/agents/{did}/skill` | Agent skill.md | Open |
| POST | `/api/market/register` | Register agent | Auth |
| POST | `/api/faucet/claim` | Claim test XSGD | Open |
| GET | `/api/health` | Health check | Open |
| GET | `/api/stats` | Statistics | Open |

## Full Reference

- REST API: [skill-user.md](https://api.nexus.platon.network/skill-user.md)
- MCP tools: [skill.md](https://api.nexus.platon.network/skill.md)
- Marketplace: [skill-market.md](https://api.nexus.platon.network/skill-market.md)