---
title: "create payments"
method: POST
path: "/payments"
tags: ["Payments"]
---

# create payments

`POST /payments`

## Request

- Base URL: `https://api.togai.com`
- URL: `https://api.togai.com/payments`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/togaihq/apis/togai-apis/docs/payments/post.ts> (a function with typed inputs; its response is checked against the schema)

create payments

## Request body

- CreatePaymentRequest: payload to create payment
  - `description` string: A brief description of the payment
  - `notes` string: A detailed note about the payment
  - `accountId` string, required
  - `externalPaymentReference` ExternalPaymentReference, required: external payment reference object
    - `sourceName` string, required
    - `sourceType` 'GATEWAY' | 'CASH' | 'CHEQUE' | 'BANK_TRANSFER' | 'CARD', required
    - `transactionNumber` string, required: Check number or Card transaction number
    - `description` string
    - `metadata` object
  - `lineItemRecords` PaymentLineItemRecord[], required
    - `type` 'INVOICE' | 'CREDIT' | 'WALLET_CREDIT', required
    - `togaiId` string
    - `amount` number
    - `order` integer, required
  - `currency` string, required
  - `totalAmount` number, required

## Response `201`

Response for POST payments requests

- Payment: Payment object
  - `id` string, required
  - `description` string
  - `notes` string
  - `accountId` string, required
  - `externalPaymentReferences` ExternalPaymentReference, required: external payment reference object
    - `sourceName` string, required
    - `sourceType` 'GATEWAY' | 'CASH' | 'CHEQUE' | 'BANK_TRANSFER' | 'CARD', required
    - `transactionNumber` string, required: Check number or Card transaction number
    - `description` string
    - `metadata` object
  - `lineItemRecords` PaymentLineItemRecord[], required
    - `type` 'INVOICE' | 'CREDIT' | 'WALLET_CREDIT', required
    - `togaiId` string
    - `amount` number
    - `order` integer, required
  - `totalAmount` number, required
  - `currency` string, required
  - `version` number, required
  - `createdBy` string, required
  - `createdAt` string, date-time, required

## Other responses

- `400`: Error response
- `401`: Error response
- `403`: Error response
- `404`: Error response
- `429`: Error response
- `default`: Error response

## Changes

- **2024-04-18** `f22fc08442b7`: 1 info
  - the response property `externalPaymentReferences` became required for the status `201`
- **2024-01-05** `ea9c4628bfdb`: 1 breaking, 1 warning, 2 info
  - removed the enum value `CHECK` of the request property `externalPaymentReference/sourceType`
  - added the new `CHEQUE` enum value to the `externalPaymentReferences/sourceType` response property for the response status `201`
  - added the new `CHEQUE` enum value to the request property `externalPaymentReference/sourceType`
  - removed the `CHECK` enum value from the `externalPaymentReferences/sourceType` response property for the response status `201`
- **2023-12-21** `dbff52f9d224`: 5 breaking, 2 warning, 6 info
  - added the new required request property `lineItemRecords/items/order`
  - added the new required request property `totalAmount`
  - removed the enum value `CREDITS` of the request property `lineItemRecords/items/type`
  - the response property `lineItemRecords/items/amount` became optional for the status `201`
  - …9 more
- **2023-12-08** `49b2a2e3f198`: 1 breaking
  - the `createdAt` response's property type changed from `date-time` to `string`, and format from no format to `date-time` for status `201`
- **2023-12-07** `9f3c4190595b`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/togaihq/apis/togai-apis/changes/payments/post.md)

---

[API](https://skmtc.dev/togaihq/apis/togai-apis.md) - [All operations](https://skmtc.dev/togaihq/apis/togai-apis/llms.txt) - [OpenAPI document](https://skmtc.dev/togaihq/apis/togai-apis/revisions/442f5d8f4aa0?raw)