Developer Docs

Getting Started

Welcome to Payyvion! This guide will help you make your first API request and integrate Payyvion into your app.

1. Create an Account

Sign up for a Payyvion account and retrieve your API keys from the dashboard ↗.

2. Make Your First Request

Payyvion provides a RESTful API. You can make requests using any HTTP client. Here’s an example using cURL to create a wallet:

curl https://api.payyvion.com/v1/wallets \
  -X POST \
  -H "Authorization: Bearer sk_live_1234567890abcdef" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Primary Wallet",
    "currency": "eUSD"
  }'

If successful, you’ll receive a response like this:

{
  "id": "wlt_8h3e5f17",
  "name": "Primary Wallet",
  "currency": "eUSD",
  "balance": "0.00",
  "status": "active",
  "created_at": "2024-05-20T10:15:30Z"
}

3. What’s Next?

Explore the docs to learn more about what you can build with Payyvion.

Wallets

A wallet holds a balance in a single currency. Each account can create as many wallets as it needs — one per customer, per currency, or per business unit.

Create a wallet

Pass a display name and the currency the wallet should hold.

curl https://api.payyvion.com/v1/wallets \
  -X POST \
  -H "Authorization: Bearer sk_live_1234567890abcdef" \
  -d '{
    "name": "Payouts Wallet",
    "currency": "eUSD"
  }'

List wallets

Results are paginated, newest first.

{
  "data": [
    {
      "id": "wlt_8h3e5f17",
      "name": "Payouts Wallet",
      "currency": "eUSD",
      "balance": "1240.55",
      "status": "active"
    }
  ],
  "has_more": false
}

Payments

Move eUSD between Payyvion wallets in seconds. Payments settle instantly and are end-to-end encrypted, so amounts stay off the public ledger.

Send a payment

The recipient can be a wallet id or a phone number registered with Payyvion.

curl https://api.payyvion.com/v1/payments \
  -X POST \
  -H "Authorization: Bearer sk_live_1234567890abcdef" \
  -d '{
    "from": "wlt_8h3e5f17",
    "to": "+2348012345678",
    "amount": "25.00",
    "currency": "eUSD",
    "note": "Design work — May"
  }'

{
  "id": "pay_4kd91mz2",
  "status": "completed",
  "amount": "25.00",
  "fee": "0.00256",
  "settled_at": "2024-05-20T10:16:02Z"
}

Fees are flat — $0.00256 per payment, regardless of the amount or destination country.

Invoicing

Create and send invoices that clients can pay in eUSD from anywhere. Every invoice gets a hosted payment link, so your client does not need an API integration.

Create an invoice

Line items are optional — pass a single amount if you prefer.

curl https://api.payyvion.com/v1/invoices \
  -X POST \
  -H "Authorization: Bearer sk_live_1234567890abcdef" \
  -d '{
    "wallet_id": "wlt_8h3e5f17",
    "client_email": "client@example.com",
    "due_date": "2024-06-01",
    "items": [
      { "description": "Landing page design", "amount": "450.00" }
    ]
  }'

{
  "id": "inv_7bq02xd4",
  "number": "INV-0042",
  "status": "draft",
  "total": "450.00",
  "currency": "eUSD",
  "hosted_url": "https://pay.payyvion.com/i/inv_7bq02xd4"
}

Call /v1/invoices/{id}/send to email the invoice and move it from draft to open.

Webhooks

Webhooks let Payyvion notify your server when something happens — a payment lands, an invoice is paid, or a withdrawal completes. Every request is signed so you can verify it.

Register an endpoint

Subscribe only to the events you need — you can add more later.

curl https://api.payyvion.com/v1/webhooks \
  -X POST \
  -H "Authorization: Bearer sk_live_1234567890abcdef" \
  -d '{
    "url": "https://example.com/hooks/sentz",
    "events": ["payment.completed", "invoice.paid"]
  }'

Event payload

Your endpoint should reply with a 2xx status within 10 seconds. Failed deliveries are retried with exponential backoff for 24 hours.

{
  "id": "evt_1c9x40ab",
  "type": "payment.completed",
  "created_at": "2024-05-20T10:16:02Z",
  "data": {
    "id": "pay_4kd91mz2",
    "amount": "25.00",
    "currency": "eUSD",
    "wallet_id": "wlt_8h3e5f17"
  }
}

Verify the Payyvion-Signature header against your endpoint secret before trusting a payload.