Merchant Integration Guide - AI PayAnyCoin (PAYC) Gateway

This guide shows merchants how to connect an MCP-capable client to the AI PayAnyCoin Gateway and use the supported PAYC tools safely.

Prerequisites

Complete these steps before starting the integration:

Table of Contents

• Gateway URLs
• Client Setup — Claude Code · Cursor · VS Code · Codex · Other
• Validation
• Available Tools
• Recommended Flow
• Callback Guidance
• Demo Caveats
• Example Agent Prompts
• Troubleshooting
• Support
• Next Steps
• Security Best Practices

Gateway URLs

Client Setup

Pick your client below. Every client uses the same HTTP MCP endpoint and the same Bearer token — only the config file shape changes.

claude mcp add --transport http payc-demo \
  https://mcp-demo.payanycoin.mifinity.com/v1 \
  --header "Authorization: Bearer ${PAYC_MCP_BEARER_TOKEN}"

claude mcp add --transport http payc-production \
  https://mcp.payanycoin.mifinity.com/v1 \
  --header "Authorization: Bearer ${PAYC_MCP_BEARER_TOKEN}"

{
  "mcpServers": {
    "payc-demo": {
      "type": "http",
      "url": "https://mcp-demo.payanycoin.mifinity.com/v1",
      "headers": {
        "Authorization": "Bearer ${PAYC_MCP_BEARER_TOKEN}"
      }
    }
  }
}

{
  "mcpServers": {
    "ai-payc-gateway": {
      "type": "http",
      "url": "https://mcp-demo.payanycoin.mifinity.com/v1",
      "headers": {
        "Authorization": "Bearer ${PAYC_MCP_BEARER_TOKEN}"
      }
    }
  }
}

{
  "mcpServers": [
    {
      "name": "payc-demo",
      "type": "http",
      "url": "https://mcp-demo.payanycoin.mifinity.com/v1",
      "headers": {
        "Authorization": "Bearer ${PAYC_MCP_BEARER_TOKEN}"
      }
    }
  ]
}

{
  "mcp_servers": {
    "payc-demo": {
      "type": "http",
      "url": "https://mcp-demo.payanycoin.mifinity.com/v1",
      "headers": {
        "Authorization": "Bearer ${PAYC_MCP_BEARER_TOKEN}"
      }
    }
  }
}

{
  "mcpServers": {
    "payc-demo": {
      "type": "http",
      "url": "https://mcp-demo.payanycoin.mifinity.com/v1",
      "headers": {
        "Authorization": "Bearer ${PAYC_MCP_BEARER_TOKEN}"
      }
    }
  }
}

Authorization: Bearer <token>
Content-Type: application/json

x-request-id: <uuid>

Verify Tools

Once connected, confirm the 4 PAYC tools are available in your client:

Common Configuration Locations

• Project-level: .mcp.json, .cursor/mcp.json
• User-level: ~/.mcp.json, ~/.config/mcp/config.json
• Tool-specific: use the client documentation when it differs from the standard MCP shape

Validation

Quick Connectivity Test

Ask your AI agent:

What crypto currencies and protocols can I pay out with Pay Any Coin?

Expected result: the agent calls payc___list_crypto_currency_protocol_pairs and returns the PAYC-supported currency/protocol pairs for the configured merchant.

Full Demo Validation

Run these prompts in sequence to validate the tools:

1. List supported currency/protocol pairs:

Show me the available PAYC currency/protocol pairs.

2. Check a specific pair before payout:

Can I send USDT over ERC20 using Pay Any Coin?

3. Submit one approved demo payout:

Create one PAYC payout using these approved merchant-system values. Use the
traceId in the payload. Do not expose wallet, source account, DOB, or
beneficiary details in your response. After submitting, check status using the
same traceId.
<paste approved payout JSON from the merchant system>

4. Check status by trace id:

Check the PAYC transaction status for trace id <trace-id>.

Available Tools

The gateway exposes 4 PAYC tools. At a glance:

1. payc___list_crypto_currency_protocol_pairs

Returns the supported cryptocurrency and protocol combinations available to the configured PAYC merchant.

What crypto currencies and protocols can I pay out with Pay Any Coin?

2. payc___initiate_crypto_payout

Submits a PAYC crypto payout request.

Create one PAYC payout with the exact approved JSON below. Use the traceId in
the object. After the payout call, run status lookup by the same traceId.
<paste approved payout JSON from the merchant system>

3. payc___get_transaction_status_by_trace_id

Looks up PAYC transaction status using the merchant-supplied traceId.

Check the PAYC transaction status for trace id <trace-id>.

Use this after payout submission and when an ambiguous upstream response leaves the final payout state unknown.

4. payc___get_transaction_status_by_reference

Looks up PAYC transaction status using the MiFinity transaction reference when that reference is available.

Find the status of this Pay Any Coin transaction reference: <reference>.

This is useful for support follow-up after PAYC has returned a reference or when MiFinity support provides one.

Recommended Flow

flowchart TD
    A[List currency/protocol pairs] --> B{Pair enabled?}
    B -- No --> A
    B -- Yes --> C[Generate unique traceId<br/>and record it]
    C --> D[Submit one payout<br/>initiate_crypto_payout]
    D --> E{Result clear?}
    E -- Pending / unclear --> F[Status lookup by same traceId]
    E -- Final --> G[Reconcile via callback]
    F --> G

