---
title: "Create Public Charge"
method: POST
path: "/api/v1/payments/charges"
tags: ["payments-api"]
---

# Create Public Charge

`POST /api/v1/payments/charges`

## Request

- Base URL: `https://www.elocuenti.com`
- URL: `https://www.elocuenti.com/api/v1/payments/charges`
- Auth: HTTP bearer

## Headers

- `Idempotency-Key` string, nullable: Required. Retrying with the same key returns the same charge.

## Request body

- PublicChargeBody
  - `amount_in_cents` integer, nullable: Amount the payer pays, in cents (COP 1.000 = 100000). Omit it to send `price_amount`.
  - `price_currency` 'USD', nullable: Prices in dollars (turn it on in Ajustes de cobros): the payer pays in COP at the day's official rate (TRM) + 1.5 %, held 24 h. Send it with `price_amount` instead of `amount_in_cents`.
  - `price_amount` integer, nullable: Your price in US cents (US$70 = 7000), with `price_currency`.
  - `currency` 'COP'
  - `description` string: What the payer sees on the checkout.
  - `customer` PublicCustomer: The payer as the business knows them: the checkout opens with these filled in. Every field is optional and NOT validated beyond its type: an invalid value shows in its field with its error, so the buyer fixes it; it never fails the charge. `extra="allow"`: a key an integrator sends today keeps working.
    - `email` string, nullable: Optional; Wompi sends the receipt there.
    - `full_name` string, nullable: Nequi and PSE.
    - `phone_number` string, nullable: Colombian mobile, 10 digits (+57 accepted): the Nequi to charge; PSE.
    - `legal_id_type` string, nullable: PSE: RC, TI, CC, TE, CE, NIT, PP, DNI, PPT, PA. DaviPlata: CC, CE, TI.
    - `legal_id` string, nullable: PSE and DaviPlata (digits).
    - `person_type` 'natural' | 'juridica', nullable: PSE: `juridica` pays with its NIT.
  - `customer_country` string, nullable: ISO 3166-1 alpha-2, e.g. CO.
  - `method_hint` 'any' | 'nequi' | 'card' | 'pse' | 'qr': `any` opens the checkout; the others start that method directly.
  - `allowed_methods` string[], nullable: Methods the checkout offers; omit it for every method the account has enabled.
  - `external_reference` string, nullable: Your id for this charge, unique per account and environment (reuse: 409).
  - `return_url` string, nullable: https URL the payer's browser returns to after paying.
  - `notification_url` string, nullable: https URL that receives the signed status notification (see webhooks).
  - `expires_in_minutes` integer: Minutes until it expires.
  - `metadata` object, nullable: Stored as-is, never shown.

## Response `201`

Successful Response

- ChargeResponse
  - `data` Charge, required: A charge. Creation answers the first block; reads add the fields after `terms`.
    - `id` string, required
    - `status` string, required: pending, paid, failed, expired or cancelled.
    - `payment_url` string, nullable, required: Link to send the payer: Elopay Checkout (https://elopay.elocuenti.com/c/<id>). Links issued before (https://www.elocuenti.com/api/payments/pay/<id>) redirect to it.
    - `methods` ChargeMethods, required
      - `checkout` ChargeCheckout, required
        - `url` string, nullable, required
        - `account` string, nullable, required
      - `nequi_only` object, nullable, required: Only on creation with `method_hint: nequi`: transaction_id, status, phone_masked.
      - `qr` object, nullable, required: Only on creation with `method_hint: qr`: transaction_id, image.
    - `expires_at` string, nullable, required
    - `amounts` ChargeAmounts, required
      - `amount_in_cents` integer, nullable, required
      - `provider_fee_cents` integer, nullable, required: Always null.
      - `platform_commission_cents` integer, nullable, required
      - `tenant_net_cents` integer, nullable, required: What reaches your account.
    - `terms` ChargeTerms, required
      - `privacy_url` string, nullable, required
      - `personal_auth_url` string, nullable, required
    - `external_reference` string, nullable
    - `payment_method` string, nullable
    - `paid_at` string, nullable
    - `provider_transaction_id` string, nullable
    - `created_at` string, nullable
  - `request_id` string, nullable

## Other responses

- `400`: Petición malformada: una validación que el JSON Schema no puede expresar (reglas entre campos, headers de firma obligatorios ausentes) o un cuerpo que no es UTF-8. Un JSON roto en UTF-8 responde, en cambio, **422** `json_invalid`.
- `401`: No autenticado: falta la credencial, es inválida o expiró.
- `403`: Autenticado, pero sin permiso sobre este recurso o tenant.
- `409`: Conflicto con el estado actual del recurso.
- `422`: El cuerpo o los parámetros no pasan la validación del esquema.
- `429`: Se superó el límite de peticiones del API key o de la IP.
- `500`: Error interno no recuperable por el cliente.
- `503`: El servicio no puede atender la petición por configuración ausente o una dependencia caída. Es reintentable.

---

[API](https://skmtc.dev/elocuenti/apis/elocuenti-api.md) · [All operations](https://skmtc.dev/elocuenti/apis/elocuenti-api/llms.txt) · [OpenAPI document](https://skmtc.dev/elocuenti/apis/elocuenti-api/revisions/633c2767ac8a?raw)