Versine API for AI assistants

Last updated: November 5, 2026

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 answers approval_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.

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 POST needs an Idempotency-Key header (8 to 255 characters). Repeating a request with the same key returns the first result instead of creating a second draft. For payments, a key holds for 10 minutes. Two requests don’t replay: a repeated POST /permission-requests files a new request that replaces the open one, and a repeated POST /scheduled-payments/{id}/pause pauses 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 200 result: read its status. Errors are application/problem+json with a code and a detail that 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:

Request

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.

Response

{
  "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.
Request money	Ask Versine members to pay the user.
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.	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 /payment-methods`	Lists the user’s saved cards and banks, so a draft can name one to cover a short balance.	Send money to Versine members
`POST /requests`	Asks a Versine member to pay the user.	Request money
`POST /requests/{id}/cancel`	Cancels a request this assistant sent that nobody has paid.	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 /permission-requests`	Asks the user in the Versine app to allow the assistant more. Only the user can approve it.	None
`GET /permission-requests/{id}`	Shows whether the user approved a permission request.	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. 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. Report pending as on its way and completed as paid.
Don’t pay twice. Use a new Idempotency-Key for each payment and the same key to retry one. If a call is interrupted, check GET /transfers/{id} or GET /connection/activity before trying again.
Ask for more, don’t work around it. If the assistant needs a permission it doesn’t have, call POST /permission-requests and let the user decide.
Keep the key private. Never show it, or put it in a message, file or link.

8. 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.

9. Help

Email support@versine.com.