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://api.nanowallet.net/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

Code Examples

Create Payment

curl

curl -X POST https://api.nanowallet.net/v1/gateway/payments \
  -H "X-API-Key: nano_test_sk_1234567890" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100.00,
    "currency": "USD",
    "description": "Test payment",
    "successUrl": "https://yoursite.com/success",
    "cancelUrl": "https://yoursite.com/cancel"
  }'

Get Payment

curl

curl -X GET https://api.nanowallet.net/v1/gateway/payments/pay_1234567890 \
  -H "X-API-Key: nano_test_sk_1234567890"