---
title: "Create a payment record"
method: POST
path: "/api/payments"
tags: ["Payments"]
---

# Create a payment record

`POST /api/payments`

Create a payment record manually. Useful for importing historical data. If status is SUCCEEDED, the associated invoice will also be marked as paid.

## Request body

- CreatePaymentDto
  - `invoiceId` string, required — Invoice ID this payment is for
  - `provider` string, required — Payment provider name (e.g. stripe, paystack, manual)
  - `amount` number, required — Payment amount
  - `currency` string, required — Currency
  - `status` 'PROCESSING' | 'SUCCEEDED' | 'FAILED' | 'REFUNDED', required — Payment status
  - `providerTransactionId` string — Provider transaction ID
  - `failureReason` string — Failure reason (for FAILED payments)
  - `createdAt` string — Backdate createdAt (ISO 8601). For data imports.

## Response `201`

Payment created

- PaymentResponse
  - `id` string, required
  - `invoiceId` string, required
  - `provider` string, required
  - `providerTransactionId` string
  - `amount` string, required — Decimal amount as string
  - `currency` string, required
  - `status` 'PENDING' | 'PROCESSING' | 'SUCCEEDED' | 'FAILED' | 'REFUNDED', required
  - `failureReason` string
  - `metadata` object
  - `createdAt` string, required
  - `updatedAt` string, required

## Other responses

- `404` — Invoice not found

---

[API](https://skmtc.net/novabilling/apis/novabilling-api.md) · [All operations](https://skmtc.net/novabilling/apis/novabilling-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/novabilling/novabilling-api/revisions/0e449a4e0dc8/schema)