Charges

New here? See how to charge a customer, step by step

The charge object

Endpoints

• GET /v1/charges List charges, newest first. Filter with ?status=, ?payment_link=, ?asset=, ?search= (the charge id, customer email or customer name), ?created_from= and ?created_to=.
• POST /v1/charges Create a charge; the body is described below. Answers 201 with the charge, 429 with Retry-After once the account has created 300 charges in this mode in the last 30 minutes (canceled ones included, paid live ones not, through the API, MCP and the dashboard; payments customers start at checkout do not count), or 503 while no exchange rate is available.
• GET /v1/charges/{id} Retrieve a charge and its current status.
• POST /v1/charges/{id}/cancel Cancel a pending charge nothing has been sent to yet. Answers 409 once it is paid, underpaid, expired or canceled, and as soon as a transfer to it has been seen, even an unconfirmed one.
• POST /v1/charges/{id}/send Email the customer the payment page of a pending charge. They have until expires_at to pay, so for a bill to pay later create an invoice instead. 409 unless it is pending and has a customer email; 429 with Retry-After within 10 minutes of the last email, or past 100 emails an hour for the account (shared with invoices and refund notices, and with the other accounts its owner owns). In test mode, only members of your account are emailed; anyone else answers 422 under errors.customer_email.
• POST /v1/charges/{id}/accept Accept an underpaid charge, or a late payment on an expired or canceled one, as paid for what actually arrived. It is forwarded to you and charge.paid goes out. 409 for any other charge.
• POST /v1/charges/{id}/refunds Record a refund you sent from your wallet. Body: amount (in the asset, up to 18 decimals), txid (optional, letters and digits, up to 100) and reason (optional, up to 255). Answers 201 with the updated charge; 422 when the amount is more than what was counted towards the charge, less what was already refunded; a late payment counts once it is accepted.
• POST /v1/charges/{id}/simulate Test mode only: pay the charge without coins. Body: amount (optional, in the asset; left out, whatever is still due, so pass less to try an underpayment). 409 for a live charge, and for one that is not awaiting payment.

Creating a charge

A charge created through a payment link skips the questions its hosted checkout would ask: require_email, collect_name and required custom_fields are not enforced. Pass the answers you have under customer and custom_fields.

Example: create a charge

curl -X POST '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' \
  -H 'Idempotency-Key: 4d6c1e1a-…' \
  -H 'Content-Type: application/json' \
  -d '{
    "amount": "150.00",
    "currency": "USD",
    "asset": "BTC",
    "customer": {
      "email": "buyer@example.com",
      "ip_address": "203.0.113.7",
      "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 14_6) …",
      "reference": "cus_1042",
      "country": "FR"
    },
    "description": "Order #1042",
    "metadata": {"order_id": "1042"},
    "success_url": "https://example.com/orders/1042"
  }'

<?php

use VeliraPay\VeliraPayClient;

require __DIR__.'/vendor/autoload.php';

$apiKey = getenv('VELIRAPAY_API_KEY') ?: throw new RuntimeException('Set VELIRAPAY_API_KEY.');
$velirapay = new VeliraPayClient($apiKey, baseUrl: 'https://api.velirapay.com');

$charge = $velirapay->charges->create([
    'amount' => '150.00',
    'currency' => 'USD',
    'asset' => 'BTC',
    'customer' => [
        'email' => 'buyer@example.com',
        'ip_address' => '203.0.113.7',
        'user_agent' => 'Mozilla/5.0 (Macintosh; Intel Mac OS X 14_6) …',
        'reference' => 'cus_1042',
        'country' => 'FR',
    ],
    'description' => 'Order #1042',
    'metadata' => ['order_id' => '1042'],
    'success_url' => 'https://example.com/orders/1042',
], idempotencyKey: '4d6c1e1a-…');

echo json_encode($charge, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES | JSON_THROW_ON_ERROR), PHP_EOL;

use VeliraPay\Laravel\Facades\VeliraPay;

