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

# Payment API

> Process payments and manage payment methods

# Payment API Documentation

## Overview

The Payment API provides endpoints for processing various types of payments, including card payments, USSD payments, and POS card payments. It supports multiple payment providers and currencies.

## Base URL

`/api/v1/payment`

## Authentication

All endpoints require authentication using an API key in the request headers:

* `X-API-KEY`: Your API key

## Endpoints

### Card Payment

Initiate a payment using a card.

**Endpoint:** `POST /card/pay`

**Headers:**

* `X-API-KEY`: API key for authentication

**Request Body:**

```json theme={null}
{
  "requestId": "string",
  "amount": "number",
  "accountId": "string",
  "narration": "string",
  "callbackUrl": "string",
  "currency": "string"
}
```

**Response:**

```json theme={null}
{
  "statusCode": 200,
  "message": "string",
  "data": {
    "authorizationUrl": "string",
    "reference": "string",
    "accessCode": "string"
  }
}
```

### USSD Payment

Initiate a payment using USSD.

**Endpoint:** `POST /ussd/pay`

**Headers:**

* `X-API-KEY`: API key for authentication

**Request Body:**

```json theme={null}
{
  "requestId": "string",
  "amount": "number",
  "accountId": "string",
  "narration": "string",
  "callbackUrl": "string",
  "currency": "string"
}
```

**Response:**

```json theme={null}
{
  "statusCode": 200,
  "message": "string",
  "data": {
    "ussdCode": "string",
    "reference": "string"
  }
}
```

### POS Card Payment

Process a card payment through a POS terminal.

**Endpoint:** `POST /pos/purchase`

**Headers:**

* `X-API-KEY`: API key for authentication

**Request Body:**

```json theme={null}
{
  "requestId": "string",
  "terminalId": "string",
  "amount": "number",
  "accountType": "string",
  "terminalSerialNumber": "string",
  "cardData": "string",
  "currency": "string",
  "accountId": "string"
}
```

**Response:**

```json theme={null}
{
  "statusCode": 200,
  "message": "string",
  "data": {
    "transactionId": "string",
    "status": "string",
    "referenceNumber": "string",
    "cardNumber": "string",
    "cardType": "string"
  }
}
```

## Error Responses

**401 Unauthorized**

```json theme={null}
{
  "statusCode": 401,
  "message": "user not found",
  "data": null
}
```

**404 Not Found**

```json theme={null}
{
  "statusCode": 404,
  "message": "account not found",
  "data": null
}
```

**409 Conflict**

```json theme={null}
{
  "statusCode": 409,
  "message": "duplicate request id",
  "data": null
}
```

**422 Unprocessable Entity**

```json theme={null}
{
  "statusCode": 422,
  "message": "amount must be more than 100",
  "data": null
}
```

## Notes

* Payment Methods:
  * Card payments (online)
  * USSD payments
  * POS card payments
* Payment Requirements:
  * Minimum amount is 100
  * Accounts must be active
  * Currencies must be supported
  * User must own the account
  * Platform admins cannot perform payments
* Payment Processing:
  * Card payments are processed through payment gateways
  * USSD payments generate USSD codes
  * POS payments require terminal data
  * All payments are tracked with unique references
* Security:
  * All payments require authentication
  * Duplicate request IDs are rejected
  * Account ownership is verified
  * Platform admins are restricted
* Payment Status:
  * Processing
  * Approved
  * Failed
  * Pending
* Payment Notifications:
  * Users are notified of payment status
  * Callback URLs are supported
  * Webhook notifications are sent
* Payment Tracking:
  * All payments are logged
  * Payment history is maintained
  * Payment status can be queried
* Payment Fees:
  * Fees are calculated based on payment type
  * Fees are included in the payment amount
  * Fee formulas are configurable
* Payment Validation:
  * Amounts are validated
  * Currencies are validated
  * Account status is checked
  * User permissions are verified
* Payment Settlement:
  * Card payments are settled immediately
  * USSD payments are settled after confirmation
  * POS payments are settled after terminal response
  * Settlement status is tracked