---
title: 'Payments Service Overview'
description: 'Overview of the live WinkSocial payments and wallet surfaces'
---

# Payments Service API

The payments stack is split across authenticated wallet endpoints and
provider-specific payment endpoints.

## Live Surfaces

### Wallet APIs

Base URL:

```text
https://api.joinwink.app/api/v1/wallet
```

Current wallet endpoints:

- `GET /api/v1/wallet/overview` — balance and tier summary
- `POST /api/v1/wallet/transfer` — peer-to-peer transfer
- `POST /api/v1/wallet/coins/award` — coin awards and rewards
- `GET /api/v1/wallet/leaderboard` — leaderboard reads

### Provider Payment APIs

Base URL:

```text
https://api.joinwink.app/api/payments
```

Current provider-oriented payment endpoints:

- `POST /api/payments/lemon-squeezy/checkout` — card checkout creation
- `POST /api/v1/payments/flick/card-collection` — live Flick checkout creation
- `POST /api/payments/crypto/create` — crypto payment intent
- `GET /api/payments/{paymentId}/status` — payment status lookup

### M-Pesa APIs

M-Pesa flows are handled by dedicated backend services. Web wallet UX
reaches them through Next.js proxy routes.

## Authentication

The active frontend/client model uses authenticated user sessions:

- Web clients send the `wink_session` httpOnly cookie through Next.js API
  routes and `credentials: 'include'`
- Backend requests are authorized with the propagated `Authorization: Bearer`
  header or session-derived auth context

## Available Flows

### Wallet

- Wallet overview and balance reads
- Peer-to-peer wallet transfers
- Coin awards and reward writes
- Wallet leaderboard reads

### Payment Providers

- Lemon Squeezy checkout creation for card-oriented flows
- Flick checkout creation and verified webhook reconciliation
- Crypto payment intent creation
- Payment status lookup

### Adjacent Runtime Paths

- Wallet transaction records are written to the platform datastore
- Provider callbacks are handled by backend webhooks
- Payment reminders and analytics use the backend data model directly

## Example Responses

Wallet overview:

```json
{
  "walletId": "wallet_123",
  "userId": "user_123",
  "balance": 1250,
  "coins": 1250,
  "tier": "free"
}
```

Wallet transfer:

```json
{
  "success": true,
  "balance": 850,
  "transferredAmount": 400
}
```

Lemon Squeezy checkout:

```json
{
  "status": "success",
  "checkoutUrl": "https://checkout.lemonsqueezy.com/...",
  "fundingRequestId": "funding_123",
  "amount": 1500,
  "currency": "USD"
}
```

## Integration Notes

### Web

Prefer the Next.js proxy routes for user-facing wallet operations:

- `/api/wallet/overview`
- `/api/wallet/transactions`
- `/api/wallet/transfer`

These preserve the authenticated session model.

### Testing

For smoke checks, use the actual wallet and payment routes in the running stack.
There is no dedicated health endpoint for payments.

## Best Practices

- Use the existing web proxy routes for browser-originated wallet traffic.
- Treat payment-provider endpoints as authenticated backend routes.
- Keep provider-specific behavior documented near the route that owns it.

## Support

- **Email**: hello@joinwink.app
- **Documentation**: This site