Integration skill

If you integrate B4bit Pay with Claude Code, Claude Desktop, or Cursor, install the b4bit-pay-integrator skill. Claude recognizes the context (files like webhook.ts, X-Device-Id headers, XRP/XLM/ALGO symbols) and offers safe templates, HMAC signature diagnostics, and a complete go-live checklist.

What does the skill do?

When Claude detects you are working on code that touches B4bit Pay (through triggers like pos.b4bit.com, X-Device-Id, webhook HMAC, X-NONCE, payment_uri), it automatically activates this skill and applies:

Non-negotiable security rules: timing-safe HMAC comparison (crypto.timingSafeEqual / hmac.compare_digest / hash_equals), never ==.
Ready-made templates for webhook handlers in Node (Express), Python (Flask), PHP (Slim), Go (Gin), and Next.js (Route Handler) — all with correctly validated signatures.
Mapping of the 11 states (NR, PE, AC, IA, CO, CA, EX, OC, FA, DE, CM) to the 4-5 typical merchant states (pending / processing / cancelled / failed).
TAG/MEMO detection: if the flow uses XRP, XLM, or ALGO, Claude inserts the callout that makes tag_memo visible in the customer UI (omission = loss of funds).
Go-live checklist (11 items) executed before letting you mark the integration as ready.
HMAC mismatch diagnostics: if your signature does not match, the skill walks you through typical causes (bad secret decoding, reserialized body, wrong charset).

Installation

Install the MCP server in your AI client (next section).
Install the skill under ~/.claude/skills/:
Ventana de terminal
```
npx @b4bit/b4bit-pay-mcp install-skill
```
This copies the b4bit-pay-integrator/ folder (templates, scripts, SKILL.md) to your personal skills directory.
Restart Claude Code / Claude Desktop / Cursor and open a merchant project. The skill activates on its own when it detects triggers related to B4bit Pay.

Configure the MCP server

The skill delegates operations like “verify this signature” or “list the currencies” to the MCP server. Add it to the client you use:

{
"mcpServers": {
  "b4bit-pay": {
    "command": "npx",
    "args": ["-y", "@b4bit/b4bit-pay-mcp"],
    "env": { "B4BIT_API_KEY": "<tu-api-key>" }
  }
}
}

{
"mcpServers": {
  "b4bit-pay": {
    "command": "npx",
    "args": ["-y", "@b4bit/b4bit-pay-mcp"],
    "env": { "B4BIT_API_KEY": "<tu-api-key>" }
  }
}
}

{
"mcpServers": {
  "b4bit-pay": {
    "command": "npx",
    "args": ["-y", "@b4bit/b4bit-pay-mcp"],
    "env": { "B4BIT_API_KEY": "<tu-api-key>" }
  }
}
}

The API key is obtained from Settings → Merchant → Devices (pay.b4bit.com/settings/commerce/devices).

What you can ask Claude

Once installed, these requests activate the skill automatically:

“Integrate B4bit Pay into my Express app.” → Generates the webhook handler with timing-safe HMAC + an endpoint to create an order + handling for all 11 states.
“My webhook returns 401 invalid signature, what is wrong?” → Claude invokes the MCP’s verify_webhook with your actual nonce/body/signature and diagnoses the problem (secret decoded as base64 instead of hex, reserialized body, reversed concatenation…).
“What does status=AC with safe=true mean?” → Invokes map_status and returns the matching merchant state and whether it is safe to release the product.
“I want to add XRP as an input currency.” → Inserts the TAG/MEMO callout in the UI and validates that tag_memo renders as prominently as the address.
“Audit before production.” → Runs the go-live checklist on your repo and reports outstanding items.

MCP tools the skill uses

Tool	Use case
`list_currencies`	Validate the input symbol before creating the order.
`create_order`	Dry-run or create a real order respecting all fields.
`get_order`	Fetch the current state of a payment.
`list_orders`	Reconciliation by date window.
`verify_webhook`	Replay the HMAC and diagnose mismatches.
`map_status`	Translate `NR…CM` into pending/processing/cancelled/failed.
`probe_endpoint`	Arbitrary GET/POST against `pos.b4bit.com` (with dry-run).
`list_endpoints`	Quick reference of the 5 public endpoints.
`create_device`	Create a device (requires explicit confirmation).

Verification

Confirm the skill is active:

ls ~/.claude/skills/b4bit-pay-integrator/
# SKILL.md  references/  scripts/  templates/

Then try in Claude: “What is the official test vector of the B4bit Pay webhook?” — it should respond with the vector from SKILL.md and offer to replay it via the MCP.

Resources

npm package @b4bit/b4bit-pay-mcp on npmjs.com

Quickstart 5-min guide without the skill (manual).

Webhook — test vectors Reproducible official vector.

Common errors 403/404/429/500 and troubleshooting.