# SPEI

### 支付流程

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

1、用户在商户网站进行下单选择SPEI付款；

&#x20;2、商户向Supefina发起SPEI支付请求；

&#x20;3、Supefina返回付款参考（CLABE账号）信息； 当“checkOut”是“true”则返回带有CLABE账号的收银台页面，当“checkOut”是“false”则只返回CLABE账号。

&#x20;4、商户将该付款参考（CLABE账号）展示给用户；

&#x20;5、用户复制该付款参考（CLABE账号）。

&#x20;6、用户打开银行APP选择转账，输入复制的付款参考（CLABE账号）和金额完成转账。

&#x20;7、Supefina通知商户订单成功。

### 请求地址

<table data-full-width="true"><thead><tr><th width="135">环境名称</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><mark style="color:red;">正式环境</mark> </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>

### 请求参数

#### 请求头

<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>

#### 请求体

<table data-full-width="true"><thead><tr><th width="188">变量名</th><th width="97">类型</th><th width="85">必填</th><th width="506">描述</th></tr></thead><tbody><tr><td>countryId</td><td>String</td><td>是</td><td>国家编号<br>参照：<a href="/pages/17IKBEvxR4cpZue8BRdD#afwzp">字典表-国家编号</a><br>墨西哥：<code>MEX</code></td></tr><tr><td>currency</td><td>String</td><td>是</td><td>币种<br>参照：<a href="/pages/17IKBEvxR4cpZue8BRdD#huo-bi-currency">字典表-货币</a><br>墨西哥比索：<code>MXN</code></td></tr><tr><td>payProduct</td><td>String</td><td>是</td><td><a href="/pages/17IKBEvxR4cpZue8BRdD#mfocd">支付类型</a><br>SPEI：<code>15</code></td></tr><tr><td>maxOrderAmount</td><td>String</td><td>否</td><td>最大订单金额<br>需要大于等于订单金额</td></tr><tr><td>minOrderAmount</td><td>String</td><td>否</td><td><p>最小订单金额<br>需要小于等于订单金额</p><p>建议传<code>00.00</code></p></td></tr><tr><td>orderAmount</td><td>String</td><td>是</td><td><p>订单金额<br>1、未传入（最大和最小）订单金额时，用户支付则会对<code>orderAmount</code>进行校验，用户支付金额与<code>orderAmount</code>不相等时，则支付拒绝；<br>2、若传入（最大和最小）订单金额时，以该区间金额进行校验。<br>3、单位比索，需要分可以传入小数，支持两位小数</p><p>4、若使用了订单金额<code>orderAmount</code>、<code>repeat</code>、<code>maxOrderAmount</code>、<code>minOrderAmount</code>参数，付款金额不符合参数要求导致交易被拒，渠道会固定收取6比索手续费,交易被拒产生的手续费需商户自行承担，请慎重考虑。</p></td></tr><tr><td>repeat</td><td>Boolean</td><td>是</td><td>Clabe是否重复使用<br><code>true</code>：多次使用<br><code>false</code>：单次使用</td></tr><tr><td>merId</td><td>String</td><td>是</td><td>商户ID<br>商户ID获取路径：Supefina商户后台-商户管理-基本信息-商户ID</td></tr><tr><td>merOrderNo</td><td>String</td><td>是</td><td>商户订单号</td></tr><tr><td>nonceStr</td><td>String</td><td>是</td><td>随机字符串<br>长度不能超过32位</td></tr><tr><td>callbackUrl</td><td>String</td><td>是</td><td><p>回调地址</p><p>详见<a href="/pages/mfMq4AmXGJtMyIPchGsF">通知回调说明</a></p></td></tr><tr><td>sign</td><td>String</td><td>是</td><td>签名<br><a href="/pages/DR0Ieg3d88mBdWrXD882">具体参照：签名算法</a></td></tr></tbody></table>

#### 请求示例

{% 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 %}

#### 签名组装字符串

`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`

### 响应参数

<mark style="color:red;">注意：由于SPEI支付仅在用户支付成功后才创建订单，因此响应中不会包含Supefina订单号。</mark>

