Skip to main content

Payment Gateway API

Accept crypto payments with instant USD conversion

Getting Started

Introduction

The Nano Wallet Payment Gateway API allows you to accept cryptocurrency payments (USDC) with instant conversion to USD. Our compliance-first approach ensures secure and regulated transactions.

Base URL

https://nanowallet.net/api/v1/gateway

Authentication

Authenticate your API requests by including your API key in the X-API-Key header.

# Test keys start with nano_test_
X-API-Key: nano_test_sk_1234567890

# Live keys start with nano_live_
X-API-Key: nano_live_sk_1234567890

Payments

Create Payment

POST/payments

Create a new payment session for crypto to USD conversion

Response

json
{
  "success": true,
  "data": {
    "id": "pay_1234567890",
    "status": "pending",
    "amount": 100.00,
    "currency": "USD",
    "description": "Test payment",
    "checkoutUrl": "https://checkout.nanowallet.net/pay_1234567890",
    "expiresAt": "2024-01-01T12:30:00Z",
    "createdAt": "2024-01-01T12:00:00Z"
  }
}

Get Payment

GET/payments/:id

Retrieve the status and details of a specific payment

Response

json
{
  "success": true,
  "data": {
    "id": "pay_1234567890",
    "status": "completed",
    "amount": 100.00,
    "currency": "USD",
    "description": "Test payment",
    "completedAt": "2024-01-01T12:15:00Z",
    "createdAt": "2024-01-01T12:00:00Z"
  }
}

List Payments

GET/payments

Retrieve a list of payments

key 'webhooks (en)' returned an object instead of string.

Webhook Events

payment.completedPayment successfully completed
payment.failedPayment failed or expired
payment.refundedPayment was refunded
subscription.createdNew subscription created
subscription.billing_succeededSubscription billing succeeded
subscription.billing_failedSubscription billing failed
subscription.cancelledSubscription was cancelled

Signature Verification

Verify webhook signatures using HMAC-SHA256 to ensure the request came from Nano Wallet.

Node.js

javascript
const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload, 'utf8')
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

// Usage
const isValid = verifyWebhookSignature(
  req.body,
  req.headers['nano-signature'],
  process.env.WEBHOOK_SECRET
);

Python

python
import hmac
import hashlib

def verify_webhook_signature(payload, signature, secret):
    expected_signature = hmac.new(
        secret.encode('utf-8'),
        payload.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()
    
    return hmac.compare_digest(signature, expected_signature)

# Usage
is_valid = verify_webhook_signature(
    request.body,
    request.headers.get('nano-signature'),
    os.environ['WEBHOOK_SECRET']
)

Retry Policy

If your webhook endpoint returns a non-2xx status code, we will retry delivery using exponential backoff.

  • Attempt 1:Immediate
  • Attempt 2:30 seconds
  • Attempt 3:2 minutes
  • Attempt 4:10 minutes
  • Attempt 5:1 hour
  • Final attempt:6 hours

Error Handling

Error Codes

400
Bad Request
Invalid parameters
401
Unauthorized
Missing or invalid API key
404
Not Found
Resource not found
429
Too Many Requests
Rate limit exceeded (100 requests/minute)
500
Internal Server Error
Something went wrong on our end

Error Response Format

json
{
  "success": false,
  "error": {
    "code": "invalid_request",
    "message": "The amount field is required",
    "param": "amount"
  }
}

Rate Limits

The API is rate limited to 100 requests per minute per API key. Rate limit information is included in response headers.

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1609459200