Enter at least two characters to search. Searching documentation… No matching sections. Try an endpoint, field or event name.

Authentication

View as Markdown

Every request to /v1 needs an API key. Owners and admins create them under Developers → API keys in the dashboard, which asks for a second factor (a passkey or an authenticator app) and your password. Keys belong to one account, your personal one or an organization, and act on its behalf. Send it as a bearer token. Keys are shown once, so store them somewhere safe and revoke them if they leak. A key with the api_keys:write permission can also make, change and revoke keys through the API.

On this page
GET /v1/charges

Copy failed. Select the code and copy it manually.

curl 'https://api.velirapay.com/v1/charges' \
  --fail-with-body --silent --show-error --max-time 30 \
  -H "Authorization: Bearer ${VELIRAPAY_API_KEY:?Set VELIRAPAY_API_KEY}" \
  -H 'Accept: application/json'

A missing, revoked or unknown key answers with 401 and {"message": "Invalid API key. Pass a live or test key as a bearer token."}. A key made before keys carried their mode in their prefix answers 401 too, with "This API key does not say which mode it works in. Create a new one."

Live keys and test keys

Every account has two modes, and the key you present is what picks one. A key starting with vp_live_ works in live mode, where the coins are real. A key starting with vp_test_ works in test mode, where the same endpoints run against the test networks and nothing is worth anything. Either prefix is followed by 40 letters and digits.

The two modes share nothing. Objects are created in the mode of the key that made them and are only ever listed to that mode; asking a live key for a test charge, payment link, invoice or event answers 404, exactly as if it did not exist, and the other way round. Deposit addresses are derived separately per mode, so a test payment can never land where real money is held.

To make a key of a mode, switch the dashboard to that mode with the live and test toggle at the top of the page and create the key there. Test mode needs a payout address of its own, which is set on the payment settings page while in test mode. BNB Chain has no test mode, so its coins can only be used with a live key.

No test coins at hand? POST /v1/charges/{id}/simulate, or the Simulate payment button on a test charge's page in the dashboard, pays it without any, in full or by a chosen amount. It records a transfer that is already confirmed, so charge.paid or charge.underpaid and the emails go out as for a real payment, but charge.payment_detected does not. The transfer's txid starts with simulated- and has no explorer_url, and no settlement or payout is written, because no coins moved.

GET /v1/charges Test mode

Copy failed. Select the code and copy it manually.

curl 'https://api.velirapay.com/v1/charges' \
  --fail-with-body --silent --show-error --max-time 30 \
  -H "Authorization: Bearer ${VELIRAPAY_API_KEY:?Set VELIRAPAY_API_KEY}" \
  -H 'Accept: application/json'

# Use a vp_test_ API key for this request.

GET /v1/account reports which mode the key is in under meta.mode, so a client can show what it is working with.

Which account is this key for?

GET /v1/account describes the account behind the key: whether it is a personal account or an organization, its public profile (display name, logo, website, support email and phone, brand color), its business details, the default currency, the payment tolerances and, under meta.accepted_assets, the coins it has a wallet for.

See the account endpoint and a full response

Restricted keys

A key has full access unless you restrict it, by ticking the permissions it gets when you create it or edit it later. A restricted key can only call the endpoints and use the MCP tools its permissions cover, so a key that leaks is worth far less: a server that creates charges and reads them back needs charges:write and charges:read, and nothing else. Every key, restricted or not, can call GET /v1/account and GET /v1/assets.

Writing does not include reading: a key with charges:write but not charges:read can create a charge and is answered with it, but cannot list or retrieve charges. Accepting a charge as paid and recording a refund are permissions of their own, apart from charges:write. Events carry the charges and invoices they are about, customers included, so events:read reads those too.

