API errors
| HTTP status | Meaning |
|---|---|
400 | Invalid request body or business rule violation |
401 | Missing or invalid API key |
404 | Payment or resource not found |
Payment statuses
| Status | Description |
|---|---|
pending | Awaiting customer payment |
completed | Verified on Horizon |
failed | Transaction failed or verification rejected |
expired | Past expires_at without completion |
Stellar network errors
op_no_trust
Cause: Missing USDC trustline on the customer or merchant wallet.
Fix: Add a trustline to the correct USDC issuer for your network. See Settlement wallet.
op_underfunded
Cause: Wallet balance is too low for the payment amount plus fees.
Fix: Fund the wallet with enough XLM or USDC.
op_line_full
Cause: Destination trustline limit reached.
Fix: Increase the trustline limit on the receiving account.
Issuer is invalid
Cause:STELLAR_*_USDC_ISSUER environment variable is missing or incorrect on the Payoes server.
Fix: Set the correct Circle USDC issuer for testnet or mainnet in your deployment environment.
Verification errors
| Error | Cause |
|---|---|
| Payment operation not found | No matching payment op in the transaction |
| Payment was sent to a different address | Destination does not match settlement wallet |
| Payment amount does not match | Amount differs from the payment record |
| Payment asset does not match | Wrong asset type or issuer |
| Transaction was not successful | Transaction failed on Stellar |
2 equals 2.0000000).
Getting help
- Check the transaction on Stellar Expert for the correct network
- Review Developers → API Logs for request details
- Confirm settlement wallet and trustlines are configured for the payment asset