# SPEI

### **Proceso de pago**

<figure><img src="/files/mrWkPNPDpgn9MS5mizrE" alt=""><figcaption></figcaption></figure>

1. El usuario realiza un pedido en el sitio web del comerciante y elige el pago por SPEI.
2. El comerciante inicia una solicitud de pago por SPEI a Supefina.
3. Supefina devuelve la referencia de pago (número CLABE); si "checkOut" es "true", se devuelve una página de caja con el número CLABE; si "checkOut" es "false", solo se devuelve el número CLABE.
4. El comerciante muestra esa referencia de pago (número CLABE) al usuario.
5. El usuario copia esa referencia de pago (número CLABE).
6. El usuario abre la app del banco, selecciona transferencia, ingresa la referencia de pago copiada (número CLABE) y el monto para completar la transferencia.
7. Supefina notifica al comerciante que el pedido fue exitoso.

### Dirección de solicitud

<table data-full-width="true"><thead><tr><th width="206">Nombre del entorno</th><th>URL</th></tr></thead><tbody><tr><td>SandBox </td><td><mark style="color:blue;"><code>POST</code></mark><br>https://api.supefina.tech/api/supefina/transactions/payin</td></tr><tr><td>Producción </td><td><mark style="color:red;"><code>POST</code></mark><br><mark style="color:red;">https://api.supefina.net/api/supefina/transactions/payin</mark></td></tr></tbody></table>

### Parámetros de solicitud

#### Encabezado de solicitud

<table data-full-width="true"><thead><tr><th>Key</th><th>Value</th></tr></thead><tbody><tr><td><code>Content-Type</code></td><td><code>application/json</code></td></tr></tbody></table>

**Cuerpo de solicitud**

<table data-full-width="true"><thead><tr><th width="199"> Nombre de variable</th><th width="97">Tipo</th><th width="121">Obligatorio</th><th width="506">Descripción</th></tr></thead><tbody><tr><td>countryId</td><td>String</td><td>Sí</td><td>Código del país<br>Referencia：<a href="/pages/17IKBEvxR4cpZue8BRdD#afwzp">Tabla de diccionario-Código del país</a><br>Mexico：<code>MEX</code></td></tr><tr><td>currency</td><td>String</td><td>Sí</td><td>Moneda <br>Referencia：<a href="/pages/17IKBEvxR4cpZue8BRdD#huo-bi-currency">Tabla de diccionario-Moneda</a><br>Peso mexicano：<code>MXN</code></td></tr><tr><td>payProduct</td><td>String</td><td>Sí</td><td><a href="/pages/17IKBEvxR4cpZue8BRdD#mfocd">Tipo de pago</a><br>SPEI：<code>15</code></td></tr><tr><td>maxOrderAmount</td><td>String</td><td>Sí</td><td><p>Monto máximo </p><p>Debe ser mayor o igual al monto de pedido</p></td></tr><tr><td>minOrderAmount</td><td>String</td><td>Sí</td><td><p>Monto mínimo </p><p>Debe ser menor o igual al monto de pedido</p></td></tr><tr><td>orderAmount</td><td>String</td><td>Sí</td><td><p>Monto del pedido</p><ol><li>Si no se ingresan (máximo y mínimo) montos del pedido, se validará el <code>orderAmount</code>; si el monto pagado no es igual a <code>orderAmount</code>, se rechazará el pago.</li><li>Si se ingresan (máximo y mínimo) montos del pedido, se validará dentro de ese rango.</li><li>Unidad en pesos, se pueden ingresar decimales, soporta hasta dos decimales.</li><li>Si se utilizan los parámetros <code>orderAmount</code>, <code>repeat</code>, <code>maxOrderAmount</code>, <code>minOrderAmount</code>, y el monto de pago no cumple con los requisitos, la transacción será rechazada; el canal cobrará una tarifa fija de 6 pesos, y las tarifas generadas por el rechazo serán asumidas por el comerciante. Por favor, considere cuidadosamente.</li></ol></td></tr><tr><td>repeat</td><td>Boolean</td><td>Sí</td><td>Si se reutiliza Clabe<br><code>true</code>：uso múltiple<br><code>false</code>：uso único</td></tr><tr><td>merId</td><td>String</td><td>Sí</td><td><p>ID del comerciante </p><p>Ruta para obtener el ID del comerciante: Panel de comerciante Supefina - Gestión de comerciantes - Información básica - ID del comerciante</p></td></tr><tr><td>merOrderNo</td><td>String</td><td>Sí</td><td>Número de pedido del comerciante</td></tr><tr><td>nonceStr</td><td>String</td><td>Sí</td><td><p>Cadena aleatoria </p><p>La longitud no puede exceder 32 caracteres</p></td></tr><tr><td>callbackUrl</td><td>String</td><td>No</td><td><p>Dirección de callback</p><p>Consulte la <a href="/pages/L5h5HTfYtaLWtbYEgScv">explicación de notificación de callback</a></p></td></tr><tr><td>sign</td><td>String</td><td>Sí</td><td>Firma<br><a href="/pages/DR0Ieg3d88mBdWrXD882">Referencia específica: algoritmo de firma</a></td></tr></tbody></table>

