PublicChargeBody

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/elocuenti-com/json-schema/elocuenti-com-public-charge-body-schema.json",
  "title": "PublicChargeBody",
  "x-generated": "2026-11-06",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/elocuenti-com-openapi.json#/components/schemas/PublicChargeBody",
  "type": "object",
  "properties": {
    "amount_in_cents": {
      "description": "Amount the payer pays, in cents (COP 1.000 = 100000). Omit it to send `price_amount`.",
      "anyOf": [
        {
          "type": "integer",
          "exclusiveMinimum": 0
        },
        {
          "type": "null"
        }
      ],
      "title": "Amount In Cents"
    },
    "price_currency": {
      "description": "Prices in dollars (turn it on in Charge settings): the payer pays the equivalent in COP at the day's rate (how it is computed: Charge settings in the dashboard), held 24 h. Send it with `price_amount` instead of `amount_in_cents`.",
      "anyOf": [
        {
          "type": "string",
          "const": "USD"
        },
        {
          "type": "null"
        }
      ],
      "title": "Price Currency"
    },
    "price_amount": {
      "description": "Your price in US cents (US$70 = 7000), with `price_currency`.",
      "anyOf": [
        {
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 100000000
        },
        {
          "type": "null"
        }
      ],
      "title": "Price Amount"
    },
    "currency": {
      "default": "COP",
      "type": "string",
      "const": "COP",
      "title": "Currency"
    },
    "description": {
      "default": "",
      "description": "What the payer sees on the checkout.",
      "type": "string",
      "title": "Description"
    },
    "customer": {
      "description": "Payer data the checkout opens with (all optional; see PublicCustomer).",
      "$ref": "#/$defs/PublicCustomer"
    },
    "customer_country": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "ISO 3166-1 alpha-2, e.g. CO.",
      "title": "Customer Country"
    },
    "method_hint": {
      "default": "any",
      "description": "`any` opens the checkout; the others start that method directly.",
      "type": "string",
      "enum": [
        "any",
        "nequi",
        "card",
        "pse",
        "qr"
      ],
      "title": "Method Hint"
    },
    "allowed_methods": {
      "description": "Methods the checkout offers; omit it for every method the account has enabled.",
      "anyOf": [
        {
          "minItems": 1,
          "type": "array",
          "items": {
            "type": "string",
            "enum": [
              "card",
              "nequi",
              "daviplata",
              "qr",
              "pse",
              "bancolombia",
              "breb"
            ]
          }
        },
        {
          "type": "null"
        }
      ],
      "title": "Allowed Methods"
    },
    "external_reference": {
      "description": "Your id for this charge, unique per account and environment (reuse: 409).",
      "anyOf": [
        {
          "type": "string",
          "maxLength": 200
        },
        {
          "type": "null"
        }
      ],
      "title": "External Reference"
    },
    "return_url": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "https URL the payer's browser returns to after paying.",
      "title": "Return Url"
    },
    "notification_url": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "https URL that receives each status change of the charge, signed with the notification secret of its environment (one for sandbox, one for production, in Settings → API Keys). Without that secret the charge is refused with 422 `WEBHOOK_SECRET_MISSING` and nothing is created: generate it and send the same request with the same Idempotency-Key. The same happens when you leave it out and your business has a default notification URL.",
      "title": "Notification Url"
    },
    "expires_in_minutes": {
      "default": 1440,
      "description": "Minutes until it expires.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 43200,
      "title": "Expires In Minutes"
    },
    "metadata": {
      "description": "Stored as-is, never shown.",
      "anyOf": [
        {
          "type": "object",
          "additionalProperties": true
        },
        {
          "type": "null"
        }
      ],
      "title": "Metadata"
    }
  },
  "additionalProperties": false,
  "$defs": {
    "PublicCustomer": {
      "type": "object",
      "properties": {
        "email": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "Optional; the payment processor sends the receipt there.",
          "title": "Email"
        },
        "full_name": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "Nequi and PSE.",
          "title": "Full Name"
        },
        "phone_number": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "Colombian mobile, 10 digits (+57 accepted): the Nequi to charge; PSE.",
          "title": "Phone Number"
        },
        "legal_id_type": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "PSE: RC, TI, CC, TE, CE, NIT, PP, DNI, PPT, PA. DaviPlata: CC, CE, TI.",
          "title": "Legal Id Type"
        },
        "legal_id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "PSE and DaviPlata (digits).",
          "title": "Legal Id"
        },
        "person_type": {
          "description": "PSE: `juridica` pays with its NIT.",
          "anyOf": [
            {
              "type": "string",
              "enum": [
                "natural",
                "juridica"
              ]
            },
            {
              "type": "null"
            }
          ],
          "title": "Person Type"
        }
      },
      "additionalProperties": true,
      "description": "The payer as the business knows them: the checkout opens with these filled in.\n\nEvery field is optional and NOT validated beyond its type: an invalid value shows in its field with its error, so\nthe buyer fixes it; it never fails the charge. A key this list does not name is accepted, so one an integrator sends today keeps working.",
      "title": "PublicCustomer"
    }
  }
}