Saltar al contenido principal
POST
/
invoices
Crear factura
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"
}

Autorizaciones

​
Authorization
string
header
requerido

Enviar header: Authorization: Bearer <apiKey>.

Cuerpo

application/json
​
reference
string
requerido

Referencia unica de la factura para tus registros (ej. "INV-2026-0001").

Minimum string length: 1
​
amount
integer
requerido

Monto de la factura en COP. Debe estar entre 3.000 y 550.000.000.

Rango requerido: 3000 <= x <= 550000000
​
description
string
requerido

Descripcion de la factura mostrada al cliente.

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

URL a la que se redirige al cliente despues de completar el flujo de pago.

​
customerDocumentNumber
string
requerido

Numero de documento o identificacion del cliente.

Minimum string length: 1
​
documentType
enum<string>

Tipo de documento del cliente. Uno de: cc (cédula), ce (cédula de extranjería), nit (NIT), ti (tarjeta de identidad), ps (pasaporte), cif (código de identificación fiscal), ne (NIT extranjero), rc (registro civil), ppt (permiso de permanencia temporal).

Opciones disponibles:
cc,
ce,
nit,
ti,
ps,
cif,
ne,
rc,
ppt
​
customerName
string

Nombre del cliente (opcional).

​
contract
string
predeterminado:00000

Identificador del contrato. Por defecto "00000" si no se proporciona.

Respuesta

Factura creada

​
id
string
requerido

Identificador unico de la factura.

​
status
enum<string>
requerido

Estado de la factura: ready (link de pago activo), paid (pagada), cancelled (cancelada) o chargeback (contracargo).

Opciones disponibles:
ready,
paid,
cancelled,
chargeback
​
amount
number
requerido

Monto de la factura en COP.

​
description
string
requerido

Descripcion de la factura.

​
contract
string
requerido

Identificador del contrato.

​
customerDocumentNumber
string
requerido

Numero de documento del cliente.

​
createdAt
string
requerido

Fecha y hora de creacion de la factura (ISO 8601).

​
paymentUrl
string<uri>
requerido

URL de la pagina de pago de Palomma para esta factura.

​
reference
string

Referencia de factura proporcionada por el comercio.

​
expirationDate
string

Fecha y hora de expiracion del link de pago (ISO 8601). Las facturas expiran 5 minutos despues de la creacion, por lo que se debe redirigir al cliente de inmediato. Una vez que la transaccion esta en progreso, no expira hasta que se complete.

​
customerName
string

Nombre del cliente.

​
paymentDate
string<date-time>

Fecha y hora en que se pago la factura. Presente en facturas pagadas y con contracargo.

​
paymentMethod
enum<string>

Metodo de pago utilizado. Presente en facturas pagadas y con contracargo.

Opciones disponibles:
pse,
nequiButton,
bancolombiaButton,
breb,
card
​
paymentSource
enum<string>

Canal a traves del cual se realizo el pago. Presente en facturas pagadas y con contracargo.

Opciones disponibles:
whatsapp,
portal,
link
​
paymentAmount
number

Monto efectivamente pagado en COP. Presente en facturas pagadas y con contracargo.

​
settlementDate
string

Fecha esperada de liquidacion (YYYY-MM-DD). Presente en facturas pagadas y con contracargo.

​
settlementTime
string

Ciclo esperado de liquidacion. Presente en facturas pagadas y con contracargo.

​
paymentId
string

Identificador del pago. Presente en facturas pagadas y con contracargo.