Quickstart

This guide takes you from a new account to a settled payment.

1. Set your payouts. In the dashboard, open Settings → Payouts and choose the token, network and address you want to receive. Do this once per mode (test and live). Creating a payment before payouts are set returns 409 conflict.

2. Create an API key. Open Developers → API keys and create a key. Test keys start with uzp_test_, live keys with uzp_live_. The key is shown once: store it in your server’s secrets.

3. Create a payment from your server:

   curl

   curl https://api.unizpay.com/v1/payments \
     -H "Authorization: Bearer $UNIZPAY_SECRET_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "amount": "25.00",
       "payment_id": "order_1001",
       "description": "Order #1001",
       "success_url": "https://shop.example.com/orders/1001"
     }'

   Node.js

   const res = await fetch("https://api.unizpay.com/v1/payments", {
     method: "POST",
     headers: {
       Authorization: `Bearer ${process.env.UNIZPAY_SECRET_KEY}`,
       "Content-Type": "application/json",
     },
     body: JSON.stringify({
       amount: "25.00",
       payment_id: "order_1001",
       description: "Order #1001",
       success_url: "https://shop.example.com/orders/1001",
     }),
   });
   const payment = await res.json();

   Python

   import os, requests
   
   payment = requests.post(
       "https://api.unizpay.com/v1/payments",
       headers={"Authorization": f"Bearer {os.environ['UNIZPAY_SECRET_KEY']}"},
       json={
           "amount": "25.00",
           "payment_id": "order_1001",
           "description": "Order #1001",
           "success_url": "https://shop.example.com/orders/1001",
       },
   ).json()

   The response is a payment object with status awaiting_payment and a checkout_url.

4. Send the payer to checkout_url. The hosted page lets them choose a token and network, shows the deposit address and amount, and follows the payment until it settles.

5. Receive webhooks. Open Developers → Webhooks, add your endpoint URL and copy its signing secret. Each status change is sent there as a signed event; see Webhooks to verify them. Fulfil the order on payment.settled.

Safe to retry

payment_id is your own order id and makes creation idempotent: repeating the same request returns the existing payment (200) instead of creating a second one (201).