Create a payment

POST

https://api.agentpaid.io/api/v2/payments/

Records a payment received from a customer, e.g. a bank transfer or check collected outside Paid. Allocate it to invoice lines with the payment allocations endpoints.

Authentication

AuthorizationBearer

API Key authentication using Bearer token

Request

Body

amountintegerRequired

Payment amount in cents (minor currency units).

currencystringRequired=3 characters

Three-letter ISO currency code.

paymentTypeenumRequired

How the payment was made.

customerIdstringOptional>=1 character

Paid customer ID the payment belongs to.

externalCustomerIdstringOptional>=1 character

Your external customer ID the payment belongs to.

paymentDatedatetimeOptional

When the payment was made (ISO 8601). Defaults to the current time.

statusenumOptionalDefaults to posted

Initial status. Use draft to keep the payment editable, posted to record it as received. Defaults to posted.

metadatamap from strings to anyOptional

Key-value metadata stored on the payment.

Response

201

idstring

Unique payment identifier.

numberinteger

Sequential payment number within your organization (shown as “PAY-0001”).

customerIdstring

The customer this payment belongs to.

invoiceIdstring or null

The invoice this payment was collected for, when created by an automatic charge. Null for manually recorded payments.

orderIdstring or null

The order this payment relates to, when known.

amountinteger

Payment amount in cents (minor currency units).

allocatedAmountinteger

Portion of the amount already allocated to invoice lines, in cents.

balanceinteger

Unallocated remainder of the payment, in cents.

currencystring

Three-letter ISO currency code.

paymentDatedatetime

When the payment was made.

paymentTypestring

How the payment was made, e.g. creditCard, bankTransfer, ach, cash, or check.

statusstring

Payment status: draft, posted, processing, requiresAction, failed, or canceled.

metadatamap from strings to any or null

Key-value metadata stored on the payment.

createdAtdatetime

updatedAtdatetime

Errors

400

Bad Request Error

403

Forbidden Error

404

Not Found Error

500

Internal Server Error

1	import { PaidClient } from "@paid-ai/paid-node";
2
3	async function main() {
4	const client = new PaidClient({
5	token: "YOUR_TOKEN_HERE",
6	});
7	await client.payments.createPayment({
8	amount: 15000,
9	currency: "USD",
10	paymentType: "creditCard",
11	});
12	}
13	main();

1	{
2	"id": "pay_9f8b7c6d5a4e3f21",
3	"number": 1024,
4	"customerId": "cus_7a6b5c4d3e2f1g0h",
5	"invoiceId": "inv_20240115_001",
6	"orderId": "ord_20240110_789",
7	"amount": 15000,
8	"allocatedAmount": 15000,
9	"balance": 0,
10	"currency": "USD",
11	"paymentDate": "2024-01-15T09:30:00Z",
12	"paymentType": "creditCard",
13	"status": "posted",
14	"metadata": {},
15	"createdAt": "2024-01-15T09:30:00Z",
16	"updatedAt": "2024-01-15T09:30:00Z"
17	}