Testnet

Endpoint reference

Payment API documentation

Production-ready examples for fixed asset payments and checkout-session quote flows.

https://testnet-api.payvenax.com/api/v1/openapi.json

Open API ReferenceView raw JSON

Payments

Checkout sessions

Webhooks

Verification / Signature examples

POST

Create Fixed Asset Payment

/api/v1/public/payments/create

Creates a hosted payment for a specific currency and network, then returns checkoutUrl.

curl -X POST https://testnet-api.payvenax.com/api/v1/public/payments/create \
-H "Content-Type: application/json" \
-H "Idempotency-Key: ORDER-1001" \
-H "x-api-key: your_api_key" \
-d '{
  "amount": 25,
  "currency": "ETH",
  "network": "BASE",
  "orderId": "ORDER-1001",
  "customerEmail": "customer@example.com"
}'

HTTP/1.1 201 Created
Content-Type: application/json

{
  "message": "Payment created successfully",
  "checkout": {
    "paymentId": "payment_id",
    "url": "https://pay.example.com/payvenax/payment_id",
    "expiresAt": "2026-06-09T14:30:00.000Z"
  },
  "checkoutUrl": "https://pay.example.com/payvenax/payment_id",
  "payment": {
    "id": "payment_id",
    "amount": "25",
    "currency": "ETH",
    "network": "BASE",
    "walletAddress": "0x_payment_wallet",
    "status": "PENDING",
    "txHash": null,
    "expiresAt": "2026-06-09T14:30:00.000Z"
  }
}

Essentials

Use the generated OpenAPI contract with Swagger UI, Postman, Insomnia, or SDK generators.

OpenAPI URL

https://testnet-api.payvenax.com/api/v1/openapi.json

API header

x-api-key

Webhook header

x-webhook-signature / x-webhook-timestamp / x-webhook-id

Signature format

HMAC_SHA256(timestamp.rawBody)

Integration guide

Go-live integration checklist

Use this order before connecting a real storefront to checkout payments.

Use the right API key

Create payments with the live or test key that matches the intended mode.

Send idempotency keys

Use the order id as Idempotency-Key to prevent duplicate checkout sessions.

Redirect to checkout

Send the customer to checkoutUrl and never expose private wallet data.

Verify webhooks

Validate x-webhook-signature using the raw body before fulfilling orders.

Keep a status fallback

Poll status by payment id or order id when webhook delivery is delayed.

Test/live readiness

Separate what can be tested now from what needs a public production URL.

Local testing

Create payments, redirect to checkoutUrl, and poll status without owning a domain yet.

Public webhook URL

Webhook delivery needs a reachable HTTPS URL such as staging, a tunnel, or your future domain.

Production secrets

Keep API keys and webhook secrets on the server; never ship them to the storefront browser.

Integration preflight

Run these checks before connecting the payment button on a real storefront.

The storefront server creates payments with x-api-key and Idempotency-Key.

The browser only receives redirectUrl and never receives private API credentials.

The webhook receiver validates x-webhook-signature against the raw request body.

The storefront can poll payment status by orderId if webhook delivery is delayed.

Webhook events and checkout creation are idempotent for retries and refreshes.

API usage, webhook logs, and payment detail evidence are reviewed after a test order.

Troubleshooting

Use these checks when the storefront integration returns an error or an order does not update.

400

Fix request fields

Check amount limits, decimal precision, orderId format, and customerEmail before retrying.

401

Check the API key

Send x-api-key from the server and confirm the key belongs to the active merchant account.

409

Reuse idempotency

Use the same Idempotency-Key for the same order and do not create multiple pending checkouts.

WEBHOOK

Verify delivery

Inspect webhook logs, validate the raw-body signature, then use status fallback if delivery is delayed.

API Usage

Public API request volume and recent integration calls.

Last 24 hours

Requests

Successful

Failed

Create Calls

Status Calls

curl -X POST https://testnet-api.payvenax.com/api/v1/public/payments/create \ -H "Content-Type: application/json" \ -H "Idempotency-Key: ORDER-1001" \ -H "x-api-key: your_api_key" \ -d '{ "amount": 25, "currency": "ETH", "network": "BASE", "orderId": "ORDER-1001", "customerEmail": "customer@example.com" }' HTTP/1.1 201 Created Content-Type: application/json { "message": "Payment created successfully", "checkout": { "paymentId": "payment_id", "url": "https://pay.example.com/payvenax/payment_id", "expiresAt": "2026-06-09T14:30:00.000Z" }, "checkoutUrl": "https://pay.example.com/payvenax/payment_id", "payment": { "id": "payment_id", "amount": "25", "currency": "ETH", "network": "BASE", "walletAddress": "0x_payment_wallet", "status": "PENDING", "txHash": null, "expiresAt": "2026-06-09T14:30:00.000Z" } }