#### Ejemplo de solicitud

{% code fullWidth="true" %}

```json
{
	"callbackUrl": "https://test.com",
	"countryId": "MEX",
	"currency": "MXN",
	"maxOrderAmount": "15000.00",
	"merId": "8302921196770572",
	"merOrderNo": "2025072419233923321993765",
	"minOrderAmount": "10.00",
	"nonceStr": "737eb662f1384c4490c77d7565518d22",
	"orderAmount": "30",
	"payProduct": "15",
	"repeat": true,
	"sign": "C7AC1590DCFF78529C5B433F4500CC8A"
}
```

{% endcode %}

#### ensamblar una cadena de firma

`callbackUrl=https://test.com&countryId=MEX&currency=MXN&maxOrderAmount=15000.00&merId=8302921196770572&merOrderNo=2025072419233923321993765&minOrderAmount=10.00&nonceStr=737eb662f1384c4490c77d7565518d22&orderAmount=30&payProduct=15&repeat=true&key=de53650e1a6b494087d8c472516cc1cb`

### Parámetros de respuesta

<table data-full-width="true"><thead><tr><th width="220">Nombre de variable</th><th width="119">Tipo</th><th width="355">Descripción</th></tr></thead><tbody><tr><td>code</td><td>String</td><td>Código de respuesta<br>Referencia específica: <a href="/pages/j56ENY9y4TEhx8ssOv8a">Códigos de estado de respuesta</a></td></tr><tr><td>data</td><td>Object</td><td>Datos de respuesta</td></tr><tr><td>amount</td><td>BigDecimal</td><td>Monto del pedido</td></tr><tr><td>channelName</td><td>String</td><td>Banco correspondiente a Clabe</td></tr><tr><td>identifier</td><td>String</td><td>Identificador de referencia del pago<br>Clabe</td></tr><tr><td>merCode</td><td>String</td><td>ID de comerciante</td></tr><tr><td>merOrderNo</td><td>String</td><td>Número de pedido del comerciante</td></tr><tr><td>transactionStatus</td><td>String</td><td><p>Estado del pedido. Este estado indica si la solicitud fue exitosa, sin relación con el estado real de la transacción. </p><p><code>00</code>: Pedido exitoso; </p><p><code>04</code>: Pedido fallido.</p></td></tr><tr><td>url</td><td>String</td><td>Enlace de la transacción</td></tr><tr><td>msg</td><td>String</td><td>Descripción de la respuesta</td></tr></tbody></table>

#### Ejemplo de respuesta

{% code fullWidth="true" %}

```json
{
	"code": "200",
	"msg": "success ",
	"data": {
		"merCode": "8302921196770572",
		"merOrderNo": "2025072419233923321993765",
		"amount": 30,
		"transactionStatus": "00",
		"url": "https://h5.supefina.net/clabe?token=tg3njqvv98nvml8i",
		"identifier": "736869302197372480",
		"channelName": "DEMO"
	}
}
```

{% endcode %}

### **Notificación de callback**

Método de envío: `POST`

<table data-full-width="true"><thead><tr><th width="220"> Nombre de variable</th><th width="119">Tipo</th><th width="355">Descripción</th></tr></thead><tbody><tr><td>payerName</td><td>String</td><td>Nombre del pagador</td></tr><tr><td>payerAccount</td><td>String</td><td>Número de cuenta del pagador</td></tr><tr><td>amount</td><td>String</td><td>Monto del pedido</td></tr><tr><td>countryId</td><td>String</td><td><p>Código del país.</p><p>Referencia: <a href="/pages/17IKBEvxR4cpZue8BRdD#afwzp">Tabla de diccionario - Códigos de país</a></p><p>México: MEX</p></td></tr><tr><td>fee</td><td>String</td><td>Comisión anticipada</td></tr><tr><td>identifier</td><td>String</td><td>Referencia de pago<br>Clabe</td></tr><tr><td>merId</td><td>String</td><td>ID del comerciante</td></tr><tr><td>merOrderId</td><td>String</td><td>Número de pedido del comerciante</td></tr><tr><td>msg</td><td>String</td><td>Descripción de la respuesta</td></tr><tr><td>nonceStr</td><td>String</td><td><p>Cadena aleatoria </p><p>La longitud no puede exceder 32 caracteres</p></td></tr><tr><td>realityAmount</td><td>String</td><td>Monto recibido</td></tr><tr><td>realityFee</td><td>String</td><td>Comisión recibida</td></tr><tr><td>reference</td><td>String</td><td>Identificador</td></tr><tr><td>sign</td><td>String</td><td>Firma</td></tr><tr><td>status</td><td>String</td><td><p><a href="/pages/17IKBEvxR4cpZue8BRdD#kxzkj">Estado de la transacción</a> </p><p>Referencia específica: <a href="/pages/17IKBEvxR4cpZue8BRdD#kxzkj">Tabla de diccionario - Estado del pedido de transacción</a></p></td></tr><tr><td>successTime</td><td>Date</td><td><p>Tiempo de éxito de la transacción</p><p>Hora UTC</p></td></tr><tr><td>supefinaOrderId</td><td>String</td><td>Número del pedido de Supefina</td></tr><tr><td>transactionType</td><td>String</td><td>Tipo de transacción<br><code>01</code>：Payin<br><code>02</code>：Payout</td></tr></tbody></table>