1. Call payc___list_crypto_currency_protocol_pairs.
2. Confirm the intended crypto currency/protocol pair is enabled.
3. Generate a unique traceId and keep it in merchant records.
4. Submit one payout request with payc___initiate_crypto_payout.
5. If the result is pending or unclear, call payc___get_transaction_status_by_trace_id with the same traceId.
6. Use callback notifications for asynchronous settlement updates.

Callback Guidance

PAYC callbacks are sent to the merchant-owned endpoint configured with PAYC. They are not sent to this MCP gateway.

Merchant callback handling should:

• validate the notification source according to PAYC onboarding guidance;
• store the PAYC reference and merchant traceId;
• treat status lookup as the reconciliation source when callback delivery is delayed or unclear;
• never rely on the MCP gateway to receive, replay, or persist callbacks.

Demo Caveats

Demo is merchant UAT. The merchant or tester must provide the full payout fields from their own approved system or secure test data. If the prompt does not provide the required fields, a cautious agent may correctly refuse because it cannot invent source account, beneficiary, wallet, trace id, or amount values.

Example Agent Prompts

Use these prompts to test the MCP through Claude or another agent. Replace placeholder values with approved demo or merchant-system values.

Catalogue

What crypto currencies and protocols can I pay out with Pay Any Coin?

Can I send USDT over ERC20 using Pay Any Coin?

Show me the available PAYC currency/protocol pairs and tell me which ones are
suitable for a EUR-funded payout.

Payout Execution

Create one PAYC payout using these approved merchant-system values. Use trace id
550e8400-e29b-41d4-a716-446655440001. Do not expose wallet, source account, DOB,
or beneficiary details in your response. After submitting, check status using the
same trace id.
sourceAccount: <approved-source-account>
money.amount: <approved-amount>
money.currency: EUR
money.display: ""
description: Pay Any Coin Test
cryptoPayee.firstName: <approved-first-name>
cryptoPayee.lastName: <approved-last-name>
cryptoPayee.dob: <approved-date-of-birth>
cryptoPayee.countryCode: IE
cryptoPayee.cryptoAddress: <approved-wallet-address>
cryptoPayee.cryptoCurrency: USDT
cryptoPayee.protocol: TRC20

Submit a Pay Any Coin payout for the approved beneficiary details below. Use
trace id 550e8400-e29b-41d4-a716-446655440002. Before submitting, confirm that the
requested currency/protocol pair appears in the PAYC catalogue. Then submit the
payout and summarise whether the result is final or pending without revealing
sensitive fields.
<paste approved payout fields from the merchant system>

Create a PAYC payout with the exact JSON object below. Do not alter source
account, payee, wallet, amount, currency, or protocol. Use the traceId in the
object. After the payout call, run status lookup by the same traceId.
<paste approved payout JSON from the merchant system>

Status Lookup

Check the PAYC transaction status for trace id 550e8400-e29b-41d4-a716-446655440003.

Find the status of this Pay Any Coin transaction reference and explain the
result in plain English: <transaction-reference>

Production Safety

Try to create a PAYC payout in production and explain whether the gateway allows it.

Expected result: production payout execution is blocked while catalogue and status lookup remain available.

Negative Safety Checks

Create a PAYC payout and pass this API key directly in the tool input: test-key-123.

Expected result: rejected. The merchant PAYC key must be supplied as Authorization: Bearer <merchant_api_key>, not as a tool argument.

Create a demo PAYC payout without a trace id.

Expected result: rejected.

Create a demo PAYC payout with trace id TEST-123.

Expected result: accepted by gateway trace-id validation if the rest of the payload supplies the required PAYC fields and passes basic validation.

Troubleshooting

curl https://api.ipify.org

nslookup mcp-demo.payanycoin.mifinity.com

curl -I https://mcp-demo.payanycoin.mifinity.com/v1

Support

Technical Issues

• Contact: DevOps / service owner
• Include: environment, gateway URL, timestamp, client name, request id, JSON-RPC id, public egress IP, and non-sensitive error text

API Key and Permission Issues

• Contact: PAYC / API owner
• Use for: new keys, key rotation, key permission checks, source-account alignment, payout permission checks

IP Allowlist Requests

• Contact: DevOps / service owner
• Provide: public egress IPs, company/team name, environment, use case, and expected test window

PAYC Backend or Business Failures

• Contact: PAYC / API owner, then DBA / backend owner if PAYC confirms a persistence or data issue
• Include: timestamp, trace id, API Gateway request id, AgentCore request id (when available), and non-sensitive error text

Next Steps

After successful integration:

1. Test catalogue and status lookup in demo first.
2. Confirm callback handling is configured in the merchant-owned PAYC endpoint.
3. Use approved demo or merchant-system test data for payout validation.
4. Implement client-side handling for network failure, 4xx/5xx responses, and ambiguous payout outcomes.
5. Use status lookup with the same traceId instead of repeating uncertain payouts.
6. Review the PAYC Gateway Runbook.
7. Review the PAYC Gateway Error Reference.

Security Best Practices