CLI Command Reference
Every command of the IZI Pay CLI, what it does and what can go wrong. All commands work against the sandbox only.
Commands at a glance
| Command | What it does |
|---|---|
izipay login | Saves the sandbox Client ID and secret that IZI Pay gave you |
izipay check | Confirms your credentials and payment reference (PPR) access |
izipay logout | Removes the saved credentials |
izipay ppr create | Creates a single-use payment reference |
izipay ppr get | Shows a reference's status, amount and expiry |
izipay ppr pay | Simulates a customer paying a reference |
izipay webhooks status | Shows the webhook attempts for a payment |
izipay ppr test | Creates, pays and waits for your webhook, then answers PASS or FAIL |
Options for every command
| Option | Meaning |
|---|---|
--json | Prints one JSON object instead of text. See JSON output. |
--help, -h | Shows help for the command, for example izipay ppr pay --help. |
--version | Prints the CLI version. |
Amounts are in kwanza. Write them with a dot for decimals and no thousands separator: 1000, 1500.50.
Which credentials are used
- If
IZIPAY_CLIENT_IDandIZIPAY_CLIENT_SECRETare both set, the CLI uses them. This is meant for CI. - Otherwise it uses the credentials saved by
izipay login. - If only one of the two variables is set, the command stops and tells you which one is missing.
izipay login
bash
Asks for the Client ID and Client Secret, checks them with the sandbox and saves them in your system's credential store (macOS Keychain, Windows Credential Manager or the Linux keyring). Nothing is saved if the sandbox doesn't accept them.
| Option | Meaning |
|---|---|
--client-id <id> | Gives the Client ID on the command line, so only the secret is asked for. |
Linux without a keyring
Servers and containers often have no keyring service. There, izipay login explains that it can't save the credentials. Set IZIPAY_CLIENT_ID and IZIPAY_CLIENT_SECRET instead.
izipay check
bash
Gets an access token and reads your payment references. It tells you apart:
- wrong credentials: the Client ID or secret isn't accepted;
- no PPR access: the credentials work, but the Client App isn't enabled for payment references. Contact IZI Pay support.
izipay logout
bash
Removes the credentials saved by izipay login. Running it again is harmless. It doesn't touch IZIPAY_CLIENT_ID or IZIPAY_CLIENT_SECRET.
izipay ppr create
bash
Creates a single-use (Dynamic) reference. The sandbox assigns the reference number, your entity and the expiry date (one month later). The customer must pay exactly this amount.
| Option | Meaning |
|---|---|
--amount <kz> | Amount of the reference. Required. |
--description <text> | Optional text saved with the reference. |
text
izipay ppr get
bash
Shows the reference status (Active, Paid, Expired or Cancelled), the amount and the dates. Reference numbers are kept exactly as typed, including leading zeros. Customer details stored with the reference are not shown.
izipay ppr pay
bash
Simulates a customer paying the reference, the way MULTICAIXA reports a real payment. The reference becomes Paid, and the sandbox sends the payment webhook to your application.
The amount is sent exactly as you type it. This is on purpose: it lets you see what happens when a payment doesn't match. A reference can only be paid with the exact amount it was created with.
| Option | Meaning |
|---|---|
--amount <kz> | Amount the customer pays. Required. |
--callback-url <url> | Sends this payment's webhook to this address. It must be a public internet address; private and local network addresses are refused. |
--access-key <key> | Value of the Access-Key header on that webhook, so you can test your key check. If you leave it out, the sandbox generates one and shows it. |
Without --callback-url, the sandbox uses the payment reference webhook saved for your sandbox merchant, if IZI Pay set one up for you. If there is none, the payment still succeeds and the CLI tells you no webhook was sent.
text
Keep the Payment ID: you need it to check the webhook.
izipay webhooks status
bash
Lists each attempt to deliver the payment's webhook to your application: when it happened, the HTTP status your application answered and whether it was accepted. Without --wait, it checks once.
| Option | Meaning |
|---|---|
--wait | Keeps checking every few seconds until the webhook is accepted. |
--timeout <seconds> | How long --wait keeps checking. Default 60, from 5 to 600. |
text
The command exits with 0 when the webhook was accepted and 1 when it wasn't (yet). The body of the webhook and of your application's answer are not shown.
izipay ppr test
bash
Runs the whole flow with a new reference: create it, pay it with the same amount, then wait until your application accepts the webhook. It prints PASS or FAIL and the step that failed.
| Option | Meaning |
|---|---|
--amount <kz> | Amount of the new reference. Required. |
--callback-url <url> | Where to send the webhook. Same as for ppr pay. |
--access-key <key> | Access-Key header value for that webhook. |
--timeout <seconds> | How long to wait for the webhook. Default 60. |
Each run creates and pays a new reference. That is expected in the sandbox.
When the sandbox says no
When the sandbox refuses an operation, the CLI explains it and shows the sandbox's own answer underneath:
text
| Sandbox code | What it means | What to do |
|---|---|---|
AMOUNT_MISMATCH | The amount paid differs from the reference amount. | Pay the exact amount. |
REFERENCE_EXPIRED | The reference expired ("Referencia Expirada"). | Create a new reference. |
REFERENCE_ALREADY_PAID | The reference was already paid ("Referencia ja paga"). | Single-use references can be paid once. Create a new one. |
REFERENCE_CANCELLED | The reference was cancelled. | Create a new reference. |
REFERENCE_NOT_FOUND | No such reference for your merchant. | Check the number. |
PAYMENT_NOT_FOUND | No such payment for your merchant. | Use the Payment ID shown by ppr pay. |
INVALID_CALLBACK_URL | The webhook address isn't a public internet address. | Use a public https:// address. |
PPR_ENTITY_ID_REQUIRED | Your Client App isn't enabled for payment references. | Contact IZI Pay support. |
Outcome unknown
If the connection breaks or the sandbox doesn't answer within 60 seconds while creating or paying a reference, the CLI says the outcome is unknown. It never repeats a payment by itself. Run izipay ppr get <reference> to see whether the reference is now Paid before you try again.
Exit codes
| Code | Meaning |
|---|---|
0 | Done. For ppr test and webhooks status: the webhook was accepted. |
1 | The sandbox refused the operation, or the webhook wasn't accepted (yet). |
2 | The command line was wrong, for example a missing --amount or an invalid --callback-url. |
3 | Credentials are missing or wrong, or the Client App has no PPR access. |
4 | The sandbox couldn't be reached, had an internal error, or the outcome is unknown. |
JSON output
With --json, every command prints exactly one JSON object and nothing else. ok is true only when the exit code is 0. Errors include an error object with a code and a message.
json
When ppr test fails, outcome is "fail" and step says where: create, pay or webhook. The reference and payment ID are included when they are known. In JSON, attempt times (at) are in UTC.