$charge = VeliraPay::charges()->create([
    'amount' => '150.00',
    'currency' => 'USD',
    'asset' => 'BTC',
    'customer' => [
        'email' => 'buyer@example.com',
        'ip_address' => '203.0.113.7',
        'user_agent' => 'Mozilla/5.0 (Macintosh; Intel Mac OS X 14_6) …',
        'reference' => 'cus_1042',
        'country' => 'FR',
    ],
    'description' => 'Order #1042',
    'metadata' => ['order_id' => '1042'],
    'success_url' => 'https://example.com/orders/1042',
], idempotencyKey: '4d6c1e1a-…');

const secretKey = process.env.VELIRAPAY_API_KEY;
if (!secretKey) throw new Error('Set VELIRAPAY_API_KEY.');

const response = await fetch('https://api.velirapay.com/v1/charges', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${secretKey}`,
    Accept: 'application/json',
    'Idempotency-Key': '4d6c1e1a-…',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    amount: '150.00',
    currency: 'USD',
    asset: 'BTC',
    customer: {
      email: 'buyer@example.com',
      ip_address: '203.0.113.7',
      user_agent: 'Mozilla/5.0 (Macintosh; Intel Mac OS X 14_6) …',
      reference: 'cus_1042',
      country: 'FR',
    },
    description: 'Order #1042',
    metadata: { order_id: '1042' },
    success_url: 'https://example.com/orders/1042',
  }),
  redirect: 'error',
  signal: AbortSignal.timeout(30_000),
});

if (!response.ok) {
  throw new Error(`VeliraPay ${response.status}: ${await response.text()}`);
}

const charge = response.status === 204 ? null : (await response.json()).data;
console.log(JSON.stringify(charge, null, 2));

import json
import os
import requests

api_key = os.environ["VELIRAPAY_API_KEY"]

response = requests.post(
    "https://api.velirapay.com/v1/charges",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Accept": "application/json",
        "Idempotency-Key": "4d6c1e1a-…",
    },
    json={
        "amount": "150.00",
        "currency": "USD",
        "asset": "BTC",
        "customer": {
            "email": "buyer@example.com",
            "ip_address": "203.0.113.7",
            "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 14_6) …",
            "reference": "cus_1042",
            "country": "FR",
        },
        "description": "Order #1042",
        "metadata": {"order_id": "1042"},
        "success_url": "https://example.com/orders/1042",
    },
    timeout=(5, 30),
    allow_redirects=False,
)

if not 200 <= response.status_code < 300:
    raise RuntimeError(f"VeliraPay {response.status_code}: {response.text}")

charge = None if response.status_code == 204 else response.json()["data"]
print(json.dumps(charge, indent=2))

using System;
using System.Net;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;

var secretKey = Environment.GetEnvironmentVariable("VELIRAPAY_API_KEY")
    ?? throw new InvalidOperationException("Set VELIRAPAY_API_KEY.");

using var client = new HttpClient(new HttpClientHandler { AllowAutoRedirect = false })
{
    Timeout = TimeSpan.FromSeconds(30),
};
using var request = new HttpRequestMessage(HttpMethod.Post, "https://api.velirapay.com/v1/charges");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", secretKey);
request.Headers.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
request.Headers.Add("Idempotency-Key", "4d6c1e1a-…");
request.Content = new StringContent("""
    {
      "amount": "150.00",
      "currency": "USD",
      "asset": "BTC",
      "customer": {
        "email": "buyer@example.com",
        "ip_address": "203.0.113.7",
        "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 14_6) …",
        "reference": "cus_1042",
        "country": "FR"
      },
      "description": "Order #1042",
      "metadata": {"order_id": "1042"},
      "success_url": "https://example.com/orders/1042"
    }
    """, Encoding.UTF8, "application/json");

using var response = await client.SendAsync(request);
var responseBody = await response.Content.ReadAsStringAsync();
if (!response.IsSuccessStatusCode)
{
    throw new HttpRequestException($"VeliraPay {(int)response.StatusCode}: {responseBody}");
}

JsonElement? charge = null;
if (response.StatusCode != HttpStatusCode.NoContent)
{
    using var document = JsonDocument.Parse(responseBody);
    charge = document.RootElement.GetProperty("data").Clone();
}

Console.WriteLine(charge?.GetRawText() ?? "null");

{
  "data": {
    "id": "2t4bcuqkpkoy",
    "object": "charge",
    "status": "pending",
    "fiat_amount": "150.00",
    "fiat_currency": "USD",
    "asset": "BTC",
    "asset_amount": "0.0025",
    "received_amount": null,
    "remaining_amount": "0.0025",
    "overpaid": false,
    "exchange_rate": "60000",
    "deposit_address": "bc1q…",
    "transactions": [],
    "checkout_url": "https://velirapay.com/c/2t4bcuqkpkoy",
    "expires_at": "2026-09-17T00:30:00.000000Z",
    …
  }
}

Poll GET /v1/charges/{id} if you must, but a webhook endpoint tells you when a payment is seen on-chain and when a charge is paid, underpaid, expired or canceled, without polling.

Customer details

The customer object gathers what is known about who pays, to help you spot fraud before you ship anything. When the customer starts the payment on the hosted checkout, the IP address and browser (user agent) they did it from are recorded for you. When you create the charge from your own server, that request comes from you rather than from the customer, so pass what you know under customer instead:

Any other key in customer is refused with 422, so a typo does not go unnoticed. The object comes back on the charge, in the dashboard and in every webhook about it, with null for whatever is not known and an empty metadata object.

How the status changes

• pending → paid, underpaid Confirmed funds arrive, within or short of your underpayment tolerance.
• pending → expired The rate lock runs out. Expiry waits while a transfer to the charge is still confirming, and for up to 3 hours while its chain cannot be read.
• pending → canceled You cancel it, the customer switches to another coin on the checkout, or the invoice it belongs to is voided.
• underpaid → paid The rest arrives. An underpaid charge never expires.
• underpaid, expired, canceled → paid You accept an underpaid charge, or a late payment on an expired or canceled one, as paid, with POST /v1/charges/{id}/accept or in the dashboard (admins only).

How payments are detected

Every open charge's deposit address is checked about once a minute. A transfer shows up under transactions as soon as the network reports it, the checkout page tells the customer it was seen, and a charge.payment_detected webhook goes out with the transfer under data.transaction. It is credited once it has the required confirmations (2 for Bitcoin, 6 on Ethereum by default, other networks have their own); only then does the charge become paid or underpaid, with a charge.paid or charge.underpaid webhook. A charge does not expire while a transfer is still confirming.

Because the check runs once a minute, a transfer can already have confirmations when it is first seen, and on a fast chain charge.paid can follow charge.payment_detected within the same minute. A simulated test payment is recorded as confirmed straight away, without a charge.payment_detected.

Every charge is given a deposit address of its own, so a payment is matched to its charge by where it was sent rather than by its amount.

A payment that arrives after a charge expired or was canceled is still recorded against it. Its address is watched for 3 hours after expires_at, and every day at 04:00 UTC the addresses of closed charges up to 30 days old are read again, so a later payment can still surface the next morning. The charge keeps its status, a charge.late_payment webhook goes out, the dashboard flags the late payment, and you decide whether to accept it as paid.

A second transfer to a charge that is already paid raises charge.late_payment as well. It is counted automatically once confirmed, so received_amount, and possibly overpaid, change without a further webhook.

Refunds

A refund is a transfer you make yourself, from your own wallet: a payment that has been forwarded to you cannot be pulled back. Record it on the charge, in the dashboard or with POST /v1/charges/{id}/refunds, and the charge shows what was sent back, the customer is emailed if the charge has their email (at most once every 10 minutes for one charge, and counted against the account's 100 customer emails an hour), and a charge.refunded event goes out. A late payment is accepted before it is refunded, so that it is forwarded to you first.

Underpayments and overpayments

Customers rarely send the exact amount: wallets and exchanges take fees out of it. Each account sets an underpayment tolerance under Payment settings. A payment that lands within the tolerance settles the charge as paid; one that falls further short moves it to underpaid, where received_amount and remaining_amount tell you where it stands. The customer can top it up on the same checkout page until the rate lock ends, and you can accept it as paid from the dashboard. An underpaid charge never expires: it stays underpaid until the rest arrives or you accept it.

Paying too much never blocks a charge. When the surplus exceeds your overpayment threshold, overpaid is true so you can refund the difference.

A charge can only be created for an asset your account has a payout address for, and for at least the asset's minimum; anything else fails validation with 422 under errors.asset. See the coins and their minimums