Quick start

Run these in order after you have a sandbox key (vbk_test_…).

export BASE_URL="https://viban-api.enovipay.com"
export KEY_ID="vbk_test_…"
export SECRET="…"

# 1. Accounts — use id as sourceAccountId, and as accountId on a declaration
curl -sS -u "$KEY_ID:$SECRET" "$BASE_URL/v1/accounts"

# 2. Balance
curl -sS -u "$KEY_ID:$SECRET" "$BASE_URL/v1/balance"

# 3. Recent credits
curl -sS -u "$KEY_ID:$SECRET" \
  "$BASE_URL/v1/transactions?limit=20&direction=incoming"

# 4. Webhook (store signingSecret from this response)
curl -sS -u "$KEY_ID:$SECRET" -X PUT "$BASE_URL/v1/webhook" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://merchant.example.com/webhooks","enabled":true}'

# 5. Save a customer; keep customerId from the response
curl -sS -u "$KEY_ID:$SECRET" -X POST "$BASE_URL/v1/customers" \
  -H "Content-Type: application/json" \
  -d '{
    "fullName": "Acme GmbH",
    "rail": "swift",
    "iban": "DE89370400440532013000",
    "swiftCode": "COBADEFFXXX",
    "entityType": "business",
    "currency": "EUR",
    "addressCountryCode": "DE",
    "addressLine1": "Hauptstrasse 1",
    "customerReference": "SUP-DE-007"
  }'

# 6. Declare the deposit you expect, on the vIBAN from step 1
curl -sS -u "$KEY_ID:$SECRET" -X POST "$BASE_URL/v1/deposits" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 500.00,
    "currency": "EUR",
    "accountId": "ACCOUNT_UUID",
    "customer": {
      "customerReference": "CRM-42",
      "fullName": "Layla Haddad",
      "iban": "AE070331234567890123456"
    },
    "externalReference": "INV-2026-0042",
    "idempotencyKey": "dep-inv-2026-0042"
  }'

# 7. Payout to the customer from step 5. A new idempotencyKey for every distinct transfer.
curl -sS -u "$KEY_ID:$SECRET" -X POST "$BASE_URL/v1/payouts" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceAccountId": "ACCOUNT_UUID",
    "amount": 1250.00,
    "currency": "EUR",
    "purpose": "goods_sold",
    "externalReference": "INV-2026-0417",
    "idempotencyKey": "inv-2026-0417-eur",
    "customer": { "customerId": "CUSTOMER_UUID", "customerReference": "SUP-DE-007" }
  }'

Send exactly one of accountId or receivingIban on a declaration. The payee of a payout goes in a customer object, by id or written out, and carries your own customerReference. While a declaration is open it also appears on GET /v1/transactions as a pending incoming line.


Did this page help you?