Skip to main content

​
Integrate usmewe Pay

Accept payments and enable micro-loans in your application with usmewe Pay.

​
Overview

usmewe Pay lets your users:
  • Pay with their Trust Score credit
  • Split payments over time
  • Use USDC from their Trust Vault
  • Pay instantly with zero friction

​
Quick Start

​
1. Install the SDK

npm install @usmewe/pay

​
2. Initialize

import { UsmewePay } from '@usmewe/pay';

const usmewePay = new UsmewePay({
  merchantId: 'your_merchant_id',
  apiKey: process.env.USMEWE_API_KEY,
  environment: 'production'
});

​
3. Create a Payment

const payment = await usmewePay.createPayment({
  amount: 50.00,
  currency: 'USDC',
  description: 'Premium subscription',
  metadata: {
    orderId: 'order_123',
    userId: 'user_456'
  }
});

// Redirect user to payment page
window.location.href = payment.checkoutUrl;

​
Payment Flow

┌─────────────────────────────────────────────────────────────────┐
│  Your App                usmewe Pay              User's Wallet  │
│     │                        │                        │         │
│     │  Create Payment        │                        │         │
│     │───────────────────────►│                        │         │
│     │                        │                        │         │
│     │  Checkout URL          │                        │         │
│     │◄───────────────────────│                        │         │
│     │                        │                        │         │
│     │  Redirect User         │                        │         │
│     │─────────────────────────────────────────────────►         │
│     │                        │                        │         │
│     │                        │  User Pays             │         │
│     │                        │◄───────────────────────│         │
│     │                        │                        │         │
│     │  Webhook: payment.success                       │         │
│     │◄───────────────────────│                        │         │
└─────────────────────────────────────────────────────────────────┘

​
Payment Options

​
Direct USDC Payment

User pays immediately with USDC: 
const payment = await usmewePay.createPayment({
  amount: 50.00,
  currency: 'USDC',
  paymentMethods: ['direct']
});

​
Pay with Credit

User borrows against their Trust Score: 
const payment = await usmewePay.createPayment({
  amount: 50.00,
  currency: 'USDC',
  paymentMethods: ['credit'],
  creditOptions: {
    maxDuration: 30, // days
    maxInterest: 0.05 // 5%
  }
});

​
Split Payment

User pays in installments: 
const payment = await usmewePay.createPayment({
  amount: 100.00,
  currency: 'USDC',
  paymentMethods: ['split'],
  splitOptions: {
    installments: 4,
    frequency: 'weekly'
  }
});

​
All Methods

Let user choose: 
const payment = await usmewePay.createPayment({
  amount: 50.00,
  currency: 'USDC',
  paymentMethods: ['direct', 'credit', 'split']
});

​
Handling Webhooks

Set up a webhook endpoint to receive payment events: 
import express from 'express';
import { UsmewePay, verifyWebhook } from '@usmewe/pay';

const app = express();

app.post('/webhooks/usmewe-pay', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-usmewe-signature'];

  if (!verifyWebhook(req.body, signature, WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }

  const event = JSON.parse(req.body);

  switch (event.type) {
    case 'payment.success':
      // Fulfill the order
      fulfillOrder(event.data.metadata.orderId);
      break;

    case 'payment.failed':
      // Handle failure
      handlePaymentFailed(event.data);
      break;

    case 'payment.refunded':
      // Handle refund
      handleRefund(event.data);
      break;
  }

  res.status(200).send('OK');
});

​
Embedded Checkout

Embed the payment form directly in your page: 
import { UsmewePayButton } from '@usmewe/pay/react';

function CheckoutPage() {
  return (
    <div>
      <h1>Complete Your Purchase</h1>

      <UsmewePayButton
        merchantId="your_merchant_id"
        amount={50.00}
        currency="USDC"
        description="Premium subscription"
        onSuccess={(payment) => {
          console.log('Payment successful:', payment.id);
          // Redirect to success page
        }}
        onError={(error) => {
          console.error('Payment failed:', error);
        }}
      />
    </div>
  );
}

​
Customization

​
Styling

const payment = await usmewePay.createPayment({
  amount: 50.00,
  currency: 'USDC',
  appearance: {
    theme: 'dark',
    primaryColor: '#6366F1',
    borderRadius: '12px',
    fontFamily: 'Inter'
  }
});

​
Localization

const payment = await usmewePay.createPayment({
  amount: 50.00,
  currency: 'USDC',
  locale: 'fr-FR'
});

​
Refunds

Issue a refund: 
const refund = await usmewePay.createRefund({
  paymentId: 'pay_abc123',
  amount: 50.00, // Full or partial
  reason: 'Customer request'
});

​
Testing

Use test mode for development: 
const usmewePay = new UsmewePay({
  merchantId: 'your_merchant_id',
  apiKey: process.env.USMEWE_TEST_API_KEY,
  environment: 'testnet'
});

​
Test Card Numbers

ScenarioWallet Address
SuccessAny valid address
Decline0x0000…0001
Insufficient funds0x0000…0002

​
API Reference

​
Create Payment

POST /v1/payments

{
  "amount": 50.00,
  "currency": "USDC",
  "description": "Order #123",
  "paymentMethods": ["direct", "credit"],
  "metadata": {},
  "redirectUrl": "https://yoursite.com/success",
  "cancelUrl": "https://yoursite.com/cancel"
}

​
Get Payment

GET /v1/payments/{paymentId}

​
List Payments

GET /v1/payments?limit=10&status=success

​
Fees

Payment MethodFee
Direct USDC1%
Credit2% + interest
Split1.5% per installment
Fees are deducted from the payment amount. You receive the net amount.

​
Security

  • Never expose your API key in client-side code
  • Use environment variables
  • Rotate keys periodically
Always verify webhook signatures to prevent fraud.
All API calls and webhooks use HTTPS.

​
Support

Trust Score Widget

Display Trust Scores

Webhooks Guide

Handle all events