Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.zendfi.tech/llms.txt

Use this file to discover all available pages before exploring further.

The payments commands let you create, monitor, and inspect payments directly from the CLI. Useful for testing your integration without writing any code.

​
payment create

Create a new payment and get a checkout URL. 
zendfi payment create [options]
Aliases: zendfi payment test, zendfi pay create

​
Options

FlagDescriptionDefault
--amount <amount>Payment amount in USDInteractive prompt
--description <text>Payment descriptionInteractive prompt
--email <email>Customer email addressInteractive prompt
--openOpen the checkout URL in your browserInteractive prompt
--watchWatch payment status until completionInteractive prompt

​
Interactive Mode

If you omit the flags, the CLI prompts you for each value: 
$ zendfi payment create

Create Test Payment

? Amount (USD): 50
? Description: Premium plan upgrade
? Customer email (optional): alice@example.com

​
Non-Interactive Mode

Pass all options as flags to skip prompts: 
zendfi payment create --amount 50 --description "Test order" --open --watch

​
What Happens

1

API key validation

The CLI checks for ZENDFI_API_KEY in your environment. If the key starts with zfi_live_ instead of zfi_test_, it warns you and asks for confirmation before proceeding.
2

Payment creation

Sends a POST /api/v1/payments request with your parameters:
{
  "amount": 50,
  "currency": "USD",
  "description": "Premium plan upgrade",
  "customer_email": "alice@example.com",
  "metadata": {
    "source": "cli-test"
  }
}
All CLI-created payments include "source": "cli-test" in their metadata so you can identify them.
3

Display results

Shows a formatted summary with Payment ID, status, amount, mode (Test/Live), and checkout URL. The checkout URL is automatically copied to your clipboard.
4

Optional: open in browser

If you pass --open or confirm the prompt, the CLI opens the checkout URL in your default browser.
5

Optional: watch status

If you pass --watch or confirm the prompt, the CLI polls the payment status every few seconds and displays live updates until the payment is confirmed, fails, or expires.

​
Example Output

✓ Payment created!

════════════════════════════════════════════════════════════

  Payment Details:

  Payment ID:   pay_test_7f3k9x2m
  Status:       ⏳ PENDING
  Amount:       $50.00 USD
  Mode:         Test (Devnet)
  Created:      12/15/2024, 2:30:00 PM

  This is a test payment (devnet)
     Use your test wallet to complete it

──────────────────────────────────────────────────────────

  Checkout URL:

  https://checkout.zendfi.tech/pay/pay_test_7f3k9x2m

════════════════════════════════════════════════════════════

✓ Copied to clipboard!

? Open checkout URL in browser? Yes
  Opened in browser

? Watch payment status? Yes
  Watching... (Ctrl+C to stop)
  ⏳ pending → ⏳ pending → ✓ CONFIRMED (12s)

​
payment status

Check the current status and details of any payment. 
zendfi payment status <payment-id>

​
Arguments

ArgumentDescriptionRequired
payment-idThe payment ID (e.g., pay_test_abc123)Yes

​
Output Sections

The status command displays a rich, formatted view of the payment: Payment Details — ID, status badge, amount, mode (test/live), description, customer email. Timeline — Creation time, confirmation time (if confirmed), duration between creation and confirmation, expiration countdown (if still pending). Transaction — Solana transaction signature and a direct link to the block explorer (Solscan). Wallets — Merchant wallet address and customer wallet address (truncated for readability). Metadata — Any custom metadata attached to the payment. Actions — For pending payments, shows the checkout URL. For confirmed payments, shows a success message. For failed or expired payments, shows the reason and suggests creating a new payment.

​
Status Badges

StatusBadge
pendingPENDING
confirmedCONFIRMED
failedFAILED
expiredEXPIRED

​
Example

$ zendfi payment status pay_test_7f3k9x2m

✓ Payment found!

══════════════════════════════════════════════════════════════════════

  Payment Details

  Payment ID:      pay_test_7f3k9x2m
  Status:          ✓ CONFIRMED
  Amount:          $50.00 USD
  Mode:            Test (Devnet)
  Description:     Premium plan upgrade
  Customer:        alice@example.com

  ──────────────────────────────────────────────────────────────────

  Timeline

  Created:         12/15/2024, 2:30:00 PM
  Confirmed:       12/15/2024, 2:30:12 PM
  Duration:        12 seconds

  ──────────────────────────────────────────────────────────────────

  Transaction

  Signature:       5K7x...mR3q
  Explorer:        https://solscan.io/tx/5K7x...mR3q

  ──────────────────────────────────────────────────────────────────

  ✓ Payment successfully completed!

══════════════════════════════════════════════════════════════════════

​
Debugging

Enable verbose output with the DEBUG environment variable: 
DEBUG=1 zendfi payment status pay_test_abc123
This logs the raw API response JSON, which is useful for troubleshooting unexpected behavior.

​
Common Patterns

​
Quick smoke test

# Create and immediately watch a payment
zendfi payment create --amount 1 --description "Smoke test" --open --watch

​
Scripting

# Create a payment and extract the ID
PAYMENT_ID=$(zendfi payment create --amount 50 2>/dev/null | grep "Payment ID" | awk '{print $NF}')
echo "Created: $PAYMENT_ID"

# Check status later
zendfi payment status $PAYMENT_ID

​
Live key safety

The CLI prevents accidental live payments. If your ZENDFI_API_KEY starts with zfi_live_, the CLI displays a warning and requires explicit confirmation before creating a real payment. Use test keys (zfi_test_) for development and CI environments.