Payments API and webhooks

Overview

The Uniquity Solutions API is a JSON-over-HTTPS REST API. Authenticate using Bearer tokens, handle idempotency, and receive events via webhooks.

Authentication

Use your secret key in the Authorization header. Keep keys confidential and rotate as needed.

curl -X GET "https://sandbox.api.uniquitysolutions.com/v1/payments" \
  -H "Authorization: Bearer sk_test_123456789" \
  -H "Accept: application/json"
            

Quickstart

Create a one-time payment with minimal fields.

POST /v1/payments
Content-Type: application/json
Authorization: Bearer sk_test_123...

{
  "amount": 10000,
  "currency": "USD",
  "payment_method": {
    "type": "card",
    "token": "tok_test_visa"
  },
  "description": "Order #1001",
  "idempotency_key": "7c2f1c8a-9d8e-4b0d-92f1-a6b8f7e90123"
}
            

200 OK
{
  "id": "pay_abc123",
  "status": "succeeded",
  "amount": 10000,
  "currency": "USD",
  "created": 1715012345
}
            

Common endpoints

• GET /v1/payments — list payments
• POST /v1/payments — create a payment
• GET /v1/payments/{id} — retrieve a payment
• POST /v1/refunds — create a refund
• POST /v1/customers — create a customer
• POST /v1/payment_methods — attach or tokenize a method

Idempotency

Prevent duplicate charges by sending an Idempotency-Key header (a UUID) on POST requests. Re-using the same key returns the original result.

Errors

Errors return 4xx/5xx with a JSON body.

400 Bad Request
{
  "error": {
    "type": "invalid_request",
    "code": "missing_parameter",
    "message": "amount is required",
    "param": "amount"
  }
}
            

Rate limits

Default limit: 100 requests per minute per IP and key. The response includes headers X-RateLimit-Limit, X-RateLimit-Remaining, and Retry-After.

Webhooks

Receive asynchronous events (payment.succeeded, payment.failed, refund.created, payout.sent).

• Configure your endpoint in Dashboard: https://dashboard.uniquitysolutions.com/webhooks
• Verify signatures using the shared signing secret and the X-Webhook-Signature header
• Return 2xx within 10s; we retry with exponential backoff on failure

POST /webhooks/uniquity
X-Webhook-Signature: t=1715012345,v1=7e4a...,v1=backup...

{
  "id": "evt_123",
  "type": "payment.succeeded",
  "data": { "object": { "id": "pay_abc123", "amount": 10000, "currency": "USD" } }
}