Skip to main content

Build with AI

AI coding assistants can dramatically speed up a CodePay integration — but they often hallucinate protocol details, invent field names, and skip critical steps like transaction recovery. The result compiles fine and fails at runtime.

The CodePay Agent Skill solves this. It injects the correct integration knowledge directly into your AI assistant so it selects the right architecture, uses the real protocol, and implements payment flows that work in production.

note

Agent Skills is an emerging standard. Installation steps may vary as the specification evolves.

Install the skill​

# macOS / Linux
git clone https://github.com/codepay-us/integrating-agent-skill \
  ~/.claude/skills/integrating-codepay-payments

# Windows (PowerShell)
git clone https://github.com/codepay-us/integrating-agent-skill `
  "$env:USERPROFILE\.claude\skills\integrating-codepay-payments"

After cloning, the skill is auto-discovered. Invoke it with /integrating-codepay-payments or reference it by name in any prompt.

To keep the skill up to date:

git -C ~/.claude/skills/integrating-codepay-payments pull

Claude Desktop / claude.ai​

  1. Download the repository as a ZIP from GitHub.
  2. Upload it as a Skill in Claude Desktop.

Cursor, GitHub Copilot CLI, and other tools​

Add SKILL.md and codepay-protocol-reference.md as system context or rules files in your AI tool of choice. The skill works with any assistant that supports custom system instructions.

How the skill works​

When you ask your AI assistant to integrate CodePay payments, the skill guides it through a three-phase process before writing any code:

  1. Refresh live documentation. The skill instructs your AI assistant to fetch the latest protocol spec from developer.codepay.us and reconcile it against its bundled snapshot. This prevents implementations based on stale field definitions.

  2. Select the right topology. Based on your POS deployment, your AI assistant selects the correct integration path:

    • On-Terminal — POS app runs on the CodePay device, uses Android Intents
    • Local (WLAN) — POS connects over LAN or serial, uses ECR Hub WebSocket messages
    • Cloud — POS communicates through CodePay's cloud API with RSA2 signatures

  3. Implement with production safeguards. Your AI assistant applies amount formatting rules, transaction recovery, PCI storage constraints, and credential validation before generating code.

Example prompts​

Copy these prompts directly into your AI assistant after installing the skill. In Claude Code, you can also invoke the skill first with /integrating-codepay-payments, then describe your task.

On-terminal (same device)

I have a Flutter POS app running on the same CodePay terminal.
Integrate CodePay payments using the integrating-codepay-payments skill.
Support Sale, Void, and Refund.

Local network (external POS)

My Windows cashier app connects to a CodePay terminal over the local network.
Use the integrating-codepay-payments skill to add payment support.

Cloud integration

My web-based POS needs to talk to CodePay through the cloud API.
Use the integrating-codepay-payments skill and guide me through the credential setup.

What the skill protects against​

Without the skill, AI assistants frequently make these mistakes:

Common AI mistakeWhat the skill enforces
Sending amounts as integers (e.g. 215 for $2.15)Decimal strings in major units ("2.15")
Treating a timeout as a failed transactionMandatory query-based recovery before any recovery action
Using placeholder app_id values in generated codeReal credentials required before transport code is written
Inventing protocol field names and response codesEvery field confirmed against the official ECR Hub spec
Storing full card numbers or track dataOnly masked data (card_last4, card_brand) allowed

Next steps​