refacil-pay-cli CLI

Generated CLI for Refácil Pay — produced by postman-to-cli.

AI agents / autonomous operation: read AGENTS.md for the full self-service guide. Install the skill into the skills directory your agent reads (refacil-pay-cli skills install --path <your-agent-skills-dir>) and operate this CLI with that skill, not from --help alone.

Installation

npm install -g refacil-pay-cli

Authentication

Security of login (OAuth 2.1 + PKCE)

This CLI uses OAuth 2.1 Authorization Code + PKCE as the default authentication flow:

| Security property | Detail | |---|---| | No password in terminal | Credentials are entered in the browser; the CLI never sees them | | PKCE protection | code_verifier never leaves the user's machine — an intercepted code is useless without it | | Token not in URL | Token travels only in the back-channel POST /oauth/token response body, never in a URL or fragment | | OS keychain storage | The access token is stored in the system keychain (not in a file), protecting it at rest | | Short-lived one-time code | Authorization code has a TTL of ~60 s and is invalidated after first use | | State (CSRF protection) | A random 256-bit state is generated per flow and validated on the callback — a mismatched state is rejected, preventing CSRF | | Loopback callback port | The client sends only callback_port (an integer in 1024–65535), never a full URL — the API reconstructs the http://127.0.0.1:{callback_port}/callback loopback address server-side, so no external redirect URI can be injected |

First time / no account — sign-up wizard

If you do not have an account, run refacil-pay-cli login. The CLI will first ask whether you already have an account:

