Merchants

​

Overview

​

Endpoints

​

Get Merchant by Address

GET /api/identipay/v1/merchants/by-address/:suiAddress

​

Path Parameters

​

Response

​

Example Request

curl https://api.identipay.com/api/identipay/v1/merchants/by-address/0xabc123...

​

Example Response

{
  "name": "Acme Store",
  "publicKey": "a1b2c3d4e5f6...",
  "suiAddress": "0xabc123...",
  "did": "did:identipay:acme.com:550e8400-e29b-41d4-a716-446655440000"
}

​

Error Responses

{
  "error": "Merchant not found"
}

​

Register Merchant

POST /api/identipay/v1/merchants/register

​

Request Body

​

Response

​

Example Request

curl -X POST https://api.identipay.com/api/identipay/v1/merchants/register \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Store",
    "suiAddress": "0xabc123...",
    "hostname": "acme.com",
    "publicKey": "a1b2c3d4e5f6..."
  }'

​

Example Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "did": "did:identipay:acme.com:550e8400-e29b-41d4-a716-446655440000",
  "apiKey": "ip_live_abc123def456..."
}

​

Error Responses

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid merchant registration input",
    "details": {
      "fieldErrors": {
        "name": ["String must contain at least 1 character(s)"],
        "suiAddress": ["Invalid"],
        "publicKey": ["Must be 64-char lowercase hex"]
      }
    }
  }
}

{
  "error": {
    "code": "CONFLICT",
    "message": "A merchant with this hostname already exists"
  }
}

{
  "error": {
    "code": "SUI_ERROR",
    "message": "Failed to register merchant on-chain",
    "details": {}
  }
}

​

Implementation Details

​

Registration Flow

1. Validate Input: Check required fields and formats
2. Check Uniqueness: Verify hostname is not already registered
3. Generate Credentials:
   • UUID for merchant ID
   • DID: did:identipay:{hostname}:{id}
   • API key (random secure string)
   • API key hash (SHA-256)
4. On-Chain Registration: Call suiService.registerMerchantOnChain() to register in the trust registry
5. Database Storage: Store merchant info with hashed API key
6. Return Response: Return ID, DID, and plain-text API key

​

Security

• API keys are hashed using SHA-256 before storage
• Only the hash is stored in the database
• The plain-text API key is never retrievable after initial registration

​

DID Format

did:identipay:{hostname}:{uuid}

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

​

Related Endpoints

• Proposals - Create payment proposals (requires API key)
• Transactions - Check transaction status (requires API key)