Skip to main content
Vereist een Silver-lidmaatschap of hoger — zowel om je aan te melden als voor elke geauthenticeerde aanroep. Verloopt het lidmaatschap van de sleutelhouder, dan wordt het project bevroren tot hij zich opnieuw abonneert.
Een REST-API waarmee je applicatie vanuit Discord met het Vito-saldo van een gebruiker werkt: uitlezen, afschrijven, bijschrijven of tussen gebruikers verplaatsen. Alle endpoints geven JSON terug en zijn geversioneerd onder /v1.
Vito wordt nooit omgezet in echt geld, en komt er ook nooit uit voort. Het beweegt uitsluitend tussen Vetox-saldi.

Toegang krijgen

Toegang wordt per project verleend. Je hebt alle vier nodig:
1

Een actief lidmaatschap, Silver of hoger

Wordt bij elke aanroep gecontroleerd, niet alleen bij goedkeuring.
2

Een goedgekeurde ontwikkelaarsaanvraag

Ingediend via de Vito API-pagina in je dashboard. Wordt handmatig beoordeeld door het Vetox-team.
3

Geaccepteerde API-ontwikkelaarsvoorwaarden

Worden bevestigd bij het indienen van de aanvraag.
4

De scopes die je project nodig heeft

Worden door het Vetox-team toegekend op basis van je beschrijving.
Wees concreet over wat je bouwt en hoe je de sleutel opslaat. Het zijn de vage aanvragen die worden afgewezen.

Scopes

Authenticatie

Stuur je geheime sleutel mee als Bearer-token:
Twee optionele lagen maken een project extra robuust:
  • IP-allowlist — beperk aanroepen tot specifieke server-IP’s
  • Rate limits — plafonds per project die meeschalen met het lidmaatschapsniveau van de houder

Sleutels, rotatie en opslag

Je sleutel en signing secret worden precies één keer getoond. Na goedkeuring heb je een venster van 7 dagen om ze te onthullen op het tabblad met API-sleutels. Vetox bewaart alleen een hash en kan ze niet opnieuw tonen — mis je het venster, dan moet je roteren.
  • Houd hem uitsluitend serverzijdig — wie hem heeft, kan je gebruikers afschrijven
  • Roteer via het tabblad met API-sleutels. De vorige sleutel blijft nog 24 uur werken als overgangsperiode, zodat je zonder downtime kunt uitrollen
  • Het webhook-signing-secret roteert apart, met een eigen overlap van 24 uur
  • Bij een lek: onmiddellijk roteren

Een gebruiker afschrijven

Je sleutel alleen kan het Vito van een gebruiker niet verplaatsen. Elke afschrijving vereist dat de gebruiker akkoord gaat met de pincode van zijn wallet, op vetox.io — nooit in je app en nooit in Discord.
1

Je app roept POST /v1/deduct aan

Met de gebruiker, het bedrag, de guildId van herkomst en de artikelgegevens.
2

Vito geeft een confirmUrl terug

Een openstaande bevestiging, 10 minuten geldig. De gebruiker krijgt ook een DM.
3

De gebruiker keurt goed met zijn pincode

Op vetox.io.
4

Vito verrekent en meldt

Het saldo wordt afgeschreven, de transactie vastgelegd en er wordt een ondertekende webhook verstuurd als je er een hebt ingesteld.
5

Je app verifieert en rondt af

Controleer de handtekening en ontgrendel dan de content of lever het artikel.
Rond je actie uitsluitend af bij confirmation.completed — nooit op basis van het antwoord van /deduct. Op dat moment staat de afschrijving nog niet vast.

Requestparameters — /v1/deduct

Een gebruiker bijschrijven

POST /v1/add schrijft Vito bij een gebruiker bij uit je eigen saldo — voor beloningen of terugbetalingen. Dezelfde velden als /deduct, behalve guildId en product.
Anders dan een afschrijving heeft een bijschrijving geen bevestigingsstap: die wordt direct verrekend. Vereist de scope credit:create en voldoende saldo, anders geeft de aanroep 402 VITO_INSUFFICIENT_OWNER_FUNDS terug.

Kosten

