Authentication

Credentials

Mint keys from the dashboard Settings → Security page (GET/POST/DELETE /merchant/api-credentials, cookie session). Enovipay ops can also issue or revoke on your behalf. There is no credential signup on /v1.

PieceRoleFormat
Key idHTTP Basic usernamevbk_test_… (sandbox) or vbk_live_… (production)
SecretHTTP Basic passwordshown once at issue time

Only a hash of the secret is stored. If it is lost, issue a new credential from Settings → Security (or ask Enovipay) and revoke the old one. Treat the secret like a password: never commit it, never put it in a browser, rotate it if it leaks.

Five consecutive failed authentications lock that credential for 15 minutes. Revocation is permanent.

Who can mint keys

Dashboard teammates need permission to manage API credentials. Owners and members with the Administrator preset (or a custom access matrix that includes manage ApiCredential) can open Settings → Security and issue or revoke keys. A narrower teammate who only holds Finance or Read only cannot mint credentials until someone with manage Team assigns them an access level that includes it.

Minting an unscoped key needs wide grants. A key minted with no scope (scopedRules omitted or null) skips every ability check, declares and reads deposits with nothing withheld, and reads transactions whole. Whoever mints one must hold, without conditions: manage on Account, Payout, Beneficiary (the customers permission) and Webhook; create and read Deposit; and read Transaction with no condition and no withheld field. Anyone short of one of these is refused with 403 ESCALATION_REFUSED and can still mint a scoped key within what they hold.

On the dashboard Team page, managers can start from a shipped preset, save a private access matrix for the company, and assign that access level when inviting a colleague. Those matrices are private to your merchant.

Scoped credentials

A credential can be issued narrower than the merchant that owns it. It cannot be widened afterwards, only replaced. A credential issued without a scope carries the merchant's full set.

A scoped credential is refused 403 ABILITY_DENIED for anything outside its scope. On POST /v1/payouts that refusal lands before the payment is attempted. A scope can also narrow a list: a credential confined to one account sees that account's transactions, and total reflects the same restriction.

Deposits have their own permission. Declaring needs create Deposit and reading declarations needs read Deposit. A Deposit grant can be limited by currency and by amountMax (the largest single declaration, in minor units). Administrator, Finance and Payments clerk can create and read; Read only can read; Support can read without the declared IBAN and name.

Customers are the Beneficiary permission, shown in the dashboard as Customer. A grant can be limited to some customers and to a rail (swift or local). A Payout grant limited to some customers is judged on the id the payout names, so that key must pay by customer.customerId. An inline payout is refused 403 CONDITION_FAILED.

Fields a key can have hidden

A scoped credential can withhold fields from what it reads. A withheld field is absent, not null. A key cannot write, filter or declare by a field it cannot read (403 FIELD_EXCLUDED).

PermissionFields a read rule can withhold
Accountiban, accountNumber, routingNumber, swiftCode
TransactioncounterpartyIban, counterpartyName, reference, customerReference, customerId
Payoutiban, accountNumber, routingNumber, swiftCode, customerReference, customerId
Beneficiary (customers)iban, accountNumber, routingNumber, swiftCode, bankName, customerReference
Depositiban, fullName, customerReference, customerId

accountIban on a transaction is withheld when the account read hides iban.

Base URL and headers

Base URL: https://viban-api.enovipay.com.

Authorization: Basic base64({keyId}:{secret})
Content-Type: application/json
curl -sS -u "$KEY_ID:$SECRET" "$BASE_URL/v1/accounts"

Conventions

  • CSRF is not required.
  • Do not send dashboard JWT cookies.
  • Optional X-Correlation-ID is echoed on the response if you want to thread your logs with ours.
  • Unknown JSON fields are rejected (400).
  • Amounts are major units (for example 1250.00, not 125000). Send numbers on payout and deposit creates; most read responses return decimal strings.
  • Supported currencies: USD, AED, EUR, GBP. The source account currency must match the payout currency. A deposit's currency must match the receiving account.

Did this page help you?