Updates a template

Updates specific fields of a payin template. Scoped to the requesting client.

The update is presence-aware: an omitted field keeps its current value and an explicit null clears a nullable field. payin_data and form_customization are partial objects merged field by field; expected_payers replaces the whole list.

A template cannot be updated while still created (its Bre-B setup may be in flight), in discarded or failed state, as a consumed (paid) single-use template, or while being pruned (prune_state not null). The update is serialized with payin processing through the template lock.

Updating total_minimum_amount/total_maximum_amount may transition the template state (ready ⇄ minimum_paid, → paid, or back out of paid). The transition is included in the payin_template_updated webhook — which every successful update emits, with the previous values of the changed fields — and does NOT trigger the separate state-change webhooks.

Authorization

authorization

AuthorizationBearer <token>

In: header

Path Parameters

idstring

Template ID

Match^[A-Za-z]{2,7}_[\w-]{22}$

Example"cpitpl_5tgliBmzjZ6mpQPRbQjfKj"

Request Body

application/json

Attributes to update the template

TypeScript Definitions

Use the request body type in TypeScript.

expected_payers?array|null

If set, only these payers are allowed to pay the template. The provided list replaces the current one as a whole; null clears the restriction.

expires_at?string|null

Expiration date for the template as ISO-8601 datetime. Must be in the future; null removes the expiration.

Formatdate-time

Example"2022-01-01T01:00:00Z"

form_customization?object|null

Customization applied to the payment form. Partial: only the provided fields are updated; null clears the whole customization, brand included.

maximum_payin_amount?object|null

Maximum amount allowed in a single Payin.

metadata?object|null

Arbitrary tenant-defined metadata.

Example

{
  "id": 3,
  "reference": 123
}

minimum_payin_amount?object|null

Minimum amount allowed in a single Payin.

nickname?string|null

Human-readable name to identify the template.

Length5 <= length <= 255

Example"string"

payin_data?object

Configuration applied to every payin of the template. Partial: only the provided fields are updated.

reference?string|null

Free-format reference shown to the payer.

Length1 <= length <= 255

Example"string"

total_maximum_amount?object|null

Maximum cumulative amount the template is allowed to collect. Cannot be less than the current paid_amount.

total_minimum_amount?object|null

Minimum cumulative amount the template must collect.

Response Body

`application/json`

curl -X PATCH "https://api.sandbox.cuentamono.com/v1/core/payins/templates/cpitpl_5tgliBmzjZ6mpQPRbQjfKj" \  -H "Content-Type: application/json" \  -d '{}'