Permission Endpoints MCP tools
charges:read GET /v1/charges, GET /v1/charges/{id} list_charges
charges:write POST /v1/charges, POST /v1/charges/{id}/send, POST /v1/charges/{id}/cancel, POST /v1/charges/{id}/simulate create_charge, send_charge, cancel_charge, simulate_payment
charges:accept POST /v1/charges/{id}/accept accept_charge
charges:refund POST /v1/charges/{id}/refunds record_refund
invoices:read GET /v1/invoices, GET /v1/invoices/{id} list_invoices
invoices:write POST /v1/invoices, POST /v1/invoices/{id}/send, POST /v1/invoices/{id}/void create_invoice, send_invoice, void_invoice
payment_links:read GET /v1/payment-links, GET /v1/payment-links/{id} list_payment_links
payment_links:write POST /v1/payment-links, PATCH /v1/payment-links/{id}, POST /v1/payment-links/{id}/archive, DELETE /v1/payment-links/{id}/archive create_payment_link, update_payment_link
coupons:read GET /v1/coupons, GET /v1/coupons/{code} list_coupons
coupons:write POST /v1/coupons, PATCH /v1/coupons/{code}, DELETE /v1/coupons/{code} create_coupon, update_coupon, delete_coupon
payouts:read GET /v1/payouts, GET /v1/payouts/summary, GET /v1/payouts/{id} list_payouts, get_payout_summary
events:read GET /v1/events, GET /v1/events/{id} list_events
webhook_endpoints:read GET /v1/webhook-endpoints, GET /v1/webhook-endpoints/{id}, GET /v1/webhook-endpoints/{id}/deliveries list_webhook_endpoints, list_webhook_deliveries
overview:read GET /v1/overview get_overview
payout_addresses:read GET /v1/payout-addresses list_payout_addresses
activity:read GET /v1/activity list_activity
account:write PATCH /v1/account update_account
payment_settings:write PATCH /v1/payment-settings update_payment_settings
payout_addresses:write PUT /v1/payout-addresses/{id}, DELETE /v1/payout-addresses/{id} set_payout_address, remove_payout_address
webhook_endpoints:write POST /v1/webhook-endpoints, PATCH /v1/webhook-endpoints/{id}, DELETE /v1/webhook-endpoints/{id}, POST /v1/webhook-endpoints/{id}/verify, POST /v1/webhook-endpoints/{id}/test, POST /v1/webhook-endpoints/{id}/secret, POST /v1/webhook-endpoints/{id}/deliveries/{id}/retry create_webhook_endpoint, update_webhook_endpoint, delete_webhook_endpoint, verify_webhook_endpoint, send_test_webhook, rotate_webhook_secret, retry_webhook_delivery
api_keys:read GET /v1/api-keys list_api_keys
api_keys:write POST /v1/api-keys, PATCH /v1/api-keys/{id}, DELETE /v1/api-keys/{id} create_api_key, update_api_key, revoke_api_key
members:read GET /v1/members, GET /v1/invitations list_members, list_invitations
members:write PATCH /v1/members/{id}, DELETE /v1/members/{id}, POST /v1/invitations, DELETE /v1/invitations/{id} update_member_role, remove_member, invite_member, cancel_invitation
billing:write POST /v1/billing/pro start_pro_payment

A request the key's permissions do not cover answers 403 with the permission it lacks, {"message": "This API key does not have the charges:write permission."}, before the object or the fields it names are looked at. Over the MCP server every tool stays listed, and one the key may not use answers with the same message as its error, before it looks at its arguments, adding which tool needs the permission and that an owner or admin can add it. Keys made before keys could be restricted have full access. An owner or admin can change a key's permissions at any time from the API keys page of the dashboard, or a key with api_keys:write through the API: the key itself stays the same, and the change applies from its next request.

Sensitive permissions

Some permissions reach what a leaked key should never reach, so full access leaves them out: activity:read, account:write, payment_settings:write, payout_addresses:write, webhook_endpoints:write, api_keys:read, api_keys:write, members:read, members:write. A key only has one when it is restricted and the permission is ticked on it, which is also why no key made before they existed has any. A sensitive permission also only works while the person who made the key is still an owner or admin of the account; otherwise the request answers 403, saying so.

Allowed IP addresses

A key, restricted or not, can also be limited to the addresses it is used from: up to 20 IPv4 or IPv6 addresses, each a single one such as 203.0.113.7 or a range such as 203.0.113.0/24 or 2001:db8::/32. A request from any other address answers 403 with the address it came from, {"message": "This API key cannot be used from 198.51.100.4."}, which is the one to allow if it is yours. A key with no addresses can be used from anywhere. Its addresses can be changed later, the same way as its permissions.

Rate limits

Each key may make 120 requests per minute, and each IP address 600 across all keys; a request without a key counts against 120 per minute for its IP address. Every response carries X-RateLimit-Limit and X-RateLimit-Remaining for whichever of those limits has the fewest requests left. Going over answers with 429 and a Retry-After header saying how many seconds to wait. MCP server requests count towards the same limits.