<table data-full-width="true"><thead><tr><th width="220">变量名</th><th width="119">类型</th><th width="355">描述</th></tr></thead><tbody><tr><td>code</td><td>String</td><td>响应编码<br>具体参照：<a href="/pages/j56ENY9y4TEhx8ssOv8a">响应状态码</a></td></tr><tr><td>data</td><td>Object</td><td>响应数据</td></tr><tr><td>amount</td><td>BigDecimal</td><td>订单金额</td></tr><tr><td>channelName</td><td>String</td><td>Clabe所属银行</td></tr><tr><td>identifier</td><td>String</td><td>付款参考标识符<br>Clabe</td></tr><tr><td>merCode</td><td>String</td><td>商户ID</td></tr><tr><td>merOrderNo</td><td>String</td><td>商户订单号</td></tr><tr><td>transactionStatus</td><td>String</td><td>下单状态<br>该笔订单的的发起状态是否成功，与订单真正的交易状态无关。<br><code>00</code>：下单成功<br><code>04</code>：下单失败</td></tr><tr><td>url</td><td>String</td><td>交易链接</td></tr><tr><td>msg</td><td>String</td><td>响应描述</td></tr></tbody></table>

#### 响应示例

{% 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 %}

### 回调通知

提交方式：`POST`

<table data-full-width="true"><thead><tr><th width="220">变量名</th><th width="119">类型</th><th width="355">描述</th></tr></thead><tbody><tr><td>amount</td><td>String</td><td>订单金额</td></tr><tr><td>countryId</td><td>String</td><td>国家编号<br>参照：<a href="/pages/17IKBEvxR4cpZue8BRdD#afwzp">字典表-国家编号</a><br>墨西哥：MEX</td></tr><tr><td>fee</td><td>String</td><td>预收手续费</td></tr><tr><td>identifier</td><td>String</td><td>付款参考<br>Clabe</td></tr><tr><td>merId</td><td>String</td><td>商户ID</td></tr><tr><td>merOrderId</td><td>String</td><td>商户订单号</td></tr><tr><td>msg</td><td>String</td><td>响应描述</td></tr><tr><td>nonceStr</td><td>String</td><td>随机字符串<br>长度不能超过32位</td></tr><tr><td>realityAmount</td><td>String</td><td>实收金额</td></tr><tr><td>realityFee</td><td>String</td><td>实收手续费</td></tr><tr><td>reference</td><td>String</td><td>标识符</td></tr><tr><td>sign</td><td>String</td><td>签名</td></tr><tr><td>status</td><td>String</td><td><a href="/pages/17IKBEvxR4cpZue8BRdD#kxzkj">交易状态</a><br>具体参照：<a href="/pages/17IKBEvxR4cpZue8BRdD#kxzkj">字典表——交易订单状态</a></td></tr><tr><td>successTime</td><td>Date</td><td>交易成功时间<br>UTC时间</td></tr><tr><td>supefinaOrderId</td><td>String</td><td>supefina订单号</td></tr><tr><td>transactionType</td><td>String</td><td>交易类型<br><code>01</code>：代收<br><code>02</code>：代付</td></tr></tbody></table>

#### 回调通知示例

{% 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 %}

签名组装字符串

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>

**回调通知响应**

商户成功收到回调后需同步返回指定字符串：`SUCCESS` 不返回或返回其他内容默认通知失败\
如：

{% code fullWidth="true" %}

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

{% endcode %}

{% hint style="info" %}
**注意**

用户支付完成后，支付系统会把相关支付结果通过数据流的形式发送给商户，商户需要接收处理，并按文档规范返回应答。&#x20;

1. 同样的通知可能会多次发送给商户系统。商户系统必须能够正确处理重复的通知。
2. 后台通知交互时，如果支付系统收到商户的应答不符合规范或超时，支付系统会判定本次通知失败，<mark style="color:red;">重新发送通知（在通知一直不成功的情况下，支付系统总共会发起多次通知，通知频率为0min/3min/6min/9min/12min</mark>）但支付系统不保证通知最终一定能成功。
3. 在订单状态不明或者没有收到支付结果通知的情况下，建议商户主动调用【查询API】确认订单状态。
4. 重复支付，SPEI存在多次支付情况，请注意处理收到多次支付通知的情况。多次支付，Supefina后台会创建多笔订单,并多次通知商户,商户可以通过通知中的 `supefinaOrderId` 判断是否是同一订单。多次付款时`identifier`不变，`supefinaOrderId`、`reference`每次都不一样（HSBC银行存在多次支付，`reference`相同的情况）
5. SPEI代收仅在用户支付成功后才会创建订单并通知商户，因此用户取消支付或支付失败时不会发送通知。商户收到的回调信息中交易订单状态（transactionStatus）只有两种：【03 支付拒绝】和【01 交易成功】。
   {% 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://docs.supefina.net/huan-ying-shi-yong-supefina-de-api-wen-dang/dai-shou/mo-xi-ge/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.