IZI Pay CLI
The IZI Pay CLI is a small command-line program for testing your Payment by Reference (PPR) integration in the sandbox. With a few commands you can:
- create a MULTICAIXA payment reference;
- simulate a customer paying it, as if they paid at an ATM or in their banking app;
- check that your application received and accepted the payment webhook.
The command izipay ppr test does all three in one go and answers PASS or FAIL, so you can also use it in automated tests.
Sandbox only
The CLI only works with the sandbox (https://pay-sandbox.izipay.ao). No real money moves and nothing reaches production.
Before you start
You need:
- Sandbox credentials. IZI Pay creates your sandbox merchant and a Client App for it, and sends you its Client ID and Client Secret. The Client App is enabled for payment references. If you don't have them yet, contact IZI Pay support.
- A webhook address, so the sandbox can notify your application when a reference is paid. It must be reachable from the internet, for example
https://your-app.example.com/webhooks/izipay. For a first try you can use a free request inspector such as webhook.site. See Testing webhooks. - A supported computer:
- macOS on Apple silicon or Intel;
- Windows 10 or 11, 64-bit;
- Linux on x64 with glibc 2.27 or newer (for example Ubuntu 18.04 or later, Debian 10 or later).
You don't need .NET, Node.js or any other runtime. The CLI is a single program.
Install
macOS and Linux
Open a terminal and run:
bash
The installer downloads the right program for your computer, checks its checksum and puts it in ~/.local/bin. It doesn't need an administrator password. If that folder isn't in your PATH yet, the installer shows the line to add.
Windows
Open PowerShell and run:
text
The command above only works in PowerShell. In Command Prompt (cmd.exe), run this instead:
text
This only matters for installing. Once installed, izipay works the same in Command Prompt, PowerShell and Windows Terminal.
The installer puts izipay.exe in %LOCALAPPDATA%\Programs\IziPay and adds that folder to your user PATH. Open a new terminal afterwards so the izipay command is found.
Check the installation
bash
Manual download
If you prefer not to run an install script, download the file for your system, check it against SHA256SUMS.txt and put the izipay program somewhere in your PATH:
| System | File |
|---|---|
| macOS, Apple silicon | izipay-osx-arm64.tar.gz |
| macOS, Intel | izipay-osx-x64.tar.gz |
| Linux, x64 | izipay-linux-x64.tar.gz |
| Windows, 64-bit | izipay-win-x64.zip |
Security warning after a manual download
Files downloaded with a web browser are marked by the operating system. On macOS, if you see "cannot be opened because the developer cannot be verified", run xattr -d com.apple.quarantine ./izipay once. On Windows, right-click izipay.exe, choose Properties and tick Unblock. The install commands above don't trigger this warning.
Your first test
1. Log in
bash
Enter the Client ID and Client Secret that IZI Pay sent you. The secret isn't shown while you type. The CLI checks them with the sandbox and saves them in your system's credential store: macOS Keychain, Windows Credential Manager or the Linux keyring.
2. Check your access
bash
text
3. Create a reference
bash
text
4. Simulate the payment
bash
text
The amount must be exactly the amount of the reference, just like a real MULTICAIXA payment. Try a different amount to see the error your customers' banks would get.
5. Check the webhook
bash
text
The webhook counts as accepted only when your application answers HTTP 2xx with JSON {"Success": true}. See Testing webhooks.
All in one: ppr test
bash
text
Every option is explained in the command reference.
Use it in CI
In a pipeline, don't run izipay login. Store the Client ID and secret in your CI system's secret variables and expose them as IZIPAY_CLIENT_ID and IZIPAY_CLIENT_SECRET. Then use --json for output that scripts can read. The exit code is 0 only when the test passes.
yaml
Never write the Client Secret in a pipeline file, a script or your repository. Use your CI system's protected or masked variables.
Update and uninstall
To update, run the install command again. It replaces the program with the latest version.
To uninstall:
- Run
izipay logoutto remove the saved credentials. - Delete the program:
- macOS and Linux:
rm ~/.local/bin/izipay - Windows: delete the folder
%LOCALAPPDATA%\Programs\IziPayand remove it from your userPATH.
- macOS and Linux:
Your credentials
izipay loginkeeps the Client ID and secret in your system's credential store, never in a plain file.- The CLI never prints the Client Secret or the access token.
- When
IZIPAY_CLIENT_IDandIZIPAY_CLIENT_SECRETare both set, they are used instead of the saved login. izipay logoutremoves the saved credentials and is safe to run more than once.