Creates a template

Creates a template: a reusable configuration, tied to a subaccount, that defines how payins are collected (accepted methods, amount limits, expected payers and expiration). The request is idempotent on external_id — repeating it returns the existing template instead of creating a duplicate.

Authorization

authorization

AuthorizationBearer <token>

In: header

Request Body

application/json

Attributes to create a template

TypeScript Definitions

Use the request body type in TypeScript.

reference?string|null

Free-format reference shown to the payer.

Length1 <= length <= 255

Example"Invoice #0042"

maximum_payin_amount?object|null

Maximum amount allowed in a single Payin.

payin_data?object

type?string

Purpose of the template. If omitted, defaults to collection.

Default"collection"

Value in"topup" | "collection"

Example"collection"

minimum_payin_amount?object|null

Minimum amount allowed in a single Payin.

total_maximum_amount?object|null

Maximum cumulative amount the template is allowed to collect.

total_minimum_amount?object|null

Minimum cumulative amount the template must collect.

expires_at?string|null

Expiration date for the template as ISO-8601 datetime. Mutually exclusive with expires_in on request. If neither is set, the template does not expire.

Formatdate-time

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

usage_modestring

Whether the template can be paid once or many times.

Value in"single_use" | "multiple_use"

Example"single_use"

subaccount_idstring

Subaccount that owns the template.

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

Example"lacc_5tgliBmzjZ6mpQPRbQjfKj"

currency?string

Currency of the template. All template amounts must be denominated in this currency. Cannot be changed after creation.

Default"COP"

Match^[A-Z]{3}$

Example"COP"

expected_payers?array|null

If set, only these payers are allowed to pay the template. If omitted, any payer can pay the template.

external_idstring

Tenant-side identifier. Must be unique per tenant.

Length1 <= length <= 255

Example"invoice-2026-0042"

method_params?object

Per-method configuration overrides. If omitted, no per-method overrides are applied and each method uses its defaults.

nickname?string|null

Human-readable name to identify the template.

Length5 <= length <= 255

Example"Monthly rent - Apt 101"

custom_merchant_name?string|null

Merchant name shown to the payer in receipts and statements. If omitted, it is null and the subaccount's default merchant name is used.

Length5 <= length <= 50

Example"Acme Store"

metadata?object|null

Arbitrary tenant-defined metadata.

Example

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

form_customization?object|null

expires_in?integer|null

Expiration time in seconds from now. Mutually exclusive with expires_at on request. If neither is set, the template does not expire.

Range1 <= value

Example1

available_methods?array|null

Payment methods enabled for this template. If omitted or null, the template defaults to the methods enabled for the program.

Example

[
  "co_breb"
]

Response Body

`application/json`

curl -X POST "https://api.sandbox.cuentamono.com/v1/core/payins/templates" \  -H "Content-Type: application/json" \  -d '{    "usage_mode": "single_use",    "subaccount_id": "lacc_5tgliBmzjZ6mpQPRbQjfKj",    "external_id": "invoice-2026-0042"  }'

{
  "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"
  ]
}

{
  "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": "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"
}

Creates a template

Authorization

Request Body

Response Body

200application/json

201application/json

400application/json

401application/json

403application/json

422application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`