Versine API for AI assistants
Última actualización: November 9, 2026
Este documento solo está disponible en inglés.
The Versine API lets an AI assistant check a user’s balance, find their contacts and prepare payments for them over plain HTTPS.
The API never moves money by itself. A payment created through it is a draft that waits in the user’s Versine app. Nothing is sent until the user reviews it and approves it on their own phone. If they decline it or let it expire, nothing moves.
1. How payments work
- The user asks their assistant to pay someone, for example “Pay Maya $24 for dinner.”
- The assistant checks the person and amount with the user, then calls
POST /transfers. Versine saves the payment as a draft and answersapproval_required. No money has moved. - The draft appears in the user’s Versine app with who it’s for and how much. The user approves it with their passkey on their own device, or declines it.
- Only after the user approves the draft does Versine send it. The assistant can check where it stands with
GET /transfers/{id}.
The assistant never holds the user’s passkey and can’t approve anything itself. A draft the user doesn’t approve expires on its own, at the time given in expires_at.
2. Get an API key
- In the Versine app, open Agents and add your assistant, or Custom if it isn’t listed.
- Choose what the assistant may do (section 4), then allow it.
- Copy the setup prompt the app shows and paste it into a new conversation with your assistant. It has the API key and tells the assistant how to use Versine. An assistant with its own vault (Instinct) sends you a secure link instead: paste the API key there, never in the chat.
- Once it has the key, the assistant calls
GET /connectionright away. That first call checks the key and is what shows the assistant as connected in the app.
Each key belongs to one assistant and does only what you allowed it. To stop an assistant, open it on the Agents page and tap Disconnect: its key stops working at once.
3. Making requests
- Base URL.
https://api.versine.com/v1/assistant - Authentication. Send the key on every request as
Authorization: Bearer <key>. Assistants registered with Versine can sign in with OAuth 2.0 instead, as the OpenAPI document describes. - Idempotency. Every
POSTneeds anIdempotency-Keyheader (8 to 255 characters). Repeating a payment, request or schedule with the same key returns the first result instead of creating a second one. For payments, a key holds for 10 minutes. OtherPOSTs don’t replay: a repeatedPOST /scheduled-payments/{id}/pausepauses the schedule again, even if the user resumed it. - Amounts. Strings in US dollars, like
"24.00". - Results. A draft waiting for the user, or a payment Versine refused, is a normal
200result: read itsstatus. Errors areapplication/problem+jsonwith acodeand adetailthat says what to do. - OpenAPI. The full schema of every request and response is at
https://api.versine.com/v1/assistant/openapi.json, no key needed.
Creating a payment for a contact:
POST /v1/assistant/transfers HTTP/1.1
Host: api.versine.com
Authorization: Bearer <your API key>
Idempotency-Key: <a new key for each payment>
Content-Type: application/json
{"contact_id": "3b1e9c40-…", "amount": "24.00"}The answer: a draft waiting for the user, with nothing sent.
{
"status": "approval_required",
"payment_id": "a1f0c9e2-…",
"recipient": {"name": "Maya R.", "on_versine": true},
"amount": "24.00",
"approval_id": "5d7e1b44-…",
"expires_at": "2026-11-05T18:40:00Z",
"code": "needs_approval",
"hint": "The user must approve this in the Versine app before any money moves. Check on it with get_status and its payment_id."
}4. What an assistant may do
Each assistant gets only the permissions the user gives it, and the user can change them at any time on the Agents page of the Versine app. An assistant can never change its own permissions. GET /connection shows what it may do and the account’s limits.
| Permission | What it allows |
|---|---|
| See the balance | Read what the user can spend now. |
| See past activity | Read the user’s payments and requests, and where each stands. |
| See contacts | Find and add people in the user’s Versine contacts. |
| Send money to Versine members | Create payment drafts for people on Versine, which the user approves in the Versine app. |
| Send money to people not on Versine | Create payment drafts for people who aren’t on Versine yet. Once the user approves, they get a link to claim the money. Also sends the user’s Versine gifts. |
| Request money | Ask Versine members to pay the user, now or on a schedule. |
| Set up routines | Propose scheduled payments, which the user sets up in the app, and pause them. |
5. Endpoints
Paths are relative to the base URL. An assistant without the permission an endpoint needs gets a 403 that says so.
| Endpoint | What it does | Permission |
|---|---|---|
GET /balance | Shows what the user can spend now. | See the balance |
GET /connection | Shows what the assistant may do and the account’s limits. | None |
GET /activity | Lists recent payments and requests and where each stands. | See past activity |
GET /connection/activity | Lists what this assistant did, and whether each was allowed, waited for the user or was refused. | None |
GET /contacts | Lists the user’s contacts, with the IDs used to pay them. | See contacts |
GET /contacts/find | Finds a contact by name, phone or email. | See contacts |
POST /contacts | Saves someone to the user’s contacts. | See contacts, and Send money or Request money |
POST /contacts/{id}/update | Saves a US mobile number for a contact who isn’t on Versine, so they can be paid. | See contacts, and Send money or Request money |
POST /transfers | Creates a payment draft for one person, for the user to approve. | Send money to Versine members (and to people not on Versine, for them) |
POST /transfer-groups | Creates payment drafts for several people at once, which the user approves together. Also sends the user’s Versine gifts (section 7). | Send money to Versine members (and to people not on Versine, for them) |
GET /transfers/{id} | Shows where one payment stands. | None (its own payments) |
GET /gifts | Shows the user’s Versine gift credit, how many gifts are left and the gifts they sent. | Send money to people not on Versine |
POST /requests | Asks a Versine member to pay the user. | Request money |
POST /request-groups | Asks several Versine members to pay the user at once. | Request money |
GET /request-approvals/{id} | Shows what the user decided on a request that waited for them. | None |
POST /requests/{id}/cancel | Cancels a request this assistant sent that nobody has paid. | Request money |
POST /request-schedules | Asks one or more people later, or on repeat. Versine sends each request when it’s due. | Request money |
GET /request-schedules | Lists the user’s scheduled requests. | Request money |
POST /request-schedules/{id}/stop | Stops a scheduled request this assistant made. | Request money |
GET /scheduled-payments | Lists the user’s scheduled payments, and the ones this assistant proposed. | Set up routines |
POST /scheduled-payments | Proposes a payment at a later time or on a schedule. The user reviews it and sets it up in the app. | Set up routines (and Send money to Versine members, to pay a person) |
POST /scheduled-payments/{id}/pause | Pauses a scheduled payment. Only the user can resume or stop it, in the app. | Set up routines |
POST /feedback | Tells the Versine team what was hard or missing. | None |
6. Payment statuses
POST /transfers and POST /transfer-groups answer with a status for each payment:
| Status | Meaning |
|---|---|
approval_required | A draft. Nothing has moved; it waits for the user to approve it in the Versine app. Groups say in_approval. |
denied | Versine refused it and nothing moved. code says why, for example a limit or a recipient who can’t be paid. |
failed | It couldn’t be paid and nothing moved. |
After the user acts, GET /transfers/{id} shows awaiting_approval while it still waits, pending once the user approved it and it’s on its way, then completed. A draft the user turned down or let expire shows declined or expired.
7. Gifts
Some users have gift credit from Versine to send friends who aren’t on Versine yet. A gift is paid with Versine’s money, never the user’s. GET /gifts shows whether the user can send one, the exact gift_amount, how many are left and the gifts they’ve sent.
To send gifts, call POST /transfer-groups with one item per friend, each with gift: true and no amount (it’s then gift_amount), even for a single friend. An item with gift: true is only ever a gift: if it can’t be one, nothing in the group is sent from the user’s money, and its gift_fallback says why. POST /transfers never sends a gift: it pays from the user’s own money. Each item’s paid_as says whether it went as a gift or a payment, and gift_fallback says why one that could have been a gift wasn’t. Versine texts each friend. The gift reaches them once they join Versine with that number, verify their identity, connect an agent and import their contacts.
8. Guidelines for assistants
- Confirm first. Before creating a payment or a request, tell the user who it’s for and how much, and wait for their yes.
- Say what happened. When the answer is
approval_required, tell the user the payment is waiting for them in the Versine app. Don’t say it was sent. Reportpendingas on its way andcompletedas paid. - Don’t pay twice. Use a new
Idempotency-Keyfor each payment and the same key to retry one. If a call is interrupted, checkGET /transfers/{id}orGET /connection/activitybefore trying again. - Ask for more, don’t work around it. If the assistant needs a permission it doesn’t have, tell the user. Only they can allow it, on the Agents page of the Versine app.
- Keep the key private. Never show it, or put it in a message, file or link.
9. Privacy
An assistant sees only what its permissions allow, and never the user’s contacts’ phone numbers or email addresses. Our Privacy Policy explains what we collect, and our Terms of Service apply to payments made through the API.
10. Help
Email support@versine.com.