Skip to main content

​
Payments

Payments are the core resource in ZendFi. A payment represents a request for funds from a customer, tracked from creation through to on-chain confirmation or expiry.

​
Create a Payment

Requires authentication with a valid API key.
POST /api/v1/payments
Creates a new payment and returns a checkout URL the customer can use to pay.

​
Request Body

​
amount
number
required
Payment amount in the specified currency. Must be greater than zero.
​
currency
string
default:"USD"
Currency code. Supported values: USD, EUR, GBP.
​
token
string
default:"USDC"
Solana token to accept. Supported values: USDC, USDT, SOL.
​
description
string
Description shown to the customer on the checkout page.
​
metadata
object
Arbitrary key-value pairs attached to the payment. Useful for storing order IDs or internal references.
​
webhook_url
string
Override the default webhook URL for this specific payment.
​
split_recipients
array
Optional array of recipients for payment splits. See Payment Splits for details.

​
Example Request

curl -X POST https://api.zendfi.tech/api/v1/payments \
  -H "Authorization: Bearer zfi_test_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 49.99,
    "currency": "USD",
    "token": "USDC",
    "description": "Pro Plan - Monthly",
    "metadata": {
      "order_id": "order_12345",
      "plan": "pro"
    }
  }'

​
Response

{
  "id": "pay_test_abc123def456",
  "merchant_id": "merch_xyz789",
  "amount_usd": 49.99,
  "currency": "USD",
  "payment_token": "USDC",
  "status": "pending",
  "description": "Pro Plan - Monthly",
  "payment_url": "https://checkout.zendfi.tech/pay/pay_test_abc123def456",
  "qr_code": "solana:...",
  "expires_at": "2026-03-01T13:00:00Z",
  "metadata": {
    "order_id": "order_12345",
    "plan": "pro"
  },
  "mode": "test",
  "created_at": "2026-03-01T12:00:00Z"
}
​
id
string
Unique payment identifier. Prefixed with pay_test_ or pay_live_.
​
status
string
Current payment status: pending, confirmed, failed, or expired.
​
payment_url
string
Hosted checkout URL. Redirect the customer here or embed it in an iframe.
​
qr_code
string
Solana Pay compatible URI for QR code generation.
​
expires_at
string
ISO 8601 timestamp after which the payment will be marked as expired if not confirmed.

​
Get a Payment

GET /api/v1/payments/{id}
Retrieves full details of a specific payment. Requires authentication.

​
Path Parameters

​
id
string
required
The payment ID (e.g., pay_test_abc123).

​
Example

curl https://api.zendfi.tech/api/v1/payments/pay_test_abc123 \
  -H "Authorization: Bearer zfi_test_your_key"

​
Response

Returns the full payment object as shown above, with additional fields if the payment has been confirmed: 
{
  "id": "pay_test_abc123def456",
  "status": "confirmed",
  "transaction_signature": "5UfDuX...abc",
  "confirmed_at": "2026-03-01T12:05:30Z",
  "customer_wallet": "7xKXtg...xyz"
}
​
transaction_signature
string
Solana transaction signature. Only present when status is confirmed.
​
confirmed_at
string
ISO 8601 timestamp of when the payment was confirmed on-chain.
​
customer_wallet
string
The Solana wallet address that sent the payment.

​
Check Payment Status

GET /api/v1/payments/{id}/status
A lightweight endpoint that returns only the payment status. This endpoint is public — it does not require authentication. Designed for client-side polling.

​
Example

curl https://api.zendfi.tech/api/v1/payments/pay_test_abc123/status

​
Response

{
  "id": "pay_test_abc123",
  "status": "confirmed",
  "transaction_signature": "5UfDuX...abc"
}

​
Payment Statuses

StatusDescriptionTerminal
pendingPayment created, awaiting customer transactionNo
confirmedTransaction verified on Solana. Funds settled.Yes
failedTransaction found but verification failedYes
expiredNo valid transaction received before timeoutYes

​
Checkout Flow

ZendFi provides several ways for customers to complete payment:

​
Hosted Checkout

Redirect the customer to the payment_url returned in the create response. The hosted checkout page handles wallet connection, QR codes, and payment status automatically.

​
Embedded Checkout

Use the Embedded Checkout SDK component to render the checkout directly in your application without a redirect.

​
Direct Transfer

Customers can send funds directly to the payment wallet address or scan the QR code with any Solana wallet app.

​
Gasless Transactions

For a frictionless experience, use the transaction builder endpoints to create gasless transactions: 
POST /api/v1/payments/{payment_id}/build-transaction
POST /api/v1/payments/{payment_id}/submit-gasless-transaction
The customer signs the transaction, and ZendFi sponsors the gas fees.

​
Webhook Events

Payments trigger the following webhook events:
EventWhen
PaymentCreatedPayment is created
PaymentConfirmedPayment is confirmed on-chain
PaymentFailedPayment verification failed
PaymentExpiredPayment window elapsed
See Webhooks for payload format and delivery details.