Skip to main content
POST
/
invoices
Create invoice
curl --request POST \
  --url https://api.palomma.com/invoices \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "reference": "INV-2026-0001",
  "amount": 1850000,
  "description": "Canon de arrendamiento marzo 2026",
  "redirectUrl": "https://merchant.example.com/payments/return",
  "customerDocumentNumber": "900123456"
}
'
{
  "id": "01HQY8EW1H9YGH5PAV5Y2M9R3T",
  "reference": "INV-2026-0001",
  "status": "ready",
  "amount": 1850000,
  "description": "Canon de arrendamiento marzo 2026",
  "contract": "00000",
  "expirationDate": "2026-03-11T16:37:14.007Z",
  "customerDocumentNumber": "900123456",
  "customerName": "Inmobiliaria Ejemplo SAS",
  "createdAt": "2026-03-11T16:32:14.007Z",
  "paymentUrl": "https://pagos.palomma.com/pay/merchant_123/01HQY8EW1H9YGH5PAV5Y2M9R3T"
}

Authorizations

​
Authorization
string
header
required

Send header: Authorization: Bearer <apiKey>.

Body

application/json
​
reference
string
required

Unique invoice reference for your records (e.g. "INV-2026-0001").

Minimum string length: 1
​
amount
integer
required

Invoice amount in COP. Must be between 3,000 and 550,000,000.

Required range: 3000 <= x <= 550000000
​
description
string
required

Invoice description shown to the customer.

Minimum string length: 1
​
redirectUrl
string<uri>
required

URL where the customer is redirected after completing the payment flow.

​
customerDocumentNumber
string
required

Customer's document or identification number.

Minimum string length: 1
​
documentType
enum<string>

Customer's document type. One of: cc (cedula), ce (cedula de extranjeria), nit (NIT), ti (tarjeta de identidad), ps (pasaporte), cif (codigo de identificacion fiscal), ne (NIT extranjero), rc (registro civil), ppt (permiso de permanencia temporal).

Available options:
cc,
ce,
nit,
ti,
ps,
cif,
ne,
rc,
ppt
​
customerName
string

Customer's display name (optional).

​
contract
string
default:00000

Contract identifier. Defaults to "00000" if not provided.

Response

Created invoice

​
id
string
required

Unique invoice identifier.

​
status
enum<string>
required

Invoice status: ready (payment link active), paid, cancelled, or chargeback.

Available options:
ready,
paid,
cancelled,
chargeback
​
amount
number
required

Invoice amount in COP.

​
description
string
required

Invoice description.

​
contract
string
required

Contract identifier.

​
customerDocumentNumber
string
required

Customer's document number.

​
createdAt
string
required

Invoice creation datetime (ISO 8601).

​
paymentUrl
string<uri>
required

Palomma hosted payment page URL for this invoice.

​
reference
string

Merchant-provided invoice reference.

​
expirationDate
string

Payment link expiration datetime (ISO 8601). Invoices expire 5 minutes after creation, so redirect the customer immediately. Once a transaction is in progress, it no longer expires until the transaction completes.

​
customerName
string

Customer's display name.

​
paymentDate
string<date-time>

When the invoice was paid. Present on paid and chargeback invoices.

​
paymentMethod
enum<string>

Payment method used. Present on paid and chargeback invoices.

Available options:
pse,
nequiButton,
bancolombiaButton,
breb,
card
​
paymentSource
enum<string>

Channel through which payment was made. Present on paid and chargeback invoices.

Available options:
whatsapp,
portal,
link
​
paymentAmount
number

Amount actually paid in COP. Present on paid and chargeback invoices.

​
settlementDate
string

Expected settlement date (YYYY-MM-DD). Present on paid and chargeback invoices.

​
settlementTime
string

Expected settlement cycle. Present on paid and chargeback invoices.

​
paymentId
string

Payment identifier. Present on paid and chargeback invoices.