Developer Docs — VyCheckout

How It Works

1. Sign up & get your API key

Create a free account at vycheckout.com → go to API Keys tab → click Generate New Key. Copy your vy_... key.

2. Create a payment collection

Call the API from your server with the item name and amount. You get back a payment_url.

3. Redirect your customer

Send your customer to the payment_url. They pay on VyCheckout's secure hosted page via PayPal.

4. Funds appear in your balance

Payment is processed and credited to your VyCheckout balance minus the platform fee. You can see it in your dashboard and request a withdrawal anytime.

💡 Base URL: https://admvtnirnjfikquognbl.supabase.co/functions/v1/api

Authentication

All requests must include your API key in the Authorization header.

Authorization: Bearer vy_your_api_key_here

⚠️ Keep your API key on your server only. Never put it in frontend JavaScript — anyone can see it.

Error Handling

The API uses standard HTTP status codes. All errors return a JSON body.

Status	Meaning
200	Success
201	Created
400	Bad request — missing or invalid parameters
401	Unauthorized — invalid or missing API key
404	Endpoint not found

{"error": "Unauthorized", "message": "Invalid or missing API key"}

Balance

GET /balance

Get your current account balance and total earnings.

curl https://admvtnirnjfikquognbl.supabase.co/functions/v1/api/balance \
  -H "Authorization: Bearer vy_your_key"

{
  "balance": 840.00,
  "total_earned": 4210.00,
  "ref_earned": 42.00,
  "currency": "USD"
}

Collections

POST /collections/create

Create a payment page. Returns a hosted payment URL to redirect your customer to.

Parameter	Type	Description
namerequired	string	Payment title shown to customer
amountrequired	number	Amount to charge
currency	string	Currency code — default USD
description	string	Optional description shown to customer

curl -X POST .../api/collections/create \
  -H "Authorization: Bearer vy_your_key" \
  -H "Content-Type: application/json" \
  -d '{"name":"Order #1234","amount":49.99,"currency":"USD","description":"Monthly plan"}'

{
  "id": "a1b2c3d4-...",
  "name": "Order #1234",
  "amount": 49.99,
  "currency": "USD",
  "payment_url": "https://vycheckout.com/?pay=col:a1b2c3d4-...",
  "created_at": "2025-04-30T12:00:00Z"
}

👆 Redirect your customer to payment_url — they pay on VyCheckout's hosted page and funds go straight to your balance.

GET /collections

List all your collections.

curl .../api/collections \
  -H "Authorization: Bearer vy_your_key"

Pay Links

POST /links/create

Create a shareable pay link with optional expiry date.

Parameter	Type	Description
namerequired	string	Link title
amountrequired	number	Amount to charge
currency	string	Currency code — default USD
expires_in_days	number	Auto-expire after N days
note	string	Note shown to payer

curl -X POST .../api/links/create \
  -H "Authorization: Bearer vy_your_key" \
  -H "Content-Type: application/json" \
  -d '{"name":"Invoice #001","amount":250,"currency":"USD","expires_in_days":7}'

{
  "id": "e5f6g7h8-...",
  "name": "Invoice #001",
  "amount": 250.00,
  "currency": "USD",
  "payment_url": "https://vycheckout.com/?pay=lnk:e5f6g7h8-...",
  "expires_at": "2025-05-07T12:00:00Z",
  "created_at": "2025-04-30T12:00:00Z"
}

Transactions

GET /transactions

List all successful payments received. Supports filtering.

Query Param	Type	Description
limit	number	Max results (default 50, max 200)
from	date	Filter from date (ISO 8601)
to	date	Filter to date (ISO 8601)

curl ".../api/transactions?limit=10&from=2025-01-01" \
  -H "Authorization: Bearer vy_your_key"

{
  "transactions": [
    {
      "id": "txn-uuid",
      "description": "Order #1234",
      "payer_name": "John Doe",
      "gross_amount": 49.99,
      "net_amount": 45.49,
      "fee_amount": 4.50,
      "payment_method": "PayPal",
      "created_at": "2025-04-30T12:00:00Z"
    }
  ],
  "count": 1
}

Webhooks

Register a URL to receive real-time notifications when payments succeed on your collections.

POST /webhooks/register

curl -X POST .../api/webhooks/register \
  -H "Authorization: Bearer vy_your_key" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://yoursite.com/webhook","events":["payment.succeeded"]}'

VyCheckout will POST this to your URL when a payment succeeds:

{
  "event": "payment.succeeded",
  "data": {
    "transaction_id": "uuid",
    "amount": 49.99,
    "currency": "USD",
    "payer_name": "John Doe",
    "description": "Order #1234",
    "payment_method": "PayPal",
    "created_at": "2025-04-30T12:00:00Z"
  }
}

Code Examples

JavaScript / Node.js

javascript

// Create a payment and redirect customer
const res = await fetch(
  'https://admvtnirnjfikquognbl.supabase.co/functions/v1/api/collections/create',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer vy_your_key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Order #1234',
      amount: 49.99,
      currency: 'USD'
    })
  }
);

const data = await res.json();

// Redirect customer to pay
window.location.href = data.payment_url;
// → https://vycheckout.com/?pay=col:uuid
// Customer pays → funds go to your VyCheckout balance

Python

python

import requests

response = requests.post(
    'https://admvtnirnjfikquognbl.supabase.co/functions/v1/api/collections/create',
    headers={
        'Authorization': 'Bearer vy_your_key',
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Order #1234',
        'amount': 49.99,
        'currency': 'USD'
    }
)

data = response.json()
payment_url = data['payment_url']
print(payment_url)
# Redirect your customer to payment_url

PHP

php

<?php
$ch = curl_init();
curl_setopt_array($ch, [
    CURLOPT_URL => 'https://admvtnirnjfikquognbl.supabase.co/functions/v1/api/collections/create',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer vy_your_key',
        'Content-Type: application/json'
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'name'     => 'Order #1234',
        'amount'   => 49.99,
        'currency' => 'USD'
    ])
]);

$response = json_decode(curl_exec($ch), true);
curl_close($ch);

// Redirect customer
header('Location: ' . $response['payment_url']);
exit;

VyCheckout API