#### Ejemplo de notificación de callback

{% code fullWidth="true" %}

```json
{
	"amount": "30.00",
	"countryId": "MEX",
	"fee": "1.00",
	"identifier": "736869302197372480",
	"merId": "8302921196770572",
	"merOrderId": "2025072419233923321993765",
	"msg": "交易成功",
	"nonceStr": "b607adb6-bec4-44cc-a60a-7d3c4c",
	"realityAmount": "30",
	"realityFee": "1.00",
	"reference": "CRTYPODPDYJW4V2XK5QZ6LGSNYRPG5R",
	"sign": "1A341F36DE64A915D62A11721DEC0EB1",
	"status": "01",
	"successTime": 1753356221224,
	"supefinaOrderId": "202507b926c36081de43ee9a1cfb9ade91ef5a",
	"transactionType": "01"
}
```

{% endcode %}

#### ensamblar una cadena de firma

callbackUrl=<https://test.com\\&countryId=MEX\\&currency=MXN\\&maxOrderAmount=15000.00\\&merId=8302921196770572\\&merOrderNo=2025072419233923321993765\\&minOrderAmount=10.00\\&nonceStr=737eb662f1384c4490c77d7565518d22\\&orderAmount=30\\&payProduct=15\\&repeat=true\\&key=de53650e1a6b494087d8c472516cc1cb>

**Respuesta de notificación de callback**

Después de que el comerciante reciba correctamente la notificación de callback, debe devolver la cadena especificada: `SUCCESS`. Si no se devuelve o se devuelve otro contenido, se considerará que la notificación ha fallado. Por ejemplo:

{% code fullWidth="true" %}

```java
public String test(){
	return "SUCCESS";
}
```

{% endcode %}

{% hint style="info" %}
**Atención**

Después de que el usuario complete el pago, el sistema de pago enviará los resultados relacionados a través de un flujo de datos al comerciante, quien deberá recibir y procesar esta información, y devolver una respuesta conforme a la normativa del documento.

1. La misma notificación puede ser enviada varias veces al sistema del comerciante. El sistema del comerciante debe ser capaz de manejar correctamente las notificaciones duplicadas.
2. Durante la interacción de notificaciones en segundo plano, si el sistema de pago recibe una respuesta del comerciante que no cumple con la normativa o si hay un tiempo de espera, el sistema de pago considerará que la notificación ha fallado y <mark style="color:red;">volverá a enviar la notificación (si la notificación sigue sin tener éxito, el sistema de pagos realizará múltiples intentos, con una frecuencia de 0min/3min/6min/9min/12min)</mark>, pero el sistema de pago no garantiza que la notificación finalmente tenga éxito.
3. En caso de que el estado del pedido sea incierto o no se haya recibido la notificación del resultado del pago, se recomienda que el comerciante llame proactivamente a la \[API de consulta] para confirmar el estado del pedido.
4. En caso de pagos duplicados, SPEI puede presentar situaciones de múltiples pagos; por favor, tenga en cuenta cómo manejar las notificaciones de múltiples pagos recibidas. En caso de múltiples pagos, Supefina creará varios pedidos y notificará al comerciante varias veces; el comerciante puede determinar si se trata del mismo pedido a través del `supefinaOrderId` en la notificación. Al realizar múltiples pagos, el `identifier` permanece igual, mientras que el `supefinaOrderId` y el `reference` son diferentes cada vez (en el caso del banco HSBC, puede haber múltiples pagos con el mismo `reference`).
   {% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developers.supefina.net/bienvenido-a-la-documentacion-api-de-supefina/payin/mexico/spei.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.