LevelGift Pay

API documentation

Accept payments by CashApp, Apple Pay, Google Pay and Chime, and send payouts, with one REST API. Every account starts in test mode; live keys work once your account is approved.

Become a merchant Sign in

Authentication

Base URL: https://pay.levelgift.online/api/v1. Send your secret key as a bearer token. Create keys under Developers in the dashboard.

curl https://pay.levelgift.online/api/v1/methods \
  -H "Authorization: Bearer sk_test_xxx"

Keep secret keys on your server only. All amounts are integers in cents (1999 = $19.99). Requests are limited to 120 per minute per key.

Errors

Errors use HTTP status codes and a consistent body:

{ "error": { "code": "amount_not_allowed", "message": "Amount for Chime must be one of: $20, $25, …", "allowed_amounts": [2000, 2500] } }
StatusCodeMeaning
401authentication_failedMissing or invalid key
403account_not_approved, account_disabledLive key before approval, or suspended account
404not_foundNo such object for this key's mode
422validation_failed, amount_not_allowedBad input; fields lists each problem
402payment_failed, payout_failed, insufficient_balanceThe request was valid but could not be completed
429rate_limitedToo many requests

Idempotency. Send an Idempotency-Key header (any unique string, e.g. your order ID) on POST requests. Retrying with the same key returns the original object instead of creating a duplicate.

Methods

GET /methods

Lists the payment methods available right now, the exact amounts each accepts, payout methods with their recipient fields, and your fees. Payment providers only accept certain amounts per method, so build your price picker from allowed_amounts.

{
  "payment_methods": [
    { "method": "applepay", "name": "Apple Pay", "allowed_amounts": [999, 1499, 1999, …, 19999], "logo_url": "…" },
    { "method": "chime", "name": "Chime", "allowed_amounts": [2000, 2500, 5000, 10000, 20000, 50000] }
  ],
  "payout_methods": [
    { "method": "ecashapp", "name": "Cash App ($cashtag)", "recipient_fields": [{ "field": "cashtag", "required": true, "example": "$johndoe" }] }
  ],
  "fees": { "payment": { "percent": 3.5, "fixed": 30 }, "payout": { "percent": 1, "fixed": 100 } }
}

Payments

Create a payment

POST /payments

FieldRequiredDescription
amountYesCents. Must be one of the method's allowed_amounts.
methodYesecashapp, applepay, googlepay, chime (see /methods)
customer_idNoYour stable ID for the customer. Improves approval rates. Generated if omitted.
customer_name, customer_ip, device_idNoHelp fraud screening; send them when you have them.
referenceNoYour order ID (max 120 chars). Filterable.
metadataNoUp to 20 string key/values, returned unchanged.
return_urlNoWhere the customer lands after checkout. We add payment_id and status to the query string.
expires_in_minutesNo30–1440, default 120.
curl https://pay.levelgift.online/api/v1/payments \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Idempotency-Key: order_1042" \
  -H "Content-Type: application/json" \
  -d '{"amount": 4999, "method": "applepay", "reference": "order_1042", "return_url": "https://shop.example/thanks"}'

Response 201: redirect your customer to checkout_url.

{
  "id": "pay_k2m9qx4…", "object": "payment", "mode": "test", "status": "processing",
  "amount": 4999, "amount_paid": null, "fee": 205, "currency": "usd", "method": "applepay",
  "customer_id": "CUS7K2M9QX4", "reference": "order_1042", "metadata": null,
  "checkout_url": "https://…", "expires_at": "…", "paid_at": null, "created_at": "…"
}

Statuses

pending → processing → succeeded or failed. Later: closed (expired or canceled), refunded, revoked, disputed. Fulfil orders on the payment.succeeded webhook, never on the browser redirect alone.

For ecashapp (CashApp Personal) the customer may send a different amount: amount_paid shows what was actually received, and your fee is based on it.

Retrieve, list, cancel

GET /payments/{id} GET /payments?status=succeeded&reference=order_1042&limit=20&page=1 POST /payments/{id}/cancel

Payouts

POST /payouts

Sends money from your balance. The amount plus the payout fee is reserved immediately and returned automatically if the payout fails or is canceled.

FieldRequiredDescription
amountYesCents
methodYesecashapp, paypal, venmo, card, ach, chime, zelle
recipientYesObject with the method's recipient_fields, e.g. {"cashtag": "$jane"}, {"email": "jane@x.com"}, {"accountNumber": "…", "routingNumber": "…"}
reason, reference, metadata, expires_in_minutesNoAs for payments
curl https://pay.levelgift.online/api/v1/payouts \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Idempotency-Key: withdrawal_77" \
  -H "Content-Type: application/json" \
  -d '{"amount": 2500, "method": "ecashapp", "recipient": {"cashtag": "$jane"}, "reference": "withdrawal_77"}'

Statuses: pending, processing, succeeded, failed, canceled, refunded, closed. Also GET /payouts/{id} and GET /payouts.

Balance

GET /balance

{ "object": "balance", "mode": "live", "currency": "usd", "available": 152340, "payouts_in_progress": 2500 }

Successful live payments are credited minus your fee as soon as they succeed.

Webhooks

Set your endpoint under Developers. We POST JSON when a payment or payout changes:

{
  "id": "evt_…", "type": "payment.succeeded", "created": 1792580660, "livemode": true,
  "data": { "id": "pay_…", "object": "payment", "status": "succeeded", "amount": 4999, … }
}

Event types: payment.processing, payment.succeeded, payment.failed, payment.closed, payment.refunded, payment.revoked, payment.disputed, payout.processing, payout.succeeded, payout.failed, payout.canceled, payout.refunded, payout.closed, and ping for tests.

Reply with any 2xx within 10 seconds. Failed deliveries are retried after 1, 5, 30, 120 and 720 minutes. Events can arrive more than once or out of order, so key your processing on data.id + data.status.

Verify the signature

Each request has X-Signature: t=<unix time>,v1=<hex>, where v1 = HMAC-SHA256 of "<t>.<raw body>" with your signing secret. Reject timestamps older than 5 minutes.

// PHP
[$t, $v1] = sscanf(str_replace(['t=', 'v1='], '', $_SERVER['HTTP_X_SIGNATURE']), '%d,%s');
$body = file_get_contents('php://input');
$ok = hash_equals(hash_hmac('sha256', $t.'.'.$body, getenv('WEBHOOK_SECRET')), $v1) && abs(time() - $t) < 300;

// Node.js
const [t, v1] = req.headers['x-signature'].split(',').map(p => p.split('=')[1]);
const expected = crypto.createHmac('sha256', process.env.WEBHOOK_SECRET).update(`${t}.${rawBody}`).digest('hex');
const ok = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1)) && Math.abs(Date.now() / 1000 - t) < 300;

# Python
t, v1 = [p.split('=')[1] for p in request.headers['X-Signature'].split(',')]
expected = hmac.new(SECRET.encode(), f"{t}.".encode() + request.get_data(), hashlib.sha256).hexdigest()
ok = hmac.compare_digest(expected, v1) and abs(time.time() - int(t)) < 300

Testing