---
title: "Crear Referencia Pagos Referenciados"
method: POST
path: "/referenced-payment-mx/public/reference"
tags: ["Efectivo"]
---

# Crear Referencia Pagos Referenciados

`POST /referenced-payment-mx/public/reference`

## Request

- Base URL: `https://api.trytoku.com`
- URL: `https://api.trytoku.com/referenced-payment-mx/public/reference`
- Auth: API key in header `x-api-key`

Genera la Referencia con la que un Customer paga en BBVA.

Devuelve la referencia numérica y el número de convenio CIE que el Customer informa al pagar, junto con el monto y la fecha de expiración cuando la configuración de recaudación de la Organization los usa. Pedirla dos veces con los mismos datos devuelve la Referencia que ya existe en vez de crear otra, así que reintentar es seguro.

Qué campos aplican depende del algoritmo de referencia configurado para la Organization: `amount` y `expiration_date` son obligatorios en algunas configuraciones, se ignoran en otras y en otras se rechazan. Los errores 400 indican cuál de esos casos aplica.

## Request body

- ReferencedPaymentMxReferenceCreateInput: Datos para generar una Referencia de pago referenciado de un Customer.
  - `additional_metadata` object, nullable: Metadatos adicionales opcionales que se asocian a la Referencia.
  - `amount` union: Monto exacto a pagar. Según la configuración de recaudación de la Organization puede ser obligatorio o no aplicar; cuando no aplica, el valor enviado se ignora.
    - number
    - string
  - `expiration_date` string, date, nullable: Fecha a partir de la cual la Referencia deja de aceptar pagos. Su uso depende de la configuración de recaudación de la Organization; en algunas configuraciones no está permitida.
  - `id_customer` string, required: Identificador del Customer para el que se genera la Referencia.

## Response `200`

Successful Response

- ReferencedPaymentMxReferenceCreateResponse: Referencia de pago generada con la que el Customer paga en el banco.
  - `account_identifier` string, required: Número de convenio CIE de BBVA al que queda asociada la Referencia.
  - `amount` union: Monto exacto a pagar asociado a la Referencia, si aplica.
    - integer
    - number
  - `expiration_date` string, date, nullable: Fecha a partir de la cual la Referencia deja de aceptar pagos, si aplica.
  - `reference` string, required: Referencia numérica que el Customer informa al pagar.

## Other responses

- `400`: El algoritmo configurado para la Organization no admite los campos enviados: `Amount is required for reference creation` cuando falta el monto y el algoritmo lo exige, o `Expiration date is not allowed for reference creation` cuando se envía una fecha de expiración y el algoritmo no la usa.
- `401`: Faltan las credenciales o son inválidas.
- `403`: La Organization no tiene configurada la recaudación por convenio CIE. Requiere que el equipo de operaciones la habilite.
- `404`: El `id_customer` enviado no corresponde a ningún Customer de una Organization.
- `422`: El cuerpo de la petición no pasó la validación.
- `429`: Se superó el límite de peticiones permitidas.
- `500`: No se pudo generar una Referencia utilizable para esos datos. Es reintentable y, si persiste, requiere revisión de Toku.

## Changes

- **2026-11-03** `a6ef070075b1`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/trytoku/apis/toku-api/changes/referenced-payment-mx/public/reference/post.md)

---

[API](https://skmtc.dev/trytoku/apis/toku-api.md) - [All operations](https://skmtc.dev/trytoku/apis/toku-api/llms.txt) - [OpenAPI document](https://skmtc.dev/trytoku/apis/toku-api/revisions/a6ef070075b1?raw)