> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usmewe.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Integrate usmewe Pay

> Add usmewe payments to your application

# 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

<CodeGroup>
  ```bash npm theme={null}
  npm install @usmewe/pay
  ```

  ```bash yarn theme={null}
  yarn add @usmewe/pay
  ```
</CodeGroup>

### 2. Initialize

```typescript theme={null}
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

```typescript theme={null}
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:

```typescript theme={null}
const payment = await usmewePay.createPayment({
  amount: 50.00,
  currency: 'USDC',
  paymentMethods: ['direct']
});
```

### Pay with Credit

User borrows against their Trust Score:

```typescript theme={null}
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:

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

### All Methods

Let user choose:

```typescript theme={null}
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:

```typescript theme={null}
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:

```tsx theme={null}
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

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

### Localization

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

## Refunds

Issue a refund:

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

## Testing

Use test mode for development:

```typescript theme={null}
const usmewePay = new UsmewePay({
  merchantId: 'your_merchant_id',
  apiKey: process.env.USMEWE_TEST_API_KEY,
  environment: 'testnet'
});
```

### Test Card Numbers

| Scenario           | Wallet Address    |
| ------------------ | ----------------- |
| Success            | Any valid address |
| Decline            | 0x0000...0001     |
| Insufficient funds | 0x0000...0002     |

## API Reference

### Create Payment

```bash theme={null}
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

```bash theme={null}
GET /v1/payments/{paymentId}
```

### List Payments

```bash theme={null}
GET /v1/payments?limit=10&status=success
```

## Fees

| Payment Method | Fee                  |
| -------------- | -------------------- |
| Direct USDC    | 1%                   |
| Credit         | 2% + interest        |
| Split          | 1.5% per installment |

<Note>
  Fees are deducted from the payment amount. You receive the net amount.
</Note>

## Security

<AccordionGroup>
  <Accordion title="API Key Security" icon="key">
    * Never expose your API key in client-side code
    * Use environment variables
    * Rotate keys periodically
  </Accordion>

  <Accordion title="Webhook Verification" icon="shield">
    Always verify webhook signatures to prevent fraud.
  </Accordion>

  <Accordion title="HTTPS Only" icon="lock">
    All API calls and webhooks use HTTPS.
  </Accordion>
</AccordionGroup>

## Support

* **Documentation**: [docs.usmewe.com](https://docs.usmewe.com)
* **Discord**: [discord.gg/usmewe](https://discord.gg/usmewe)
* **Email**: [developers@usmewe.com](mailto:developers@usmewe.com)

<CardGroup cols={2}>
  <Card title="Trust Score Widget" icon="chart-line" href="/guides/developers/trust-score-widget">
    Display Trust Scores
  </Card>

  <Card title="Webhooks Guide" icon="webhook" href="/guides/developers/webhook-implementation">
    Handle all events
  </Card>
</CardGroup>