---
title: 'Payment Processing'
description: 'Live payment-processing routes exposed by the WinkSocial backend'
---

# Payment Processing

This page documents the payment-processing routes that currently exist in the
repo. Earlier docs described a much larger `/api/v1/payments/*` product API with
public token auth, analytics, search, and country-method discovery. Those
routes are not implemented in the live backend.

## Authentication

All routes below are authenticated user routes. In the current stack:

- browser clients typically go through authenticated web proxies
- backend routes rely on the caller session or propagated bearer auth
- there is no active `X-API-Token` payments contract in this repo

## Live Backend Routes

### 1. Lemon Squeezy Checkout

```http
POST /api/payments/lemon-squeezy/checkout
```

Creates a wallet-funding checkout session for card-oriented flows.

Request body:

```json
{
  "amount": 1500,
  "currency": "USD"
}
```

Notes:

- `amount` is in cents
- values must be greater than `50`
- requires backend secrets:
  - `LEMONSQUEEZY_API_KEY`
  - `LEMONSQUEEZY_STORE_ID`
  - `LEMONSQUEEZY_WALLET_VARIANT_ID`

Example response:

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

Implemented in the platform payment controller.

### 2. Flick Checkout

```http
POST /api/v1/payments/flick/card-collection
```

Creates a live Flick checkout. The payments microservice authenticates with the
production private key, persists the pending transaction, and returns the
provider checkout URL.

Request body:

```json
{
  "amount": 1000,
  "currency": "NGN",
  "phoneNumber": "+2348100000000",
  "email": "customer@example.com"
}
```

Notes:

- `amount`, `phoneNumber`, and `email` are required
- requires backend secrets:
  - `FLICK_SECRET_KEY`
  - `FLICK_WEBHOOK_SECRET`

Example response:

```json
{
  "status": "success",
  "status": "success",
  "checkoutUrl": "https://...",
  "sessionId": "wink_1736947800_123",
  "transactionId": "wink_1736947800_123",
  "currency": "NGN"
}
```

Wallet crediting occurs only after a webhook with a matching
`Verification-Hash`. Browser redirects do not mark a payment successful.

### 3. Crypto Payment

```http
POST /api/payments/crypto/create
```

Creates a crypto payment intent and address.

Request body:

```json
{
  "amount": 25,
  "currency": "USDT"
}
```

Supported currencies in the current controller:

- `BTC`
- `ETH`
- `LTC`
- `BCH`
- `USDC`
- `USDT`

Example response:

```json
{
  "status": "success",
  "paymentAddress": "0xabc123...",
  "amount": 25,
  "currency": "USDT",
  "reference": "CRYPTO_user_123_1736947800",
  "paymentId": "crypto_payment_123",
  "expiresAt": 1736951400,
  "instructions": "Send 25 USDT to the provided address"
}
```

### 4. Payment Status

```http
GET /api/payments/{paymentId}/status
```

Looks up a payment by ID across the current backend collections used by
`PaymentController`:

- `WalletFundingRequests`
- `FlickPayments`
- `CryptoPayments`

Example response:

```json
{
  "status": "success",
  "paymentId": "payment_123",
  "paymentStatus": "pending",
  "amount": 25,
  "currency": "USDT",
  "provider": "coinbase",
  "timestamp": 1736947800
}
```

## Adjacent Payment Route

### M-Pesa STK Push

```http
POST /api/v1/mpesa/stk-push
```

This route is implemented by the platform M-Pesa controller.

Request body:

```json
{
  "phoneNumber": "+254700000000",
  "amount": 1000
}
```

Example response:

```json
{
  "success": true,
  "requestId": "funding_request_123",
  "checkoutRequestId": "ws_CO_123",
  "merchantRequestId": "29115-34620561-1",
  "message": "STK push sent to +254700000000",
  "amount": 1000,
  "currency": "KES"
}
```

## What Is Not Implemented

The following earlier-doc claims do not match the live backend and should not be
treated as supported contracts:

- `POST /api/v1/payments/process`
- `GET /api/v1/payments/status/{transactionId}`
- `GET /api/v1/payments/methods/{countryCode}`
- `GET /api/v1/payments/methods/cards`
- `GET /api/v1/payments/search`
- `POST /api/v1/payments/{transactionId}/cancel`
- `GET /api/v1/payments/analytics`
- public `X-API-Token` auth
- a canonical `/api/v1/payments/health` endpoint
- public SDK packages such as `@winksocial/payments-js`

## Verification Path

To confirm current behavior, use the live endpoint directly. If the docs need
to expand, add routes only after the endpoint is confirmed live.