CanadaCanada API Reference (Merchant Server)Canada API Reference (Merchant Server)
All endpoints use HMAC authentication on https://api.transacty.ai. Live API keys
only — a test key returns 503 payment_unavailable. The canada market must
be approved (and KYC verified) or /v1/cad/* returns 403 market_not_enabled.
Settlement currency is CAD. There is no FX swap to USDC/USDT on this rail.
Collect
| Method | Path | Scope | Purpose |
|---|---|---|---|
POST | /v1/cad/collects | payin:create | Create Interac collect. Show paymentInstructions (Interac email: no outbound payment email). Idempotency-Key required |
GET | /v1/cad/collects/:transactionId | payin:create | Get collect status |
Payout
| Method | Path | Scope | Purpose |
|---|---|---|---|
GET | /v1/cad/institutions | payout:create | List banks — use items[].identifier as institutionIdentifier (not a 3-digit institution number) |
POST | /v1/cad/verify-bank | payout:create | Optional bank verify (institutionIdentifier, accountNumber, sortCode) |
GET | /v1/cad/bills/search | payout:create | Search billers (?query=) |
POST | /v1/cad/payouts | payout:create | Create CAD payout (rail: bank | interac_email | bill). Idempotency-Key required |
GET | /v1/cad/payouts/:transactionId | payout:create | Get payout status |
Shared read endpoints
| Method | Path | Notes |
|---|---|---|
GET | /v1/transactions | Filter type=payin|payout only; then filter rail === "canada" in your app |
GET | /v1/transactions/:transactionId | Status poll; same rail fields |
GET | /v1/balance | Read items[] — Canada is CAD |
PATCH | /v1/me/webhook | Register the URL for Transacty → merchant events |
Settlement
- Collect credits the CAD wallet when the deposit is credited (
settled: true). - Payouts debit CAD immediately and send CAD via bank, Interac email, or bill pay.
CADis a separate wallet pocket. CAD payouts cannot spendUSDC,PYUSD-USDC, orNGN.- Limits: 1–50,000 CAD for collect and payout.
Webhook events
When configured, Transacty sends payin.completed / payin.failed and
payout.completed / payout.failed. Payload currency for CAD money movements is
CAD. The same webhook URL serves all rails. See Webhooks.
Common errors
| HTTP | Meaning |
|---|---|
| 400 | Validation (amount, phone, missing beneficiary) or insufficient CAD |
| 401 | Missing/invalid HMAC |
| 403 | Missing scope, KYC, or canada market not approved |
| 503 | payment_unavailable — live-only rail, provider not configured, or circuit open |
Body often includes { "error", "message", "code?" }. Prefer code when present.
Last updated on