Skip to main content

ACP Sidecar Integration

Resonance operates as a loyalty sidecar alongside ACP (Agentic Commerce Protocol) checkout flows. Shopping agents call Resonance before and after ACP checkout to maximize rewards for users.

Architecture​

Shopping Agent ──► Resonance (pre-checkout) ──► ACP Merchant (checkout) ──► Resonance (post-checkout)
                   │                                                        │
                   ├─ route_purchase                                        └─ process_event
                   ├─ stack_deals                                              (record cashback)
                   └─ browse_perks

Resonance provides discount codes and loyalty data. The merchant handles checkout via ACP. Resonance records cashback after the purchase completes.

Pre-Checkout: Optimize the Deal​

Before initiating ACP checkout, the shopping agent should:

1. Route the Purchase​

Find the best brand for the user's intent:

// MCP tool call
{
  "name": "rsnc_agent_route_purchase",
  "arguments": {
    "intent": "running shoes",
    "purchaseAmount": 120
  }
}

Or via A2A:

curl -X POST https://agent.rsnc.network/tasks/send \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "role": "user",
      "parts": [{
        "type": "data",
        "mimeType": "application/json",
        "data": {
          "skill": "route_purchase",
          "intent": "running shoes",
          "purchaseAmount": 120
        }
      }]
    }
  }'

2. Stack Deals​

Get the optimal discount combination:

{
  "name": "rsnc_agent_stack_deals",
  "arguments": {
    "brandId": "0xBrandAddress",
    "purchaseAmount": 120,
    "userId": "[email protected]"
  }
}

Response includes:

  • Base cashback rate and amount
  • Best redeemable perk with discount_code
  • Streak multiplier bonus
  • Total savings breakdown

3. Apply Discount Codes to ACP Checkout​

The stack_deals response includes discount codes. Pass these into the ACP UpdateCheckoutRequest:

// Extract discount codes from Resonance response
const discountCodes = resonanceResponse.bestPerk?.discountCode
  ? [resonanceResponse.bestPerk.discountCode]
  : [];

// Apply to ACP checkout
await fetch(`${merchantUrl}/checkouts/${checkoutId}`, {
  method: 'PUT',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    line_items: [...],
    discount_codes: discountCodes,
  }),
});

Post-Checkout: Record Cashback​

After ACP checkout completes successfully, record the purchase to earn cashback:

{
  "name": "rsnc_agent_process_event",
  "arguments": {
    "brandId": "0xBrandAddress",
    "eventType": "purchase",
    "userEmail": "[email protected]",
    "domain": "brand.com",
    "metadata": {
      "acp_order_id": "ord_123",
      "amount": 120
    }
  }
}

This triggers cashback calculation based on the brand's configured reward rules.

Authentication​

For Public Queries (route_purchase, browse_perks)​

No authentication required — these are public discovery tools.

For User-Specific Actions (stack_deals, process_event)​

HMAC authentication required:

HeaderValue
X-RSNC-Agent-KeyYour agent key ID
X-RSNC-TimestampUnix timestamp (seconds)
X-RSNC-SignatureHMAC-SHA256 signature

See Authentication for signing details.

For Payment Network Transactions​

Use RFC 9421 Ed25519 signatures. See RFC 9421 Authentication.

Complete Flow​

1. User tells shopping agent: "Buy me running shoes under $150"
2. Shopping agent calls Resonance: route_purchase(intent="running shoes", amount=150)
3. Resonance returns: best brand, cashback rate, available perks
4. Shopping agent calls Resonance: stack_deals(brandId, amount=150, userId)
5. Resonance returns: discount code "SAVE15", cashback $7.50, streak bonus 1.2x
6. Shopping agent creates ACP checkout with merchant, applies "SAVE15"
7. User completes payment via ACP checkout flow
8. Shopping agent calls Resonance: process_event(brandId, "purchase", userId)
9. Resonance records $9.00 cashback (base $7.50 × 1.2x streak)

Discovery​

Shopping agents can discover Resonance capabilities via:

  • MCP: Connect to https://agent.rsnc.network/mcp
  • A2A: Fetch https://agent.rsnc.network/.well-known/a2a/agent-card
  • UCP: Fetch https://agent.rsnc.network/.well-known/ucp
Last updated on