1. No account: choose the second option — the CLI opens the sign-up page for the active environment in your browser automatically (sandbox: https://autoregistro.qa.refacilpay.co/ / prod: https://autoregistro.refacilpay.co/). Complete web registration, then return to run the login step below.
2. Already have an account: choose the first option — proceeds directly to credentials.

You can also open the sign-up page directly at any time:

refacil-pay-cli register

Agent note: If the user does not have an account or the login command fails, instruct them to choose option 2 in the wizard or to run refacil-pay-cli register. Never collect or transmit credentials yourself.

Login modes (users with an account)

| Mode | Command | Description | |------|---------|-------------| | Browser login (default) | refacil-pay-cli login | Opens the OAuth login page in the browser; no password typed in the terminal. Token stored in the OS keychain. | | Console login | refacil-pay-cli login --console | Secure prompts in the terminal. Confirm whether to save credentials for automatic token renewal (auto-refresh when the session expires). | | Device flow | refacil-pay-cli login --device | OAuth 2.0 Device Authorization Grant (RFC 8628) — explicit fallback for isolated environments that cannot open a browser or receive a localhost callback (cloud/sandbox agents, CI, SSH-only). Prints a verification URL + code to authorize from another device. See below. |

# After any successful login, verify with:
refacil-pay-cli whoami

# Logout
refacil-pay-cli logout

Isolated environments (Device Authorization Grant, RFC 8628)

Loopback refacil-pay-cli login is the secure default. Use the Device Authorization Grant only when this machine cannot open a browser or receive a 127.0.0.1 callback — cloud/sandbox agents (e.g. Codex), CI, or SSH-only sessions. The CLI does not auto-detect this; you opt in explicitly:

refacil-pay-cli login --device

The CLI:

1. Requests a device_code + user_code and prints a verification URL and a short code to stdout.
2. In an interactive terminal it also prints a QR code — scan it with your phone to open the verification page with the code already filled in (scan-and-go).
3. You (or an AI agent relaying the values) open the URL — or scan the QR — on any other device and enter the code.
4. The CLI polls the token endpoint at the server-provided interval (RFC 8628 §3.4) and stores the token on success.

==== Device Authorization ====
Visit: https://…/device
Enter code: ABCD-1234
Code expires in 300 seconds.

  █▀▀▀▀▀█ ▀▄ █▀ █▀▀▀▀▀█
  █ ███ █ ▀█▄▀▄ █ ███ █     ← scan to open the verification page
  █ ▀▀▀ █ █▀▄ █ █ ▀▀▀ █        with the code already filled in
  ▀▀▀▀▀▀▀ ▀ ▀ ▀ ▀▀▀▀▀▀▀

Waiting for authorization...

| Detail | Behavior | |---|---| | When to use | Explicitly, when this machine cannot open a browser or reach a 127.0.0.1 callback (cloud/sandbox, CI, SSH-only). Loopback (login) is the secure default everywhere else — there is no auto-detection. | | QR scan-and-go | In an interactive terminal (TTY) the CLI prints a QR encoding verification_uri_complete (code pre-filled), falling back to verification_uri. In non-interactive output (pipe, CI, agent reading stdout) no QR is printed — the text output is unchanged. A QR render failure never aborts login. | | Non-interactive equivalent | Set REFACIL_PAY_CLI_HEADLESS=1 to select the device flow without passing --device (e.g. from an MCP/agent config). | | Mutual exclusion | --device and --console cannot be combined. | | No password in the chat/terminal | Credentials are entered on the verification page in a browser, never in the CLI or relayed to an agent. | | Token storage | Primarily the OS keychain. Only when no keychain is available (headless / CI) does it fall back to ~/.config/refacil-pay-cli/credentials.json with 0600 perms (owner-only). The token is short-lived — on shared/CI hosts, prefer the keychain and protect the host filesystem. | | Expiration | Polling is bounded by the server-provided expires_in value. When the device code expires the CLI prints Device code expired — run login again and exits. There is no infinite polling loop. |

Agent note: Run refacil-pay-cli login --device as a real background process that survives — on Windows use your harness's Bash-tool background (run_in_background), not a PowerShell background, and never a sub-agent (either can die before the token is received). Read its output immediately and relay the direct link (the Or open directly: … URL, which embeds the code) — do not open the browser yourself. Then wait for that process to finish (it stores the token and exits on success); only afterwards confirm with refacil-pay-cli whoami --json. The shipped skill (skills/refacil-pay-cli/references/env-headless.md) has the full pattern.

Environments

Use --env sandbox or --env prod to target different environments.

• Sandbox: https://pay-api.qa.refacil.co
• Production: https://pay-api.refacil.co

login and register ask you which environment to use in an interactive terminal (pre-selecting your saved default) instead of silently assuming sandbox. Pass --env to skip the prompt, or set a persistent default with refacil-pay-cli config set-environment <sandbox|prod>. Non-interactive sessions (agents/CI) fall back to the saved default, else sandbox.

Global Flags

| Flag | Description | |------|-------------| | --profile <name> | Credential profile (default: default) | | --env <env> | Environment: sandbox | prod (default: sandbox) | | --json | Output raw JSON | | --yes | Skip confirmation prompts | | --dry-run | Show request payload without making HTTP call | | --no-color | Disable colored output |

Commands

Base Commands

• init — Interactive onboarding: install the AI skills into your IDEs (or a custom path)
• login — Authenticate and store credentials
• logout — Remove stored credentials
• whoami — Show current user
• register — Open signup page in browser
• config — Manage CLI configuration
• skills — Install/manage the AI skills in your IDEs (skills install / list / uninstall)
• whatsapp — Send generated resources to a customer over WhatsApp (Kapso)

Generated API Commands

• cash-in-link-create — (safe-mutation)
• cash-in-payment-method — This endpoint allows you to generate payment requests through the available cash-in methods. (safe-mutation)
• cash-out-withdraw — This endpoint allows you to generate withdrawal (cash-out) requests through the available payout methods. (dangerous)
• balance — This service allows you to consult the balance exchange and the dispersion exchange associated with the client's identi… (read-only)
• payment-status — This service allows you to check the status of a transaction made, for this you must have the reference data that retur… (read-only)
• payment-customer-reference-status — This endpoint allows API Pay users to query the status of a transaction using only the customerReference value origin… (read-only)
• payment-features — This service allows you to consult the necessary characteristics of a payment method to successfully generate a resourc… (safe-mutation)
• webhook-notify — Body (safe-mutation)
• merchant-enrollment-data — This endpoint retrieves the merchant's enrollment details after the enrollment process has been completed. (read-only)
• user-webhooks-get — Returns the backup webhooks configured for the authenticated user. (read-only)
• user-webhooks-post — Creates a backup webhook for a user and webhook type. (safe-mutation)
• user-webhooks-id-status — Updates the active/inactive status of a backup webhook owned by the authenticated user. (read-only)
• trx-token-link — (safe-mutation)
• trx-token-method — (safe-mutation)
• trx-token-withdraw — (safe-mutation)
• trx-token-merchant-key-create — (safe-mutation)
• trx-token-merchant-key-cancel — (safe-mutation)

AI Skills

On install, refacil-pay-cli automatically deploys a context file to your AI IDE (Claude Code, Cursor, OpenCode, Codex) so it understands the API without extra configuration.

For a guided setup, run the onboarding wizard — it detects your installed IDEs (pre-selecting the ones found) and lets you pick a custom path for non-standard skills directories:

refacil-pay-cli init              # interactive wizard: pick IDEs / custom path

Manage skills manually:

refacil-pay-cli skills list           # show installation status per IDE
refacil-pay-cli skills install        # re-run the installer (detected IDEs)
refacil-pay-cli skills install --path <dir>   # install into a custom directory
refacil-pay-cli skills uninstall      # remove all installed skills

Opt out — set the env var before installing to skip skill installation entirely:

REFACIL_PAY_CLI_NO_SKILLS=1 npm install -g refacil-pay-cli

WhatsApp delivery (Kapso) — optional

refacil-pay-cli can send a generated resource (payment link, QR, etc.) to a customer over WhatsApp through Kapso. This is optional — the CLI works fully without it.

One-time setup

# Required on first configuration:
refacil-pay-cli config set-kapso --api-key <kapso-api-key> --phone-number-id <whatsapp-phone-number-id>

# Optional extras (can be set/updated later; existing values are preserved):
refacil-pay-cli config set-kapso --merchant-name "Mi Negocio"        # commerce name shown in the message
refacil-pay-cli config set-kapso --default-phone +573001234567        # default recipient (skips --to)

The API key is stored in the system keychain. Check the active configuration at any time:

refacil-pay-cli config get-kapso --json     # { kapsoEnabled, phoneNumberId, defaultPhone, merchantName }

To remove it:

refacil-pay-cli config clear-kapso

Sending a resource

After a command produces a resource URL, send it with whatsapp send:

refacil-pay-cli whatsapp send --to +573001234567 --command-key <key> --url <resource-url> --amount "<amount>"

| Flag | Required | Description | |------|----------|-------------| | --to <e164> | ✅ | Recipient phone number in E.164 format (e.g. +573001234567). Falls back to the configured --default-phone. | | --command-key <key> | — | Selects the YAML-configured message template and label (e.g. cash-in.link.create). Recommended — without it the message uses generic fallback text and drops the label. | | --url <url> | — | Resource URL inserted into the message ({{url}} placeholder). | | --amount <value> | — | Amount string inserted into the message ({{amount}} placeholder), e.g. "$50.000 COP". | | --message <text> | — | Free-text body that overrides the template and label. Use only for custom wording. |

Result:

• ✓ WhatsApp message sent to <number> (exit 0) — delivered.
• WhatsApp not sent: <reason> ⚠ (exit 1) — not delivered.

24-hour window: WhatsApp only delivers free-text messages within 24 hours of the recipient's last inbound message. Outside that window the message may not arrive even if the command reports success.

Audit Log

Mutation commands are logged to ~/.refacil-pay-cli/audit.log in JSONL format.

License

MIT