Elke afschrijving wordt aan jou uitbetaald minus de platformkosten — hetzelfde schema als Vito-overboekingen in de app, op basis van jouw lidmaatschapsniveau:
Bedragen van 5 Vito of minder zijn kosteloos, en bijschrijvingen via /v1/add zijn dat altijd.

Webhooks

Voeg op het tabblad met instellingen een of meer https-callback-URL’s toe. Vito stuurt een ondertekende POST zodra een bevestiging een eindtoestand bereikt.
Webhooks worden alleen verstuurd als je project zowel een callback-URL als een signing secret heeft. Onthul het secret (whsec_…) eenmalig op het tabblad met API-sleutels.

De handtekening verifiëren

Elke aflevering draagt een X-Vito-Signature-header:
Twee andere headers vergezellen elke aflevering — gebruik X-Vito-Event-Id als deduplicatiesleutel, want een nieuwe poging stuurt hetzelfde id opnieuw:
Tijdens een rotatie van het signing secret bevat de header meer dan één handtekening, de nieuwste eerst:
Accepteer de aflevering als een willekeurige h1 klopt. Een verifier die alleen de eerste leest, wijst elke webhook af totdat het nieuwe secret is uitgerold — precies wat de overlap van 24 uur moest voorkomen.
Herbereken de HMAC over <ts>:<rawBody> met je signing secret en vergelijk in constante tijd.
Verifieer tegen de ruwe body, vóór JSON-parsing of middleware die hem herschrijft.

Gebeurtenissen

Vijf gebeurtenistypen, allemaal met dezelfde payloadstructuur. data.status bevat de uitkomst.
Webhooks worden 5 keer met backoff opnieuw geprobeerd. Bevestig snel met een 2xx en doe je afhandeling asynchroon.

Foutcodes

Elk antwoord zit in een envelope. Een succes bevat data, een fout bevat error — nooit allebei:
Elke code begint met VITO_. Vergelijk de volledige string — een kale RATE_LIMITED of FORBIDDEN komt nooit over de lijn.

Rate limits

Er geldt ook een limiet per IP van de helft van je minuutquotum, met een ondergrens van 30.
Onder belasting falen schrijf-endpoints gesloten — een afschrijving wordt geweigerd in plaats van dubbele besteding te riskeren. Lees-endpoints falen open. Behandel een geweigerde schrijfactie als “niet gebeurd” en probeer opnieuw.
Stuur een Idempotency-Key-header mee om herhaalde pogingen veilig te dedupliceren.

Endpoints

Limieten

  • Bevestigingen verlopen na 10 minuten — beschouw niet-bevestigde verzoeken als afgebroken
  • amount moet een positief geheel getal zijn
  • metadata is beperkt tot 10 sleutels
  • Limieten per transactie en per dag worden door het Vetox-team ingesteld en staan alleen-lezen op het tabblad met instellingen

Beveiligingschecklist

De API-sleutel en het signing secret horen nooit in clientcode. Roteer meteen als er een lekt.
Controleer de handtekening tegen de ruwe body en weiger afleveringen ouder dan ~5 minuten.
Lever nooit op basis van het /deduct-antwoord — de afschrijving staat pas vast bij confirmation.completed.
Vraag alleen de scopes aan die je echt gebruikt, en zet de IP-allowlist aan.

Problemen oplossen

Het lidmaatschap van de houder is verlopen. Het wordt bij elke aanroep opnieuw gecontroleerd.
Die is niet terug te halen — er wordt alleen een hash bewaard. Roteer voor een nieuwe.
Accepteer beide secrets tijdens de overlap van 24 uur.
De gebruiker heeft niet goedgekeurd. Bevestigingen verlopen na 10 minuten.
Een project heeft zowel een callback-URL als een signing secret nodig. Met maar één van beide wordt er niets afgeleverd.
Dat zijn de verrekeningskosten. Gebruik bedragen van 5 Vito of minder om ze te vermijden, of reken ze door.
/v1/add wordt uit je eigen saldo gefinancierd, niet uit het niets gemaakt. Vul aan.

Vito

Saldi, de pincode en kosten.

Betaalverzoeken

Wat de gebruiker ziet wanneer je hem afschrijft.