{
  "reference": "Invoice #0042",
  "maximum_payin_amount": {
    "amount": 100000000,
    "currency": "COP"
  },
  "prune_reason": null,
  "inserted_at": "2022-01-01T01:00:00Z",
  "payin_data": {
    "fee_override": [
      {
        "fixed": {
          "amount": 100000000,
          "currency": "COP"
        },
        "percentage": "0.05",
        "tx_description": "Collection service fee",
        "type": "payin"
      }
    ],
    "metadata": {
      "id": 3,
      "reference": 123
    },
    "redirect_url": "https://merchant.example.com/checkout/return",
    "subaccount_disbursement_trigger": "on_approval"
  },
  "type": "collection",
  "minimum_payin_amount": {
    "amount": 100000000,
    "currency": "COP"
  },
  "total_maximum_amount": {
    "amount": 100000000,
    "currency": "COP"
  },
  "payment_tokens": {
    "co_breb": {
      "key_type": "alphanumeric",
      "key_value": "@MN1A2B3C4D5E",
      "qr": {
        "amount": {
          "amount": 100000000,
          "currency": "COP"
        },
        "emvco": "00020101021226440014CO.COM.CRB.RED0122CO.COM.CRB.TRXIDP123456752045411530317054061000005802CO5910Acme Store6006Bogota6304A1B2",
        "error_correction_level": "medium",
        "expires_at": "2022-01-01T01:00:00Z",
        "image": "iVBORw0KGgoAAAANSUhEUgAABAAAAAQACAYAAAB...",
        "image_width": 512,
        "payment_id": "CO.COM.CRB.TRXIDP1234567891234",
        "usage_mode": "multiple_use"
      },
      "qr_error": null
    }
  },
  "state_reason": null,
  "total_minimum_amount": {
    "amount": 100000000,
    "currency": "COP"
  },
  "expires_at": "2022-01-01T01:00:00Z",
  "usage_mode": "single_use",
  "checkout_url": "https://www.mono.la/",
  "updated_at": "2022-01-01T01:00:00Z",
  "id": "cpitpl_5tgliBmzjZ6mpQPRbQjfKj",
  "subaccount_id": "lacc_5tgliBmzjZ6mpQPRbQjfKj",
  "pruned_at": "2022-01-01T01:00:00Z",
  "prune_state": null,
  "currency": "COP",
  "enabled": false,
  "expected_payers": [
    {
      "document_number": "1023711432",
      "document_type": "CC",
      "kind": "co_person_document"
    }
  ],
  "paid_amount": {
    "amount": 100000000,
    "currency": "COP"
  },
  "external_id": "invoice-2026-0042",
  "method_params": {
    "co_breb": {
      "create_qr": false,
      "custom_key_value": "@MYSTORE01",
      "key_per": "template",
      "qr_code_data": {
        "merchant_category_code": "5411",
        "receiver_city": "Bogota",
        "receiver_postal_code": "110111"
      }
    }
  },
  "nickname": "Monthly rent - Apt 101",
  "custom_merchant_name": "Acme Store",
  "state": "ready",
  "failed_payins": 1,
  "successful_payins": 1,
  "metadata": {
    "id": 3,
    "reference": 123
  },
  "form_customization": {
    "brand_id": "cpitplb_5tgliBmzjZ6mpQPRbQjfKj",
    "custom_fields": [
      {
        "default_value": "ORD-1042",
        "description": "The one on the invoice, without dashes.",
        "editable": true,
        "label": "Order number",
        "required": false,
        "type": "text"
      }
    ]
  },
  "expires_in": 1,
  "available_methods": [
    "co_breb"
  ]
}

{
  "code": "400 Bad Request",
  "errors": [
    {
      "error_code": "validation_error",
      "message": "Generic changeset errors",
      "path": null,
      "url": null
    }
  ],
  "id": "log_7MkWaFqvfosB8fzHhb1Eql",
  "message": "Malformed request"
}

{
  "code": "401 Unauthorized",
  "errors": [
    {
      "error_code": "expired_token",
      "message": "The token is expired, inactive, or doesn't exist.",
      "path": null,
      "url": null
    }
  ],
  "id": "log_7MkWaFqvfosB8fzHhb1Eql",
  "message": "Authorization header is missing or invalid."
}

{
  "code": "403 Forbidden",
  "errors": [
    {
      "error_code": "not_authorized",
      "message": "Not authorized to have access to this resource.",
      "path": null,
      "url": null
    }
  ],
  "id": "log_7MkWaFqvfosB8fzHhb1Eql",
  "message": "Not authorized to have access to this resource"
}

{
  "code": "404 Not Found",
  "errors": [
    {
      "error_code": "item_not_found",
      "message": "The item doesn't exist",
      "path": null,
      "url": null
    }
  ],
  "id": "log_7MkWaFqvfosB8fzHhb1Eql",
  "message": "Resource not defined"
}

{
  "code": "409 Conflict",
  "errors": [
    {
      "error_code": "template_invalid_state",
      "message": "The template is in an invalid state for this operation.",
      "path": null,
      "url": null
    }
  ],
  "id": "log_7MkWaFqvfosB8fzHhb1Eql",
  "message": "Conflict"
}

{
  "code": "422 Unprocessable Content",
  "errors": [
    {
      "error_code": "missing_field",
      "message": "The field is missing on the request body or parameters.",
      "path": "#/path/to/field",
      "url": null
    }
  ],
  "id": "log_7MkWaFqvfosB8fzHhb1Eql",
  "message": "Validation errors"
}

Updates a template

Authorization

Path Parameters

Request Body

Response Body

200application/json

400application/json

401application/json

403application/json

404application/json

409application/json

422application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`