# 快速开始

## <mark style="color:red;">**【重要通知】当前接口为历史旧接口，后续不再新增功能，长期将逐步下线。为保障业务稳定性与获得完整能力支持，请新接入业务直接对接**</mark>[<mark style="color:$primary;">**新版接口文档**</mark>](https://help.supefina.net/)<mark style="color:red;">**；存量业务建议尽快完成迁移改造。新版接口能力更强、规范更统一，相关对接文档详见：**</mark>[<mark style="color:$primary;">**新版接口文档**</mark>](https://help.supefina.net/)<mark style="color:red;">**。如有迁移疑问，可联系我方技术，运营支持沟通方案。**</mark>

欢迎使用 Supefina 开发人员文档。

在开始前，请联系 Supefina 运营人员获取您在 UAT 环境的`merId`和`key`做技术集成。生产环境中的`merId`和`key`，待获取商户生产账户后，可以在 Supefina 商户系统中进行获取。

### 支付产品 <a href="#sjvrv" id="sjvrv"></a>

Supefina为您提供拉丁美洲本地化，更安全，更便捷的支付解决方案，将您与拉丁美洲多个本地支付方式联系起来，助力您的业务拓展。

<figure><img src="https://3631787624-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FuukVORWjXBgcGu8MirPR%2Fuploads%2FNuhULevu4905O8YC0y4U%2Fimg_v3_02sl_536ea9be-524a-422c-8a9f-2661c9a482hu.png?alt=media&amp;token=55eca719-8b59-45dd-888a-76ffdb55c9a8" alt=""><figcaption></figcaption></figure>

### 代付到账时间

<figure><img src="https://3631787624-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FuukVORWjXBgcGu8MirPR%2Fuploads%2F9NEc73QbBBaIszN6JQsd%2F%E5%88%B0%E8%B4%A6%E6%97%B6%E9%97%B4.jpg?alt=media&amp;token=8af7a847-18e6-4ba7-ac8a-9bd158d5f345" alt=""><figcaption></figcaption></figure>


# 签名算法

## 签名生成步骤

1. 设所有发送或者接收到的数据为集合M，将集合M内非空参数值的参数按照参数名ASCII码从小到大排序（字典序），使用URL键值对的格式（即key1=value1\&key2=value2…）拼接成字符串stringA。
2. 在stringA最后拼接上key（商户密钥）得到stringSignTemp字符串，并对stringSignTemp进行MD5运算，再将得到的字符串所有字符转换为大写，得到sign值signValue。

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

1. 参数名ASCII码从小到大排序（字典序）；
2. 如果参数的值为空不参与签名；
3. 参数名区分大小写；
4. 验证调用返回或支付系统主动通知签名时，数据中sign参数不参与签名，将生成的签名与该sign值作校验。
5. 支付接口可能增加字段，验证签名时必须支持增加的扩展字段。
6. 签名时商户密钥使用设置时的明文（未绑定谷歌验证码可能导致商户后台密钥显示密文）
   {% endhint %}

## 示例

1. 例如请求参数如下：

```json
 {
  "countryId": "COL",
  "currency": "COP",
  "customerAccount": "3720000264",
  "merId": "8301000002750275",
  "merOrderNo": "merOrderNo",
  "nonceStr": "string",
  "orderAmount": "30000",
  "payProduct": "08",
  "nonceStr": "4cKcL83FIsDgjAi"
}
```

2. 根据规则拼接字符串得到待签名的字符串：

```
countryId=COL&currency=COP&customerAccount=3720000264&merId=8301000002750275&merOrderNo=merOrderNo&nonceStr=4cKcL83FIsDgjAi&orderAmount=30000&payProduct=08&key=11111111111111111111111111111111
```

3. 最终签名结果

```
1DD2448C750D92B3AE512F2E493F5665
```

4. 最终请求参数

```
 {
  "countryId": "COL",
  "currency": "COP",
  "customerAccount": "3720000264",
  "merId": "8301000002750275",
  "merOrderNo": "merOrderNo",
  "nonceStr": "string",
  "orderAmount": "30000",
  "payProduct": "08",
  "nonceStr": "4cKcL83FIsDgjAi",
  "sign": "1DD2448C750D92B3AE512F2E493F5665"
}
```

## 签名SDK使用

1. SDK下载见[“字典资源＞下载”-“签名SDK”](/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/xia-zai#qian-ming-sdk)
2. 将“supefina-sign”jar包引入自己的项目
3. 通过com.supefina.sign.SupefinaSignUtils#sign(java.lang.Object,java.lang.String)方法完成签名操作。（参数1：请求参数json对象；参数2：商户密钥）

## 签名Demo

```java
public static String sign(Object data, String key) {
        return sign(JSON.parseObject(JSONObject.toJSONString(data)), key);
    }

public static String sign(Map<String, Object> data, String key) {
        data.remove("sign");
        String signedValue = getSignedValue(data);
        signedValue += "key=" + key;
        log.info("signedValue:{}", signedValue);
        return md5(signedValue, "UTF-8").toUpperCase();
    }

private static String getSignedValue(Map<String, Object> reqMap) {
        Map<String, String> copy = new TreeMap<>();
        reqMap.forEach((k, v) -> {
            if (v != null && !"".equals(v)) {
                copy.put(k, v.toString());
            }
        });
        StringBuilder sb = new StringBuilder();
        copy.forEach((k, v) -> {
            if (v != null) {
                sb.append(k).append("=").append(v).append("&");
            }
        });
        return sb.toString();
    }
```

## 验签demo

```java
String callbackData = "{\n" + "  \"countryId\": \"COL\",\n" + "  \"currency\": \"COP\",\n"
+ "  \"customerAccount\": \"3720000264\",\n" + "  \"merId\": \"8301000002750275\",\n"
+ "  \"merOrderNo\": \"merOrderNo\",\n" + "  \"nonceStr\": \"string\",\n"
+ "  \"orderAmount\": \"30000\",\n" + "  \"payProduct\": \"08\",\n"
+ "  \"nonceStr\": \"4cKcL83FIsDgjAi\",\n" + "  \"sign\": \"1DD2448C750D92B3AE512F2E493F5665\"\n" + "}";
JSONObject data = JSON.parseObject(callbackData);

String sign = data.get("sign").toString();
data.remove("sign");
String signValue = SupefinaSignUtils.sign(data, "商户key");
if (Objects.equals(sign, signValue)) {
    // 验证签名通过
} else {
    // 失败
}
```


# 通知回调说明

## 使用场景 <a href="#spgvh" id="spgvh"></a>

***

用户发起支付，当交易完成之后，Supefina支付系统会通过调用商户提供的回调接口告知交易结果详情，商户需要按响应规则接受并实现自己的处理逻辑。

## 回调配置 <a href="#wqsls" id="wqsls"></a>

***

1. 商户在发起交易前，需要在<商户后台-安全中心>中配置回调地址，否则将无法正常接收交易结果。
2. 回调地址可以配置多个。如需更换或新增回调地址，请先在商户后台进行配置，然后再发起交易。
3. 为保持回调地址的唯一性，建议不要在地址中加入订单号、支付产品等变量。
4. 为确保交易安全，Supefina会对callbackUrl字段与配置的回调地址进行规则校验，请确保二者一致。

## 注意 <a href="#cgzaw" id="cgzaw"></a>

***

1. 支付系统不保证一定能成功通知，在某些情况下可能会通知失败导致商户收不到回调，包括但不限于商户提供的回调地址有误。
2. 商户系统对于结果通知的内容需要做签名验证，签名和验签逻辑见“[签名算法](/huan-ying-shi-yong-supefina-de-api-wen-dang/qian-ming-suan-fa)”。
3. 某些渠道在某些情况下可能存在多次回调的情况，如：先成功，再失败，需要自行增加处理逻辑。

## 常见问题：

Q：Supefina系统显示“通知失败”是什么原因导致的？需要怎么处理？

A：Supefina 系统将订单信息发送至商户提供或配置的回调地址。如果商户未按规则返回"SUCCESS"或返回其他内容，Supefina 系统会认为商户未收到通知。系统会以 3 分钟的间隔进行 5 次连续通知，直到商户返回"SUCCESS"后停止。需要注意的是，通知失败并不一定意味着 Supefina 未进行回调，也可能是商户系统在接收回调后处理失败，这种情况需要商户自行排查解决。

***

Q：如果用户取消支付或者支付失败的话，会通知商户吗？

A：用户取消支付或支付失败时，Supefina通知商户。如果用户在订单过期时间截止前仍未完成支付，系统会向商户发送交易失败通知。<mark style="color:red;">SPEI不包含此通知处理方法。</mark>

***

Q：订单的结算状态是否会进行回调？

A：结算状态不包含在回调信息中。您可以通过[结算状态查询](/huan-ying-shi-yong-supefina-de-api-wen-dang/cha-xun/jie-suan-zhuang-tai-cha-xun)接口查询订单的结算状态。

***

Q：异步通知没收到怎么办？

A：可在对接群内联系运营再次进行通知

***

Q：交易查询API的回调内容里是否包含失败原因？

A：交易失败原因将在回调内容的 errorMsg 字段中显示。


# 代收聚合收银台


# 墨西哥

（多种支付方式集成）

### 目前支持的支付产品

1. Cash
2. SPEI
3. Card
4. OXXO

### 支付流程（具体支付方式的流程请查看代收列表中的文档）

1. 用户在商户网站进行下单付款.
2. 商户向Supefina发起API支付请求.
3. Supefina返回聚合收银台地址以及相关单号数据.
4. 用户在收银台上选择相关的支付方式并进行付款操作.
5. 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="157">类型</th><th width="85">必填</th><th width="506">描述</th></tr></thead><tbody><tr><td>merOrderNo</td><td>String</td><td>是</td><td>商户订单号</td></tr><tr><td>countryId</td><td>String</td><td>是</td><td>国家编号<br>参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#afwzp">字典表-国家编号</a><br>墨西哥：<code>MEX</code></td></tr><tr><td>customerName</td><td>String</td><td>是</td><td>客户姓名</td></tr><tr><td>orderAmount</td><td>BigDecimal</td><td>是</td><td><strong>订单金额(只支持固额付款)</strong><br><strong>1. 如果用户付款金额与下单金额不一致，我们进行相关的退款操作，如果无法退款会有相关运营联系。</strong><br><strong>2. 如果用户在收银台有效期外进行付款操作，我们也会进行相关的退款操作，如果无法退款会有相关运营联系。</strong><br><strong>3. 退款操作针对不同的支付方式会收取相关的手续费，请知悉。</strong><br><strong>4. 手续费金额可联系运营人员。</strong></td></tr><tr><td>merId</td><td>String</td><td>是</td><td>商户ID<br>商户ID获取路径：Supefina商户后台-商户管理-基本信息-商户I</td></tr><tr><td>currency</td><td>String</td><td>是</td><td>币种<br>参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#huo-bi-currency">字典表-货币</a><br>墨西哥比索：<code>MXN</code></td></tr><tr><td>checkOut</td><td>Boolean</td><td>是</td><td>拉取聚合收银台条件<br><strong>此模式下只支持传入true</strong></td></tr><tr><td>description</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>sign</td><td>String</td><td>是</td><td>签名<br><a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/qian-ming-suan-fa">具体参照：签名算法</a></td></tr><tr><td>payProduct</td><td>String</td><td>否</td><td><a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#mfocd">支付类型</a><br>如果不传入则拉取商户配置下全部支付方式的收银台。<br>如果传入相关支付方式，则收银台上只展示对应的支付方式。<br><strong>注意：</strong><br><strong>如果此时传入没有配置的支付方式会返回异常信息。</strong></td></tr><tr><td>callbackUrl</td><td>String</td><td>否</td><td><p>回调地址</p><p>详见<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/tong-zhi-hui-tiao-shuo-ming">通知回调说明</a></p></td></tr><tr><td>expireTimeL</td><td>Long</td><td>否</td><td>收银台过期时间（单位秒）<br><strong>1. 如果不传入默认12H</strong><br><strong>2.如果传入的时间小于3分钟或者大于7天，我们也会默认为12H</strong></td></tr><tr><td>requestData</td><td>Object</td><td>否</td><td>额外参数<br><strong>注意：如果商户配置了Cash的支付方式，此参数必传</strong>。</td></tr><tr><td>businessUnit</td><td>Object</td><td>是</td><td>业务单位</td></tr><tr><td>name</td><td>String</td><td>是</td><td>业务单位的名称</td></tr><tr><td>key</td><td>String</td><td>是</td><td>业务单位的唯一标识</td></tr><tr><td>showHtmlFlag</td><td>String</td><td>是</td><td><p>展示html收款页</p><p> 收款页URL：<code>1</code> </p></td></tr><tr><td>repeat</td><td>Boolean</td><td>否</td><td>Clabe是否重复使用<br><strong>注意：如果指定payProduct为15(SPEI)，此参数必传</strong><br><code>true</code>：多次使用</td></tr><tr><td>productName</td><td>String</td><td>是</td><td>商品名称<br>最大50个字符<br><strong>如果商户配置了Card的支付方式，此参数必传</strong></td></tr><tr><td>email</td><td>String</td><td>否</td><td>顾客邮箱<br>3-256个字符<br><strong>如果商户配置了Card的支付方式，此参数必传</strong></td></tr><tr><td>receiverAddressMain</td><td>String</td><td>否</td><td>收件地址，街道<br>0-50个字符<br><strong>如果商户配置了Card的支付方式，此参数必传</strong></td></tr><tr><td>receiverAddressExtra</td><td>String</td><td>否</td><td>收件地址，小区，门牌号<br>0-50个字符<br><strong>如果商户配置了Card的支付方式，此参数必传</strong></td></tr><tr><td>receiverCity</td><td>String</td><td>否</td><td>收件人城市<br>0-50个字符，可包括空格、连字符、撇号、逗号和点<br><strong>如果商户配置了Card的支付方式，此参数必传</strong></td></tr><tr><td>receiverProvince</td><td>String</td><td>否</td><td>收件人所在省<br>0-40个字符<br>参数：<a href="https://en.wikipedia.org/wiki/ISO_3166-2">https://en.wikipedia.org/wiki/ISO_3166-2</a> 例：NY<br><strong>如果商户配置了Card的支付方式，此参数必传</strong></td></tr><tr><td>receiverCountry</td><td>String</td><td>否</td><td>收件人国家<br>参照：<a href="https://docs.supefina.net/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#afwzp">字典表-国家编号</a> 例：BRA<br><strong>如果商户配置了Card的支付方式，此参数必传</strong></td></tr><tr><td>receiverZipCode</td><td>String</td><td>否</td><td>邮政编码<br>0-12个字母或数字<br><strong>如果商户配置了Card的支付方式，此参数必传</strong></td></tr><tr><td>receiverPhone</td><td>String</td><td>否</td><td>收件人电话<br>5-20个字符，区添加区号。如：+1 111111111<br><strong>如果商户配置了Card的支付方式，此参数必传</strong></td></tr></tbody></table>

### 请求示例

1. 开通全部支付方式 — 不传入payProduct

<pre class="language-json"><code class="lang-json">{
    "merOrderNo": "20240920195501",
    "sign": "xxxx",
    "requestData": {
        "businessUnit": {
            "key": "11",
            "name": "123456"
        },
        "showHtmlFlag": "1"
    },
    "countryId": "MEX",
    "nonceStr": "20240920195501",
    "customerName": "xx",
    "orderAmount": 100,
    "merId": "xxxxx",
    "checkOut": "true",
    "currency": "MXN",
    "callbackUrl": "xxxx",
    "productName": "test1",
    "email": "xxxx",
    "receiverAddressMain": "xxxx",
    "receiverAddressExtra": "xx",
    "receiverCity": "xxxx",
    "receiverCountry": "MEX",
    "receiverPhone": "+86123456789012345",
    "receiverProvince": "Example city",
    "receiverZipCode": "xxx",
    "description": "supefina",
    "expireTimeL": 3600
<strong>}
</strong></code></pre>

2. 开通部分支付方式(Cash和SPEI) — 不传入payProduct

```json
{
    "merOrderNo": "20240920195501",
    "sign": "xxxx",
    "requestData": {
        "businessUnit": {
            "key": "1098345673212",
            "name": "epay"
        },
        "showHtmlFlag": "1"
    },
    "countryId": "MEX",
    "nonceStr": "20240920195501",
    "customerName": "xxx",
    "orderAmount": 100,
    "merId": "xxxxx",
    "checkOut": "true",
    "currency": "MXN",
    "callbackUrl": "xxxx",
    "description": "supefina",
    "expireTimeL": 3600
}
```

3. 开通部分支付方式(Cash和Card) — 不传入payProduct

```json
{
    "merOrderNo": "20240920195501",
    "sign": "xxxx",
    "requestData": {
        "businessUnit": {
            "key": "11",
            "name": "123456"
        },
        "showHtmlFlag": "1"
    },
    "countryId": "MEX",
    "nonceStr": "20240920195501",
    "customerName": "xx",
    "orderAmount": 100,
    "merId": "xxxxx",
    "checkOut": "true",
    "currency": "MXN",
    "callbackUrl": "xxxx",
    "productName": "test1",
    "email": "xxxx",
    "receiverAddressMain": "xxxx",
    "receiverAddressExtra": "xx",
    "receiverCity": "xxxx",
    "receiverCountry": "MEX",
    "receiverPhone": "+86123456789012345",
    "receiverProvince": "Example city",
    "receiverZipCode": "xxx",
    "description": "supefina",
    "expireTimeL": 3600
}
```

4. 传入指定的支付方式

* payProduct：03

```json
{
    "merOrderNo": "20240920195501",
    "sign": "xxxxxx",
    "requestData": {
        "businessUnit": {
            "key": "111",
            "name": "123456"
        },
        "showHtmlFlag": "1"
    },
    "payProduct":"03",
    "countryId": "MEX",
    "nonceStr": "20240920195501",
    "customerName": "xxx",
    "orderAmount": 100,
    "merId": "xxxxx",
    "checkOut": "true",
    "currency": "MXN",
    "callbackUrl": "xxxxxx",
    "description": "supefina",
    "expireTimeL": 3600
}
```

* payProduct：15

```json
{
    "merOrderNo": "20240920195501",
    "sign": "xxxxx",
    "payProduct":"15",
    "repeat":true,
    "countryId": "MEX",
    "nonceStr": "20240920195501",
    "customerName": "xxxx",
    "orderAmount": 100,
    "merId": "xxxxx",
    "checkOut": "true",
    "currency": "MXN",
    "callbackUrl": "xxxxxx",
    "description": "supefina",
    "expireTimeL": 3600
}
```

* payProduct：18

```json
{
    "merOrderNo": "20240920195501",
    "sign": "xxxxxxx",
    "payProduct":"18",
    "countryId": "MEX",
    "nonceStr": "20240920195501",
    "customerName": "xxxx",
    "orderAmount": 100,
    "merId": "xxxxx",
    "checkOut": "true",
    "currency": "MXN",
    "callbackUrl": "xxxxx",
    "productName": "test1",
    "email": "xxxxxx",
    "receiverAddressMain": "xxxxxx",
    "receiverAddressExtra": "xxxxx",
    "receiverCity": "Example city",
    "receiverCountry": "MEX",
    "receiverPhone": "+86123456789012345",
    "receiverProvince": "Example city",
    "receiverZipCode": "xxxxx",
    "description": "supefina",
    "expireTimeL": 3600
}
```

### 响应参数

<table data-full-width="true"><thead><tr><th width="215">变量名</th><th width="119">类型</th><th width="355">描述</th></tr></thead><tbody><tr><td>code</td><td>String</td><td>响应编码<br>具体参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/xiang-ying-zhuang-tai-ma">响应状态码</a></td></tr><tr><td>msg</td><td>String</td><td>响应描述</td></tr><tr><td>data</td><td>Object</td><td>响应数据</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>supefinaOrderNo</td><td>String</td><td>Supefina订单号</td></tr><tr><td>amount</td><td>BigDecimal</td><td>订单金额</td></tr><tr><td>url</td><td>String</td><td>交易链接</td></tr><tr><td>currency</td><td>String</td><td>币种</td></tr></tbody></table>

### 响应示例 — 成功

```json
{
    "code": "200",
    "msg": "success ",
    "data": {
        "merCode": "xxxxx",
        "merOrderNo": "20240920195501",
        "supefinaOrderNo": "2025011877286055912513536",
        "amount": 100,
        "url": "http://h5.supefina.tech/combineCashier?token=3eeec61dc9544b41b9086e953b52571c",
        "currency": "MXN"
    }
}
```

### 响应示例 — 失败

```json
{
    "code": "400",
    "msg": "param error : requestData is null"
}

```

### 回调通知 — 提交方式：`POST`

<table data-full-width="true"><thead><tr><th width="220">变量名</th><th width="119">类型</th><th width="406.25">描述</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="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#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="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#kxzkj">交易状态</a><br>具体参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#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>：代收</td></tr></tbody></table>

#### 回调通知示例

```json
{
    "amount": "30.00",
    "countryId": "MEX",
    "fee": "3.30",
    "identifier": "706180968985601627",
    "merId": "8302636872670229",
    "merOrderId": "P1790641845848850466",
    "msg": "SUCCESS",
    "nonceStr": "03aeeb11-0ad8-42dd-9f00-be1aae",
    "realityAmount": "30.00",
    "realityFee": "3.30",
    "reference": "3843CP03202405190062858560",
    "sign": "27C5933E426DD7A9EABD5C9D50F6BEBE",
    "status": "01",
    "successTime": 1715757366244,
    "supefinaOrderId": "202405150301469d1e0b38e7fdc46",
    "transactionType": "01"
}
```

**回调通知响应**

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

{% code fullWidth="true" %}

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

{% endcode %}


# 秘鲁

（多种支付方式集成）

### 目前支持的支付产品

1. Cash
2. Transfer

### 支付流程（具体支付方式的流程请查看代收列表中的文档）

1. 用户在商户网站进行下单付款.
2. 商户向Supefina发起API支付请求.
3. Supefina返回聚合收银台地址以及相关单号数据.
4. 用户在收银台上选择相关的支付方式并进行付款操作.
5. 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="257">变量名</th><th width="104">类型</th><th width="100">必填</th><th width="428">描述</th></tr></thead><tbody><tr><td>countryId</td><td>String</td><td>是</td><td><p>国家编号<br>参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#afwzp">字典表-国家编号</a></p><p>秘鲁：<code>PER</code></p></td></tr><tr><td>currency</td><td>String</td><td>是</td><td><p>币种<br>参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#huo-bi-currency">字典表-货币</a></p><p>秘鲁索尔：<code>PEN</code></p></td></tr><tr><td>orderAmount</td><td>String</td><td>是</td><td>订单金额</td></tr><tr><td>payProduct</td><td>String</td><td>否</td><td><a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#mfocd">支付类型</a><br>如果不传入则拉取商户配置下全部支付方式的收银台。<br>如果传入相关支付方式，则收银台上只展示对应的支付方式。<br><strong>注意：</strong><br><strong>如果此时传入没有配置的支付方式会返回异常信息。</strong></td></tr><tr><td>customerIdentification</td><td>String</td><td>是</td><td><p>用户证件号<br><code>00</code>：身份证（CC），8位<br><code>01</code>：外国人身份证（CE），大于9位<br><code>02</code>：税号，11位</p><p><code>03</code>：护照，大于9位</p><p><code>04</code>：离境证（PAR）<br><code>05</code>：军官证（LMI）</p><p>同一个证件号<code>customerIdentification</code>进行代收 不超过20次/天</p></td></tr><tr><td>customerIdentificationType</td><td>String</td><td>是</td><td><p>用户证件类型<br><code>00</code>：身份证（CC）<br><code>01</code>：外国人身份证（CE）</p><p><code>02</code>:   税号<br><code>03</code>：护照（PAS)<br><code>04</code>：离境证（PAR）<br><code>05</code>：军官证（LMI）</p></td></tr><tr><td>customerName</td><td>String</td><td>是</td><td>用户姓名</td></tr><tr><td>lastName</td><td>String</td><td>是</td><td>用户姓氏</td></tr><tr><td>customerPhone</td><td>String</td><td>是</td><td><p>用户电话,  9位数字</p><p>示例：975728895</p></td></tr><tr><td>customerEmail</td><td>String</td><td>是</td><td>用户邮箱</td></tr><tr><td>expireTimeL</td><td>Long</td><td>否</td><td>收银台过期时间（单位秒）<br><strong>1. 如果不传入默认12H</strong><br><strong>2.如果传入的时间小于3分钟或者大于7天，我们也会默认为12H</strong></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>description</td><td>String</td><td>是</td><td>付款相关描述</td></tr><tr><td>callbackUrl</td><td>String</td><td>否</td><td><p>回调地址</p><p>详见<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/tong-zhi-hui-tiao-shuo-ming">通知回调说明</a></p></td></tr><tr><td>checkOut</td><td>Boolean</td><td>是</td><td>拉取聚合收银台条件<br><strong>此模式下只支持传入true</strong></td></tr><tr><td>nonceStr</td><td>String</td><td>是</td><td>随机字符串<br>长度不能超过32位</td></tr><tr><td>sign</td><td>String</td><td>是</td><td>签名<br><a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/qian-ming-suan-fa">具体参照：签名算法</a></td></tr></tbody></table>

### 请求示例

1. 开通全部支付方式 — 不传入payProduct

```json
{
    "customerIdentificationType": "00",
    "lastName": "xxxx",
    "merOrderNo": "20240920195501",
    "sign": "xxxxxx",
    "customerIdentification": "22345678",
    "countryId": "PER",
    "nonceStr": "20240920195501",
    "customerName": "xxxx",
    "customerPhone": "1234567890",
    "orderAmount": 100,
    "customerEmail": "123456@qq.com",
    "merId": "xxxxxxx",
    "checkOut": "true",
    "description":"supefina",
    "currency": "PEN",
    "callbackUrl": "xxxxxxxx"
}
```

2. 传入指定的支付方式

* payProduct：03

```json
{
    "customerIdentificationType": "00",
    "payProduct":"03",
    "lastName": "xxxx",
    "merOrderNo": "20240920195501",
    "sign": "xxxxxx",
    "customerIdentification": "22345678",
    "countryId": "PER",
    "nonceStr": "20240920195501",
    "customerName": "xxxx",
    "customerPhone": "1234567890",
    "orderAmount": 100,
    "customerEmail": "123456@qq.com",
    "merId": "xxxxxxx",
    "checkOut": "true",
    "description":"supefina",
    "currency": "PEN",
    "callbackUrl": "xxxxxxxx"
}
```

* payProduct：12

```json
{
    "customerIdentificationType": "00",
    "payProduct":"12",
    "lastName": "xxxx",
    "merOrderNo": "20240920195501",
    "sign": "xxxxxx",
    "customerIdentification": "22345678",
    "countryId": "PER",
    "nonceStr": "20240920195501",
    "customerName": "xxxx",
    "customerPhone": "1234567890",
    "orderAmount": 100,
    "customerEmail": "123456@qq.com",
    "merId": "xxxxxxx",
    "checkOut": "true",
    "description":"supefina",
    "currency": "PEN",
    "callbackUrl": "xxxxxxxx"
}
```

### 响应参数

<table data-full-width="true"><thead><tr><th width="215">变量名</th><th width="119">类型</th><th width="355">描述</th></tr></thead><tbody><tr><td>code</td><td>String</td><td>响应编码<br>具体参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/xiang-ying-zhuang-tai-ma">响应状态码</a></td></tr><tr><td>msg</td><td>String</td><td>响应描述</td></tr><tr><td>data</td><td>Object</td><td>响应数据</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>supefinaOrderNo</td><td>String</td><td>Supefina订单号</td></tr><tr><td>amount</td><td>BigDecimal</td><td>订单金额</td></tr><tr><td>url</td><td>String</td><td>交易链接</td></tr><tr><td>currency</td><td>String</td><td>币种</td></tr></tbody></table>

### 响应示例 — 成功

```json
{
    "code": "200",
    "msg": "success ",
    "data": {
        "merCode": "xxxxxx",
        "merOrderNo": "20240920195501",
        "supefinaOrderNo": "2025011877295415489306624",
        "amount": 100,
        "url": "http://h5.supefina.tech/combineCashier?token=349472b99a184e0f9da91a3b290d4ad7",
        "currency": "PEN"
    }
}
```

### 响应示例 — 失败

```json
{
    "code": "400",
    "msg": "param error customerName cannot be empty"
}
```

### 回调通知 — 提交方式：`POST`

<table data-full-width="true"><thead><tr><th width="222">变量名</th><th width="138">类型</th><th width="447">描述</th></tr></thead><tbody><tr><td>amount</td><td>String</td><td>订单金额</td></tr><tr><td>countryId</td><td>String</td><td>国家编号</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>商户编号</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="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#kxzkj">交易状态</a><br>具体参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#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>：代收</td></tr></tbody></table>

#### 回调通知示例

{% code fullWidth="true" %}

```json
{
    "amount": "230.00",
    "countryId": "PER",
    "customerName": "Test Name",
    "fee": "6.90",
    "identifier": "90911988431",
    "merId": "8202980903390150",
    "merOrderId": "17922853818122896811753697281175369728",
    "nonceStr": "935111b9-968e-4b3d-9036-fd1acf",
    "realityAmount": "230",
    "realityFee": "6.90",
    "reference": "90911988431",
    "sign": "69DF96903B85CD1408BD6849C62254C0",
    "status": "01",
    "successTime": 1716149235000,
    "supefinaOrderId": "202405190101010696298b1ca1141",
    "transactionType": "01"
}
```

{% endcode %}

**回调通知响应**

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

{% code fullWidth="true" %}

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

{% endcode %}


# 代收

目前我们提供多个国家的多种支付方式，包括信用卡、银行转账、电子钱包以及现金支付。

<figure><img src="https://3631787624-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FuukVORWjXBgcGu8MirPR%2Fuploads%2FbxRLkfmqelnEA3lMmBw8%2Fimg_v3_02sl_536ea9be-524a-422c-8a9f-2661c9a482hu.png?alt=media&amp;token=32b2d95d-3a48-4ae7-aba4-9588fdd18d09" alt=""><figcaption></figcaption></figure>


# 墨西哥

在墨西哥，我们提供银行转账（SPEI），现金支付（Cash），银行卡（Card）等支付产品。

<figure><img src="https://3631787624-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FuukVORWjXBgcGu8MirPR%2Fuploads%2FLJJPZQge3rWpoVFjJDeY%2F%E5%A2%A8%E8%A5%BF%E5%93%A5-update.jpg?alt=media&amp;token=e030d659-ca71-42a9-b370-99c8e9abc021" alt=""><figcaption></figcaption></figure>

{% content-ref url="/pages/OsxFxtXj7qvFebpP1BpS" %}
[SPEI](/huan-ying-shi-yong-supefina-de-api-wen-dang/dai-shou/mo-xi-ge/spei)
{% endcontent-ref %}

{% content-ref url="/pages/MKWRLB5SQpGkHIoFsufA" %}
[Cash](/huan-ying-shi-yong-supefina-de-api-wen-dang/dai-shou/mo-xi-ge/cash)
{% endcontent-ref %}

{% content-ref url="/pages/ZowkrSgIv8ZpVz3xpMJZ" %}
[Card](/huan-ying-shi-yong-supefina-de-api-wen-dang/dai-shou/mo-xi-ge/card)
{% endcontent-ref %}

{% content-ref url="/pages/G2tkrlXQdwGe9wy58NaX" %}
[Broken mention](broken://pages/G2tkrlXQdwGe9wy58NaX)
{% endcontent-ref %}

{% content-ref url="/pages/qjE44AJa9CIR9AeAlt0l" %}
[Broken mention](broken://pages/qjE44AJa9CIR9AeAlt0l)
{% endcontent-ref %}


# SPEI

（payProduct=15）

### 支付流程

<figure><img src="https://3631787624-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FuukVORWjXBgcGu8MirPR%2Fuploads%2FjTBV6U1Z3S5Ao3HO8Buf%2Fclabe.png?alt=media&amp;token=02410b63-ed74-45e0-b9cb-dc6cbcdbbdf6" 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="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#afwzp">字典表-国家编号</a><br>墨西哥：<code>MEX</code></td></tr><tr><td>currency</td><td>String</td><td>是</td><td>币种<br>参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#huo-bi-currency">字典表-货币</a><br>墨西哥比索：<code>MXN</code></td></tr><tr><td>payProduct</td><td>String</td><td>是</td><td><a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#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="/huan-ying-shi-yong-supefina-de-api-wen-dang/tong-zhi-hui-tiao-shuo-ming">通知回调说明</a></p></td></tr><tr><td>sign</td><td>String</td><td>是</td><td>签名<br><a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/qian-ming-suan-fa">具体参照：签名算法</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="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/xiang-ying-zhuang-tai-ma">响应状态码</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="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#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="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#kxzkj">交易状态</a><br>具体参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#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 %}


# Cash

（payProduct=03）

### 支付流程

<figure><img src="https://3631787624-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FuukVORWjXBgcGu8MirPR%2Fuploads%2FvOiwsSm7s4BHBHb8tYpA%2FCash.png?alt=media&amp;token=ca3138f9-70c7-40c7-ace9-0545ab733656" alt=""><figcaption></figcaption></figure>

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

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

&#x20;3、Supefina返回Cash付款码信息。

&#x20;4、商户将该付款码参考展示给用户；

&#x20;5、用户保存付款码信息到可支持的线下网点支付；

6、付款成功；

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

### 请求地址

<table data-full-width="true"><thead><tr><th width="118">环境名称</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="168">变量名</th><th width="97">类型</th><th width="78">必填</th><th width="524">描述</th></tr></thead><tbody><tr><td>countryId</td><td>String</td><td>是</td><td>国家编号<br>参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#afwzp">字典表-国家编号</a><br>墨西哥：<code>MEX</code></td></tr><tr><td>currency</td><td>String</td><td>是</td><td>币种<br>参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#huo-bi-currency">字典表-货币</a><br>墨西哥比索：<code>MXN</code></td></tr><tr><td>orderAmount</td><td>String</td><td>是</td><td>订单金额<br>单位比索，需要分可以传入小数，支持两位小数</td></tr><tr><td>payProduct</td><td>String</td><td>是</td><td><a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#mfocd">支付类型</a><br>Cash：<code>03</code></td></tr><tr><td>merId</td><td>String</td><td>是</td><td>商户ID<br>商户ID获取路径：Supefina商户后台-商户管理-基本信息-商户ID</td></tr><tr><td>expireTimeL</td><td>long</td><td>否</td><td>过期时间，无需传递，固定7*24*60*60=604800秒过期</td></tr><tr><td>description</td><td>String</td><td>是</td><td>订单描述</td></tr><tr><td>merOrderNo</td><td>String</td><td>是</td><td>商户订单号</td></tr><tr><td>requestData</td><td>Object</td><td>是</td><td>额外参数</td></tr><tr><td>businessUnit</td><td>String</td><td>是</td><td>业务单位</td></tr><tr><td>name</td><td>String</td><td>是</td><td>业务单位的名称</td></tr><tr><td>key</td><td>String</td><td>是</td><td>业务单位的唯一标识</td></tr><tr><td>showHtmlFlag</td><td>String</td><td>是</td><td><p>展示html收款页</p><p>只使用Cash二维码：<code>0</code></p><p>收款页URL：<code>1</code> </p></td></tr><tr><td>customerEmail</td><td>String</td><td>否</td><td>顾客邮箱</td></tr><tr><td>appName</td><td>String</td><td>否</td><td>应用主体名称</td></tr><tr><td>sign</td><td>String</td><td>是</td><td>签名<br><a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/qian-ming-suan-fa">具体参照：签名算法</a></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="/huan-ying-shi-yong-supefina-de-api-wen-dang/tong-zhi-hui-tiao-shuo-ming">通知回调说明</a></p></td></tr></tbody></table>

### 请求示例

{% code fullWidth="true" %}

```json

{
	"appName": "Supefina",
	"callbackUrl": "http://test.com",
	"countryId": "MEX",
	"currency": "MXN",
	"customerEmail": "21312312312@qq.com",
	"description": "transas12121dasdasda",
	"expireTimeL": 259200,
	"merId": "8302109931230575",
	"merOrderNo": "2025072919104648604106643",
	"nonceStr": "ade2d8b720cc41bd8738b628ad8dfd0d",
	"orderAmount": 20,
	"payProduct": "03",
	"requestData": {
		"businessUnit": {
			"name": "12",
			"key": "111"
		},
		"showHtmlFlag": "1"
	},
	"sign": "1B7453071B3AB467A3E8F405234552AE"
}
```

{% endcode %}

签名组装字符串

appName=Supefina\&callbackUrl=<http://test.com\\&countryId=MEX\\&currency=MXN\\&customerEmail=21312312312@qq.com\\&description=transas12121dasdasda\\&expireTimeL=259200\\&merId=8302109931230575\\&merOrderNo=2025072919104648604106643\\&nonceStr=ade2d8b720cc41bd8738b628ad8dfd0d\\&orderAmount=20\\&payProduct=03\\&requestData={"businessUnit":{"name":"12","key":"111"},"showHtmlFlag":"1"}\\&key=10b8a891ff6a479e8135f3367c17e87d>

### 响应参数

<table data-full-width="true"><thead><tr><th width="200">变量名</th><th width="220">类型</th><th width="624">描述</th></tr></thead><tbody><tr><td>code</td><td>String</td><td>响应编码<br>具体参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/xiang-ying-zhuang-tai-ma">响应状态码</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>fee</td><td>BigDecimal</td><td>预收手续费</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>supefinaOrderNo</td><td>String</td><td>supefina订单号</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": "8302109931230575",
		"merOrderNo": "2025072919104648604106643",
		"supefinaOrderNo": "202507290301000b99dfd47bbba43",
		"amount": 20,
		"fee": 1.0,
		"transactionStatus": "00",
		"url": "https://h5.supefina.net/pagos?token=vd0u0n5e2rig8346"
	}
}
```

{% endcode %}

### 回调通知

提交方式：`POST`

<table data-full-width="true"><thead><tr><th width="200">变量名</th><th width="153">类型</th><th width="624">描述</th></tr></thead><tbody><tr><td>amount</td><td>String</td><td>订单金额</td></tr><tr><td>countryId</td><td>String</td><td>国家编号<br>参照：字典表-国家编号</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>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>付款参考<br>付款码</td></tr><tr><td>sign</td><td>String</td><td>签名</td></tr><tr><td>status</td><td>String</td><td><a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#kxzkj">交易状态</a><br>具体参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#kxzkj">字典表——交易订单状态</a></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="false" %}

```json
{
	"amount": "20.00",
	"countryId": "MEX",
	"fee": "1.00",
	"merId": "8302109931230575",
	"merOrderId": "2025072919104648604106643",
	"nonceStr": "e2ffce1e-c54b-456d-8f5a-3cadfd",
	"realityAmount": "20",
	"realityFee": "1.00",
	"reference": "CRTPPY8MAQ67WU8AUGWDPL4N25KCTOT",
	"sign": "A89A7822C07E94CA68B814A4A3AC9902",
	"status": "01",
	"successTime": 1753787454313,
	"supefinaOrderId": "202507290301000b99dfd47bbba43",
	"transactionType": "01"
}
```

{% endcode %}

签名组装字符串

amount=20.00\&countryId=MEX\&fee=1.00\&merId=8302109931230575\&merOrderId=2025072919104648604106643\&nonceStr=e2ffce1e-c54b-456d-8f5a-3cadfd\&realityAmount=20\&realityFee=1.00\&reference=CRTPPY8MAQ67WU8AUGWDPL4N25KCTOT\&status=01\&successTime=1753787454313\&supefinaOrderId=202507290301000b99dfd47bbba43\&transactionType=01\&key=10b8a891ff6a479e8135f3367c17e87d

**回调通知响应**

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

{% code fullWidth="false" %}

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

{% endcode %}


# OXXO

（payProduct=32）

### 支付流程

<figure><img src="https://3631787624-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FuukVORWjXBgcGu8MirPR%2Fuploads%2FdwMFjF0reh6yKRmR2RbX%2Fimg_v3_02u4_c336ebb5-a4d9-48ec-ade0-e244186481hu.png?alt=media&amp;token=7e4b7ede-6f81-4aab-b3c1-8a5c313542d2" alt=""><figcaption></figcaption></figure>

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

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

&#x20;3、Supefina返回oxxo付款码信息。

&#x20;4、商户将该付款码参考展示给用户；

&#x20;5、用户保存付款码信息到oxxo便利店支付；

6、付款成功；

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

### 请求地址

<table data-full-width="true"><thead><tr><th width="118">环境名称</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="168">变量名</th><th width="97">类型</th><th width="78">必填</th><th width="524">描述</th></tr></thead><tbody><tr><td>countryId</td><td>String</td><td>是</td><td>国家编号<br>参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#afwzp">字典表-国家编号</a><br>墨西哥：<code>MEX</code></td></tr><tr><td>currency</td><td>String</td><td>是</td><td>币种<br>参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#huo-bi-currency">字典表-货币</a><br>墨西哥比索：<code>MXN</code></td></tr><tr><td>orderAmount</td><td>String</td><td>是</td><td>订单金额<br>单位比索，需要分可以传入小数，支持两位小数</td></tr><tr><td>payProduct</td><td>String</td><td>是</td><td><a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#mfocd">支付类型</a><br>oxxo：32</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>sign</td><td>String</td><td>是</td><td>签名<br><a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/qian-ming-suan-fa">具体参照：签名算法</a></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="/huan-ying-shi-yong-supefina-de-api-wen-dang/tong-zhi-hui-tiao-shuo-ming">通知回调说明</a></p></td></tr></tbody></table>

### 请求示例

{% code fullWidth="true" %}

```json
{
  "callbackUrl": "http://test.com",
  "countryId": "MEX",
  "currency": "MXN",
  "merId": "8102401785904873",
  "merOrderNo": "2026011918295925593025317",
  "nonceStr": "e4658505b611417daa36981ff021506a",
  "orderAmount": 20,
  "payProduct": "32",
  "sign": "1E3685ED6881BA05106C4CFB012955D1"
}
```

{% endcode %}

签名组装字符串

callbackUrl=<http://test.com\\&countryId=MEX\\&currency=MXN\\&merId=8102401785904873\\&merOrderNo=2026011918295925593025317\\&nonceStr=e4658505b611417daa36981ff021506a\\&orderAmount=20\\&payProduct=32\\&key=8102401785904873>

### 响应参数

<table data-full-width="true"><thead><tr><th width="200">变量名</th><th width="220">类型</th><th width="624">描述</th></tr></thead><tbody><tr><td>code</td><td>String</td><td>响应编码<br>具体参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/xiang-ying-zhuang-tai-ma">响应状态码</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>fee</td><td>BigDecimal</td><td>预收手续费</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>supefinaOrderNo</td><td>String</td><td>supefina订单号</td></tr><tr><td>transactionStatus</td><td>String</td><td>下单状态<br>该笔订单的的发起状态是否成功，与订单真正的交易状态无关。<br><code>00</code>：下单成功<br><code>04</code>：下单失败</td></tr><tr><td>orderExpirationTime</td><td>String</td><td>过期时间</td></tr><tr><td>channelName</td><td>String</td><td>渠道</td></tr><tr><td>identifier</td><td>String</td><td>付款参考，oxxo付款码值</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": "8102401785904873",
    "merOrderNo": "2026011918295925593025317",
    "supefinaOrderNo": "2026011903010295e3cf5583e7a4e",
    "amount": 20,
    "fee": 0.6,
    "transactionStatus": "00",
    "url": "https://h5.supefina.tech/mex/oxxo?token=lTuw6Sl%2BbO4OK2qpqcBYLQ5V11Yzyani09/b8G2Spcw=",
    "identifier": "8204230000011759",
    "channelName": "oxxo",
    "orderExpirationTime": "2026-01-31T10:30:00.843"
  }
}
```

{% endcode %}

### 回调通知

提交方式：`POST`

<table data-full-width="true"><thead><tr><th width="200">变量名</th><th width="153">类型</th><th width="624">描述</th></tr></thead><tbody><tr><td>amount</td><td>String</td><td>订单金额</td></tr><tr><td>countryId</td><td>String</td><td><a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#afwzp">国家编号</a><br>参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#afwzp">字典表-国家编号</a></td></tr><tr><td>fee</td><td>String</td><td>预收手续费</td></tr><tr><td>identifier</td><td>String</td><td>付款参考，oxxo条形码值</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>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>付款参考，oxxo付款码值</td></tr><tr><td>sign</td><td>String</td><td>签名</td></tr><tr><td>status</td><td>String</td><td><a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#kxzkj">交易状态</a><br>具体参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#kxzkj">字典表——交易订单状态</a></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="false" %}

```json
{
	"amount": "20.00",
	"countryId": "MEX",
	"fee": "1.00",
	"merId": "8302109931230575",
	"merOrderId": "2025072919104648604106643",
	"nonceStr": "e2ffce1e-c54b-456d-8f5a-3cadfd",
	"realityAmount": "20",
	"realityFee": "1.00",
	"reference": "CRTPPY8MAQ67WU8AUGWDPL4N25KCTOT",
	"sign": "A89A7822C07E94CA68B814A4A3AC9902",
	"status": "01",
	"successTime": 1753787454313,
	"supefinaOrderId": "202507290301000b99dfd47bbba43",
	"transactionType": "01"
}
```

{% endcode %}

签名组装字符串

amount=20.00\&countryId=MEX\&fee=1.00\&merId=8302109931230575\&merOrderId=2025072919104648604106643\&nonceStr=e2ffce1e-c54b-456d-8f5a-3cadfd\&realityAmount=20\&realityFee=1.00\&reference=CRTPPY8MAQ67WU8AUGWDPL4N25KCTOT\&status=01\&successTime=1753787454313\&supefinaOrderId=202507290301000b99dfd47bbba43\&transactionType=01\&key=10b8a891ff6a479e8135f3367c17e87d

**回调通知响应**

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

{% code fullWidth="false" %}

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

{% endcode %}


# Card

（payProduct=18）

### 支付流程

<figure><img src="https://3631787624-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FuukVORWjXBgcGu8MirPR%2Fuploads%2FicrEwyOzKErpNs0Y9Jyk%2Fcard.png?alt=media&amp;token=7ee57223-4a71-411f-bd5d-ba59ee598cc7" alt=""><figcaption></figcaption></figure>

1、用户在商户网站/应用下单，并选择Card支付；

2、商户向Supefina发起Card支付请求；

3、Supefina返回Card支付URL地址；

4、商户将该地址在用户侧打开；

5、用户按照页面提示进行验证和支付；

6、用户支付成功；

7、Supefina将支付成功信息通知商户。

### 请求地址

<table data-full-width="true"><thead><tr><th width="122">环境名称</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="138">类型</th><th width="83">必填</th><th width="504">描述</th></tr></thead><tbody><tr><td>countryId</td><td>String</td><td>是</td><td>国家编号<br>参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#afwzp">字典表-国家编号</a><br>墨西哥：<code>MEX</code></td></tr><tr><td>currency</td><td>String</td><td>是</td><td>币种<br>参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#huo-bi-currency">字典表-货币</a><br>墨西哥比索：<code>MXN</code></td></tr><tr><td>orderAmount</td><td>String</td><td>是</td><td>订单金额<br>单位比索，需要分可以传入小数，支持两位小数</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>payProduct</td><td>String</td><td>是</td><td><a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#mfocd">支付类型</a><br>Card：<code>18</code></td></tr><tr><td>checkOut</td><td>Boolean</td><td>是</td><td>收银台<br><code>true</code>：需要收银台<br><code>false</code>：不需要收银台<br>传<code>true</code></td></tr><tr><td>returnUrl</td><td>Boolean</td><td>否</td><td>支付完成返回地址</td></tr><tr><td>callbackUrl</td><td>String</td><td>是</td><td><p>回调地址</p><p>详见<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/tong-zhi-hui-tiao-shuo-ming">通知回调说明</a></p></td></tr><tr><td>productName</td><td>String</td><td>是</td><td>商品名称<br>最大50个字符</td></tr><tr><td>productQuantity</td><td>Integer</td><td>否</td><td>商品数量<br>范围[0,1000]</td></tr><tr><td>email</td><td>String</td><td>否</td><td>顾客邮箱<br>3-256个字符<br><strong>电商行业必传</strong></td></tr><tr><td>receiverAddressMain</td><td>String</td><td>否</td><td>收件地址，街道<br>0-50个字符<br><strong>电商行业必传</strong></td></tr><tr><td>receiverAddressExtra</td><td>String</td><td>否</td><td>收件地址，小区，门牌号<br>0-50个字符<br><strong>电商行业必传</strong></td></tr><tr><td>receiverCity</td><td>String</td><td>否</td><td>收件人城市<br>0-50个字符，可包括空格、连字符、撇号、逗号和点<br><strong>电商行业必传</strong></td></tr><tr><td>receiverProvince</td><td>String</td><td>否</td><td>收件人所在省<br>0-40个字符<br>参数：<a href="https://en.wikipedia.org/wiki/ISO_3166-2">https://en.wikipedia.org/wiki/ISO_3166-2</a>  例：NY<br><strong>电商行业必传</strong></td></tr><tr><td>receiverCountry</td><td>String</td><td>否</td><td>收件人国家<br>参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#afwzp">字典表-国家编号</a>  例：BRA<br><strong>电商行业必传</strong></td></tr><tr><td>receiverZipCode</td><td>String</td><td>否</td><td>邮政编码<br>0-12个字母或数字<br><strong>电商行业必传</strong></td></tr><tr><td>receiverPhone</td><td>String</td><td>否</td><td>收件人电话<br>5-20个字符，区添加区号。如：+1 111111111<br><strong>电商行业必传</strong></td></tr><tr><td>alias</td><td>String</td><td>否</td><td>用户名<br>0-60个字符<br><strong>游戏行业必传</strong></td></tr><tr><td>newUser</td><td>Boolean</td><td>否</td><td>是否一个月内的用户<br>true：新用户<br>false：老用户<br><strong>游戏行业必传</strong></td></tr><tr><td>hasDispute</td><td>Boolean</td><td>否</td><td>是否有过历史争议，包含以下任一条：<br>1、利用作弊工具、游戏漏洞等进行不正当行为； <br>2、骚扰其他玩家、进行恶意行为或破坏游戏体验的行为； <br>3、玩家有不当言论、违反游戏规则、频繁被举报；<br>true：有过<br>false：没有<br><strong>游戏行业必传</strong></td></tr><tr><td>hasRefund</td><td>Boolean</td><td>否</td><td>是否有过退款<br>true：有过<br>false：没有<br><strong>游戏行业必传</strong></td></tr><tr><td>hasSingedLong</td><td>Boolean</td><td>否</td><td>注册时间是否超过三个月<br>true：超过<br>false：未超过<br><strong>游戏行业必传</strong></td></tr><tr><td>sign</td><td>String</td><td>是</td><td>签名<br><a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/qian-ming-suan-fa">具体参照：签名算法</a></td></tr><tr><td>customerName</td><td>String</td><td>是</td><td>用户名字</td></tr><tr><td>description</td><td>String</td><td>是</td><td><p>描述</p><p>不能带特殊符号,长度不超过200字符</p></td></tr></tbody></table>

### 请求示例

{% code fullWidth="true" %}

```json
{
	"alias": "test alias",
	"callbackUrl": "https://test.com",
	"checkOut": true,
	"countryId": "MEX",
	"currency": "MXN",
	"customerName": "Aaliyah Rogers",
	"description": "Supefina",
	"email": "test@123.com",
	"hasDispute": true,
	"hasRefund": false,
	"hasSingedLong": true,
	"merId": "8102048462634665",
	"merOrderNo": "2025072919413465743446604",
	"newUser": false,
	"nonceStr": "b4cf1bb20d8c49cca4e5815d13e5a352",
	"orderAmount": "200",
	"payProduct": "18",
	"productName": "testName",
	"productQuantity": 10,
	"receiverAddressExtra": "Apt 2",
	"receiverAddressMain": "Sample street 357",
	"receiverCity": "Example city",
	"receiverCountry": "MXN",
	"receiverPhone": "1234567890",
	"receiverProvince": "Example state",
	"receiverZipCode": "01254",
	"returnUrl": "https://www.bing.com/",
	"sign": "91ABE1CB4C93ACC3FB3D4731207B91FB"
}
```

{% endcode %}

签名组装字符串

alias=test alias\&callbackUrl=<https://test.com\\&checkOut=true\\&countryId=MEX\\&currency=MXN\\&customerName=Aaliyah> Rogers\&description=Supefina\&email=<test@123.com>\&hasDispute=true\&hasRefund=false\&hasSingedLong=true\&merId=8102048462634665\&merOrderNo=2025072919413465743446604\&newUser=false\&nonceStr=b4cf1bb20d8c49cca4e5815d13e5a352\&orderAmount=200\&payProduct=18\&productName=testName\&productQuantity=10\&receiverAddressExtra=Apt 2\&receiverAddressMain=Sample street 357\&receiverCity=Example city\&receiverCountry=MXN\&receiverPhone=1234567890\&receiverProvince=Example state\&receiverZipCode=01254\&returnUrl=<https://www.bing.com/\\&key=10b8a891ff6a479e8135f3367c17e87d>

### 响应参数

<table data-full-width="true"><thead><tr><th width="238">变量名</th><th width="208">类型</th><th width="223">描述</th></tr></thead><tbody><tr><td>code</td><td>String</td><td>响应编码<br>具体参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/xiang-ying-zhuang-tai-ma">响应状态码</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>currency</td><td>String</td><td>币种<br>参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#huo-bi-currency">字典表-货币</a><br>墨西哥比索：<code>MXN</code></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>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": "8102048462634665",
		"merOrderNo": "2025072919413465743446604",
		"supefinaOrderNo": "2025071950159781458792448",
		"amount": 200,
		"url": "http://h5.supefina.tech/combineCashier?token=22967f6fca9c4ba0a6e5d0f142f6c491",
		"currency": "MXN"
	}
}
```

{% endcode %}

### 回调通知

提交方式：`POST`

<table data-full-width="true"><thead><tr><th width="225">变量名</th><th width="175">类型</th><th width="300">描述</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="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#afwzp">字典表-国家编号</a><br>墨西哥：<code>MEX</code></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>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="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#kxzkj">交易状态</a><br>具体参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#kxzkj">字典表——交易订单状态</a></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>

#### 回调通知示例

```json
{
	"amount": "200.00",
	"countryId": "MEX",
	"customerName": "Aaliyah Rogers",
	"fee": "1.00",
	"merId": "8102048462634665",
	"merOrderId": "2025072919413465743446604",
	"nonceStr": "d8870116-0c31-4455-b745-d8576f",
	"realityAmount": "200",
	"realityFee": "1.00",
	"reference": "CRTD7QBOHTSDSFW0P065PG6F0I80C8L",
	"sign": "5CF88813736D50E062A4C88DD33DB4A6",
	"status": "01",
	"successTime": 1753789322996,
	"supefinaOrderId": "2025071950159781458792448",
	"transactionType": "01"
}
```

签名组装字符串

amount=200.00\&countryId=MEX\&customerName=Aaliyah Rogers\&fee=1.00\&merId=8102048462634665\&merOrderId=2025072919413465743446604\&nonceStr=d8870116-0c31-4455-b745-d8576f\&realityAmount=200\&realityFee=1.00\&reference=CRTD7QBOHTSDSFW0P065PG6F0I80C8L\&status=01\&successTime=1753789322996\&supefinaOrderId=2025071950159781458792448\&transactionType=01\&key=cf5fe06851e84cd7ab227dbbf16f4bf1

**回调通知响应**

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

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

### 测试数据

测试环境提供了完整的支付功能，但它只是模拟处理，没有实际的银行交易。

可以使用以下信用卡信息来测试付款。

#### Visa

| Card PAN         | 3-D Secure result                                         | Transaction result           |
| ---------------- | --------------------------------------------------------- | ---------------------------- |
| 4000000000000085 | 3-D secure version 2, challenge flow, full authentication | Payment has CONFIRMED status |
| 4580000000000059 | 3-D secure version 2, frictionless flow, attempt          | Payment has CONFIRMED status |
| 4000000000000093 | 3-D secure version 2, frictionless flow, success          | Payment has CONFIRMED status |

**Mastercard**

| Card PAN         | 3-D Secure result                                         | Transaction result           |
| ---------------- | --------------------------------------------------------- | ---------------------------- |
| 5100000000000065 | 3-D secure version 2, challenge flow, full authentication | Payment has CONFIRMED status |
| 2400000000000069 | 3-D secure version 2, frictionless flow, attempt          | Payment has CONFIRMED status |
| 5100000000000073 | 3-D secure version 2, frictionless flow, success          | Payment has CONFIRMED status |

**Maestro**

| Card PAN         | 3-D Secure result                                         | Transaction result           |
| ---------------- | --------------------------------------------------------- | ---------------------------- |
| 5000000000000025 | 3-D secure version 2, challenge flow, full authentication | Payment has CONFIRMED status |
| 5000000000000033 | 3-D secure version 2, frictionless flow, success          | Payment has CONFIRMED status |
| 5666666666666955 | 3-D secure version 2, challenge flow, full authentication | Payment has DECLINED status  |

**Discover**

| Card PAN         | 3-D Secure result                                         | Transaction result           |
| ---------------- | --------------------------------------------------------- | ---------------------------- |
| 6500000000000895 | 3-D secure version 2, challenge flow, full authentication | Payment has CONFIRMED status |
| 6500000000000069 | 3-D secure version 2, frictionless flow, attempt          | Payment has CONFIRMED status |
| 6011000000000053 | 3-D secure version 2, frictionless flow, success          | Payment has CONFIRMED status |

**JCB**

| Card PAN         | 3-D Secure result                                         | Transaction result           |
| ---------------- | --------------------------------------------------------- | ---------------------------- |
| 3528000000000015 | 3-D secure version 2, challenge flow, full authentication | Payment has CONFIRMED status |
| 3528000000000023 | 3-D secure version 2, frictionless flow, success          | Payment has CONFIRMED status |
| 3528000000000049 | 3-D secure version 2, frictionless flow, attempt          | Payment has CONFIRMED status |

**UnionPay**

| Card PAN            | 3-D Secure result                                         | Transaction result           |
| ------------------- | --------------------------------------------------------- | ---------------------------- |
| 6222020000000085    | 3-D secure version 2, challenge flow, full authentication | Payment has CONFIRMED status |
| 8171000000000000079 | 3-D secure version 2, frictionless flow, attempt          | Payment has CONFIRMED status |
| 6200000000000053    | 3-D secure version 2, frictionless flow, success          | Payment has CONFIRMED status |

**Amex**

| Card PAN        | 3-D Secure result                                         | Transaction result           |
| --------------- | --------------------------------------------------------- | ---------------------------- |
| 370000000000085 | 3-D secure version 2, challenge flow, full authentication | Payment has CONFIRMED status |
| 340000000000033 | 3-D secure version 2, frictionless flow, success          | Payment has CONFIRMED status |
| 340000000000009 | 3-D secure version 2, frictionless flow, attempt          | Payment has CONFIRMED status |

在测试过程中，商户使用任意持卡人姓名、有效期和安全码与这些卡信息进行支付。为了完成认证，3-DS安全认证也通过一个页面模拟，该页面只显示两个按钮，一个按钮用于成功认证，另一个按钮用于认证失败。请注意，当商户选择认证失败时，无论使用了哪个PAN，支付总是会被拒绝。

如果测试过程中，遇到了异常状态码，请直接联系Supefina运营人员处理。


# 哥伦比亚

在哥伦比亚，我们提供银行在线支付（PSE），现金支付（Cash）以及聚合收银台（All-Checkout）等支付产品。

<figure><img src="https://3631787624-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FuukVORWjXBgcGu8MirPR%2Fuploads%2FZLBevtvGDKs4MtDVVX0h%2F%E5%93%A5%E4%BC%A6%E6%AF%94%E4%BA%9A-update.jpg?alt=media&amp;token=6f43ec07-2e81-49d8-a4d1-ed2a67665471" alt=""><figcaption></figcaption></figure>

{% content-ref url="/pages/WDNRaux8VfDuR0N1lazt" %}
[PSE](/huan-ying-shi-yong-supefina-de-api-wen-dang/dai-shou/ge-lun-bi-ya/pse)
{% endcontent-ref %}

{% content-ref url="/pages/LUjFtzg8LovkQ7WmZUED" %}
[Cash](/huan-ying-shi-yong-supefina-de-api-wen-dang/dai-shou/ge-lun-bi-ya/cash)
{% endcontent-ref %}

{% content-ref url="/pages/hDmKs3SObXBeOdznqC7g" %}
[All-Checkout](/huan-ying-shi-yong-supefina-de-api-wen-dang/dai-shou/ge-lun-bi-ya/all-checkout)
{% endcontent-ref %}

{% content-ref url="/pages/IZXcNzPHCVVhiUOk3b4n" %}
[Broken mention](broken://pages/IZXcNzPHCVVhiUOk3b4n)
{% endcontent-ref %}

{% content-ref url="/pages/7hNifDMxXjsxXaKKo5xV" %}
[Broken mention](broken://pages/7hNifDMxXjsxXaKKo5xV)
{% endcontent-ref %}


# PSE

（payProduct=12）

### 支付流程

<figure><img src="https://3631787624-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FuukVORWjXBgcGu8MirPR%2Fuploads%2FtoiGK387i5jNulx7qrr3%2Ftransfer.png?alt=media&amp;token=fd499b16-4a49-44e2-9287-4b4ebba26206" alt=""><figcaption></figcaption></figure>

1. 用户在商户网站/应用下单，并选择PSE支付；
2. 商户向Supefina发起PSE支付请求；
3. Supefina返回PSE支付URL地址；
4. 商户将该地址在用户侧打开；
5. 用户按照页面提示进行验证和支付；
6. 用户支付成功；
7. Supefina将支付成功信息通知商户。

### 请求地址

<table><thead><tr><th width="138">环境名称</th><th width="607">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>

### 请求参数

#### 请求头

| Key            | Value              |
| -------------- | ------------------ |
| `Content-Type` | `application/json` |

#### 请求体

<table data-full-width="true"><thead><tr><th width="216">变量名</th><th width="110">类型</th><th width="95">必填</th><th width="505">描述</th></tr></thead><tbody><tr><td>countryId</td><td>String</td><td>是</td><td>国家编号<br>参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#afwzp">字典表-国家编号</a><br>哥伦比亚，<code>COL</code></td></tr><tr><td>currency</td><td>String</td><td>是</td><td>币种<br>参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#huo-bi-currency">字典表-货币</a><br>哥伦比亚比索：<code>COP</code></td></tr><tr><td>orderAmount</td><td>String</td><td>是</td><td><p>订单金额<br>3000 >= orderAmount &#x3C;= 2000000</p><p>不支持小数</p></td></tr><tr><td>payProduct</td><td>String</td><td>是</td><td><a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#mfocd">支付类型</a><br>PSE：<code>12</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>sign</td><td>String</td><td>是</td><td>签名<br><a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/qian-ming-suan-fa">具体参照：签名算法</a></td></tr><tr><td>nonceStr</td><td>String</td><td>是</td><td>随机字符串<br>长度不能超过32位</td></tr><tr><td>customerEmail</td><td>String</td><td>是</td><td><p>用户邮箱<br>邮箱用户名不能只有数字（例如31231234@gmail.com）</p><p>且同一个邮箱一天支付请求不能超过20次。</p></td></tr><tr><td>customerName</td><td>String</td><td>是</td><td>用户名字</td></tr><tr><td>customerPhone</td><td>String</td><td>是</td><td>用户电话<br>需以3开头的十位数</td></tr><tr><td>customerIdentification</td><td>String</td><td>是</td><td>用户证件号</td></tr><tr><td>checkOut</td><td>Boolean</td><td>是</td><td>收银台<br><code>true</code>：需要收银台<br><code>false</code>：不需要收银台<br>建议传<code>true</code></td></tr><tr><td>customerAccount</td><td>String</td><td>否</td><td>用户账户<br><code>checkOut</code>为<code>false</code>时必传</td></tr><tr><td>lastName</td><td>String</td><td>否</td><td>用户姓氏<br><code>checkOut</code>为<code>false</code>时必传</td></tr><tr><td>customerIdentificationType</td><td>String</td><td>否</td><td><p>用户证件类型<br><code>00</code>：身份证（CC/TI）<br><code>01</code>：外国人身份证（CE）<br><code>02</code>：税号<br><code>03</code>：护照<br><code>06</code>：其他<br><code>07</code>：公民身份证明<br><code>08</code>：居留许可证</p><p><code>checkOut</code>为<code>false</code>时必传</p></td></tr><tr><td>customerAddress</td><td>String</td><td>否</td><td>用户地址<br><code>checkOut</code>为<code>false</code>时必传</td></tr><tr><td>tipo_persona</td><td>String</td><td>否</td><td>付款主体<br><code>checkOut</code>为<code>false</code>时必传</td></tr><tr><td>bankId</td><td>String</td><td>否</td><td>银行编码<br>参照：https://api.supefina.net/api/supefina/transactions/internal/getEbixuBankList<br><code>checkOut</code>为<code>false</code>时必传</td></tr><tr><td>expireTimeL</td><td>Long</td><td>否</td><td>过期时间<br>单位：秒；默认值：10分钟，最大值：10分钟</td></tr><tr><td>callbackUrl</td><td>String</td><td>是</td><td><p>回调地址</p><p>详见<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/tong-zhi-hui-tiao-shuo-ming">通知回调说明</a></p></td></tr><tr><td>description</td><td>String</td><td>是</td><td><p>描述 </p><p>不能带特殊符号,长度不超过200字符</p></td></tr></tbody></table>

### 请求示例

{% code fullWidth="true" %}

```json
{
	"callbackUrl": "https://d3vf2zxd9jv8rh.cloudfront.net/apigate/v6sx2i/api/pay_notice/in_payback/payId/CDEA3CA37DBC4C2CB6301AED14011122",
	"checkOut": true,
	"countryId": "COL",
	"currency": "COP",
	"customerAccount": "60872832",
	"customerEmail": "eaawxmn@gmail.com",
	"customerIdentification": "9145652857",
	"customerName": "Aaliyah Rogers",
	"customerPhone": "3073030686",
	"description": "Supefina",
	"lastName": "cith",
	"merId": "8302490290654651",
	"merOrderNo": "2025072510325273646352161",
	"nonceStr": "5045ad60ca294b408006d21582f7bcad",
	"orderAmount": "20000",
	"payProduct": "12",
	"sign": "75680D040AAA6DD5EF0018CF5B34D707"// 大写
}
```

{% endcode %}

签名组装字符串

callbackUrl=<https://d3vf2zxd9jv8rh.cloudfront.net/apigate/v6sx2i/api/pay\\_notice/in\\_payback/payId/CDEA3CA37DBC4C2CB6301AED14011122\\&checkOut=true\\&countryId=COL\\&currency=COP\\&customerAccount=60872832\\&customerEmail=eaawxmn@gmail.com\\&customerIdentification=9145652857\\&customerName=Aaliyah> Rogers\&customerPhone=3073030686\&description=Supefina\&lastName=cith\&merId=8302490290654651\&merOrderNo=2025072510325273646352161\&nonceStr=5045ad60ca294b408006d21582f7bcad\&orderAmount=20000\&payProduct=12\&key=e8548e70a8ba4a658b0da4ef50600d42

### 响应参数

<table data-full-width="true"><thead><tr><th width="220">变量名</th><th width="179">类型</th><th width="396">描述</th></tr></thead><tbody><tr><td>code</td><td>String</td><td>响应编码<br>具体参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/xiang-ying-zhuang-tai-ma">响应状态码</a></td></tr><tr><td>msg</td><td>String</td><td>响应信息</td></tr><tr><td>data</td><td>Object</td><td>响应数据</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>supefinaOrderId</td><td>String</td><td>supefina订单号</td></tr><tr><td>amount</td><td>BigDecimal</td><td>订单金额</td></tr><tr><td>fee</td><td>String</td><td>预收手续费</td></tr><tr><td>identifier</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>orderExpirationTime</td><td>String</td><td>订单过期时间 （UTC 0时区时间）</td></tr></tbody></table>

#### 响应示例

{% code fullWidth="true" %}

```json
{
	"code": "200",
	"msg": "success ",
	"data": {
		"merCode": "8302490290654651",
		"merOrderNo": "2025072510325273646352161",
		"supefinaOrderNo": "20250725023253359000038212",
		"amount": 20000,
		"fee": 5.0,
		"transactionStatus": "00",
		"url": "https://docs.supefina.net/huan-ying-shi-yong-supefina-de-api-wen-dang/dai-shou/ge-lun-bi-ya",
		"referenceCode": "",
		"channelName": "rickipay",
		"orderExpirationTime": "2025-07-27T02:33:03.385"
	}
}
```

{% endcode %}

### 回调通知

提交方式：`POST`

<table data-full-width="true"><thead><tr><th width="239">变量名</th><th width="179">类型</th><th width="396">描述</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="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#afwzp">字典表-国家编号</a><br>哥伦比亚，COL</td></tr><tr><td>customerName</td><td>String</td><td>用户名字</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>sign</td><td>String</td><td>签名</td></tr><tr><td>status</td><td>String</td><td><a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#kxzkj">交易状态</a><br>具体参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#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": "20000.00",
	"countryId": "COL",
	"customerName": "Aaliyah Rogers",
	"fee": "5.00",
	"identifier": "91eda9ee-4798-4a",
	"merId": "8302490290654651",
	"merOrderId": "2025072510325273646352161",
	"msg": "SUCCESS",
	"nonceStr": "d6441e30-4f56-415c-912a-177d58",
	"payerIdNumber": "9145652857",
	"payerName": "test",
	"realityAmount": "20000",
	"realityFee": "5.00",
	"sign": "9A6F6F86ECDE461E8FA94B037632E027",// 大写
	"status": "01",
	"successTime": 1753410778000,
	"supefinaOrderId": "20250725023253359000038212",
	"transactionType": "01"
}
```

{% endcode %}

签名组装字符串

amount=20000.00\&countryId=COL\&customerName=Aaliyah Rogers\&fee=5.00\&identifier=91eda9ee-4798-4a\&merId=8302490290654651\&merOrderId=2025072510325273646352161\&msg=SUCCESS\&nonceStr=d6441e30-4f56-415c-912a-177d58\&payerIdNumber=9145652857\&payerName=test\&realityAmount=20000\&realityFee=5.00\&status=01\&successTime=1753410778000\&supefinaOrderId=20250725023253359000038212\&transactionType=01\&key=e8548e70a8ba4a658b0da4ef50600d42

**回调通知响应**

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

{% code fullWidth="true" %}

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

{% endcode %}

### 哥伦比亚代收银行列表 <a href="#z5esw" id="z5esw"></a>

| 银行编号 | 银行名称                                      |
| ---- | ----------------------------------------- |
| 1558 | BAN100                                    |
| 1059 | BANCAMIA S.A.                             |
| 1040 | BANCO AGRARIO                             |
| 1052 | BANCO AV VILLAS                           |
| 1013 | BANCO BBVA COLOMBIA S.A.                  |
| 1032 | BANCO CAJA SOCIAL                         |
| 1066 | BANCO COOPERATIVO COOPCENTRAL             |
| 1051 | BANCO DAVIVIENDA                          |
| 1001 | BANCO DE BOGOTA                           |
| 1023 | BANCO DE OCCIDENTE                        |
| 1062 | BANCO FALABELLA                           |
| 1063 | BANCO FINANDINA S.A. BIC                  |
| 1012 | BANCO GNB SUDAMERIS                       |
| 1006 | BANCO ITAU                                |
| 1060 | BANCO PICHINCHA S.A.                      |
| 1002 | BANCO POPULAR                             |
| 1065 | BANCO SANTANDER COLOMBIA                  |
| 1069 | BANCO SERFINANZA                          |
| 1303 | BANCO UNION antes GIROS                   |
| 1007 | BANCOLOMBIA                               |
| 1061 | BANCOOMEVA S.A.                           |
| 1283 | CFA COOPERATIVA FINANCIERA                |
| 1009 | CITIBANK                                  |
| 1370 | COLTEFINANCIERA                           |
| 1292 | CONFIAR COOPERATIVA FINANCIERA            |
| 1291 | COOFINEP COOPERATIVA FINANCIERA           |
| 1289 | COTRAFA                                   |
| 1097 | DALE                                      |
| 1551 | DAVIPLATA                                 |
| 1637 | IRIS                                      |
| 1070 | LULO BANK                                 |
| 1801 | MOVII S.A.                                |
| 1507 | NEQUI                                     |
| 1811 | RAPPIPAY                                  |
| 1019 | SCOTIABANK COLPATRIA                      |
| 1815 | ALIANZA FIDUCIARIA                        |
| 1071 | BANCO J.P. MORGAN COLOMBIA S.A.           |
| 1047 | BANCO MUNDO MUJER S.A.                    |
| 1816 | CREZCAMOS S.A. COMPAÑÍA DE FINANCIAMIENTO |
| 1804 | UALÁ                                      |

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

重复支付：PSE可能会出现多次支付的情况，请注意处理收到多次支付通知。发生多次支付时，Supefina后台会创建多笔订单,并多次通知商户,商户可以通过通知中的<mark style="color:red;">**`supefinaOrderId`**</mark> 判断是否是同一订单。多次付款时，merOrderId保持不变，但每次的<mark style="color:red;">**supefinaOrderId**</mark>都会不同。
{% endhint %}


# Bancolombia

（payProduct=28）

### 支付流程

<figure><img src="https://3631787624-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FuukVORWjXBgcGu8MirPR%2Fuploads%2FtoiGK387i5jNulx7qrr3%2Ftransfer.png?alt=media&amp;token=fd499b16-4a49-44e2-9287-4b4ebba26206" alt=""><figcaption></figcaption></figure>

1. 用户在商户网站/应用下单，并选择Bancolombia支付；
2. 商户向Supefina发起Bancolombia支付请求；
3. Supefina返回Bancolombia支付URL地址；
4. 商户将该地址在用户侧打开；
5. 用户按照页面提示进行验证和支付；
6. 用户支付成功；
7. Supefina将支付成功信息通知商户。

### 请求地址

<table><thead><tr><th width="138">环境名称</th><th width="607">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>

### 请求参数

#### 请求头

| Key            | Value              |
| -------------- | ------------------ |
| `Content-Type` | `application/json` |

#### 请求体

<table data-full-width="true"><thead><tr><th width="216">变量名</th><th width="110">类型</th><th width="95">必填</th><th width="505">描述</th></tr></thead><tbody><tr><td>countryId</td><td>String</td><td>是</td><td>国家编号<br>参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#afwzp">字典表-国家编号</a><br>哥伦比亚，<code>COL</code></td></tr><tr><td>currency</td><td>String</td><td>是</td><td>币种<br>参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#huo-bi-currency">字典表-货币</a><br>哥伦比亚比索：<code>COP</code></td></tr><tr><td>orderAmount</td><td>String</td><td>是</td><td><p>订单金额<br>3000 >= orderAmount &#x3C;= 2000000</p><p>不支持小数</p></td></tr><tr><td>payProduct</td><td>String</td><td>是</td><td><a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#mfocd">支付类型</a><br>Bancolombia：<code>28</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>sign</td><td>String</td><td>是</td><td>签名<br><a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/qian-ming-suan-fa">具体参照：签名算法</a></td></tr><tr><td>nonceStr</td><td>String</td><td>是</td><td>随机字符串<br>长度不能超过32位</td></tr><tr><td>customerEmail</td><td>String</td><td>是</td><td><p>用户邮箱<br>邮箱用户名不能只有数字（例如31231234@gmail.com）</p><p>且同一个邮箱一天支付请求不能超过20次。</p></td></tr><tr><td>customerName</td><td>String</td><td>是</td><td>用户名字</td></tr><tr><td>customerPhone</td><td>String</td><td>是</td><td>用户电话<br>需以3开头的十位数</td></tr><tr><td>customerIdentification</td><td>String</td><td>是</td><td>用户证件号</td></tr><tr><td>checkOut</td><td>Boolean</td><td>是</td><td>收银台<br><code>true</code>：需要收银台<br><code>false</code>：不需要收银台<br>建议传<code>true</code></td></tr><tr><td>customerAccount</td><td>String</td><td>否</td><td>用户账户<br><code>checkOut</code>为<code>false</code>时必传</td></tr><tr><td>lastName</td><td>String</td><td>否</td><td>用户姓氏<br><code>checkOut</code>为<code>false</code>时必传</td></tr><tr><td>customerIdentificationType</td><td>String</td><td>否</td><td><p>用户证件类型<br><code>00</code>：身份证（CC/TI）<br><code>01</code>：外国人身份证（CE）<br><code>02</code>：税号<br><code>03</code>：护照<br><code>06</code>：其他<br><code>07</code>：公民身份证明<br><code>08</code>：居留许可证</p><p><code>checkOut</code>为<code>false</code>时必传</p></td></tr><tr><td>customerAddress</td><td>String</td><td>否</td><td>用户地址<br><code>checkOut</code>为<code>false</code>时必传</td></tr><tr><td>tipo_persona</td><td>String</td><td>否</td><td>付款主体<br><code>checkOut</code>为<code>false</code>时必传</td></tr><tr><td>bankId</td><td>String</td><td>否</td><td>银行编码<br>参照：https://api.supefina.net/api/supefina/transactions/internal/getEbixuBankList<br><code>checkOut</code>为<code>false</code>时必传</td></tr><tr><td>expireTimeL</td><td>Long</td><td>否</td><td>过期时间<br>单位：秒；默认值：10分钟，最大值：10分钟</td></tr><tr><td>callbackUrl</td><td>String</td><td>是</td><td><p>回调地址</p><p>详见<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/tong-zhi-hui-tiao-shuo-ming">通知回调说明</a></p></td></tr><tr><td>description</td><td>String</td><td>是</td><td><p>描述 </p><p>不能带特殊符号,长度不超过200字符</p></td></tr></tbody></table>

### 请求示例

{% code fullWidth="true" %}

```json
{
	"callbackUrl": "https://d3vf2zxd9jv8rh.cloudfront.net/apigate/v6sx2i/api/pay_notice/in_payback/payId/CDEA3CA37DBC4C2CB6301AED14011122",
	"checkOut": true,
	"countryId": "COL",
	"currency": "COP",
	"customerAccount": "60872832",
	"customerEmail": "eaawxmn@gmail.com",
	"customerIdentification": "9145652857",
	"customerName": "Aaliyah Rogers",
	"customerPhone": "3073030686",
	"description": "Supefina",
	"lastName": "cith",
	"merId": "8302490290654651",
	"merOrderNo": "2025072510400064819932798",
	"nonceStr": "bbc3115a94824129bb5bd07b9248cf23",
	"orderAmount": "20000",
	"payProduct": "28",
	"sign": "187DAC099D55720608B83C24682B25B9"// 大写
}
```

{% endcode %}

签名组装字符串

callbackUrl=<https://d3vf2zxd9jv8rh.cloudfront.net/apigate/v6sx2i/api/pay\\_notice/in\\_payback/payId/CDEA3CA37DBC4C2CB6301AED14011122\\&checkOut=true\\&countryId=COL\\&currency=COP\\&customerAccount=60872832\\&customerEmail=eaawxmn@gmail.com\\&customerIdentification=9145652857\\&customerName=Aaliyah> Rogers\&customerPhone=3073030686\&description=Supefina\&lastName=cith\&merId=8302490290654651\&merOrderNo=2025072510400064819932798\&nonceStr=bbc3115a94824129bb5bd07b9248cf23\&orderAmount=20000\&payProduct=28\&key=e8548e70a8ba4a658b0da4ef50600d42

### 响应参数

<table data-full-width="true"><thead><tr><th width="220">变量名</th><th width="179">类型</th><th width="396">描述</th></tr></thead><tbody><tr><td>code</td><td>String</td><td>响应编码<br>具体参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/xiang-ying-zhuang-tai-ma">响应状态码</a></td></tr><tr><td>msg</td><td>String</td><td>响应信息</td></tr><tr><td>data</td><td>Object</td><td>响应数据</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>supefinaOrderId</td><td>String</td><td>supefina订单号</td></tr><tr><td>amount</td><td>BigDecimal</td><td>订单金额</td></tr><tr><td>fee</td><td>String</td><td>预收手续费</td></tr><tr><td>identifier</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>orderExpirationTime</td><td>String</td><td>订单过期时间 （UTC 0时区时间）</td></tr></tbody></table>

#### 响应示例

{% code fullWidth="true" %}

```json
{
	"code": "200",
	"msg": "success ",
	"data": {
		"merCode": "8302490290654651",
		"merOrderNo": "2025072510400064819932798",
		"url": "https://h5.supefina.tech/COL/copago/bancolombia/?token=tqv14tvmsnrif0j1juv960018r"
	}
}
```

{% endcode %}

响应示例2 (需要特定配置才会启用)

```json
{
	"code": "200",
	"msg": "success ",
	"data": {
		"merCode": "8302490290654651",
		"merOrderNo": "2025072616333789362511127",
		"supefinaOrderNo": "20250726083338427000038257",
		"amount": 20000,
		"fee": 201.0,
		"transactionStatus": "00",
		"url": "https://docs.supefina.net/huan-ying-shi-yong-supefina-de-api-wen-dang/dai-shou/ge-lun-bi-ya",
		"referenceCode": "",
		"channelName": "copago",
		"orderExpirationTime": "2025-07-28T08:33:48.451"
	}
}
```

### 回调通知

提交方式：`POST`

<table data-full-width="true"><thead><tr><th width="239">变量名</th><th width="179">类型</th><th width="396">描述</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="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#afwzp">字典表-国家编号</a><br>哥伦比亚，COL</td></tr><tr><td>customerName</td><td>String</td><td>用户名字</td></tr><tr><td>fee</td><td>String</td><td>预收手续费</td></tr><tr><td>identifier</td><td>String</td><td>付款参考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>sign</td><td>String</td><td>签名</td></tr><tr><td>status</td><td>String</td><td><a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#kxzkj">交易状态</a><br>具体参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#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": "20000.00",
	"countryId": "COL",
	"customerName": "jinlai he",
	"fee": "201.00",
	"identifier": "b6b8326f-248c-40",
	"merId": "8302490290654651",
	"merOrderId": "2025072510400064819932798",
	"msg": "SUCCESS",
	"nonceStr": "a2719705-3907-4c72-bf3e-0df3c6",
	"payerIdNumber": "123213",
	"payerName": "test",
	"realityAmount": "20000",
	"realityFee": "201.00",
	"reference": "c80ad7af-2c3f-47b9-96a3-67fa739ed469",
	"sign": "F391864D738B9EF3436B15D63AE93BA3",// 大写
	"status": "01",
	"successTime": 1753411271000,
	"supefinaOrderId": "20250725024106415000038663",
	"transactionType": "01"
}
```

{% endcode %}

签名组装字符串

amount=20000.00\&countryId=COL\&customerName=jinlai he\&fee=201.00\&identifier=b6b8326f-248c-40\&merId=8302490290654651\&merOrderId=2025072510400064819932798\&msg=SUCCESS\&nonceStr=a2719705-3907-4c72-bf3e-0df3c6\&payerIdNumber=123213\&payerName=test\&realityAmount=20000\&realityFee=201.00\&reference=c80ad7af-2c3f-47b9-96a3-67fa739ed469\&status=01\&successTime=1753411271000\&supefinaOrderId=20250725024106415000038663\&transactionType=01\&key=e8548e70a8ba4a658b0da4ef50600d42

**回调通知响应**

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

{% code fullWidth="true" %}

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

{% endcode %}

### 哥伦比亚代收银行列表 <a href="#z5esw" id="z5esw"></a>

| 银行编号 | 银行名称                                      |
| ---- | ----------------------------------------- |
| 1558 | BAN100                                    |
| 1059 | BANCAMIA S.A.                             |
| 1040 | BANCO AGRARIO                             |
| 1052 | BANCO AV VILLAS                           |
| 1013 | BANCO BBVA COLOMBIA S.A.                  |
| 1032 | BANCO CAJA SOCIAL                         |
| 1066 | BANCO COOPERATIVO COOPCENTRAL             |
| 1051 | BANCO DAVIVIENDA                          |
| 1001 | BANCO DE BOGOTA                           |
| 1023 | BANCO DE OCCIDENTE                        |
| 1062 | BANCO FALABELLA                           |
| 1063 | BANCO FINANDINA S.A. BIC                  |
| 1012 | BANCO GNB SUDAMERIS                       |
| 1006 | BANCO ITAU                                |
| 1060 | BANCO PICHINCHA S.A.                      |
| 1002 | BANCO POPULAR                             |
| 1065 | BANCO SANTANDER COLOMBIA                  |
| 1069 | BANCO SERFINANZA                          |
| 1303 | BANCO UNION antes GIROS                   |
| 1007 | BANCOLOMBIA                               |
| 1061 | BANCOOMEVA S.A.                           |
| 1283 | CFA COOPERATIVA FINANCIERA                |
| 1009 | CITIBANK                                  |
| 1370 | COLTEFINANCIERA                           |
| 1292 | CONFIAR COOPERATIVA FINANCIERA            |
| 1291 | COOFINEP COOPERATIVA FINANCIERA           |
| 1289 | COTRAFA                                   |
| 1097 | DALE                                      |
| 1551 | DAVIPLATA                                 |
| 1637 | IRIS                                      |
| 1070 | LULO BANK                                 |
| 1801 | MOVII S.A.                                |
| 1507 | NEQUI                                     |
| 1811 | RAPPIPAY                                  |
| 1019 | SCOTIABANK COLPATRIA                      |
| 1815 | ALIANZA FIDUCIARIA                        |
| 1071 | BANCO J.P. MORGAN COLOMBIA S.A.           |
| 1047 | BANCO MUNDO MUJER S.A.                    |
| 1816 | CREZCAMOS S.A. COMPAÑÍA DE FINANCIAMIENTO |
| 1804 | UALÁ                                      |


# Cash

（payProduct=03）系统维护中

### 支付流程

<figure><img src="https://3631787624-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FuukVORWjXBgcGu8MirPR%2Fuploads%2FvwoY3e5juX6FTdthFg6K%2FCash.png?alt=media&amp;token=e882e952-0e3f-47fa-a926-b851e781b508" alt=""><figcaption></figcaption></figure>

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

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

&#x20;3、Supefina返回Cash付款URL信息。

&#x20;4、商户将该支付URL展示给用户；

&#x20;5、用户按照页面提示进行付款；

6、付款成功；

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

### 请求地址

<table data-full-width="true"><thead><tr><th width="138">环境名称</th><th width="607">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="220">变量名</th><th width="102">类型</th><th width="89">必填</th><th>描述</th></tr></thead><tbody><tr><td>countryId</td><td>String</td><td>是</td><td>国家编号<br>参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#afwzp">字典表-国家编号</a><br>哥伦比亚，<code>COL</code></td></tr><tr><td>currency</td><td>String</td><td>是</td><td>币种<br>参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#huo-bi-currency">字典表-货币</a><br>哥伦比亚比索：<code>COP</code></td></tr><tr><td>orderAmount</td><td>String</td><td>是</td><td><p>订单金额<br>3000 >= <code>orderAmount</code> &#x3C;= 2000000</p><p>不支持小数</p></td></tr><tr><td>payProduct</td><td>String</td><td>是</td><td><a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#mfocd">支付类型</a><br>Cash：<code>03</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>sign</td><td>String</td><td>是</td><td>签名<br><a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/qian-ming-suan-fa">具体参照：签名算法</a></td></tr><tr><td>nonceStr</td><td>String</td><td>是</td><td>随机字符串<br>长度不能超过32位</td></tr><tr><td>customerEmail</td><td>String</td><td>是</td><td><p>用户邮箱<br>邮箱用户名不能只有数字（例如31231234@gmail.com）且</p><p>同一个邮箱一天支付请求不能超过20次。</p></td></tr><tr><td>customerName</td><td>String</td><td>是</td><td>用户名字</td></tr><tr><td>customerPhone</td><td>String</td><td>是</td><td>用户电话<br>需以3开头的十位数</td></tr><tr><td>customerIdentification</td><td>String</td><td>是</td><td>用户证件号</td></tr><tr><td>checkOut</td><td>Boolean</td><td>是</td><td>收银台<br><code>true</code>：需要收银台<br><code>false</code>：不需要收银台<br>建议传<code>true</code></td></tr><tr><td>customerAccount</td><td>String</td><td>否</td><td>用户账户<br><code>checkOut</code>为<code>false</code>时必传</td></tr><tr><td>lastName</td><td>String</td><td>否</td><td>用户姓氏<br><code>checkOut</code>为<code>false</code>时必传</td></tr><tr><td>customerIdentificationType</td><td>String</td><td>否</td><td><p>用户证件类型<br><code>00</code>：身份证（CC/TI）<br><code>01</code>：外国人身份证（CE）<br><code>02</code>：税号<br><code>03</code>：护照<br><code>06</code>：其他<br><code>07</code>：公民身份证明<br><code>08</code>：居留许可证</p><p><code>checkOut</code>为<code>false</code>时必传</p></td></tr><tr><td>customerAddress</td><td>String</td><td>否</td><td>用户地址<br><code>checkOut</code>为<code>false</code>时必传</td></tr><tr><td>tipo_persona</td><td>String</td><td>否</td><td>付款主体<br><code>checkOut</code>为<code>false</code>时必传</td></tr><tr><td>bankId</td><td>String</td><td>否</td><td>银行编码</td></tr><tr><td>expireTimeL</td><td>Long</td><td>否</td><td>过期时间<br>单位：秒；默认值：10分钟，最大值：10分钟</td></tr><tr><td>callbackUrl</td><td>String</td><td>是</td><td><p>回调地址</p><p>详见<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/tong-zhi-hui-tiao-shuo-ming">通知回调说明</a></p></td></tr><tr><td>description</td><td>String</td><td>是</td><td><p>描述 </p><p>不能带特殊符号,长度不超过200字符</p></td></tr></tbody></table>

### 请求示例

{% code fullWidth="true" %}

```json
{
	"callbackUrl": "https://d3vf2zxd9jv8rh.cloudfront.net/apigate/v6sx2i/api/pay_notice/in_payback/payId/CDEA3CA37DBC4C2CB6301AED14011122",
	"checkOut": true,
	"countryId": "COL",
	"currency": "COP",
	"customerAccount": "60872832",
	"customerEmail": "eaawxmn@gmail.com",
	"customerIdentification": "9145652857",
	"customerName": "Aaliyah Rogers",
	"customerPhone": "3073030686",
	"description": "Supefina",
	"lastName": "cith",
	"merId": "8302490290654651",
	"merOrderNo": "2025072510514243602509134",
	"nonceStr": "b2e310b6b06f49b8a1a01da0e1ed0357",
	"orderAmount": "20000",
	"payProduct": "03",
	"sign": "758402CA9039D41F2F884A5285039621"// 大写
}
```

{% endcode %}

签名组装字符串

callbackUrl=<https://d3vf2zxd9jv8rh.cloudfront.net/apigate/v6sx2i/api/pay\\_notice/in\\_payback/payId/CDEA3CA37DBC4C2CB6301AED14011122\\&checkOut=true\\&countryId=COL\\&currency=COP\\&customerAccount=60872832\\&customerEmail=eaawxmn@gmail.com\\&customerIdentification=9145652857\\&customerName=Aaliyah> Rogers\&customerPhone=3073030686\&description=Supefina\&lastName=cith\&merId=8302490290654651\&merOrderNo=2025072510514243602509134\&nonceStr=b2e310b6b06f49b8a1a01da0e1ed0357\&orderAmount=20000\&payProduct=03\&key=e8548e70a8ba4a658b0da4ef50600d42

### 响应参数

<table data-full-width="true"><thead><tr><th width="261">变量名</th><th width="179">类型</th><th width="396">描述</th></tr></thead><tbody><tr><td>code</td><td>String</td><td>响应编码<br>具体参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/xiang-ying-zhuang-tai-ma">响应状态码</a></td></tr><tr><td>msg</td><td>String</td><td>响应信息</td></tr><tr><td>data</td><td>Object</td><td>响应数据</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>supefinaOrderId</td><td>String</td><td>supefina订单号</td></tr><tr><td>amount</td><td>BigDecimal</td><td>订单金额</td></tr><tr><td>fee</td><td>String</td><td>预收手续费</td></tr><tr><td>identifier</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>orderExpirationTime</td><td>String</td><td>订单过期时间 （UTC 0时区时间）</td></tr></tbody></table>

#### 响应示例

{% code fullWidth="true" %}

```json
{
	"code": "200",
	"msg": "success ",
	"data": {
		"merCode": "8302490290654651",
		"merOrderNo": "2025072510514243602509134",
		"supefinaOrderNo": "20250725025143001000038155",
		"amount": 20000,
		"fee": 5.0,
		"transactionStatus": "00",
		"url": "https://docs.supefina.net/huan-ying-shi-yong-supefina-de-api-wen-dang/dai-shou/ge-lun-bi-ya",
		"referenceCode": "",
		"channelName": "rickipay",
		"orderExpirationTime": "2025-07-27T02:51:53.03"
	}
}
```

{% endcode %}

### 回调通知

提交方式：`POST`

<table data-full-width="true"><thead><tr><th width="234">变量名</th><th width="158">类型</th><th width="396">描述</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="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#afwzp">字典表-国家编号</a><br>哥伦比亚，COL</td></tr><tr><td>customerName</td><td>String</td><td>用户名字</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>sign</td><td>String</td><td>签名</td></tr><tr><td>status</td><td>String</td><td><a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#kxzkj">交易状态</a><br>具体参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#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": "20000.00",
	"countryId": "COL",
	"customerName": "Aaliyah Rogers",
	"fee": "5.00",
	"identifier": "a696e0ad-61c1-44",
	"merId": "8302490290654651",
	"merOrderId": "2025072510514243602509134",
	"msg": "SUCCESS",
	"nonceStr": "9312c568-8854-42dd-adc8-a4d9b5",
	"payerIdNumber": "9145652857",
	"payerName": "test",
	"realityAmount": "20000",
	"realityFee": "5.00",
	"sign": "A962FB48ECF86530AA42CAE859125987",// 大写
	"status": "01",
	"successTime": 1753411908000,
	"supefinaOrderId": "20250725025143001000038155",
	"transactionType": "01"
}
```

{% endcode %}

签名组装字符串

amount=20000.00\&countryId=COL\&customerName=Aaliyah Rogers\&fee=5.00\&identifier=a696e0ad-61c1-44\&merId=8302490290654651\&merOrderId=2025072510514243602509134\&msg=SUCCESS\&nonceStr=9312c568-8854-42dd-adc8-a4d9b5\&payerIdNumber=9145652857\&payerName=test\&realityAmount=20000\&realityFee=5.00\&status=01\&successTime=1753411908000\&supefinaOrderId=20250725025143001000038155\&transactionType=01\&key=e8548e70a8ba4a658b0da4ef50600d42

**回调通知响应**

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

{% code fullWidth="true" %}

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

{% endcode %}

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

重复支付：Cash可能会出现多次支付的情况，请注意处理收到多次支付通知。发生多次支付时，Supefina后台会创建多笔订单,并多次通知商户,商户可以通过通知中的<mark style="color:red;">**`supefinaOrderId`**</mark> 判断是否是同一订单。多次付款时，merOrderId保持不变，但每次的<mark style="color:red;">**supefinaOrderId**</mark>都会不同。
{% endhint %}


# All-Checkout

（payProduct=05）返回的支付链接选择bre-b，支持多笔支付生单

### 支付流程

<figure><img src="https://3631787624-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FuukVORWjXBgcGu8MirPR%2Fuploads%2FYakInUR5te4O7IXAlE2T%2F%E6%94%B6%E9%93%B6%E5%8F%B0.png?alt=media&amp;token=9d561ce7-55a7-4946-a6b4-8ef2bf30d6e9" alt=""><figcaption></figcaption></figure>

1、用户在商户网站/应用下单，并选择All-Checkout支付；

2、商户向Supefina发起All-Checkout支付请求；

3、Supefina返回All-Checkout支付URL地址；

4、商户将该地址在用户侧打开；

5、用户按照页面提示进行验证和支付；

6、用户支付成功；

7、Supefina将支付成功信息通知商户。

### 请求地址

<table data-full-width="true"><thead><tr><th width="138">环境名称</th><th width="607">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="219">变量名</th><th width="118">类型</th><th width="102">必填</th><th width="505">描述</th></tr></thead><tbody><tr><td>countryId</td><td>String</td><td>是</td><td>国家编号<br>参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#afwzp">字典表-国家编号</a><br>哥伦比亚，<code>COL</code></td></tr><tr><td>currency</td><td>String</td><td>是</td><td>币种<br>参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#huo-bi-currency">字典表-货币</a><br>哥伦比亚比索：<code>COP</code></td></tr><tr><td>orderAmount</td><td>String</td><td>是</td><td><p>订单金额<br>3000 >= orderAmount &#x3C;= 2000000</p><p>不支持小数</p></td></tr><tr><td>payProduct</td><td>String</td><td>是</td><td><a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#mfocd">支付类型</a><br>All-Checkout：<code>05</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>sign</td><td>String</td><td>是</td><td>签名<br><a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/qian-ming-suan-fa">具体参照：签名算法</a></td></tr><tr><td>nonceStr</td><td>String</td><td>是</td><td>随机字符串<br>长度不能超过32位</td></tr><tr><td>customerEmail</td><td>String</td><td>是</td><td>用户邮箱<br>邮箱用户名不能只有数字（例如31231234@gmail.com）且同一个邮箱一天支付请求不能超过20次。</td></tr><tr><td>customerName</td><td>String</td><td>是</td><td>用户名字</td></tr><tr><td>customerPhone</td><td>String</td><td>是</td><td>用户电话<br>需以3开头的十位数</td></tr><tr><td>customerIdentification</td><td>String</td><td>是</td><td>用户证件号</td></tr><tr><td>checkOut</td><td>Boolean</td><td>是</td><td>收银台<br><code>true</code>：需要收银台<br><code>false</code>：不需要收银台<br>建议传<code>true</code></td></tr><tr><td>customerAccount</td><td>String</td><td>否</td><td>用户账户<br><code>checkOut</code>为<code>false</code>时必传</td></tr><tr><td>lastName</td><td>String</td><td>否</td><td>用户姓氏<br><code>checkOut</code>为<code>false</code>时必传</td></tr><tr><td>customerIdentificationType</td><td>String</td><td>否</td><td><p>用户证件类型<br><code>00</code>：身份证（CC/TI）<br><code>01</code>：外国人身份证（CE）<br><code>02</code>：税号<br><code>03</code>：护照<br><code>06</code>：其他<br><code>07</code>：公民身份证明<br><code>08</code>：居留许可证</p><p><code>checkOut</code>为<code>false</code>时必传</p></td></tr><tr><td>customerAddress</td><td>String</td><td>否</td><td>用户地址<br><code>checkOut</code>为<code>false</code>时必传</td></tr><tr><td>tipo_persona</td><td>String</td><td>否</td><td>付款主体<br><code>checkOut</code>为<code>false</code>时必传</td></tr><tr><td>bankId</td><td>String</td><td>否</td><td>银行编码<br>参照：https://api.supefina.net/api/supefina/transactions/internal/getEbixuBankList<br><code>checkOut</code>为<code>false</code>时必传</td></tr><tr><td>expireTimeL</td><td>Long</td><td>否</td><td>过期时间<br>单位：秒；默认值：10分钟，最大值：10分钟</td></tr><tr><td>callbackUrl</td><td>String</td><td>是</td><td><p>回调地址</p><p>详见<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/tong-zhi-hui-tiao-shuo-ming">通知回调说明</a></p></td></tr><tr><td>description</td><td>String</td><td>是</td><td><p>描述 </p><p>不能带特殊符号,长度不超过200字符</p></td></tr></tbody></table>

### 请求示例

{% code fullWidth="true" %}

```json
{
	"callbackUrl": "http://8.130.9.219:8899/api/supefina/transactions/test/zx",
	"checkOut": true,
	"countryId": "COL",
	"currency": "COP",
	"customerEmail": "eaawxmn@gmail.com",
	"customerIdentification": "7204824538",
	"customerName": "Sqtjjs Syuijfs",
	"customerPhone": "3183178077",
	"description": "Supefina",
	"merId": "8302490290654651",
	"merOrderNo": "2025072510590311464550871",
	"nonceStr": "77e7ef0a38b542828b7b88585aab6d7b",
	"orderAmount": "3001",
	"payProduct": "05",
	"sign": "26A96C032245A3825149F76478FB01BE"// 大写
}
```

{% endcode %}

签名组装字符串

callbackUrl=<http://8.130.9.219:8899/api/supefina/transactions/test/zx\\&checkOut=true\\&countryId=COL\\&currency=COP\\&customerEmail=eaawxmn@gmail.com\\&customerIdentification=7204824538\\&customerName=Sqtjjs> Syuijfs\&customerPhone=3183178077\&description=Supefina\&merId=8302490290654651\&merOrderNo=2025072510590311464550871\&nonceStr=77e7ef0a38b542828b7b88585aab6d7b\&orderAmount=3001\&payProduct=05\&key=e8548e70a8ba4a658b0da4ef50600d42

### 响应参数

<table data-full-width="true"><thead><tr><th width="223">变量名</th><th width="179">类型</th><th width="396">描述</th></tr></thead><tbody><tr><td>code</td><td>String</td><td>响应编码<br>具体参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/xiang-ying-zhuang-tai-ma">响应状态码</a></td></tr><tr><td>msg</td><td>String</td><td>响应信息</td></tr><tr><td>data</td><td>Object</td><td>响应数据</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>supefinaOrderId</td><td>String</td><td>supefina订单号</td></tr><tr><td>amount</td><td>BigDecimal</td><td>订单金额</td></tr><tr><td>fee</td><td>String</td><td>预收手续费</td></tr><tr><td>identifier</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>orderExpirationTime</td><td>String</td><td>订单过期时间 （UTC 0时区时间）</td></tr></tbody></table>

#### 响应示例

{% code fullWidth="true" %}

```json
{
	"code": "200",
	"msg": "success ",
	"data": {
		"merCode": "8302490290654651",
		"merOrderNo": "2025072510590311464550871",
		"supefinaOrderNo": "20250725025904026000038301",
		"amount": 3001,
		"fee": 5.0,
		"transactionStatus": "00",
		"url": "https://docs.supefina.net/huan-ying-shi-yong-supefina-de-api-wen-dang/dai-shou/ge-lun-bi-ya",
		"referenceCode": "",
		"channelName": "rickipay",
		"orderExpirationTime": "2025-07-27T02:59:14.059"
	}
}
```

{% endcode %}

### 回调通知

\
提交方式：`POST`

<table data-full-width="true"><thead><tr><th width="261">变量名</th><th width="179">类型</th><th width="396">描述</th></tr></thead><tbody><tr><td>amount</td><td>String</td><td>订单金额</td></tr><tr><td>countryId</td><td>String</td><td>国家编号</td></tr><tr><td>customerName</td><td>String</td><td>用户名字</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>sign</td><td>String</td><td>签名</td></tr><tr><td>status</td><td>String</td><td><a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#kxzkj">交易状态</a><br>具体参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#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>01：代收<br>02：代付</td></tr></tbody></table>

#### 回调通知示例

{% code fullWidth="true" %}

```json
{
	"amount": "3001.00",
	"countryId": "COL",
	"customerName": "Sqtjjs Syuijfs",
	"fee": "5.00",
	"identifier": "d07b3b96-c252-40",
	"merId": "8302490290654651",
	"merOrderId": "2025072510590311464550871",
	"msg": "SUCCESS",
	"nonceStr": "e37cf60f-e229-4a23-83e9-8b5092",
	"payerIdNumber": "7204824538",
	"payerName": "test",
	"realityAmount": "3001",
	"realityFee": "5.00",
	"sign": "30E7419F336A94957D020AFF7745D67D",// 大写
	"status": "01",
	"successTime": 1753412349000,
	"supefinaOrderId": "20250725025904026000038301",
	"transactionType": "01"
}
```

{% endcode %}

签名组装字符串

amount=3001.00\&countryId=COL\&customerName=Sqtjjs Syuijfs\&fee=5.00\&identifier=d07b3b96-c252-40\&merId=8302490290654651\&merOrderId=2025072510590311464550871\&msg=SUCCESS\&nonceStr=e37cf60f-e229-4a23-83e9-8b5092\&payerIdNumber=7204824538\&payerName=test\&realityAmount=3001\&realityFee=5.00\&status=01\&successTime=1753412349000\&supefinaOrderId=20250725025904026000038301\&transactionType=01\&key=e8548e70a8ba4a658b0da4ef50600d42

**回调通知响应**

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

{% code fullWidth="true" %}

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

{% endcode %}

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

重复支付：All-Checkout可能会出现多次支付的情况，请注意处理收到多次支付通知。发生多次支付时，Supefina后台会创建多笔订单,并多次通知商户,商户可以通过通知中的<mark style="color:red;">**`supefinaOrderId`**</mark> 判断是否是同一订单。多次付款时，merOrderId保持不变，但每次的<mark style="color:red;">**supefinaOrderId**</mark>都会不同。
{% endhint %}


# Bre-B

（payProduct=23）支持重复生单

### 支付流程

<figure><img src="https://3631787624-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FuukVORWjXBgcGu8MirPR%2Fuploads%2FZKAF4rjlcRSqmfVy0ecZ%2Fimage.png?alt=media&amp;token=dd5e10cb-45e7-4a0d-9623-f36a5af7a5fb" alt=""><figcaption></figcaption></figure>

1. 用户在商户网站/应用下单，并选择Bre-B支付；
2. 商户向Supefina发起Bre-B支付请求；
3. Supefina返回Bre-B支付URL地址；
4. 商户将该地址在用户侧打开；
5. 用户按照页面提示进行验证和支付；
6. 用户支付成功；
7. Supefina将支付成功信息通知商户。

### 请求地址

<table data-full-width="true"><thead><tr><th width="138">环境名称</th><th width="607">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="220">变量名</th><th width="102">类型</th><th width="89">必填</th><th>描述</th></tr></thead><tbody><tr><td>countryId</td><td>String</td><td>是</td><td>国家编号<br>参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#afwzp">字典表-国家编号</a><br>哥伦比亚，<code>COL</code></td></tr><tr><td>currency</td><td>String</td><td>是</td><td>币种<br>参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#huo-bi-currency">字典表-货币</a><br>哥伦比亚比索：<code>COP</code></td></tr><tr><td>orderAmount</td><td>String</td><td>是</td><td><p>订单金额<br>3000 >= <code>orderAmount</code> &#x3C;= 2000000</p><p>不支持小数</p></td></tr><tr><td>payProduct</td><td>String</td><td>是</td><td><a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#mfocd">支付类型</a><br>Bre-B：<code>23</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>sign</td><td>String</td><td>是</td><td>签名<br><a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/qian-ming-suan-fa">具体参照：签名算法</a></td></tr><tr><td>nonceStr</td><td>String</td><td>是</td><td>随机字符串<br>长度不能超过32位</td></tr><tr><td>customerEmail</td><td>String</td><td>是</td><td><p>用户邮箱<br>邮箱用户名不能只有数字（例如31231234@gmail.com）且</p><p>同一个邮箱一天支付请求不能超过20次。</p></td></tr><tr><td>customerName</td><td>String</td><td>是</td><td>用户名字</td></tr><tr><td>customerPhone</td><td>String</td><td>是</td><td>用户电话<br>需以3开头的十位数</td></tr><tr><td>customerIdentification</td><td>String</td><td>是</td><td>用户证件号</td></tr><tr><td>checkOut</td><td>Boolean</td><td>是</td><td>收银台<br><code>true</code>：需要收银台<br><code>false</code>：不需要收银台<br>建议传<code>true</code></td></tr><tr><td>customerAccount</td><td>String</td><td>否</td><td>用户账户<br><code>checkOut</code>为<code>false</code>时必传</td></tr><tr><td>lastName</td><td>String</td><td>否</td><td>用户姓氏<br><code>checkOut</code>为<code>false</code>时必传</td></tr><tr><td>customerIdentificationType</td><td>String</td><td>否</td><td><p>用户证件类型<br><code>00</code>：身份证（CC/TI）<br><code>01</code>：外国人身份证（CE）<br><code>02</code>：税号<br><code>03</code>：护照<br><code>06</code>：其他<br><code>07</code>：公民身份证明<br><code>08</code>：居留许可证</p><p><code>checkOut</code>为<code>false</code>时必传</p></td></tr><tr><td>customerAddress</td><td>String</td><td>否</td><td>用户地址<br><code>checkOut</code>为<code>false</code>时必传</td></tr><tr><td>tipo_persona</td><td>String</td><td>否</td><td>付款主体<br><code>checkOut</code>为<code>false</code>时必传</td></tr><tr><td>bankId</td><td>String</td><td>否</td><td>银行编码</td></tr><tr><td>expireTimeL</td><td>Long</td><td>否</td><td>过期时间<br>单位：秒；默认值：10分钟，最大值：10分钟</td></tr><tr><td>callbackUrl</td><td>String</td><td>是</td><td><p>回调地址</p><p>详见<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/tong-zhi-hui-tiao-shuo-ming">通知回调说明</a></p></td></tr><tr><td>description</td><td>String</td><td>是</td><td><p>描述 </p><p>不能带特殊符号,长度不超过200字符</p></td></tr></tbody></table>

### 请求示例

{% code fullWidth="true" %}

```json
{
	"callbackUrl": "https://d3vf2zxd9jv8rh.cloudfront.net/apigate/v6sx2i/api/pay_notice/in_payback/payId/CDEA3CA37DBC4C2CB6301AED14011122",
	"checkOut": true,
	"countryId": "COL",
	"currency": "COP",
	"customerAccount": "60872832",
	"customerEmail": "eaawxmn@gmail.com",
	"customerIdentification": "9145652857",
	"customerName": "Aaliyah Rogers",
	"customerPhone": "3073030686",
	"description": "Supefina",
	"lastName": "cith",
	"merId": "8302490290654651",
	"merOrderNo": "2025072510514243602509134",
	"nonceStr": "b2e310b6b06f49b8a1a01da0e1ed0357",
	"orderAmount": "20000",
	"payProduct": "23",
	"sign": "758402CA9039D41F2F884A5285039621"// 大写
}
```

{% endcode %}

签名组装字符串

callbackUrl=<https://d3vf2zxd9jv8rh.cloudfront.net/apigate/v6sx2i/api/pay\\_notice/in\\_payback/payId/CDEA3CA37DBC4C2CB6301AED14011122\\&checkOut=true\\&countryId=COL\\&currency=COP\\&customerAccount=60872832\\&customerEmail=eaawxmn@gmail.com\\&customerIdentification=9145652857\\&customerName=Aaliyah> Rogers\&customerPhone=3073030686\&description=Supefina\&lastName=cith\&merId=8302490290654651\&merOrderNo=2025072510514243602509134\&nonceStr=b2e310b6b06f49b8a1a01da0e1ed0357\&orderAmount=20000\&payProduct=23\&key=e8548e70a8ba4a658b0da4ef50600d42

### 响应参数

<table data-full-width="true"><thead><tr><th width="261">变量名</th><th width="179">类型</th><th width="396">描述</th></tr></thead><tbody><tr><td>code</td><td>String</td><td>响应编码<br>具体参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/xiang-ying-zhuang-tai-ma">响应状态码</a></td></tr><tr><td>msg</td><td>String</td><td>响应信息</td></tr><tr><td>data</td><td>Object</td><td>响应数据</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>supefinaOrderId</td><td>String</td><td>supefina订单号</td></tr><tr><td>amount</td><td>BigDecimal</td><td>订单金额</td></tr><tr><td>fee</td><td>String</td><td>预收手续费</td></tr><tr><td>identifier</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>orderExpirationTime</td><td>String</td><td>订单过期时间 （UTC 0时区时间）</td></tr></tbody></table>

#### 响应示例

{% code fullWidth="true" %}

```json
{
	"code": "200",
	"msg": "success ",
	"data": {
		"merCode": "8302490290654651",
		"merOrderNo": "2025072510514243602509134",
		"supefinaOrderNo": "20250725025143001000038155",
		"amount": 20000,
		"fee": 5.0,
		"transactionStatus": "00",
		"url": "https://docs.supefina.net/huan-ying-shi-yong-supefina-de-api-wen-dang/dai-shou/ge-lun-bi-ya",
		"referenceCode": "",
		"channelName": "rickipay",
		"orderExpirationTime": "2025-07-27T02:51:53.03"
	}
}
```

{% endcode %}

### 回调通知

提交方式：`POST`

<table data-full-width="true"><thead><tr><th width="234">变量名</th><th width="158">类型</th><th width="396">描述</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="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#afwzp">字典表-国家编号</a><br>哥伦比亚，COL</td></tr><tr><td>customerName</td><td>String</td><td>用户名字</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>sign</td><td>String</td><td>签名</td></tr><tr><td>status</td><td>String</td><td><a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#kxzkj">交易状态</a><br>具体参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#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": "20000.00",
	"countryId": "COL",
	"customerName": "Aaliyah Rogers",
	"fee": "5.00",
	"identifier": "a696e0ad-61c1-44",
	"merId": "8302490290654651",
	"merOrderId": "2025072510514243602509134",
	"msg": "SUCCESS",
	"nonceStr": "9312c568-8854-42dd-adc8-a4d9b5",
	"payerIdNumber": "9145652857",
	"payerName": "test",
	"realityAmount": "20000",
	"realityFee": "5.00",
	"sign": "A962FB48ECF86530AA42CAE859125987",// 大写
	"status": "01",
	"successTime": 1753411908000,
	"supefinaOrderId": "20250725025143001000038155",
	"transactionType": "01"
}
```

{% endcode %}

签名组装字符串

amount=20000.00\&countryId=COL\&customerName=Aaliyah Rogers\&fee=5.00\&identifier=a696e0ad-61c1-44\&merId=8302490290654651\&merOrderId=2025072510514243602509134\&msg=SUCCESS\&nonceStr=9312c568-8854-42dd-adc8-a4d9b5\&payerIdNumber=9145652857\&payerName=test\&realityAmount=20000\&realityFee=5.00\&status=01\&successTime=1753411908000\&supefinaOrderId=20250725025143001000038155\&transactionType=01\&key=e8548e70a8ba4a658b0da4ef50600d42

**回调通知响应**

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

{% code fullWidth="true" %}

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

{% endcode %}

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

重复支付：Cash可能会出现多次支付的情况，请注意处理收到多次支付通知。发生多次支付时，Supefina后台会创建多笔订单,并多次通知商户,商户可以通过通知中的<mark style="color:red;">**`supefinaOrderId`**</mark> 判断是否是同一订单。多次付款时，merOrderId保持不变，但每次的<mark style="color:red;">**supefinaOrderId**</mark>都会不同。
{% endhint %}


# 秘鲁

在秘鲁，我们提供银行转账（Transfer），现金支付（Cash），电子钱包（Wallet）等支付产品。

<figure><img src="https://3631787624-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FuukVORWjXBgcGu8MirPR%2Fuploads%2FFb4pencGMuk6wVgLlugn%2F%E7%A7%98%E9%B2%81-update.jpg?alt=media&amp;token=003b3f26-3446-4cdb-9582-c4d5fa23019a" alt=""><figcaption></figcaption></figure>

{% content-ref url="/pages/v7MBkOtqDmVdhXKgiy3T" %}
[Transfer](/huan-ying-shi-yong-supefina-de-api-wen-dang/dai-shou/bi-lu/transfer)
{% endcontent-ref %}

{% content-ref url="/pages/ecvWeiomKIbP4i3OkEyC" %}
[Cash](/huan-ying-shi-yong-supefina-de-api-wen-dang/dai-shou/bi-lu/cash)
{% endcontent-ref %}

{% content-ref url="/pages/l9CqsRbCBeJRt5MdZEBc" %}
[Wallet](/huan-ying-shi-yong-supefina-de-api-wen-dang/dai-shou/bi-lu/wallet)
{% endcontent-ref %}

{% content-ref url="/pages/ca7GpRcSHxkj9rVKVXoi" %}
[Broken mention](broken://pages/ca7GpRcSHxkj9rVKVXoi)
{% endcontent-ref %}


# Transfer

（payProduct=12）

### 支付流程

<figure><img src="https://3631787624-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FuukVORWjXBgcGu8MirPR%2Fuploads%2FxQmJK1BZFAoeGatZcutp%2Ftransfer.png?alt=media&amp;token=4f62280d-cbca-4ef1-8e69-cd2f7d559451" alt=""><figcaption></figcaption></figure>

1、用户在商户网站/应用下单，并选择Transfer支付；

2、商户向Supefina发起Transfer支付请求；

3、Supefina返回Transfer支付URL地址；

4、商户将该地址在用户侧打开；

5、用户按照页面提示进行验证和支付；

6、用户支付成功；

7、Supefina将支付成功信息通知商户。

### 请求地址

<table data-full-width="true"><thead><tr><th width="138">环境名称</th><th width="607">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><p><mark style="color:red;"><code>POST</code></mark></p><p><mark style="color:red;">https://api.supefina.net/api/supefina/transactions/payin</mark></p></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="253">变量名</th><th width="119">类型</th><th width="103">必填</th><th width="418">描述</th></tr></thead><tbody><tr><td>callbackUrl</td><td>String</td><td>是</td><td><p>回调地址</p><p>详见<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/tong-zhi-hui-tiao-shuo-ming">通知回调说明</a></p></td></tr><tr><td>checkOut</td><td>Boolean</td><td>否</td><td>收银台<br><code>true</code>：需要收银台<br><code>false</code>：不需要收银台<br>建议传<code>true</code></td></tr><tr><td>countryId</td><td>String</td><td>是</td><td><p>国家编号<br>参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#afwzp">字典表-国家编号</a></p><p>秘鲁：<code>PER</code></p></td></tr><tr><td>currency</td><td>String</td><td>是</td><td><p>币种<br>参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#huo-bi-currency">字典表-货币</a></p><p>秘鲁索尔：<code>PEN</code></p></td></tr><tr><td>customerEmail</td><td>String</td><td>是</td><td>用户邮箱</td></tr><tr><td>customerIdentification</td><td>String</td><td>是</td><td><p>用户证件号<br><code>00</code>：身份证（CC），8位<br><code>01</code>：外国人身份证（CE），大于9位<br><code>02</code>：税号，11位</p><p><code>03</code>：护照，大于9位</p><p><code>04</code>：出生证明（PAR）<br><code>05</code>：军官证（LMI）</p><p>同一个证件号<code>customerIdentification</code>进行代收时，游戏商户每天不超过5次，贷类商户每天不超过20次</p></td></tr><tr><td>customerIdentificationType</td><td>String</td><td>是</td><td><p>用户证件类型<br><code>00</code>：身份证（CC）<br><code>01</code>：外国人身份证（CE）</p><p><code>02</code>:   税号<br><code>03</code>：护照（PAS)<br><code>04</code>：出生证明（PAR）<br><code>05</code>：军官证（LMI）</p></td></tr><tr><td>customerName</td><td>String</td><td>是</td><td>用户姓名</td></tr><tr><td>customerPhone</td><td>String</td><td>是</td><td><p>用户电话, 9位数字</p><p>示例：975728895</p></td></tr><tr><td>expireTimeL</td><td>Long</td><td>否</td><td>过期时间<br>单位：秒；默认值：1天 ;最大值：30天 ;最小值：没有</td></tr><tr><td>lastName</td><td>String</td><td>是</td><td>用户姓氏</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>orderAmount</td><td>String</td><td>是</td><td>订单金额</td></tr><tr><td>payProduct</td><td>String</td><td>是</td><td><a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#mfocd">支付类型</a><br>Transfer：<code>12</code></td></tr><tr><td>sign</td><td>String</td><td>是</td><td>签名<br><a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/qian-ming-suan-fa">具体参照：签名算法</a></td></tr><tr><td>description</td><td>String</td><td>否</td><td>描述<br>不能带特殊符号,长度不超过200字符</td></tr></tbody></table>

### 请求示例1

{% code fullWidth="true" %}

```json
{
	"callbackUrl": "https://test.com",
	"checkOut": true,
	"countryId": "PER",
	"currency": "PEN",
	"customerEmail": "test@gmail.com",
	"customerIdentification": "76017743",
	"customerIdentificationType": "00",
	"customerName": "Test Name",
	"customerPhone": "975728895",
	"description": "asda",
	"lastName": "Name",
	"merId": "8302258550224656",
	"merOrderNo": "2025072610423152386227034",
	"nonceStr": "b01215ef9d34481997899c3fb89931f9",
	"orderAmount": "60.00",
	"payProduct": "12",
	"sign": "96AC718FE05F2D57EC265B44A07D0C0A"// 大写
}
```

{% endcode %}

签名组装字符串

callbackUrl=<https://test.com\\&checkOut=true\\&countryId=PER\\&currency=PEN\\&customerEmail=test@gmail.com\\&customerIdentification=76017743\\&customerIdentificationType=00\\&customerName=Test> Name\&customerPhone=975728895\&description=asda\&lastName=Name\&merId=8302258550224656\&merOrderNo=2025072610423152386227034\&nonceStr=b01215ef9d34481997899c3fb89931f9\&orderAmount=60.00\&payProduct=12\&key=10c44658d50e4d0da0fe1e5f7c9074a7

请求示例2

```
"checkOut": false
```

```json
{
	"callbackUrl": "https://test.com",
	"checkOut": false,
	"countryId": "PER",
	"currency": "PEN",
	"customerEmail": "test@gmail.com",
	"customerIdentification": "76017743",
	"customerIdentificationType": "00",
	"customerName": "Test Name",
	"customerPhone": "975728895",
	"description": "asda",
	"lastName": "Name",
	"merId": "8302258550224656",
	"merOrderNo": "2025072610510594611171518",
	"nonceStr": "d9a101d4894f4eb99d999c8dd71ccc35",
	"orderAmount": "60.00",
	"payProduct": "12",
	"sign": "C827977DB50ADA0CD130E744F1CBAFD9"// 大写
}
```

签名组装字符串

callbackUrl=<https://test.com\\&checkOut=false\\&countryId=PER\\&currency=PEN\\&customerEmail=test@gmail.com\\&customerIdentification=76017743\\&customerIdentificationType=00\\&customerName=Test> Name\&customerPhone=975728895\&description=asda\&lastName=Name\&merId=8302258550224656\&merOrderNo=2025072610510594611171518\&nonceStr=d9a101d4894f4eb99d999c8dd71ccc35\&orderAmount=60.00\&payProduct=12\&key=10c44658d50e4d0da0fe1e5f7c9074a7

### 响应参数

<table data-full-width="true"><thead><tr><th width="225">变量名</th><th width="168">类型</th><th width="418">描述</th></tr></thead><tbody><tr><td>code</td><td>String</td><td>响应编码<br>具体参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/xiang-ying-zhuang-tai-ma">响应状态码</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>fee</td><td>BigDecimal</td><td>预收手续费</td></tr><tr><td>identifier</td><td>String</td><td>付款参考</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>supefinaOrderNo</td><td>String</td><td>supefina订单号</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": "8302258550224656",
		"merOrderNo": "2025072610423152386227034",
		"supefinaOrderNo": "2025071948936948407578624",
		"amount": 60.0,
		"url": "http://h5.supefina.tech/combineCashier?token=3d3b7eba278944969eeba158899f4aa6",
		"currency": "PEN"
	}
}
```

{% endcode %}

#### 响应示例2

```json
{
	"code": "200",
	"msg": "success ",
	"data": {
		"merCode": "8302258550224656",
		"merOrderNo": "2025072610510594611171518",
		"supefinaOrderNo": "20250726010100017ad96e63d7e4c",
		"amount": 60.0,
		"fee": 1.6,
		"transactionStatus": "00"
	}
}
```

### 回调通知

提交方式：`POST`

<table data-full-width="true"><thead><tr><th width="213">变量名</th><th width="176">类型</th><th width="418">描述</th></tr></thead><tbody><tr><td>amount</td><td>String</td><td>订单金额</td></tr><tr><td>countryId</td><td>String</td><td>国家编号</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>商户编号</td></tr><tr><td>merOrderId</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="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#kxzkj">交易状态</a><br>具体参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#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": "60.00",
	"countryId": "PER",
	"customerName": "Test Name",
	"fee": "1.60",
	"merId": "8302258550224656",
	"merOrderId": "2025072610423152386227034",
	"nonceStr": "516d3dad-2a6a-417a-b3fc-ee651c",
	"realityAmount": "60.00",
	"realityFee": "1.60",
	"reference": "CRTBX7BFYWRJS0AS2ANUTFKOU6O7YST",
	"sign": "F951911BA813F33FAEA12CAE4527A560",// 大写
	"status": "01",
	"successTime": 1753497822961,
	"supefinaOrderId": "2025071948936948407578624",
	"transactionType": "01"
}
```

{% endcode %}

签名组装字符串

amount=60.00\&countryId=PER\&customerName=Test Name\&fee=1.60\&merId=8302258550224656\&merOrderId=2025072610423152386227034\&nonceStr=516d3dad-2a6a-417a-b3fc-ee651c\&realityAmount=60.00\&realityFee=1.60\&reference=CRTBX7BFYWRJS0AS2ANUTFKOU6O7YST\&status=01\&successTime=1753497822961\&supefinaOrderId=2025071948936948407578624\&transactionType=01\&key=10c44658d50e4d0da0fe1e5f7c9074a7

**回调通知响应**

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

{% code fullWidth="true" %}

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

{% endcode %}


# Cash

（payProduct=03）

### 支付流程

<figure><img src="https://3631787624-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FuukVORWjXBgcGu8MirPR%2Fuploads%2FjaP8k7IuMK21PVykdZYz%2FCash.png?alt=media&amp;token=74a9a5cd-7280-48dd-a973-cddd0780d3f8" alt=""><figcaption></figcaption></figure>

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

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

&#x20;3、Supefina返回Cash付款URL信息。

&#x20;4、商户将该支付URL展示给用户；

&#x20;5、用户按照页面提示进行付款；

6、付款成功；

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

### 请求地址

<table data-full-width="true"><thead><tr><th width="138">环境名称</th><th width="607">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="257">变量名</th><th width="104">类型</th><th width="100">必填</th><th width="428">描述</th></tr></thead><tbody><tr><td>countryId</td><td>String</td><td>是</td><td><p>国家编号<br>参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#afwzp">字典表-国家编号</a></p><p>秘鲁：<code>PER</code></p></td></tr><tr><td>currency</td><td>String</td><td>是</td><td><p>币种<br>参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#huo-bi-currency">字典表-货币</a></p><p>秘鲁索尔：<code>PEN</code></p></td></tr><tr><td>orderAmount</td><td>String</td><td>是</td><td>订单金额</td></tr><tr><td>payProduct</td><td>String</td><td>是</td><td><a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#mfocd">支付类型</a><br>Cash：<code>03</code></td></tr><tr><td>customerIdentification</td><td>String</td><td>是</td><td><p>用户证件号<br><code>00</code>：身份证（CC），8位<br><code>01</code>：外国人身份证（CE），大于9位<br><code>02</code>：税号，11位</p><p><code>03</code>：护照，大于9位</p><p><code>04</code>：离境证（PAR）<br><code>05</code>：军官证（LMI）</p><p>同一个证件号<code>customerIdentification</code>进行代收时，游戏商户每天不超过5次，贷类商户每天不超过20次</p></td></tr><tr><td>customerIdentificationType</td><td>String</td><td>是</td><td><p>用户证件类型<br><code>00</code>：身份证（CC）<br><code>01</code>：外国人身份证（CE）</p><p><code>02</code>:   税号<br><code>03</code>：护照（PAS)<br><code>04</code>：离境证（PAR）<br><code>05</code>：军官证（LMI）</p></td></tr><tr><td>customerName</td><td>String</td><td>是</td><td>用户姓名</td></tr><tr><td>lastName</td><td>String</td><td>是</td><td>用户姓氏</td></tr><tr><td>customerPhone</td><td>String</td><td>是</td><td><p>用户电话,  9位数字</p><p>示例：975728895</p></td></tr><tr><td>customerEmail</td><td>String</td><td>是</td><td>用户邮箱</td></tr><tr><td>expireTimeL</td><td>Long</td><td>否</td><td>过期时间<br>单位：秒；默认值：1天 ;最大值：30天 ;最小值：没有</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>callbackUrl</td><td>String</td><td>是</td><td><p>回调地址</p><p>详见<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/tong-zhi-hui-tiao-shuo-ming">通知回调说明</a></p></td></tr><tr><td>checkOut</td><td>Boolean</td><td>否</td><td>收银台<br><code>true</code>：需要收银台<br><code>false</code>：不需要收银台<br>建议传<code>true</code></td></tr><tr><td>nonceStr</td><td>String</td><td>是</td><td>随机字符串<br>长度不能超过32位</td></tr><tr><td>sign</td><td>String</td><td>是</td><td>签名<br><a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/qian-ming-suan-fa">具体参照：签名算法</a></td></tr><tr><td>description</td><td>String</td><td>否</td><td>描述<br>不能带特殊符号,长度不超过200字符</td></tr></tbody></table>

### 请求示例

{% code fullWidth="true" %}

```json
{
	"callbackUrl": "https://test.com",
	"checkOut": true,
	"countryId": "PER",
	"currency": "PEN",
	"customerEmail": "961204265@gmail.com",
	"customerIdentification": "76017743",
	"customerIdentificationType": "00",
	"customerName": "Test Name",
	"customerPhone": "975728895",
	"description": "xxx",
	"expireTimeL": 3600,
	"lastName": "Name",
	"merId": "8302258550224656",
	"merOrderNo": "2025072611333353185994189",
	"nonceStr": "b2c1934e51b84385acbbb66f58ca43fe",
	"orderAmount": "230.00",
	"payProduct": "03",
	"sign": "6F383EF7A8709B5E80620E08F69CC3D0"// 大写
}
```

{% endcode %}

签名组装字符串

callbackUrl=<https://test.com\\&checkOut=true\\&countryId=PER\\&currency=PEN\\&customerEmail=961204265@gmail.com\\&customerIdentification=76017743\\&customerIdentificationType=00\\&customerName=Test> Name\&customerPhone=975728895\&description=xxx\&expireTimeL=3600\&lastName=Name\&merId=8302258550224656\&merOrderNo=2025072611333353185994189\&nonceStr=b2c1934e51b84385acbbb66f58ca43fe\&orderAmount=230.00\&payProduct=03\&key=10c44658d50e4d0da0fe1e5f7c9074a7

### 响应参数

<table data-full-width="true"><thead><tr><th width="208">变量名</th><th width="138">类型</th><th width="447">描述</th></tr></thead><tbody><tr><td>code</td><td>String</td><td>响应编码<br>具体参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/xiang-ying-zhuang-tai-ma">响应状态码</a></td></tr><tr><td>data</td><td>Object</td><td>响应数据</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>amount</td><td>BigDecimal</td><td>订单金额</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": "8302258550224656",
		"merOrderNo": "2025072611333353185994189",
		"supefinaOrderNo": "2025071948949789537710080",
		"amount": 230.0,
		"url": "http://h5.supefina.tech/combineCashier?token=67cca65e5e4649cd846dafd40484320c",
		"currency": "PEN"
	}
}
```

{% endcode %}

### 回调通知

提交方式：`POST`

<table data-full-width="true"><thead><tr><th width="222">变量名</th><th width="138">类型</th><th width="447">描述</th></tr></thead><tbody><tr><td>amount</td><td>String</td><td>订单金额</td></tr><tr><td>countryId</td><td>String</td><td>国家编号</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>商户编号</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="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#kxzkj">交易状态</a><br>具体参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#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": "230.00",
	"countryId": "PER",
	"customerName": "Test Name",
	"fee": "3.30",
	"merId": "8302258550224656",
	"merOrderId": "2025072611333353185994189",
	"nonceStr": "616ddb3d-f5e9-461d-a6d8-c64d8f",
	"realityAmount": "230.00",
	"realityFee": "3.30",
	"reference": "CRTPFNDFFRMPA270A7KE37ORRRBAKSW",
	"sign": "B1D93E284B244611A13D445C9F0703C2",// 大写
	"status": "01",
	"successTime": 1753500831083,
	"supefinaOrderId": "2025071948949789537710080",
	"transactionType": "01"
}
```

{% endcode %}

签名组装字符串

amount=230.00\&countryId=PER\&customerName=Test Name\&fee=3.30\&merId=8302258550224656\&merOrderId=2025072611333353185994189\&nonceStr=616ddb3d-f5e9-461d-a6d8-c64d8f\&realityAmount=230.00\&realityFee=3.30\&reference=CRTPFNDFFRMPA270A7KE37ORRRBAKSW\&status=01\&successTime=1753500831083\&supefinaOrderId=2025071948949789537710080\&transactionType=01\&key=10c44658d50e4d0da0fe1e5f7c9074a7

**回调通知响应**

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

{% code fullWidth="true" %}

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

{% endcode %}


# Wallet

（payProduct=23）

### 支付流程

<figure><img src="https://3631787624-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FuukVORWjXBgcGu8MirPR%2Fuploads%2FxQmJK1BZFAoeGatZcutp%2Ftransfer.png?alt=media&amp;token=4f62280d-cbca-4ef1-8e69-cd2f7d559451" alt=""><figcaption></figcaption></figure>

1、用户在商户网站/应用下单，并选择Wallet支付；

2、商户向Supefina发起Wallet支付请求；

3、Supefina返回Wallet支付URL地址；

4、商户将该地址在用户侧打开；

5、用户按照页面提示进行验证和支付；

6、用户支付成功；

7、Supefina将支付成功信息通知商户。

### 请求地址

<table data-full-width="true"><thead><tr><th width="138">环境名称</th><th width="607">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><p><mark style="color:red;"><code>POST</code></mark></p><p><mark style="color:red;">https://api.supefina.net/api/supefina/transactions/payin</mark></p></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="256">变量名</th><th width="116">类型</th><th width="109">必填</th><th width="584">描述</th></tr></thead><tbody><tr><td>callbackUrl</td><td>String</td><td>是</td><td><p>回调地址</p><p>详见<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/tong-zhi-hui-tiao-shuo-ming">通知回调说明</a></p></td></tr><tr><td>checkOut</td><td>Boolean</td><td>否</td><td>收银台<br><code>true</code>：需要收银台<br><code>false</code>：不需要收银台<br>建议传<code>true</code></td></tr><tr><td>countryId</td><td>String</td><td>是</td><td><p>国家编号<br>参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#afwzp">字典表-国家编号</a></p><p>秘鲁：<code>PER</code></p></td></tr><tr><td>currency</td><td>String</td><td>是</td><td><p>币种<br>参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#huo-bi-currency">字典表-货币</a></p><p>秘鲁索尔：<code>PEN</code></p></td></tr><tr><td>customerEmail</td><td>String</td><td>是</td><td>用户邮箱</td></tr><tr><td>customerIdentification</td><td>String</td><td>是</td><td><p>用户证件号<br><code>00</code>：身份证（CC），8位<br><code>01</code>：外国人身份证（CE），大于9位<br><code>02</code>：税号，11位</p><p><code>03</code>：护照，大于9位</p><p><code>04</code>：离境证（PAR）<br><code>05</code>：军官证（LMI）</p><p>同一个证件号<code>customerIdentification</code>进行代收时，游戏商户每天不超过5次，贷类商户每天不超过20次</p></td></tr><tr><td>customerIdentificationType</td><td>String</td><td>是</td><td><p>用户证件类型<br><code>00</code>：身份证（CC）<br><code>01</code>：外国人身份证（CE）</p><p><code>02</code>:   税号<br><code>03</code>：护照（PAS)<br><code>04</code>：离境证（PAR）<br><code>05</code>：军官证（LMI）</p></td></tr><tr><td>customerName</td><td>String</td><td>是</td><td>用户姓名</td></tr><tr><td>customerPhone</td><td>String</td><td>否</td><td><p>用户电话,  9位数字</p><p>示例：975728895</p></td></tr><tr><td>expireTimeL</td><td>Long</td><td>否</td><td>过期时间<br>单位：秒；默认值：1天 ;最大值：30天 ;最小值：没有</td></tr><tr><td>lastName</td><td>String</td><td>是</td><td>用户姓氏</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>orderAmount</td><td>String</td><td>是</td><td>订单金额</td></tr><tr><td>payProduct</td><td>String</td><td>是</td><td><a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#mfocd">支付类型</a><br>Wallet：<code>23</code></td></tr><tr><td>sign</td><td>String</td><td>是</td><td>签名<br><a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/qian-ming-suan-fa">具体参照：签名算法</a></td></tr><tr><td>description</td><td>String</td><td>否</td><td>描述<br>不能带特殊符号,长度不超过200字符</td></tr></tbody></table>

### 请求示例

{% code fullWidth="true" %}

```json
{
	"callbackUrl": "https://test.com",
	"countryId": "PER",
	"currency": "PEN",
	"customerEmail": "test@yahoo.com",
	"customerIdentification": "76017743",
	"customerIdentificationType": "00",
	"customerName": "Test Name",
	"customerPhone": "975728895",
	"lastName": "Name",
	"merId": "8302258550224656",
	"merOrderNo": "2025072611430208983641749",
	"nonceStr": "06d3d6b920074e5babeb29b93560fc8c",
	"orderAmount": "604.00",
	"payProduct": "23",
	"sign": "69786FE6F437D93C535287643AD7BCFE"// 大写
}
```

{% endcode %}

签名组装字符串

callbackUrl=<https://test.com\\&countryId=PER\\&currency=PEN\\&customerEmail=test@yahoo.com\\&customerIdentification=76017743\\&customerIdentificationType=00\\&customerName=Test> Name\&customerPhone=975728895\&lastName=Name\&merId=8302258550224656\&merOrderNo=2025072611430208983641749\&nonceStr=06d3d6b920074e5babeb29b93560fc8c\&orderAmount=604.00\&payProduct=23\&key=10c44658d50e4d0da0fe1e5f7c9074a7

### 响应参数

<table data-full-width="true"><thead><tr><th width="221">变量名</th><th width="144">类型</th><th width="428">描述</th></tr></thead><tbody><tr><td>code</td><td>String</td><td>响应编码<br>具体参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/xiang-ying-zhuang-tai-ma">响应状态码</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>fee</td><td>BigDecimal</td><td>预收手续费</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>supefinaOrderNo</td><td>String</td><td>supefina订单号</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": "8302258550224656",
		"merOrderNo": "2025072611430208983641749",
		"supefinaOrderNo": "2025072601010004521d1329d9f45",
		"amount": 604.0,
		"fee": 7.04,
		"transactionStatus": "00"
	}
}
```

{% endcode %}

### 回调通知

提交方式：`POST`

<table data-full-width="true"><thead><tr><th width="256">变量名</th><th width="144">类型</th><th width="428">描述</th></tr></thead><tbody><tr><td>amount</td><td>String</td><td>订单金额</td></tr><tr><td>countryId</td><td>String</td><td>国家编号</td></tr><tr><td>customerName</td><td>String</td><td>用户姓名</td></tr><tr><td>fee</td><td>String</td><td>预收手续费</td></tr><tr><td>identifier</td><td>String</td><td>付款参考</td></tr><tr><td>merId</td><td>String</td><td>商户编号</td></tr><tr><td>merOrderId</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><p>交易状态</p><p>具体参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#kxzkj">字典表——交易订单状态</a></p></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": "604.00",
	"countryId": "PER",
	"customerName": "Test Name",
	"fee": "7.04",
	"merId": "8302258550224656",
	"merOrderId": "2025072611430208983641749",
	"nonceStr": "2e9e7151-9333-4a33-95b6-32752c",
	"realityAmount": "604.00",
	"realityFee": "7.04",
	"reference": "CRTMGX9XXPVVF2UV0B13ZTIDBBUZE61",
	"sign": "F6C56C3A99A04FDEC0AD2FB0D124DA11",// 大写
	"status": "01",
	"successTime": 1753501389070,
	"supefinaOrderId": "2025072601010004521d1329d9f45",
	"transactionType": "01"
}
```

{% endcode %}

签名组装字符串

amount=604.00\&countryId=PER\&customerName=Test Name\&fee=7.04\&merId=8302258550224656\&merOrderId=2025072611430208983641749\&nonceStr=2e9e7151-9333-4a33-95b6-32752c\&realityAmount=604.00\&realityFee=7.04\&reference=CRTMGX9XXPVVF2UV0B13ZTIDBBUZE61\&status=01\&successTime=1753501389070\&supefinaOrderId=2025072601010004521d1329d9f45\&transactionType=01\&key=10c44658d50e4d0da0fe1e5f7c9074a7

**回调通知响应**

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

{% code fullWidth="true" %}

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

{% endcode %}


# Card

（payProduct=18）

### 支付流程

<figure><img src="https://3631787624-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FuukVORWjXBgcGu8MirPR%2Fuploads%2FicrEwyOzKErpNs0Y9Jyk%2Fcard.png?alt=media&amp;token=7ee57223-4a71-411f-bd5d-ba59ee598cc7" alt=""><figcaption></figcaption></figure>

1、用户在商户网站/应用下单，并选择Card支付；

2、商户向Supefina发起Card支付请求；

3、Supefina返回Card支付URL地址；

4、商户将该地址在用户侧打开；

5、用户按照页面提示进行验证和支付；

6、用户支付成功；

7、Supefina将支付成功信息通知商户。

### 请求地址

<table data-full-width="true"><thead><tr><th width="122">环境名称</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="226">变量名</th><th width="138">类型</th><th width="83">必填</th><th width="504">描述</th></tr></thead><tbody><tr><td>countryId</td><td>String</td><td>是</td><td>国家编号<br>参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#afwzp">字典表-国家编号</a><br>秘鲁：<code>PER</code></td></tr><tr><td>currency</td><td>String</td><td>是</td><td>币种<br>参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#huo-bi-currency">字典表-货币</a><br>秘鲁索尔：<code>PEN</code></td></tr><tr><td>orderAmount</td><td>String</td><td>是</td><td>订单金额<br>单位比索，需要分可以传入小数，支持两位小数</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>payProduct</td><td>String</td><td>是</td><td><a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#mfocd">支付类型</a><br>Card：<code>18</code></td></tr><tr><td>checkOut</td><td>Boolean</td><td>是</td><td>收银台<br><code>true</code>：需要收银台<br><code>false</code>：不需要收银台<br>传<code>true</code></td></tr><tr><td>returnUrl</td><td>Boolean</td><td>否</td><td>支付完成返回地址</td></tr><tr><td>callbackUrl</td><td>String</td><td>是</td><td><p>回调地址</p><p>详见<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/tong-zhi-hui-tiao-shuo-ming">通知回调说明</a></p></td></tr><tr><td>productName</td><td>String</td><td>是</td><td>商品名称<br>最大50个字符</td></tr><tr><td>productQuantity</td><td>Integer</td><td>否</td><td>商品数量<br>范围[0,1000]</td></tr><tr><td>customerEmail</td><td>String</td><td>否</td><td>顾客邮箱<br>3-256个字符<br><strong>电商行业必传</strong></td></tr><tr><td>receiverAddressMain</td><td>String</td><td>否</td><td>收件地址，街道<br>0-50个字符<br><strong>电商行业必传</strong></td></tr><tr><td>receiverAddressExtra</td><td>String</td><td>否</td><td>收件地址，小区，门牌号<br>0-50个字符<br><strong>电商行业必传</strong></td></tr><tr><td>receiverCity</td><td>String</td><td>否</td><td>收件人城市<br>0-50个字符，可包括空格、连字符、撇号、逗号和点<br><strong>电商行业必传</strong></td></tr><tr><td>receiverProvince</td><td>String</td><td>否</td><td>收件人所在省<br>0-40个字符<br>参数：<a href="https://en.wikipedia.org/wiki/ISO_3166-2">https://en.wikipedia.org/wiki/ISO_3166-2</a>  例：NY<br><strong>电商行业必传</strong></td></tr><tr><td>receiverCountry</td><td>String</td><td>否</td><td>收件人国家<br>参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#afwzp">字典表-国家编号</a>  例：BRA<br><strong>电商行业必传</strong></td></tr><tr><td>receiverZipCode</td><td>String</td><td>否</td><td>邮政编码<br>0-12个字母或数字<br><strong>电商行业必传</strong></td></tr><tr><td>receiverPhone</td><td>String</td><td>否</td><td>收件人电话<br>5-20个字符，需添加区号。如：+1 111111111<br><strong>电商行业必传</strong></td></tr><tr><td>alias</td><td>String</td><td>否</td><td>用户名<br>0-60个字符<br><strong>游戏行业必传</strong></td></tr><tr><td>sign</td><td>String</td><td>是</td><td>签名<br><a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/qian-ming-suan-fa">具体参照：签名算法</a></td></tr><tr><td>customerName</td><td>String</td><td>是</td><td>用户名字</td></tr><tr><td>lastName</td><td>String</td><td>否</td><td>用户姓</td></tr><tr><td>customerIdentification</td><td>String</td><td>否</td><td>身份证明（如身份证号）</td></tr><tr><td>customerIdentificationType</td><td>String</td><td>否</td><td>身份证明类型（如身份证）<br><a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#ke-hu-shi-bie-hao-lei-xing-customeridentificationtype">身份证明类型</a></td></tr><tr><td>description</td><td>String</td><td>是</td><td><p>描述</p><p>长度不超过200字符，不能带特殊符号</p></td></tr></tbody></table>

### 请求示例

{% code fullWidth="true" %}

```json
{
	"callbackUrl": "http://8.130.9.219:8899/api/supefina/transactions/test/zx",
	"checkOut": "true",
	"countryId": "PER",
	"currency": "PEN",
	"customerEmail": "sdfdf@dd.com",
	"customerIdentification": "23443333",
	"customerIdentificationType": "00",
	"customerName": "cName",
	"customerPhone": "+51333333333",
	"description": "test product desc",
	"lastName": "lName",
	"merId": "8302258550224656",
	"merOrderNo": "2025072611383901961800677",
	"nonceStr": "1421558279604dab90e8237b04b73ac5",
	"orderAmount": "200",
	"payProduct": "18",
	"productName": "test product name",
	"productQuantity": 1,
	"receiverAddressExtra": "Apt 2",
	"receiverAddressMain": "Sample street 357",
	"receiverCity": "Receiver City",
	"receiverCountry": "PER",
	"receiverPhone": "+51333333333",
	"receiverProvince": "Example statex",
	"receiverZipCode": "01245",
	"returnUrl": "http://www.bing.com",
	"sign": "61819A906B49A33112A2AC452C20BD39"// 大写
}
```

{% endcode %}

签名组装字符串

callbackUrl=<http://8.130.9.219:8899/api/supefina/transactions/test/zx\\&checkOut=true\\&countryId=PER\\&currency=PEN\\&customerEmail=sdfdf@dd.com\\&customerIdentification=23443333\\&customerIdentificationType=00\\&customerName=cName\\&customerPhone=+51333333333\\&description=test> product desc\&lastName=lName\&merId=8302258550224656\&merOrderNo=2025072611383901961800677\&nonceStr=1421558279604dab90e8237b04b73ac5\&orderAmount=200\&payProduct=18\&productName=test product name\&productQuantity=1\&receiverAddressExtra=Apt 2\&receiverAddressMain=Sample street 357\&receiverCity=Receiver City\&receiverCountry=PER\&receiverPhone=+51333333333\&receiverProvince=Example statex\&receiverZipCode=01245\&returnUrl=<http://www.bing.com\\&key=10c44658d50e4d0da0fe1e5f7c9074a7>

### 响应参数

<table data-full-width="true"><thead><tr><th width="238">变量名</th><th width="208">类型</th><th width="223">描述</th></tr></thead><tbody><tr><td>code</td><td>String</td><td>响应编码<br>具体参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/xiang-ying-zhuang-tai-ma">响应状态码</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>currency</td><td>String</td><td>币种<br>参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#huo-bi-currency">字典表-货币</a><br>秘鲁索尔：<code>PEN</code></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>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": "8302258550224656",
		"merOrderNo": "2025072611383901961800677",
		"amount": 200,
		"url": "https://h5.supefina.tech/kushki?token=416e29ddd5ed4a04958173b17fc65fe7",
		"currency": "PEN"
	}
}
```

{% endcode %}

### 回调通知

提交方式：`POST`

<table data-full-width="true"><thead><tr><th width="225">变量名</th><th width="175">类型</th><th width="300">描述</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="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#afwzp">字典表-国家编号</a><br>秘鲁：PER</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>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="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#kxzkj">交易状态</a><br>具体参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#kxzkj">字典表——交易订单状态</a></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>

#### 回调通知示例

```json
{
	"amount": "200.00",
	"countryId": "PER",
	"fee": "3.00",
	"merId": "8302258550224656",
	"merOrderId": "2025072611383901961800677",
	"msg": "交易成功",
	"nonceStr": "498c7ee6-f84d-4091-a942-f48abc",
	"realityAmount": "200",
	"realityFee": "3.00",
	"reference": "CRTEON0JX1FZFYE42SUE3GGV75A1UM7",
	"sign": "F5AECABAD8DD9F2441DEC7D9C5BE231D",// 大写
	"status": "01",
	"successTime": 1753501120476,
	"supefinaOrderId": "2025071948951070859833344",
	"transactionType": "01"
}
```

签名组装字符串

amount=200.00\&countryId=PER\&fee=3.00\&merId=8302258550224656\&merOrderId=2025072611383901961800677\&msg=交易成功\&nonceStr=498c7ee6-f84d-4091-a942-f48abc\&realityAmount=200\&realityFee=3.00\&reference=CRTEON0JX1FZFYE42SUE3GGV75A1UM7\&status=01\&successTime=1753501120476\&supefinaOrderId=2025071948951070859833344\&transactionType=01\&key=10c44658d50e4d0da0fe1e5f7c9074a7

**回调通知响应**

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

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

### 测试数据

测试环境提供了完整的支付功能，但它只是模拟处理，没有实际的银行交易。

下面您将找到一些可以在测试模式（UAT）下使用的测试卡，以确保您的集成准备就绪。将它们与任何CVV一起使用，输入未来的到期日期。

测试环境的订单金额高于1000，将会触发3DS认证模式， 一旦3DS模式出现，输入1234作为验证码。

* 3DS验证通过的交易测试卡号：

  * `4456528080389860`
  * `4456529267234200`
  * `4456529165328302`
  * `4456524869770255`
  * `4456523340069956`

* 3DS验证拒绝的交易测试卡号：

  * `5451951574925480`

* 未经3DS验证拒绝的交易测试卡号：

  * `4349008516656431`

如果测试过程中，遇到了异常状态码，请直接联系Supefina运营人员处理。


# 智利

在智利，我们提供银行卡（Card），银行转账（Transfer），现金支付（Cash），电子钱包（Wallet）以及聚合收银台（All-Checkout）等支付产品。

<figure><img src="https://3631787624-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FuukVORWjXBgcGu8MirPR%2Fuploads%2F4bCv0vO7Ued8uZpvn93W%2F%E6%99%BA%E5%88%A9-update.jpg?alt=media&amp;token=adefde7f-6706-42cc-96a8-c6e3bdc5ae23" alt=""><figcaption></figcaption></figure>

{% content-ref url="/pages/Ysk3fRzVsRFFsCYx0Vzu" %}
[Cash](/huan-ying-shi-yong-supefina-de-api-wen-dang/dai-shou/zhi-li/cash)
{% endcontent-ref %}

{% content-ref url="/pages/QGpzpCaGYwPDN48cGNop" %}
[Transfer](/huan-ying-shi-yong-supefina-de-api-wen-dang/dai-shou/zhi-li/transfer)
{% endcontent-ref %}

{% content-ref url="/pages/JJzR5zoyTKC0fp7DobEc" %}
[Card](/huan-ying-shi-yong-supefina-de-api-wen-dang/dai-shou/zhi-li/card)
{% endcontent-ref %}

{% content-ref url="/pages/LRTNHokw3gw1BnKnXyCx" %}
[Wallet](/huan-ying-shi-yong-supefina-de-api-wen-dang/dai-shou/zhi-li/wallet)
{% endcontent-ref %}

{% content-ref url="/pages/R9lPHhQAH23Y6H1glPU8" %}
[Broken mention](broken://pages/R9lPHhQAH23Y6H1glPU8)
{% endcontent-ref %}


# Card

（payProduct=21）

### 支付流程

<figure><img src="https://3631787624-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FuukVORWjXBgcGu8MirPR%2Fuploads%2FxQmJK1BZFAoeGatZcutp%2Ftransfer.png?alt=media&amp;token=4f62280d-cbca-4ef1-8e69-cd2f7d559451" alt=""><figcaption></figcaption></figure>

1、用户在商户网站/应用下单，并选择Card支付；

2、商户向Supefina发起Card支付请求；

3、Supefina返回Card支付URL地址；

4、商户将该地址在用户侧打开；

5、用户按照页面提示进行验证和支付；

6、用户支付成功；

7、Supefina将支付成功信息通知商户。

### 请求地址

<table data-full-width="true"><thead><tr><th width="138">环境名称</th><th width="800">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="196">变量名</th><th width="152">类型</th><th width="91">必填</th><th width="604">描述</th></tr></thead><tbody><tr><td>countryId</td><td>String</td><td>是</td><td>国家编号<br>参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#afwzp">字典表-国家编号</a><br>智利：<code>CHL</code></td></tr><tr><td>merId</td><td>String</td><td>是</td><td>商户ID<br>商户ID获取路径：Supefina商户后台-商户管理-基本信息-商户ID</td></tr><tr><td>payProduct</td><td>String</td><td>是</td><td><a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#mfocd">支付类型</a><br>Card：<code>21</code></td></tr><tr><td>orderAmount</td><td>String</td><td>是</td><td>订单金额<br>只支持整数</td></tr><tr><td>currency</td><td>String</td><td>是</td><td>币种<br>参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#huo-bi-currency">字典表-货币</a><br>智利比索：<code>CLP</code></td></tr><tr><td>merOrderNo</td><td>String</td><td>是</td><td>商户订单号</td></tr><tr><td>customerEmail</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>sign</td><td>String</td><td>是</td><td>签名<br><a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/qian-ming-suan-fa">具体参照：签名算法</a></td></tr><tr><td>description</td><td>String</td><td>是</td><td>描述<br>不能带特殊符号</td></tr><tr><td>callbackUrl</td><td>String</td><td>是</td><td><p>回调地址</p><p>详见<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/tong-zhi-hui-tiao-shuo-ming">通知回调说明</a></p></td></tr><tr><td>expireTimeL</td><td>Long</td><td>否</td><td>过期时间<br>单位：秒；默认值：82800秒 ;最大值：82800秒 ;最小值：300秒。</td></tr><tr><td>customerIdentification</td><td>String</td><td>是</td><td>用户证件号</td></tr><tr><td>customerIdentificationType</td><td>String</td><td>是</td><td><p>用户证件类型</p><p><code>02</code>：税号</p><p><code>03</code>：护照</p></td></tr><tr><td>customerName</td><td>String</td><td>是</td><td>用户姓名</td></tr><tr><td>lastName</td><td>String</td><td>是</td><td>用户姓氏</td></tr></tbody></table>

### 请求示例

{% code fullWidth="true" %}

```json
{
	"callbackUrl": "https://payment.mxcash.xyz/supefina/repay?payway=stp",
	"countryId": "CHL",
	"currency": "CLP",
	"customerEmail": "Dgdg@outlook.com",
	"customerIdentification": "11.111.111-1",
	"customerIdentificationType": "02",
	"customerName": "zx",
	"description": "xxxxxx",
	"expireTimeL": 21600,
	"lastName": "z",
	"merId": "8302024214514649",
	"merOrderNo": "2025072518590270096550101",
	"nonceStr": "8884a01232ae4f9e9705377cbdaf6113",
	"orderAmount": "116138",
	"payProduct": "21",
	"returnUrl": "",
	"sign": "231BFF3481393923DD711B1EA7F63BFE"// 大写
}
```

{% endcode %}

签名组装字符串

callbackUrl=<https://payment.mxcash.xyz/supefina/repay?payway=stp\\&countryId=CHL\\&currency=CLP\\&customerEmail=Dgdg@outlook.com\\&customerIdentification=11.111.111-1\\&customerIdentificationType=02\\&customerName=zx\\&description=xxxxxx\\&expireTimeL=21600\\&lastName=z\\&merId=8302024214514649\\&merOrderNo=2025072518590270096550101\\&nonceStr=8884a01232ae4f9e9705377cbdaf6113\\&orderAmount=116138\\&payProduct=21\\&key=bb01dd04d967425ab194fff9fe8a9501>

### 响应参数

<table data-full-width="true"><thead><tr><th width="222">变量名</th><th width="196">类型</th><th width="448">描述</th></tr></thead><tbody><tr><td>code</td><td>String</td><td>响应编码<br>具体参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/xiang-ying-zhuang-tai-ma">响应状态码</a></td></tr><tr><td>msg</td><td>String</td><td>响应信息</td></tr><tr><td>data</td><td>Object</td><td>响应数据</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>supefinaOrderNo</td><td>String</td><td>supefina订单号</td></tr><tr><td>amount</td><td>BigDecimal</td><td>订单金额</td></tr><tr><td>fee</td><td>BigDecimal</td><td>预收手续费</td></tr><tr><td>identifier</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>orderExpirationTime</td><td>String</td><td>订单过期时间 （UTC 0时区时间）</td></tr></tbody></table>

#### 响应示例

{% code fullWidth="true" %}

```json
{
	"code": "200",
	"msg": "success ",
	"data": {
		"merCode": "8302024214514649",
		"merOrderNo": "2025072518590270096550101",
		"supefinaOrderNo": "20250725105904285000038445",
		"amount": 116138,
		"fee": 5.0,
		"transactionStatus": "00",
		"url": "https://cert.monnetpayments.com/api-payin/v3/card-async-yuno/token/cae4e770-4f36-4863-b7a8-28dfdb7d3d811111",
		"referenceCode": "",
		"channelName": "peronpay",
		"returnUrl": "",
		"orderExpirationTime": "2025-07-27T10:59:14.324"
	}
}
```

{% endcode %}

### 回调通知

提交方式：`POST`

<table data-full-width="true"><thead><tr><th width="222">变量名</th><th width="152">类型</th><th width="448">描述</th></tr></thead><tbody><tr><td>amount</td><td>String</td><td>订单金额</td></tr><tr><td>countryId</td><td>String</td><td>国家编号</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>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>交易状态<br>具体参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#kxzkj">字典表——交易订单状态</a></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": "116138.00",
	"countryId": "CHL",
	"customerName": "zx",
	"fee": "5.00",
	"identifier": "fc6e0a1a-fbb4-4c",
	"merId": "8302024214514649",
	"merOrderId": "2025072518590270096550101",
	"msg": "SUCCESS",
	"nonceStr": "52cb6aad-fb38-49c2-a6b8-cd3094",
	"payerIdNumber": "11.111.111-1",
	"payerName": "test",
	"realityAmount": "116138",
	"realityFee": "5.00",
	"sign": "376965F9DCDCDBAF09005FEFAF1C48DC",// 大写
	"status": "01",
	"successTime": 1753441149000,
	"supefinaOrderId": "20250725105904285000038445",
	"transactionType": "01"
}
```

{% endcode %}

签名组装字符串

amount=116138.00\&countryId=CHL\&customerName=zx\&fee=5.00\&identifier=fc6e0a1a-fbb4-4c\&merId=8302024214514649\&merOrderId=2025072518590270096550101\&msg=SUCCESS\&nonceStr=52cb6aad-fb38-49c2-a6b8-cd3094\&payerIdNumber=11.111.111-1\&payerName=test\&realityAmount=116138\&realityFee=5.00\&status=01\&successTime=1753441149000\&supefinaOrderId=20250725105904285000038445\&transactionType=01\&key=bb01dd04d967425ab194fff9fe8a9501

**回调通知响应**

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

{% code fullWidth="true" %}

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

{% endcode %}


# Cash

（payProduct=03）

### 支付流程

<figure><img src="https://3631787624-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FuukVORWjXBgcGu8MirPR%2Fuploads%2FjaP8k7IuMK21PVykdZYz%2FCash.png?alt=media&amp;token=74a9a5cd-7280-48dd-a973-cddd0780d3f8" alt=""><figcaption></figcaption></figure>

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

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

&#x20;3、Supefina返回Cash付款URL信息。

&#x20;4、商户将该支付URL展示给用户；

&#x20;5、用户按照页面提示进行付款；

6、付款成功；

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

### 请求地址

<table data-full-width="true"><thead><tr><th width="138">环境名称</th><th width="800">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="189">变量名</th><th width="123">类型</th><th width="126">必填</th><th width="623">描述</th></tr></thead><tbody><tr><td>countryId</td><td>String</td><td>是</td><td><p>国家编号<br>参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#afwzp">字典表-国家编号</a></p><p>智利：<code>CHL</code></p></td></tr><tr><td>merId</td><td>String</td><td>是</td><td>商户ID<br>商户ID获取路径：Supefina商户后台-商户管理-基本信息-商户ID</td></tr><tr><td>payProduct</td><td>String</td><td>是</td><td><a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#mfocd">支付类型</a><br>Cash：<code>03</code></td></tr><tr><td>orderAmount</td><td>String</td><td>是</td><td>订单金额<br>只支持整数</td></tr><tr><td>currency</td><td>String</td><td>是</td><td><p>币种<br>参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#huo-bi-currency">字典表-货币</a></p><p>智利比索：<code>CLP</code></p></td></tr><tr><td>merOrderNo</td><td>String</td><td>是</td><td>商户订单号</td></tr><tr><td>customerEmail</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>sign</td><td>String</td><td>是</td><td>签名<br><a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/qian-ming-suan-fa">具体参照：签名算法</a></td></tr><tr><td>description</td><td>String</td><td>是</td><td>描述<br>不能带特殊符号</td></tr><tr><td>callbackUrl</td><td>String</td><td>是</td><td><p>回调地址</p><p>详见<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/tong-zhi-hui-tiao-shuo-ming">通知回调说明</a></p></td></tr><tr><td>expireTimeL</td><td>Long</td><td>否</td><td>过期时间<br>单位：秒；默认值：82800秒 ;最大值：82800秒 ;最小值：300秒。</td></tr><tr><td>customerIdentification</td><td>String</td><td>是</td><td>用户证件号</td></tr><tr><td>customerIdentificationType</td><td>String</td><td>是</td><td><p>用户证件类型</p><p><code>02</code>：税号</p><p><code>03</code>：护照</p></td></tr><tr><td>customerName</td><td>String</td><td>是</td><td>用户姓名</td></tr><tr><td>lastName</td><td>String</td><td>是</td><td>用户姓氏</td></tr></tbody></table>

### 请求示例

{% code fullWidth="true" %}

```json
{
	"callbackUrl": "http://api.supefina.net/api/supefina/transactions/test/zx",
	"countryId": "CHL",
	"currency": "CLP",
	"customerEmail": "evan.li@supefina.net",
	"customerIdentification": "11.111.111-1",
	"customerIdentificationType": "02",
	"customerName": "Belen",
	"description": "PAYIN",
	"expireTimeL": 86400,
	"lastName": "Arin recabal",
	"merId": "8302024214514649",
	"merOrderNo": "2025072519032289937000340",
	"nonceStr": "2de836a17d284fbbbbe97e43bdc01348",
	"orderAmount": "1000",
	"payProduct": "03",
	"sign": "6E2059170F99198D13A53A1F8EA93A34"// 大写
}
```

{% endcode %}

签名组装字符串

callbackUrl=<http://api.supefina.net/api/supefina/transactions/test/zx\\&countryId=CHL\\&currency=CLP\\&customerEmail=evan.li@supefina.net\\&customerIdentification=11.111.111-1\\&customerIdentificationType=02\\&customerName=Belen\\&description=PAYIN\\&expireTimeL=86400\\&lastName=Arin> recabal\&merId=8302024214514649\&merOrderNo=2025072519032289937000340\&nonceStr=2de836a17d284fbbbbe97e43bdc01348\&orderAmount=1000\&payProduct=03\&key=bb01dd04d967425ab194fff9fe8a9501

### 响应参数

<table data-full-width="true"><thead><tr><th width="222">变量名</th><th width="156">类型</th><th width="448">描述</th></tr></thead><tbody><tr><td>code</td><td>String</td><td>响应编码<br>具体参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/xiang-ying-zhuang-tai-ma">响应状态码</a></td></tr><tr><td>msg</td><td>String</td><td>响应信息</td></tr><tr><td>data</td><td>Object</td><td>响应数据</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>supefinaOrderNo</td><td>String</td><td>supefina订单号</td></tr><tr><td>amount</td><td>BigDecimal</td><td>订单金额</td></tr><tr><td>fee</td><td>BigDecimal</td><td>预收手续费</td></tr><tr><td>identifier</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>orderExpirationTime</td><td>String</td><td>订单过期时间 （UTC 0时区时间）</td></tr></tbody></table>

#### 响应示例

{% code fullWidth="true" %}

```json
{
	"code": "200",
	"msg": "success ",
	"data": {
		"merCode": "8302024214514649",
		"merOrderNo": "2025072519032289937000340",
		"supefinaOrderNo": "20250725110324530000038021",
		"amount": 1000,
		"fee": 5.0,
		"transactionStatus": "00",
		"url": "https://cert.monnetpayments.com/api-payin/v3/card-async-yuno/token/cae4e770-4f36-4863-b7a8-28dfdb7d3d811111",
		"referenceCode": "",
		"channelName": "peronpay",
		"orderExpirationTime": "2025-07-27T11:03:34.555"
	}
}
```

{% endcode %}

### 回调通知

提交方式：`POST`

<table data-full-width="true"><thead><tr><th width="211">变量名</th><th width="170">类型</th><th width="448">描述</th></tr></thead><tbody><tr><td>amount</td><td>String</td><td>订单金额</td></tr><tr><td>countryId</td><td>String</td><td>国家编号</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>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>交易状态<br>具体参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#kxzkj">字典表——交易订单状态</a></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": "1000.00",
	"countryId": "CHL",
	"customerName": "Belen",
	"fee": "5.00",
	"identifier": "df6c4642-460f-41",
	"merId": "8302024214514649",
	"merOrderId": "2025072519032289937000340",
	"msg": "SUCCESS",
	"nonceStr": "292cfa50-bdb6-4fcc-93f0-e6b767",
	"payerIdNumber": "11.111.111-1",
	"payerName": "test",
	"realityAmount": "1000",
	"realityFee": "5.00",
	"sign": "AE379029986874F03F9196CEA88824B9",// 大写
	"status": "01",
	"successTime": 1753441410000,
	"supefinaOrderId": "20250725110324530000038021",
	"transactionType": "01"
}
```

{% endcode %}

签名组装字符串

amount=1000.00\&countryId=CHL\&customerName=Belen\&fee=5.00\&identifier=df6c4642-460f-41\&merId=8302024214514649\&merOrderId=2025072519032289937000340\&msg=SUCCESS\&nonceStr=292cfa50-bdb6-4fcc-93f0-e6b767\&payerIdNumber=11.111.111-1\&payerName=test\&realityAmount=1000\&realityFee=5.00\&status=01\&successTime=1753441410000\&supefinaOrderId=20250725110324530000038021\&transactionType=01\&key=bb01dd04d967425ab194fff9fe8a9501

**回调通知响应**

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

{% code fullWidth="true" %}

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

{% endcode %}


# Transfer

（payProduct=12）

### 支付流程

<figure><img src="https://3631787624-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FuukVORWjXBgcGu8MirPR%2Fuploads%2FxQmJK1BZFAoeGatZcutp%2Ftransfer.png?alt=media&amp;token=4f62280d-cbca-4ef1-8e69-cd2f7d559451" alt=""><figcaption></figcaption></figure>

1、用户在商户网站/应用下单，并选择Transfer支付；

2、商户向Supefina发起Transfer支付请求；

3、Supefina返回Transfer支付URL地址；

4、商户将该地址在用户侧打开；

5、用户按照页面提示进行验证和支付；

6、用户支付成功；

7、Supefina将支付成功信息通知商户。

### 请求地址

<table data-full-width="true"><thead><tr><th width="138">环境名称</th><th width="607">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="174">变量名</th><th width="111">类型</th><th width="108">必填</th><th width="658">描述</th></tr></thead><tbody><tr><td>countryId</td><td>String</td><td>是</td><td>国家编号<br>参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#afwzp">字典表-国家编号</a><br>智利：<code>CHL</code></td></tr><tr><td>merId</td><td>String</td><td>是</td><td>商户ID<br>商户ID获取路径：Supefina商户后台-商户管理-基本信息-商户ID</td></tr><tr><td>payProduct</td><td>String</td><td>是</td><td><a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#mfocd">支付类型</a><br>Transfer：<code>12</code></td></tr><tr><td>orderAmount</td><td>String</td><td>是</td><td>订单金额<br>只支持整数</td></tr><tr><td>currency</td><td>String</td><td>是</td><td>币种<br>参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#huo-bi-currency">字典表-货币</a><br>智利比索：<code>CLP</code></td></tr><tr><td>merOrderNo</td><td>String</td><td>是</td><td>商户订单号</td></tr><tr><td>customerEmail</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>sign</td><td>String</td><td>是</td><td>签名<br><a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/qian-ming-suan-fa">具体参照：签名算法</a></td></tr><tr><td>description</td><td>String</td><td>是</td><td>描述<br>不能带特殊符号</td></tr><tr><td>callbackUrl</td><td>String</td><td>是</td><td><p>回调地址</p><p>详见<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/tong-zhi-hui-tiao-shuo-ming">通知回调说明</a></p></td></tr><tr><td>expireTimeL</td><td>Long</td><td>否</td><td>过期时间<br>单位：秒；默认值：82800秒 ;最大值：82800秒 ;最小值：300秒。</td></tr><tr><td>customerIdentification</td><td>String</td><td>是</td><td>用户证件号</td></tr><tr><td>customerIdentificationType</td><td>String</td><td>是</td><td><p>用户证件类型</p><p><code>02</code>：税号</p><p><code>03</code>：护照</p></td></tr><tr><td>customerName</td><td>String</td><td>是</td><td>用户姓名</td></tr><tr><td>lastName</td><td>String</td><td>是</td><td>用户姓氏</td></tr></tbody></table>

### 请求示例

{% code fullWidth="true" %}

```json
{
	"callbackUrl": "https://channel.kina.cl/channel/supefina/callback",
	"countryId": "CHL",
	"currency": "CLP",
	"customerEmail": "luismanasesvegayunge@gmail.com",
	"customerIdentification": "11.111.111-1",
	"customerIdentificationType": "02",
	"customerName": "zx",
	"description": "bill of LUIS MANASES YUNGE",
	"expireTimeL": 10800,
	"lastName": "z2",
	"merId": "8302024214514649",
	"merOrderNo": "2025072519070746554283730",
	"nonceStr": "66786085b7724f1996bdee86399c87b5",
	"orderAmount": "391811",
	"payProduct": "12",
	"sign": "7F6B60191880F02B1C207E35739872A9"// 大写
}
```

{% endcode %}

签名组装字符串

callbackUrl=<https://channel.kina.cl/channel/supefina/callback\\&countryId=CHL\\&currency=CLP\\&customerEmail=luismanasesvegayunge@gmail.com\\&customerIdentification=11.111.111-1\\&customerIdentificationType=02\\&customerName=zx\\&description=bill> of LUIS MANASES YUNGE\&expireTimeL=10800\&lastName=z2\&merId=8302024214514649\&merOrderNo=2025072519070746554283730\&nonceStr=66786085b7724f1996bdee86399c87b5\&orderAmount=391811\&payProduct=12\&key=bb01dd04d967425ab194fff9fe8a9501

### 响应参数

<table data-full-width="true"><thead><tr><th width="222">变量名</th><th width="162">类型</th><th width="448">描述</th></tr></thead><tbody><tr><td>code</td><td>String</td><td>响应编码<br>具体参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/xiang-ying-zhuang-tai-ma">响应状态码</a></td></tr><tr><td>msg</td><td>String</td><td>响应信息</td></tr><tr><td>data</td><td>Object</td><td>响应数据</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>supefinaOrderNo</td><td>String</td><td>supefina订单号</td></tr><tr><td>amount</td><td>BigDecimal</td><td>订单金额</td></tr><tr><td>fee</td><td>BigDecimal</td><td>预收手续费</td></tr><tr><td>identifier</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>orderExpirationTime</td><td>String</td><td>订单过期时间 （UTC 0时区时间）</td></tr></tbody></table>

#### 响应示例

{% code fullWidth="true" %}

```json
{
	"code": "200",
	"msg": "success ",
	"data": {
		"merCode": "8302024214514649",
		"merOrderNo": "2025072519070746554283730",
		"supefinaOrderNo": "20250725110709034000038692",
		"amount": 391811,
		"fee": 5.0,
		"transactionStatus": "00",
		"url": "https://cert.monnetpayments.com/api-payin/v3/card-async-yuno/token/cae4e770-4f36-4863-b7a8-28dfdb7d3d811111",
		"referenceCode": "",
		"channelName": "peronpay",
		"orderExpirationTime": "2025-07-27T11:07:19.058"
	}
}
```

{% endcode %}

### 回调通知

提交方式：`POST`

<table data-full-width="true"><thead><tr><th width="198">变量名</th><th width="142">类型</th><th width="448">描述</th></tr></thead><tbody><tr><td>amount</td><td>String</td><td>订单金额</td></tr><tr><td>countryId</td><td>String</td><td>国家编号</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>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>交易状态<br>具体参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#kxzkj">字典表——交易订单状态</a></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": "391811.00",
	"countryId": "CHL",
	"customerName": "zx",
	"fee": "5.00",
	"identifier": "a8ed2568-60de-4c",
	"merId": "8302024214514649",
	"merOrderId": "2025072519070746554283730",
	"msg": "SUCCESS",
	"nonceStr": "a42cd5dc-a91a-4d21-84e1-208d0e",
	"payerIdNumber": "11.111.111-1",
	"payerName": "test",
	"realityAmount": "391811",
	"realityFee": "5.00",
	"sign": "4CA003674405E76D116DB834EC890A20",// 大写
	"status": "01",
	"successTime": 1753441634000,
	"supefinaOrderId": "20250725110709034000038692",
	"transactionType": "01"
}
```

{% endcode %}

签名组装字符串

amount=391811.00\&countryId=CHL\&customerName=zx\&fee=5.00\&identifier=a8ed2568-60de-4c\&merId=8302024214514649\&merOrderId=2025072519070746554283730\&msg=SUCCESS\&nonceStr=a42cd5dc-a91a-4d21-84e1-208d0e\&payerIdNumber=11.111.111-1\&payerName=test\&realityAmount=391811\&realityFee=5.00\&status=01\&successTime=1753441634000\&supefinaOrderId=20250725110709034000038692\&transactionType=01\&key=bb01dd04d967425ab194fff9fe8a9501

**回调通知响应**

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

{% code fullWidth="true" %}

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

{% endcode %}


# Wallet

（payProduct=23）

### 支付流程

<figure><img src="https://3631787624-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FuukVORWjXBgcGu8MirPR%2Fuploads%2FxQmJK1BZFAoeGatZcutp%2Ftransfer.png?alt=media&amp;token=4f62280d-cbca-4ef1-8e69-cd2f7d559451" alt=""><figcaption></figcaption></figure>

1、用户在商户网站/应用下单，并选择Wallet支付；

2、商户向Supefina发起Wallet支付请求；

3、Supefina返回Card支付Wallet地址；

4、商户将该地址在用户侧打开；

5、用户按照页面提示进行验证和支付；

6、用户支付成功；

7、Supefina将支付成功信息通知商户。

### 请求地址

<table data-full-width="true"><thead><tr><th width="138">环境名称</th><th width="607">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="198">变量名</th><th width="131">类型</th><th width="136">必填</th><th width="584">描述</th></tr></thead><tbody><tr><td>countryId</td><td>String</td><td>是</td><td>国家编号<br>参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#afwzp">字典表-国家编号</a><br>智利：<code>CHL</code></td></tr><tr><td>merId</td><td>String</td><td>是</td><td>商户ID<br>商户ID获取路径：Supefina商户后台-商户管理-基本信息-商户ID</td></tr><tr><td>payProduct</td><td>String</td><td>是</td><td><a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#mfocd">支付类型</a><br>Wallet：<code>23</code></td></tr><tr><td>orderAmount</td><td>String</td><td>是</td><td>订单金额<br>只支持整数</td></tr><tr><td>currency</td><td>String</td><td>是</td><td>币种<br>参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#huo-bi-currency">字典表-货币</a><br>智利比索：<code>CLP</code></td></tr><tr><td>merOrderNo</td><td>String</td><td>是</td><td>商户订单号</td></tr><tr><td>customerEmail</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>sign</td><td>String</td><td>是</td><td>签名<br><a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/qian-ming-suan-fa">具体参照：签名算法</a></td></tr><tr><td>description</td><td>String</td><td>是</td><td>描述<br>不能带特殊符号</td></tr><tr><td>callbackUrl</td><td>String</td><td>是</td><td><p>回调地址</p><p>详见<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/tong-zhi-hui-tiao-shuo-ming">通知回调说明</a></p></td></tr><tr><td>expireTimeL</td><td>Long</td><td>否</td><td>过期时间<br>单位：秒；默认值：82800秒 ;最大值：82800秒 ;最小值：300秒。</td></tr><tr><td>customerIdentification</td><td>String</td><td>是</td><td>用户证件号</td></tr><tr><td>customerIdentificationType</td><td>String</td><td>是</td><td><p>用户证件类型</p><p><code>02</code>：税号</p><p><code>03</code>：护照</p></td></tr><tr><td>customerName</td><td>String</td><td>是</td><td>用户姓名</td></tr><tr><td>lastName</td><td>String</td><td>是</td><td>用户姓氏</td></tr></tbody></table>

### 请求示例

{% code fullWidth="true" %}

```json
{
	"callbackUrl": "http://8.130.9.219:8899/api/supefina/transactions/test/zx",
	"countryId": "CHL",
	"currency": "CLP",
	"customerEmail": "evan.li@supefina.net",
	"customerIdentification": "11.111.111-1",
	"customerIdentificationType": "02",
	"customerName": "zx",
	"description": "test payku",
	"expireTimeL": 3016,
	"lastName": "z",
	"merId": "8301893137974691",
	"merOrderNo": "2025072711290632375869414",
	"nonceStr": "943be460a9624e3da58b8e5d426e5a9d",
	"orderAmount": "10",
	"payProduct": "23",
	"sign": "DDDA32B6E9CC58C6CEBD5FB41DE859AC"// 大写
}
```

{% endcode %}

签名组装字符串

callbackUrl=<http://8.130.9.219:8899/api/supefina/transactions/test/zx\\&countryId=CHL\\&currency=CLP\\&customerEmail=evan.li@supefina.net\\&customerIdentification=11.111.111-1\\&customerIdentificationType=02\\&customerName=zx\\&description=test> payku\&expireTimeL=3016\&lastName=z\&merId=8301893137974691\&merOrderNo=2025072711290632375869414\&nonceStr=943be460a9624e3da58b8e5d426e5a9d\&orderAmount=10\&payProduct=23\&key=764e7f81217541658f1ccc993b39d9e3

### 响应参数

<table data-full-width="true"><thead><tr><th width="222">变量名</th><th width="236">类型</th><th width="448">描述</th></tr></thead><tbody><tr><td>code</td><td>String</td><td>响应编码<br>具体参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/xiang-ying-zhuang-tai-ma">响应状态码</a></td></tr><tr><td>msg</td><td>String</td><td>响应信息</td></tr><tr><td>data</td><td>Object</td><td>响应数据</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>supefinaOrderNo</td><td>String</td><td>supefina订单号</td></tr><tr><td>amount</td><td>BigDecimal</td><td>订单金额</td></tr><tr><td>fee</td><td>BigDecimal</td><td>预收手续费</td></tr><tr><td>identifier</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></tbody></table>

#### 响应示例

{% code fullWidth="true" %}

```json
{
	"code": "200",
	"msg": "success ",
	"data": {
		"merCode": "8301893137974691",
		"merOrderNo": "2025072711290632375869414",
		"supefinaOrderNo": "20250727020100089adb07c9f6340",
		"amount": 10,
		"fee": 1.0,
		"transactionStatus": "00",
		"url":"https://apiin.monnetpayments.com/ms-multiprocessor/ux/operation/repynzwn61aae59w"
	}
}
```

{% endcode %}

### 回调通知

提交方式：`POST`

<table data-full-width="true"><thead><tr><th width="222">变量名</th><th width="201">类型</th><th width="448">描述</th></tr></thead><tbody><tr><td>amount</td><td>String</td><td>订单金额</td></tr><tr><td>countryId</td><td>String</td><td>国家编号</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>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>交易状态<br>具体参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#kxzkj">字典表——交易订单状态</a></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": "10.00",
	"countryId": "CHL",
	"customerName": "zx",
	"fee": "1.00",
	"merId": "8301893137974691",
	"merOrderId": "2025072711290632375869414",
	"nonceStr": "acf80428-f8b5-43ee-ab84-24993c",
	"realityAmount": "10",
	"realityFee": "1.00",
	"reference": "CRTSIAX3HEDZ0N6VPG1I9JZ7349N4F4",
	"sign": "C5158C20E610516E3C96E61F0A22F845",// 大写
	"status": "01",
	"successTime": 1753586956982,
	"supefinaOrderId": "20250727020100089adb07c9f6340",
	"transactionType": "01"
}
```

{% endcode %}

签名组装字符串

amount=10.00\&countryId=CHL\&customerName=zx\&fee=1.00\&merId=8301893137974691\&merOrderId=2025072711290632375869414\&nonceStr=acf80428-f8b5-43ee-ab84-24993c\&realityAmount=10\&realityFee=1.00\&reference=CRTSIAX3HEDZ0N6VPG1I9JZ7349N4F4\&status=01\&successTime=1753586956982\&supefinaOrderId=20250727020100089adb07c9f6340\&transactionType=01\&key=764e7f81217541658f1ccc993b39d9e3

**回调通知响应**

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

{% code fullWidth="true" %}

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

{% endcode %}


# All-Checkout

（payProduct=05）

### 支付流程

<figure><img src="https://3631787624-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FuukVORWjXBgcGu8MirPR%2Fuploads%2FxQmJK1BZFAoeGatZcutp%2Ftransfer.png?alt=media&amp;token=4f62280d-cbca-4ef1-8e69-cd2f7d559451" alt=""><figcaption></figcaption></figure>

1、用户在商户网站/应用下单，拉起聚合收银台，并自定义选择想要的支付方式进行支付；

2、商户向Supefina发起支付请求；

3、Supefina返回对应的支付地址；

4、商户将该地址在用户侧打开；

5、用户按照页面提示进行验证和支付；

6、用户支付成功；

7、Supefina将支付成功信息通知商户。

### 请求地址

<table data-full-width="true"><thead><tr><th width="138">环境名称</th><th width="607">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="198">变量名</th><th width="131">类型</th><th width="136">必填</th><th width="584">描述</th></tr></thead><tbody><tr><td>countryId</td><td>String</td><td>是</td><td>国家编号<br>参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#afwzp">字典表-国家编号</a><br>智利：<code>CHL</code></td></tr><tr><td>merId</td><td>String</td><td>是</td><td>商户ID<br>商户ID获取路径：Supefina商户后台-商户管理-基本信息-商户ID</td></tr><tr><td>payProduct</td><td>String</td><td>是</td><td><a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#mfocd">支付类型</a><br>All-Checkout：<code>05</code></td></tr><tr><td>orderAmount</td><td>String</td><td>是</td><td>订单金额<br>只支持整数</td></tr><tr><td>currency</td><td>String</td><td>是</td><td>币种<br>参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#huo-bi-currency">字典表-货币</a><br>智利比索：<code>CLP</code></td></tr><tr><td>merOrderNo</td><td>String</td><td>是</td><td>商户订单号</td></tr><tr><td>customerEmail</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>sign</td><td>String</td><td>是</td><td>签名<br><a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/qian-ming-suan-fa">具体参照：签名算法</a></td></tr><tr><td>description</td><td>String</td><td>是</td><td>描述<br>不能带特殊符号</td></tr><tr><td>callbackUrl</td><td>String</td><td>是</td><td><p>回调地址</p><p>详见<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/tong-zhi-hui-tiao-shuo-ming">通知回调说明</a></p></td></tr><tr><td>expireTimeL</td><td>Long</td><td>否</td><td>过期时间<br>单位：秒；默认值：82800秒 ;最大值：82800秒 ;最小值：300秒。</td></tr><tr><td>customerIdentification</td><td>String</td><td>是</td><td>用户证件号</td></tr><tr><td>customerIdentificationType</td><td>String</td><td>是</td><td><p>用户证件类型</p><p><code>02</code>：税号</p><p><code>03</code>：护照</p></td></tr><tr><td>customerName</td><td>String</td><td>是</td><td>用户姓名</td></tr><tr><td>lastName</td><td>String</td><td>是</td><td>用户姓氏</td></tr></tbody></table>

### 请求示例

{% code fullWidth="true" %}

```json
{
	"callbackUrl": "http://8.130.9.219:8899/api/supefina/transactions/test/zx",
	"countryId": "CHL",
	"currency": "CLP",
	"customerEmail": "evan.li@supefina.net",
	"customerIdentification": "11.111.111-1",
	"customerIdentificationType": "02",
	"customerName": "zx",
	"description": "test payku",
	"expireTimeL": 3016,
	"lastName": "z",
	"merId": "8301893137974691",
	"merOrderNo": "2025072711403484941263221",
	"nonceStr": "dd77d9eaba374d4292355d279f9e067e",
	"orderAmount": "10",
	"payProduct": "05",
	"sign": "C20DF9844043942E56E8F7008B1A8D6F"// 大写
}
```

{% endcode %}

签名组装字符串

callbackUrl=<http://8.130.9.219:8899/api/supefina/transactions/test/zx\\&countryId=CHL\\&currency=CLP\\&customerEmail=evan.li@supefina.net\\&customerIdentification=11.111.111-1\\&customerIdentificationType=02\\&customerName=zx\\&description=test> payku\&expireTimeL=3016\&lastName=z\&merId=8301893137974691\&merOrderNo=2025072711403484941263221\&nonceStr=dd77d9eaba374d4292355d279f9e067e\&orderAmount=10\&payProduct=05\&key=764e7f81217541658f1ccc993b39d9e3

### 响应参数

<table data-full-width="true"><thead><tr><th width="222">变量名</th><th width="236">类型</th><th width="448">描述</th></tr></thead><tbody><tr><td>code</td><td>String</td><td>响应编码<br>具体参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/xiang-ying-zhuang-tai-ma">响应状态码</a></td></tr><tr><td>msg</td><td>String</td><td>响应信息</td></tr><tr><td>data</td><td>Object</td><td>响应数据</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>supefinaOrderNo</td><td>String</td><td>supefina订单号</td></tr><tr><td>amount</td><td>BigDecimal</td><td>订单金额</td></tr><tr><td>fee</td><td>BigDecimal</td><td>预收手续费</td></tr><tr><td>identifier</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></tbody></table>

#### 响应示例

{% code fullWidth="true" %}

```json
{
	"code": "200",
	"msg": "success ",
	"data": {
		"merCode": "8301893137974691",
		"merOrderNo": "2025072711403484941263221",
		"supefinaOrderNo": "202507270201000387a22b63a8949",
		"amount": 10,
		"fee": 1.0,
		"transactionStatus": "00",
		"url":"https://apiin.monnetpayments.com/ms-multiprocessor/ux/operation/repynzwn61aae59w"
	}
}
```

{% endcode %}

### 回调通知

提交方式：`POST`

<table data-full-width="true"><thead><tr><th width="222">变量名</th><th width="201">类型</th><th width="448">描述</th></tr></thead><tbody><tr><td>amount</td><td>String</td><td>订单金额</td></tr><tr><td>countryId</td><td>String</td><td>国家编号</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>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>交易状态<br>具体参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#kxzkj">字典表——交易订单状态</a></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": "10.00",
	"countryId": "CHL",
	"customerName": "zx",
	"fee": "1.00",
	"merId": "8301893137974691",
	"merOrderId": "2025072711403484941263221",
	"nonceStr": "4412f17f-4040-497d-b561-4ba4b5",
	"realityAmount": "10",
	"realityFee": "1.00",
	"reference": "CRTML7WASY5652PECVO9SRI7Z0K80J7",
	"sign": "D40102EA0EA8148028B2C87452E4E3E3",// 大写
	"status": "01",
	"successTime": 1753587643423,
	"supefinaOrderId": "202507270201000387a22b63a8949",
	"transactionType": "01"
}
```

{% endcode %}

签名组装字符串

amount=10.00\&countryId=CHL\&customerName=zx\&fee=1.00\&merId=8301893137974691\&merOrderId=2025072711403484941263221\&nonceStr=4412f17f-4040-497d-b561-4ba4b5\&realityAmount=10\&realityFee=1.00\&reference=CRTML7WASY5652PECVO9SRI7Z0K80J7\&status=01\&successTime=1753587643423\&supefinaOrderId=202507270201000387a22b63a8949\&transactionType=01\&key=764e7f81217541658f1ccc993b39d9e3

**回调通知响应**

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

{% code fullWidth="true" %}

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

{% endcode %}


# 巴西

在巴西，我们提供银行在线支付（PIX）支付产品。

<figure><img src="https://3631787624-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FuukVORWjXBgcGu8MirPR%2Fuploads%2FWi75kwZkAA1wIGL2z16C%2Fimage.png?alt=media&amp;token=26c6c718-0bf9-4d4c-b642-8fd377880116" alt=""><figcaption></figcaption></figure>

{% content-ref url="/pages/LgtIFyh81M4sGLlzv6X1" %}
[PIX](/huan-ying-shi-yong-supefina-de-api-wen-dang/dai-shou/ba-xi/pix)
{% endcontent-ref %}


# PIX

（payProduct=24）

### 支付流程

<figure><img src="https://3631787624-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FuukVORWjXBgcGu8MirPR%2Fuploads%2FxQmJK1BZFAoeGatZcutp%2Ftransfer.png?alt=media&amp;token=4f62280d-cbca-4ef1-8e69-cd2f7d559451" alt=""><figcaption></figcaption></figure>

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

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

&#x20;3、Supefina返回PIX付款URL信息。

&#x20;4、商户将该支付URL展示给用户；

&#x20;5、用户打开URL展示二维码按照页面提示进行付款；

6、付款成功；

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

### 支付视频

{% file src="/files/7oPykiXxtr8yfzTjE8uc" %}

### 收银台链接请求地址

<table data-full-width="true"><thead><tr><th width="138">环境名称</th><th width="800">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 width="479">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="217">变量名</th><th width="96">类型</th><th width="115">必填</th><th width="641">描述</th></tr></thead><tbody><tr><td>callbackUrl</td><td>String</td><td>是</td><td><p>回调地址</p><p>详见<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/tong-zhi-hui-tiao-shuo-ming">通知回调说明</a></p></td></tr><tr><td>countryId</td><td>String</td><td>是</td><td>国家编号<br>参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#afwzp">字典表-国家编号</a><br>巴西：<code>BRA</code></td></tr><tr><td>currency</td><td>String</td><td>是</td><td>币种<br>参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#huo-bi-currency">字典表-货币</a><br>雷亚尔：<code>BRL</code></td></tr><tr><td>customerPhone</td><td>String</td><td>否</td><td>手机号</td></tr><tr><td>customerEmail</td><td>String</td><td>是</td><td>用户邮箱</td></tr><tr><td>customerIdentification</td><td>String</td><td>否</td><td>用户证件号（CPF）</td></tr><tr><td>customerName</td><td>String</td><td>是</td><td>用户姓名</td></tr><tr><td>description</td><td>String</td><td>是</td><td>订单描述<br>不能带特殊符号</td></tr><tr><td>expireTimeL</td><td>Long</td><td>否</td><td><p>过期时间<br>单位：秒</p><p>此过期时间不生效，默认2小时<br></p></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>orderAmount</td><td>String</td><td>是</td><td>订单金额<br>支持两位小数；<br>20 &#x3C;= <code>orderAmount</code> &#x3C;= 50000</td></tr><tr><td>payProduct</td><td>String</td><td>是</td><td><a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#mfocd">支付类型</a><br>PIX：<code>24</code></td></tr><tr><td>sign</td><td>String</td><td>是</td><td>签名<br><a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/qian-ming-suan-fa">具体参照：签名算法</a></td></tr></tbody></table>

### 请求示例

{% code fullWidth="true" %}

```json
{
	"callbackUrl": "https://test.com",
	"countryId": "BRA",
	"currency": "BRL",
	"customerEmail": "9064@outlook.com",
	"customerIdentification": "123456789-09",
	"customerName": "test name",
	"description": "test description",
	"merId": "8302996847200585",
	"merOrderNo": "2025072513271752690740186",
	"nonceStr": "1da5c04f026549968b4c393be2287ac2",
	"orderAmount": "10.00",
	"payProduct": "24",
	"sign": "70A1D73AAC2B243689D395CCD8D3D272"// 大写
}
```

{% endcode %}

签名组装字符串

callbackUrl=<https://test.com\\&countryId=BRA\\&currency=BRL\\&customerEmail=9064@outlook.com\\&customerIdentification=123456789-09\\&customerName=test> name\&description=test description\&merId=8302996847200585\&merOrderNo=2025072513271752690740186\&nonceStr=1da5c04f026549968b4c393be2287ac2\&orderAmount=10.00\&payProduct=24\&key=9dbb958a68f04252bae26a6b6d98e0ab

### 响应参数

<table data-full-width="true"><thead><tr><th width="217">变量名</th><th width="136">类型</th><th width="736">描述</th></tr></thead><tbody><tr><td>code</td><td>String</td><td>响应编码<br>具体参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/xiang-ying-zhuang-tai-ma">响应状态码</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>渠道名称</td></tr><tr><td>fee</td><td>BigDecimal</td><td>预收手续费</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>referenceCode</td><td>String</td><td>收款二维码（5分钟失效）</td></tr><tr><td>supefinaOrderNo</td><td>String</td><td>supefina订单号</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>交易链接（收银台5分钟倒计时失效）</td></tr><tr><td>msg</td><td>String</td><td>消息</td></tr><tr><td>orderExpirationTime</td><td>String</td><td>订单过期时间 （UTC 0时区时间）</td></tr></tbody></table>

#### 响应示例

{% code fullWidth="true" %}

```json
{
	"code": "200",
	"msg": "success ",
	"data": {
		"merCode": "8302996847200585",
		"merOrderNo": "2025072513271752690740186",
		"supefinaOrderNo": "20250725052717925000038423",
		"amount": 10.0,
		"fee": 5.5,
		"transactionStatus": "00",
		"url": "https://h5.supefina.tech/brazil?token=20250725052717925000038423",
		"referenceCode": "",
		"channelName": "brpix",
		"orderExpirationTime": "2025-07-27T05:27:28.083"
	}
}
```

{% endcode %}

### 回调通知

提交方式：`POST`

<table data-full-width="true"><thead><tr><th width="217">变量名</th><th width="96">类型</th><th width="746">描述</th></tr></thead><tbody><tr><td>amount</td><td>String</td><td>订单金额</td></tr><tr><td>countryId</td><td>String</td><td>国家编号</td></tr><tr><td>customerName</td><td>String</td><td>付款人姓名</td></tr><tr><td>fee</td><td>String</td><td>预收手续费</td></tr><tr><td>merId</td><td>String</td><td>商户编号</td></tr><tr><td>merOrderId</td><td>String</td><td>商户订单号</td></tr><tr><td>msg</td><td>String</td><td>信息</td></tr><tr><td>identifier</td><td>String</td><td>付款参考<br>Clabe</td></tr><tr><td>nonceStr</td><td>String</td><td>随机字符串</td></tr><tr><td>payerIdNumber</td><td>String</td><td>付款人CPF</td></tr><tr><td>payerName</td><td>String</td><td>付款人姓名</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>交易状态<br>具体参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#kxzkj">字典表——交易订单状态</a></td></tr><tr><td>successTime</td><td>Date</td><td>交易成功时间</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": "10.00",
	"countryId": "BRA",
	"customerName": "test name",
	"fee": "5.50",
	"identifier": "8d0f2d03-2c86-4b",
	"merId": "8302996847200585",
	"merOrderId": "2025072513271752690740186",
	"msg": "SUCCESS",
	"nonceStr": "c5c9eb58-751e-491f-9b1a-5b9261",
	"payerIdNumber": "123456789-09",
	"payerName": "test",
	"realityAmount": "10.00",
	"realityFee": "5.50",
	"sign": "57512911FB88A2C77566F61BB274F56D",// 大写
	"status": "01",
	"successTime": 1753421243000,
	"supefinaOrderId": "20250725052717925000038423",
	"transactionType": "01"
}
```

{% endcode %}

签名组装字符串

amount=10.00\&countryId=BRA\&customerName=test name\&fee=5.50\&identifier=8d0f2d03-2c86-4b\&merId=8302996847200585\&merOrderId=2025072513271752690740186\&msg=SUCCESS\&nonceStr=c5c9eb58-751e-491f-9b1a-5b9261\&payerIdNumber=123456789-09\&payerName=test\&realityAmount=10.00\&realityFee=5.50\&status=01\&successTime=1753421243000\&supefinaOrderId=20250725052717925000038423\&transactionType=01\&key=9dbb958a68f04252bae26a6b6d98e0ab

**回调通知响应**

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

{% code fullWidth="true" %}

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

{% endcode %}


# 厄瓜多尔

在厄瓜多尔，我们提供银行转账（Transfer），现金支付（Cash）等支付产品。

<figure><img src="https://3631787624-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FuukVORWjXBgcGu8MirPR%2Fuploads%2F2Bz1e3uXPd4XNuq628Me%2F%E5%8E%84%E7%93%9C%E5%A4%9A%E5%B0%94.jpg?alt=media&amp;token=d2adb4e8-fcef-4c86-a854-02b1f54dc2f6" alt=""><figcaption></figcaption></figure>

{% content-ref url="/pages/p4kGi0dx1gtgQ8jzlSkA" %}
[Transfer](/huan-ying-shi-yong-supefina-de-api-wen-dang/dai-shou/e-gua-duo-er/transfer)
{% endcontent-ref %}

{% content-ref url="/pages/fM9X1mtSz3aTbkNUAfMg" %}
[Cash](/huan-ying-shi-yong-supefina-de-api-wen-dang/dai-shou/e-gua-duo-er/cash)
{% endcontent-ref %}

{% content-ref url="/pages/J0n9FhR804KmmKwQrMIC" %}
[Card](/huan-ying-shi-yong-supefina-de-api-wen-dang/dai-shou/e-gua-duo-er/card)
{% endcontent-ref %}

{% content-ref url="/pages/SOeeUqfMrqSf6a1tntda" %}
[Wallet](/huan-ying-shi-yong-supefina-de-api-wen-dang/dai-shou/e-gua-duo-er/wallet)
{% endcontent-ref %}

{% content-ref url="/pages/WIcBcPpsjQG5mNCalvZE" %}
[Broken mention](broken://pages/WIcBcPpsjQG5mNCalvZE)
{% endcontent-ref %}


# Transfer

（payProduct=12）

### 支付流程

<figure><img src="https://3631787624-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FuukVORWjXBgcGu8MirPR%2Fuploads%2FxQmJK1BZFAoeGatZcutp%2Ftransfer.png?alt=media&amp;token=4f62280d-cbca-4ef1-8e69-cd2f7d559451" alt=""><figcaption></figcaption></figure>

1、用户在商户网站/应用下单，并选择Transfer支付；

2、商户向Supefina发起Transfer支付请求；

3、Supefina返回Transfer支付URL地址；

4、商户将该地址在用户侧打开；

5、用户按照页面提示进行验证和支付；

6、用户支付成功；

7、Supefina将支付成功信息通知商户。

### 请求地址

<table data-full-width="true"><thead><tr><th width="138">环境名称</th><th width="607">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="235">变量名</th><th width="96">类型</th><th width="127">必填</th><th width="511">描述</th></tr></thead><tbody><tr><td>countryId</td><td>String</td><td>是</td><td>国家编号<br>参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#afwzp">字典表-国家编号</a><br>厄瓜多尔：<code>ECU</code></td></tr><tr><td>merId</td><td>String</td><td>是</td><td>商户ID<br>商户ID获取路径：Supefina商户后台-商户管理-基本信息-商户ID</td></tr><tr><td>payProduct</td><td>String</td><td>是</td><td><a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#mfocd">支付类型</a><br>Transfer：<code>12</code></td></tr><tr><td>currency</td><td>String</td><td>是</td><td>币种<br>参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#huo-bi-currency">字典表-货币</a><br>美元：<code>USD</code></td></tr><tr><td>merOrderNo</td><td>String</td><td>是</td><td>商户订单号</td></tr><tr><td>orderAmount</td><td>String</td><td>是</td><td>订单金额<br>0>= <code>orderAmount</code> &#x3C;= 10,000</td></tr><tr><td>customerEmail</td><td>String</td><td>是</td><td>用户邮箱</td></tr><tr><td>customerName</td><td>String</td><td>是</td><td>用户姓名</td></tr><tr><td>lastName</td><td>String</td><td>是</td><td>用户姓氏</td></tr><tr><td>customerIdentificationType</td><td>String</td><td>是</td><td>用户身份证明文件类型<br><code>07</code>：身份证件（CI）<br><code>10</code>：护照号码（PP）(only for Cash)<br><code>03</code>：护照标识（PAS）(only for BankTransfer)<br><code>02</code>：税号（RUC）</td></tr><tr><td>customerIdentification</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>sign</td><td>String</td><td>是</td><td><p>签名</p><p><a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/qian-ming-suan-fa">具体参照：签名算法</a></p></td></tr><tr><td>callbackUrl</td><td>String</td><td>是</td><td><p>回调地址</p><p>详见<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/tong-zhi-hui-tiao-shuo-ming">通知回调说明</a></p></td></tr><tr><td>expireTimeL</td><td>Long</td><td>否</td><td>过期时间<br>单位：秒；默认1天，建议商户自己控制时间</td></tr><tr><td>customerPhone</td><td>String</td><td>否</td><td>用户电话</td></tr><tr><td>checkOut</td><td>Boolean</td><td>否</td><td>收银台<br><code>true</code>：需要收银台<br><code>false</code>：不需要收银台<br>建议传<code>true</code></td></tr></tbody></table>

### 请求示例

{% code fullWidth="true" %}

```json
{
	"countryId": "ECU",
	"currency": "USD",
	"customerEmail": "123456@supefina.com",
	"customerIdentification": "0943115766",
	"customerIdentificationType": "07",
	"customerName": "testName",
	"lastName": "test",
	"merId": "8302748528064643",
	"merOrderNo": "2025072611541566929937641",
	"nonceStr": "54da16074e4a4b66b58e8d9305f1ded0",
	"orderAmount": "200",
	"payProduct": "12",
	"sign": "565611A83D7A4D710C2DEBDFD2B1A481"// 大写
}
```

{% endcode %}

签名组装字符串

countryId=ECU\&currency=USD\&customerEmail=<123456@supefina.com>\&customerIdentification=0943115766\&customerIdentificationType=07\&customerName=testName\&lastName=test\&merId=8302748528064643\&merOrderNo=2025072611541566929937641\&nonceStr=54da16074e4a4b66b58e8d9305f1ded0\&orderAmount=200\&payProduct=12\&key=bb01dd04d967425ab194fff9fe8a9501

### 响应参数

<table data-full-width="true"><thead><tr><th width="235">变量名</th><th width="96">类型</th><th width="492">描述</th></tr></thead><tbody><tr><td>code</td><td>String</td><td>响应编码<br>具体参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/xiang-ying-zhuang-tai-ma">响应状态码</a></td></tr><tr><td>msg</td><td>String</td><td>响应信息</td></tr><tr><td>data</td><td>Object</td><td>响应数据</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>supefinaOrderNo</td><td>String</td><td>supefina订单号</td></tr><tr><td>amount</td><td>BigDecimal</td><td>订单金额</td></tr><tr><td>fee</td><td>BigDecimal</td><td>预收手续费</td></tr><tr><td>identifier</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></tbody></table>

#### 响应示例

{% code fullWidth="true" %}

```json
{
	"code": "200",
	"msg": "success ",
	"data": {
		"merCode": "8302748528064643",
		"merOrderNo": "2025072611541566929937641",
		"supefinaOrderNo": "202507260601000a96feb3417574a",
		"amount": 200,
		"fee": 5.0,
		"transactionStatus": "00",
		"url":"https://pay-met.ec:6080/#/metodo-pago/VE9LRU4gR0VORVJBIFJFQ0FVRE80NjU0NjI="
	}
}
```

{% endcode %}

### 回调通知

提交方式：`POST`

<table data-full-width="true"><thead><tr><th width="235">变量名</th><th width="96">类型</th><th width="517">描述</th></tr></thead><tbody><tr><td>amount</td><td>String</td><td>订单金额</td></tr><tr><td>countryId</td><td>String</td><td>国家编号</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>商户编号</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>交易状态<br>具体参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#kxzkj">字典表——交易订单状态</a></td></tr><tr><td>successTime</td><td>Date</td><td>交易成功时间</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": "200.00",
	"countryId": "ECU",
	"customerName": "testName",
	"fee": "5.00",
	"merId": "8302748528064643",
	"merOrderId": "2025072611541566929937641",
	"nonceStr": "d62a9ea8-dd38-4dff-a1bd-50ba0c",
	"realityAmount": "200",
	"realityFee": "5.00",
	"reference": "CRT4YREJJ6FONJFNLB03MO5GMFKOVIM",
	"sign": "F3B43A3C499896D8372ED2A9F63026E4",
	"status": "01",
	"successTime": 1753502062800,
	"supefinaOrderId": "202507260601000a96feb3417574a",// 大写
	"transactionType": "01"
}
```

{% endcode %}

签名组装字符串

amount=200.00\&countryId=ECU\&customerName=testName\&fee=5.00\&merId=8302748528064643\&merOrderId=2025072611541566929937641\&nonceStr=d62a9ea8-dd38-4dff-a1bd-50ba0c\&realityAmount=200\&realityFee=5.00\&reference=CRT4YREJJ6FONJFNLB03MO5GMFKOVIM\&status=01\&successTime=1753502062800\&supefinaOrderId=202507260601000a96feb3417574a\&transactionType=01\&key=bb01dd04d967425ab194fff9fe8a9501

**回调通知响应**

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

{% code fullWidth="true" %}

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

{% endcode %}


# Cash

（payProduct=03）

### 支付流程

<figure><img src="https://3631787624-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FuukVORWjXBgcGu8MirPR%2Fuploads%2FjaP8k7IuMK21PVykdZYz%2FCash.png?alt=media&amp;token=74a9a5cd-7280-48dd-a973-cddd0780d3f8" alt=""><figcaption></figcaption></figure>

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

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

&#x20;3、Supefina返回Cash付款URL信息。

&#x20;4、商户将该支付URL展示给用户；

&#x20;5、用户按照页面提示进行付款；

6、付款成功；

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

### 请求地址

<table data-full-width="true"><thead><tr><th width="138">环境名称</th><th width="607">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="285">变量名</th><th width="96">类型</th><th width="116">必填</th><th width="514">描述</th></tr></thead><tbody><tr><td>countryId</td><td>String</td><td>是</td><td>国家编号<br>参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#afwzp">字典表-国家编号</a><br>厄瓜多尔：<code>ECU</code></td></tr><tr><td>merId</td><td>String</td><td>是</td><td>商户ID<br>商户ID获取路径：Supefina商户后台-商户管理-基本信息-商户ID</td></tr><tr><td>payProduct</td><td>String</td><td>是</td><td><a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#mfocd">支付类型</a><br>Cash：<code>03</code></td></tr><tr><td>currency</td><td>String</td><td>是</td><td>币种<br>参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#huo-bi-currency">字典表-货币</a><br>美元：<code>USD</code></td></tr><tr><td>merOrderNo</td><td>String</td><td>是</td><td>商户订单号</td></tr><tr><td>orderAmount</td><td>String</td><td>是</td><td>订单金额<br>0>= <code>orderAmount</code> &#x3C;= 10,000</td></tr><tr><td>customerEmail</td><td>String</td><td>是</td><td>用户邮箱</td></tr><tr><td>customerName</td><td>String</td><td>是</td><td>用户姓名</td></tr><tr><td>lastName</td><td>String</td><td>是</td><td>用户姓氏</td></tr><tr><td>customerIdentificationType</td><td>String</td><td>是</td><td>用户身份证明文件类型<br><code>07</code>：身份证件（CI）<br><code>10</code>：护照号码（PP）(only for Cash)<br><code>03</code>：护照标识（PAS）(only for BankTransfer)<br><code>02</code>：税号（RUC）</td></tr><tr><td>customerIdentification</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>sign</td><td>String</td><td>是</td><td><p>签名</p><p><a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/qian-ming-suan-fa">具体参照：签名算法</a></p></td></tr><tr><td>callbackUrl</td><td>String</td><td>是</td><td><p>回调地址</p><p>详见<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/tong-zhi-hui-tiao-shuo-ming">通知回调说明</a></p></td></tr><tr><td>expireTimeL</td><td>Long</td><td>否</td><td>过期时间<br>单位：秒；默认1天，建议商户自己控制时间</td></tr><tr><td>customerPhone</td><td>String</td><td>否</td><td>用户电话</td></tr><tr><td>checkOut</td><td>Boolean</td><td>否</td><td>收银台<br><code>true</code>：需要收银台<br><code>false</code>：不需要收银台<br>建议传<code>true</code></td></tr></tbody></table>

### 请求示例

{% code fullWidth="true" %}

```json
{
	"countryId": "ECU",
	"currency": "USD",
	"customerEmail": "123456@supefina.com",
	"customerIdentification": "0943115766",
	"customerIdentificationType": "07",
	"customerName": "testName",
	"lastName": "test",
	"merId": "8302748528064643",
	"merOrderNo": "2025072611575720931350683",
	"nonceStr": "00723b1d685a46cab9bb6db76b8762ad",
	"orderAmount": "200",
	"payProduct": "03",
	"sign": "0412DD644F74C0D463AAE7FA27F3C99F"// 大写
}
```

{% endcode %}

签名组装字符串

countryId=ECU\&currency=USD\&customerEmail=<123456@supefina.com>\&customerIdentification=0943115766\&customerIdentificationType=07\&customerName=testName\&lastName=test\&merId=8302748528064643\&merOrderNo=2025072611575720931350683\&nonceStr=00723b1d685a46cab9bb6db76b8762ad\&orderAmount=200\&payProduct=03\&key=bb01dd04d967425ab194fff9fe8a9501

### 响应参数

<table data-full-width="true"><thead><tr><th width="244">变量名</th><th width="139">类型</th><th width="610">描述</th></tr></thead><tbody><tr><td>code</td><td>String</td><td>响应编码<br>具体参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/xiang-ying-zhuang-tai-ma">响应状态码</a></td></tr><tr><td>msg</td><td>String</td><td>响应信息</td></tr><tr><td>data</td><td>Object</td><td>响应数据</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>supefinaOrderNo</td><td>String</td><td>supefina订单号</td></tr><tr><td>amount</td><td>BigDecimal</td><td>订单金额</td></tr><tr><td>fee</td><td>BigDecimal</td><td>预收手续费</td></tr><tr><td>identifier</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></tbody></table>

#### 响应示例

{% code fullWidth="true" %}

```json
{
	"code": "200",
	"msg": "success ",
	"data": {
		"merCode": "8302748528064643",
		"merOrderNo": "2025072611575720931350683",
		"supefinaOrderNo": "202507260601000ca1dc24c1d234a",
		"amount": 200,
		"fee": 3.0,
		"transactionStatus": "00",
		"url":"https://pay-met.ec:6080/#/metodo-pago/VE9LRU4gR0VORVJBIFJFQ0FVRE80NjU0NjI="
	}
}
```

{% endcode %}

### 回调通知

提交方式：`POST`

<table data-full-width="true"><thead><tr><th width="230">变量名</th><th width="155">类型</th><th width="522">描述</th></tr></thead><tbody><tr><td>amount</td><td>String</td><td>订单金额</td></tr><tr><td>countryId</td><td>String</td><td>国家编号</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>商户编号</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>交易状态<br>具体参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#kxzkj">字典表——交易订单状态</a></td></tr><tr><td>successTime</td><td>Date</td><td>交易成功时间</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": "200.00",
	"countryId": "ECU",
	"customerName": "testName",
	"fee": "3.00",
	"merId": "8302748528064643",
	"merOrderId": "2025072611575720931350683",
	"nonceStr": "ed31557b-9b52-45de-9a41-7628cf",
	"realityAmount": "200",
	"realityFee": "3.00",
	"reference": "CRTG60ERQRF3BBF6033GIRGXQOX3NKY",
	"sign": "0209603711416D66217470E17032EACE",// 大写
	"status": "01",
	"successTime": 1753502284155,
	"supefinaOrderId": "202507260601000ca1dc24c1d234a",
	"transactionType": "01"
}
```

{% endcode %}

签名组装字符串

amount=200.00\&countryId=ECU\&customerName=testName\&fee=3.00\&merId=8302748528064643\&merOrderId=2025072611575720931350683\&nonceStr=ed31557b-9b52-45de-9a41-7628cf\&realityAmount=200\&realityFee=3.00\&reference=CRTG60ERQRF3BBF6033GIRGXQOX3NKY\&status=01\&successTime=1753502284155\&supefinaOrderId=202507260601000ca1dc24c1d234a\&transactionType=01\&key=bb01dd04d967425ab194fff9fe8a9501

**回调通知响应**

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

{% code fullWidth="true" %}

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

{% endcode %}


# Card

（payProduct=21）

### 支付流程

<figure><img src="https://3631787624-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FuukVORWjXBgcGu8MirPR%2Fuploads%2FxQmJK1BZFAoeGatZcutp%2Ftransfer.png?alt=media&amp;token=4f62280d-cbca-4ef1-8e69-cd2f7d559451" alt=""><figcaption></figcaption></figure>

1、用户在商户网站/应用下单，并选择Card支付；

2、商户向Supefina发起Card支付请求；

3、Supefina返回Card支付URL地址；

4、商户将该地址在用户侧打开；

5、用户按照页面提示进行验证和支付；

6、用户支付成功；

7、Supefina将支付成功信息通知商户。

### 请求地址

<table data-full-width="true"><thead><tr><th width="138">环境名称</th><th width="607">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="272">变量名</th><th width="96">类型</th><th width="114">必填</th><th width="513">描述</th></tr></thead><tbody><tr><td>countryId</td><td>String</td><td>是</td><td>国家编号<br>参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#afwzp">字典表-国家编号</a><br>厄瓜多尔：<code>ECU</code></td></tr><tr><td>merId</td><td>String</td><td>是</td><td>商户ID<br>商户ID获取路径：Supefina商户后台-商户管理-基本信息-商户ID</td></tr><tr><td>payProduct</td><td>String</td><td>是</td><td><a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#mfocd">支付类型</a><br>Card：<code>21</code></td></tr><tr><td>currency</td><td>String</td><td>是</td><td>币种<br>参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#huo-bi-currency">字典表-货币</a><br>美元：<code>USD</code></td></tr><tr><td>merOrderNo</td><td>String</td><td>是</td><td>商户订单号</td></tr><tr><td>orderAmount</td><td>String</td><td>是</td><td>订单金额<br>0>= <code>orderAmount</code> &#x3C;= 10,000</td></tr><tr><td>customerEmail</td><td>String</td><td>是</td><td>用户邮箱</td></tr><tr><td>customerName</td><td>String</td><td>是</td><td>用户姓名</td></tr><tr><td>lastName</td><td>String</td><td>是</td><td>用户姓氏</td></tr><tr><td>customerIdentificationType</td><td>String</td><td>是</td><td>用户身份证明文件类型<br><code>07</code>：身份证件（CI）<br><code>10</code>：护照号码（PP）(only for Cash)<br><code>03</code>：护照标识（PAS）(only for BankTransfer)<br><code>02</code>：税号（RUC）</td></tr><tr><td>customerIdentification</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>sign</td><td>String</td><td>是</td><td><p>签名</p><p><a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/qian-ming-suan-fa">具体参照：签名算法</a></p></td></tr><tr><td>callbackUrl</td><td>String</td><td>是</td><td><p>回调地址</p><p>详见<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/tong-zhi-hui-tiao-shuo-ming">通知回调说明</a></p></td></tr><tr><td>expireTimeL</td><td>Long</td><td>否</td><td>过期时间<br>单位：秒；默认1天，建议商户自己控制时间</td></tr><tr><td>customerPhone</td><td>String</td><td>否</td><td>用户电话</td></tr><tr><td>checkOut</td><td>Boolean</td><td>否</td><td>收银台<br><code>true</code>：需要收银台<br><code>false</code>：不需要收银台<br>建议传<code>true</code></td></tr></tbody></table>

### 请求示例

{% code fullWidth="true" %}

```json
{
	"countryId": "ECU",
	"currency": "USD",
	"customerEmail": "123456@supefina.com",
	"customerIdentification": "0943115766",
	"customerIdentificationType": "07",
	"customerName": "testName",
	"lastName": "test",
	"merId": "8302748528064643",
	"merOrderNo": "2025072612011580674836758",
	"nonceStr": "ac8cdd5e30604e5b90bf1739dfa0d1d9",
	"orderAmount": "200",
	"payProduct": "21",
	"sign": "799087714A2E0FCF9609C81688515D8B"// 大写
}
```

{% endcode %}

签名组装字符串

countryId=ECU\&currency=USD\&customerEmail=<123456@supefina.com>\&customerIdentification=0943115766\&customerIdentificationType=07\&customerName=testName\&lastName=test\&merId=8302748528064643\&merOrderNo=2025072612011580674836758\&nonceStr=ac8cdd5e30604e5b90bf1739dfa0d1d9\&orderAmount=200\&payProduct=21\&key=bb01dd04d967425ab194fff9fe8a9501

### 响应参数

<table data-full-width="true"><thead><tr><th width="235">变量名</th><th width="96">类型</th><th width="497">描述</th></tr></thead><tbody><tr><td>code</td><td>String</td><td>响应编码<br>具体参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/xiang-ying-zhuang-tai-ma">响应状态码</a></td></tr><tr><td>msg</td><td>String</td><td>响应信息</td></tr><tr><td>data</td><td>Object</td><td>响应数据</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>supefinaOrderNo</td><td>String</td><td>supefina订单号</td></tr><tr><td>amount</td><td>BigDecimal</td><td>订单金额</td></tr><tr><td>fee</td><td>BigDecimal</td><td>预收手续费</td></tr><tr><td>identifier</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></tbody></table>

#### 响应示例

{% code fullWidth="true" %}

```json
{
	"code": "200",
	"msg": "success ",
	"data": {
		"merCode": "8302748528064643",
		"merOrderNo": "2025072612011580674836758",
		"supefinaOrderNo": "2025072606010008a36a6592d9343",
		"amount": 200,
		"fee": 3.0,
		"transactionStatus": "00",
		"url":"https://pay-met.ec:6080/#/metodo-pago/VE9LRU4gR0VORVJBIFJFQ0FVRE80NjU0NjI="
	}
}
```

{% endcode %}

### 回调通知

提交方式：`POST`

<table data-full-width="true"><thead><tr><th width="235">变量名</th><th width="96">类型</th><th width="722">描述</th></tr></thead><tbody><tr><td>amount</td><td>String</td><td>订单金额</td></tr><tr><td>countryId</td><td>String</td><td>国家编号</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>商户编号</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>交易状态<br>具体参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#kxzkj">字典表——交易订单状态</a></td></tr><tr><td>successTime</td><td>Date</td><td>交易成功时间</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": "200.00",
	"countryId": "ECU",
	"customerName": "testName",
	"fee": "3.00",
	"merId": "8302748528064643",
	"merOrderId": "2025072612011580674836758",
	"nonceStr": "2dd4978a-cb29-44b1-8dc8-242553",
	"realityAmount": "200",
	"realityFee": "3.00",
	"reference": "CRTWIWQBANHSCCXKBQPW7B02NAS24DI",
	"sign": "346F2F0C0F47421B51302FEF523FF79F",// 大写
	"status": "01",
	"successTime": 1753502482793,
	"supefinaOrderId": "2025072606010008a36a6592d9343",
	"transactionType": "01"
}
```

{% endcode %}

签名组装字符串

amount=200.00\&countryId=ECU\&customerName=testName\&fee=3.00\&merId=8302748528064643\&merOrderId=2025072612011580674836758\&nonceStr=2dd4978a-cb29-44b1-8dc8-242553\&realityAmount=200\&realityFee=3.00\&reference=CRTWIWQBANHSCCXKBQPW7B02NAS24DI\&status=01\&successTime=1753502482793\&supefinaOrderId=2025072606010008a36a6592d9343\&transactionType=01\&key=bb01dd04d967425ab194fff9fe8a9501

**回调通知响应**

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

{% code fullWidth="true" %}

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

{% endcode %}


# Wallet

（payProduct=23）

### 支付流程

<figure><img src="https://3631787624-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FuukVORWjXBgcGu8MirPR%2Fuploads%2FxQmJK1BZFAoeGatZcutp%2Ftransfer.png?alt=media&amp;token=4f62280d-cbca-4ef1-8e69-cd2f7d559451" alt=""><figcaption></figcaption></figure>

1、用户在商户网站/应用下单，并选择Wallet支付；

2、商户向Supefina发起Wallet支付请求；

3、Supefina返回Card支付Wallet地址；

4、商户将该地址在用户侧打开；

5、用户按照页面提示进行验证和支付；

6、用户支付成功；

7、Supefina将支付成功信息通知商户。

### 请求地址

<table data-full-width="true"><thead><tr><th width="138">环境名称</th><th width="607">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="252">变量名</th><th width="96">类型</th><th width="88">必填</th><th width="555">描述</th></tr></thead><tbody><tr><td>countryId</td><td>String</td><td>是</td><td>国家编号<br>参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#afwzp">字典表-国家编号</a><br>厄瓜多尔：<code>ECU</code></td></tr><tr><td>merId</td><td>String</td><td>是</td><td>商户ID<br>商户ID获取路径：Supefina商户后台-商户管理-基本信息-商户ID</td></tr><tr><td>payProduct</td><td>String</td><td>是</td><td><a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#mfocd">支付类型</a><br>Wallet：<code>23</code></td></tr><tr><td>currency</td><td>String</td><td>是</td><td>币种<br>参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#huo-bi-currency">字典表-货币</a><br>美元：<code>USD</code></td></tr><tr><td>merOrderNo</td><td>String</td><td>是</td><td>商户订单号</td></tr><tr><td>orderAmount</td><td>String</td><td>是</td><td>订单金额<br>0>= <code>orderAmount</code> &#x3C;= 10,000</td></tr><tr><td>customerEmail</td><td>String</td><td>是</td><td>用户邮箱</td></tr><tr><td>customerName</td><td>String</td><td>是</td><td>用户姓名</td></tr><tr><td>lastName</td><td>String</td><td>是</td><td>用户姓氏</td></tr><tr><td>customerIdentificationType</td><td>String</td><td>是</td><td>用户身份证明文件类型<br><code>07</code>：身份证件（CI）<br><code>10</code>：护照号码（PP）(only for Cash)<br><code>03</code>：护照标识（PAS）(only for BankTransfer)<br><code>02</code>：税号（RUC）</td></tr><tr><td>customerIdentification</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>sign</td><td>String</td><td>是</td><td><p>签名</p><p><a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/qian-ming-suan-fa">具体参照：签名算法</a></p></td></tr><tr><td>callbackUrl</td><td>String</td><td>是</td><td><p>回调地址</p><p>详见<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/tong-zhi-hui-tiao-shuo-ming">通知回调说明</a></p></td></tr><tr><td>expireTimeL</td><td>Long</td><td>否</td><td>过期时间<br>单位：秒；默认1天，建议商户自己控制时间</td></tr><tr><td>customerPhone</td><td>String</td><td>否</td><td>用户电话</td></tr><tr><td>checkOut</td><td>Boolean</td><td>否</td><td>收银台<br><code>true</code>：需要收银台<br><code>false</code>：不需要收银台<br>建议传<code>true</code></td></tr></tbody></table>

### 请求示例

{% code fullWidth="true" %}

```json
{
	"countryId": "ECU",
	"currency": "USD",
	"customerEmail": "123456@supefina.com",
	"customerIdentification": "0943115766",
	"customerIdentificationType": "07",
	"customerName": "testName",
	"lastName": "test",
	"merId": "8302748528064643",
	"merOrderNo": "2025072612041535067601882",
	"nonceStr": "08287e396f184ab2987fc885d7cbef00",
	"orderAmount": "200",
	"payProduct": "23",
	"sign": "13AFA102C44D0D90DD1BA44B9DE78D9F"// 大写
}
```

{% endcode %}

签名组装字符串

countryId=ECU\&currency=USD\&customerEmail=<123456@supefina.com>\&customerIdentification=0943115766\&customerIdentificationType=07\&customerName=testName\&lastName=test\&merId=8302748528064643\&merOrderNo=2025072612041535067601882\&nonceStr=08287e396f184ab2987fc885d7cbef00\&orderAmount=200\&payProduct=23\&key=bb01dd04d967425ab194fff9fe8a9501

### 响应参数

<table data-full-width="true"><thead><tr><th width="217">变量名</th><th width="96">类型</th><th width="575">描述</th></tr></thead><tbody><tr><td>code</td><td>String</td><td>响应编码<br>具体参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/xiang-ying-zhuang-tai-ma">响应状态码</a></td></tr><tr><td>msg</td><td>String</td><td>响应信息</td></tr><tr><td>data</td><td>Object</td><td>响应数据</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>supefinaOrderNo</td><td>String</td><td>supefina订单号</td></tr><tr><td>amount</td><td>BigDecimal</td><td>订单金额</td></tr><tr><td>fee</td><td>BigDecimal</td><td>预收手续费</td></tr><tr><td>identifier</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></tbody></table>

#### 响应示例

{% code fullWidth="true" %}

```json
{
	"code": "200",
	"msg": "success ",
	"data": {
		"merCode": "8302748528064643",
		"merOrderNo": "2025072612041535067601882",
		"supefinaOrderNo": "2025072606010009d4ecec2b23d42",
		"amount": 200,
		"fee": 3.0,
		"transactionStatus": "00",
		"url":"https://pay-met.ec:6080/#/metodo-pago/VE9LRU4gR0VORVJBIFJFQ0FVRE80NjU0NjI="
	}
}
```

{% endcode %}

### 回调通知

提交方式：`POST`

<table data-full-width="true"><thead><tr><th width="235">变量名</th><th width="96">类型</th><th width="608">描述</th></tr></thead><tbody><tr><td>amount</td><td>String</td><td>订单金额</td></tr><tr><td>countryId</td><td>String</td><td>国家编号</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>商户编号</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>交易状态<br>具体参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#kxzkj">字典表——交易订单状态</a></td></tr><tr><td>successTime</td><td>Date</td><td>交易成功时间</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": "200.00",
	"countryId": "ECU",
	"customerName": "testName",
	"fee": "3.00",
	"merId": "8302748528064643",
	"merOrderId": "2025072612041535067601882",
	"nonceStr": "b761ce91-61e1-4c74-a443-dbc511",
	"realityAmount": "200",
	"realityFee": "3.00",
	"reference": "CRT0D6D16ICHXWJCD5EMCCOWXI0VGX9",
	"sign": "0BB0677956235DC97DEFE18B1E90B4CD",// 大写
	"status": "01",
	"successTime": 1753502666792,
	"supefinaOrderId": "2025072606010009d4ecec2b23d42",
	"transactionType": "01"
}
```

{% endcode %}

签名组装字符串

amount=200.00\&countryId=ECU\&customerName=testName\&fee=3.00\&merId=8302748528064643\&merOrderId=2025072612041535067601882\&nonceStr=b761ce91-61e1-4c74-a443-dbc511\&realityAmount=200\&realityFee=3.00\&reference=CRT0D6D16ICHXWJCD5EMCCOWXI0VGX9\&status=01\&successTime=1753502666792\&supefinaOrderId=2025072606010009d4ecec2b23d42\&transactionType=01\&key=bb01dd04d967425ab194fff9fe8a9501

**回调通知响应**

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

{% code fullWidth="true" %}

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

{% endcode %}


# 阿根廷

在阿根廷，我们提供银行转账（Transfer）支付产品。

{% content-ref url="/pages/JU68p2HbFXYw1erkkzNj" %}
[Debin](/huan-ying-shi-yong-supefina-de-api-wen-dang/dai-shou/a-gen-ting/debin)
{% endcontent-ref %}


# Debin

（payProduct=29）

### 支付流程

<figure><img src="https://3631787624-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FuukVORWjXBgcGu8MirPR%2Fuploads%2FxQmJK1BZFAoeGatZcutp%2Ftransfer.png?alt=media&amp;token=4f62280d-cbca-4ef1-8e69-cd2f7d559451" alt=""><figcaption></figcaption></figure>

1、用户在商户网站/应用下单，并选择Debin支付；

2、商户向Supefina发起Debin支付请求；

3、Supefina返回Debin支付URL地址；

4、商户将该地址在用户侧打开；

5、用户按照页面提示进行验证和支付；

6、用户支付成功；

7、Supefina将支付成功信息通知商户。

### 请求地址

<table data-full-width="true"><thead><tr><th width="138">环境名称</th><th width="607">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="252">变量名</th><th width="96">类型</th><th width="127">必填</th><th width="511">描述</th></tr></thead><tbody><tr><td>countryId</td><td>String</td><td>是</td><td>国家编号<br>参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#afwzp">字典表-国家编号</a><br>阿根廷：<code>ARG</code></td></tr><tr><td>merId</td><td>String</td><td>是</td><td>商户ID<br>商户ID获取路径：Supefina商户后台-商户管理-基本信息-商户ID</td></tr><tr><td>payProduct</td><td>String</td><td>是</td><td><a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#mfocd">支付类型</a><br>Debin：<code>29</code></td></tr><tr><td>currency</td><td>String</td><td>是</td><td>币种<br>参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#huo-bi-currency">字典表-货币</a><br>阿根廷比索：<code>ARS</code></td></tr><tr><td>merOrderNo</td><td>String</td><td>是</td><td>商户订单号</td></tr><tr><td>orderAmount</td><td>String</td><td>是</td><td>订单金额<br>只支持整数</td></tr><tr><td>customerEmail</td><td>String</td><td>是</td><td><p>用户邮箱</p><p>邮箱用户名不能只有数字（例如31231234@gmail.com）且同一个邮箱一天支付请求不能超过20次。</p></td></tr><tr><td>customerName</td><td>String</td><td>是</td><td>用户姓名</td></tr><tr><td>customerPhone</td><td>String</td><td>是</td><td>用户电话</td></tr><tr><td>customerIdentificationType</td><td>String</td><td>是</td><td><p>用户证件类型 </p><p><code>00</code>：身份证（DNI）</p><p><code>02</code>：税号（CUIT）</p></td></tr><tr><td>customerIdentification</td><td>String</td><td>是</td><td>用户身份证件号</td></tr><tr><td>checkOut</td><td>Boolean</td><td>是</td><td>传<code>true</code></td></tr><tr><td>nonceStr</td><td>String</td><td>是</td><td>随机字符串<br>长度不能超过32位</td></tr><tr><td>sign</td><td>String</td><td>是</td><td><p>签名</p><p><a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/qian-ming-suan-fa">具体参照：签名算法</a></p></td></tr><tr><td>description</td><td>String</td><td>否</td><td>描述<br>不能带特殊符号,长度不超过200字符</td></tr><tr><td>callbackUrl</td><td>String</td><td>是</td><td><p>回调地址</p><p>详见<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/tong-zhi-hui-tiao-shuo-ming">通知回调说明</a></p></td></tr><tr><td>returnUrl</td><td>String</td><td>否</td><td>支付完成后返回的地址</td></tr><tr><td>expireTimeL</td><td>Long</td><td>否</td><td>过期时间<br>单位：秒；默认：84960</td></tr></tbody></table>

### 请求示例

{% code fullWidth="true" %}

```json
{
	"callbackUrl": "http://127.0.0.1:8080/test",
	"checkOut": true,
	"countryId": "ARG",
	"currency": "ARS",
	"customerEmail": "abc@gmail.com",
	"customerIdentification": "11111111-1",
	"customerIdentificationType": "02",
	"customerName": "test name",
	"customerPhone": "123456789",
	"description": "test",
	"expireTimeL": 3600,
	"merId": "8302709349110631",
	"merOrderNo": "2025072511440655494299413",
	"nonceStr": "8cb57f06f0764d75b63d13700d0f9c2a",
	"orderAmount": 100,
	"payProduct": "29",
	"sign": "BAC8EC5C66D841191882320C4029386A"// 大写
}
```

{% endcode %}

签名组装字符串

callbackUrl=<http://127.0.0.1:8080/test\\&checkOut=true\\&countryId=ARG\\&currency=ARS\\&customerEmail=abc@gmail.com\\&customerIdentification=11111111-1\\&customerIdentificationType=02\\&customerName=test> name\&customerPhone=123456789\&description=test\&expireTimeL=3600\&merId=8302709349110631\&merOrderNo=2025072511440655494299413\&nonceStr=8cb57f06f0764d75b63d13700d0f9c2a\&orderAmount=100\&payProduct=29\&key=e200749bb5914603ad05a03d9b1b6445

### 响应参数

<table data-full-width="true"><thead><tr><th width="235">变量名</th><th width="96">类型</th><th width="492">描述</th></tr></thead><tbody><tr><td>code</td><td>String</td><td>响应编码<br>具体参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/xiang-ying-zhuang-tai-ma">响应状态码</a></td></tr><tr><td>msg</td><td>String</td><td>响应信息</td></tr><tr><td>data</td><td>Object</td><td>响应数据</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>url</td><td>String</td><td>收银台地址</td></tr></tbody></table>

#### 响应示例

{% code fullWidth="true" %}

```json
{
	"code": "200",
	"msg": "success ",
	"data": {
		"merCode": "8302709349110631",
		"merOrderNo": "2025072511440655494299413",
		"url": "https://h5.supefina.tech/ARG/debin?token=dct91npht95bu11khnk4ehl4br"
	}
}
```

{% endcode %}

### 回调通知

提交方式：`POST`

<table data-full-width="true"><thead><tr><th width="235">变量名</th><th width="96">类型</th><th width="517">描述</th></tr></thead><tbody><tr><td>amount</td><td>String</td><td>订单金额</td></tr><tr><td>countryId</td><td>String</td><td>国家编号</td></tr><tr><td>customerName</td><td>String</td><td>用户姓名</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>商户编号</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>sign</td><td>String</td><td>签名</td></tr><tr><td>status</td><td>String</td><td>交易状态<br>具体参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#kxzkj">字典表——交易订单状态</a></td></tr><tr><td>successTime</td><td>Date</td><td>交易成功时间</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><tr><td>payerIdNumber</td><td>String</td><td>付款方证件号</td></tr><tr><td>payerIdType</td><td>String</td><td>付款方证件类型</td></tr><tr><td>payerName</td><td>String</td><td>付款方名称</td></tr><tr><td>payerAccountNo</td><td>String</td><td>付款方账号</td></tr><tr><td>payerAccountType</td><td>String</td><td>付款方账号类型</td></tr></tbody></table>

#### 回调通知示例

{% code fullWidth="true" %}

```json
{
	"amount": "100.00",
	"countryId": "ARG",
	"customerName": "test name",
	"fee": "2.00",
	"identifier": "deb492fe-b70e-43",
	"merId": "8302709349110631",
	"merOrderId": "2025072511440655494299413",
	"msg": "SUCCESS",
	"nonceStr": "cdabc3da-92ac-4cec-979e-cdc557",
	"payerIdNumber": "11111111-1",
	"payerName": "test",
	"realityAmount": "100",
	"realityFee": "2.00",
	"sign": "6D151F1544DBF21E00BA4E8AC59B4AEC",// 大写
	"status": "01",
	"successTime": 1753415066000,
	"supefinaOrderId": "20250725034420972000038112",
	"transactionType": "01"
}
```

{% endcode %}

签名组装字符串

amount=100.00\&countryId=ARG\&customerName=test name\&fee=2.00\&identifier=deb492fe-b70e-43\&merId=8302709349110631\&merOrderId=2025072511440655494299413\&msg=SUCCESS\&nonceStr=cdabc3da-92ac-4cec-979e-cdc557\&payerIdNumber=11111111-1\&payerName=test\&realityAmount=100\&realityFee=2.00\&status=01\&successTime=1753415066000\&supefinaOrderId=20250725034420972000038112\&transactionType=01\&key=e200749bb5914603ad05a03d9b1b6445

**回调通知响应**

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

{% code fullWidth="true" %}

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

{% endcode %}


# 代付

我们为您提供API，以当地货币将资金直接存入合作伙伴的银行账户。

<figure><img src="https://3631787624-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FuukVORWjXBgcGu8MirPR%2Fuploads%2F9NEc73QbBBaIszN6JQsd%2F%E5%88%B0%E8%B4%A6%E6%97%B6%E9%97%B4.jpg?alt=media&amp;token=8af7a847-18e6-4ba7-ac8a-9bd158d5f345" alt=""><figcaption></figcaption></figure>


# 墨西哥

墨西哥银行转账（SPEI）是可以7\*24全天进行的，实时到账。可以支持目的账户为Clabe帐号（18位）和银行卡（16位）的代付。

{% content-ref url="/pages/aeCgQSkcT9TKaoPqLNdp" %}
[SPEI](/huan-ying-shi-yong-supefina-de-api-wen-dang/dai-fu/mo-xi-ge/spei)
{% endcontent-ref %}

{% content-ref url="/pages/6bEC7e9UNwQDj3VHuV8N" %}
[代付失败原因说明](/huan-ying-shi-yong-supefina-de-api-wen-dang/dai-fu/mo-xi-ge/dai-fu-shi-bai-yuan-yin-shuo-ming)
{% endcontent-ref %}

{% content-ref url="/pages/NR9wlSf310rnO8lMDGDv" %}
[Broken mention](broken://pages/NR9wlSf310rnO8lMDGDv)
{% endcontent-ref %}


# SPEI

### 请求地址

<table data-full-width="true"><thead><tr><th width="114">环境名称</th><th width="619">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/payout</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/payout</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="198">变量名</th><th width="100">类型</th><th width="93">必填</th><th width="487">描述</th></tr></thead><tbody><tr><td>account</td><td>String</td><td>是</td><td><p>收款方账户号</p><p>CLABE号是18位</p><p>银行卡号大多数是16位</p></td></tr><tr><td>bankId</td><td>String</td><td>是</td><td><p>收款人银行编号</p><p>具体参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/xia-zai#mo-xi-ge-yin-hang-bian-ma">下载＞墨西哥银行列表</a></p></td></tr><tr><td>callbackUrl</td><td>String</td><td>是</td><td><p>回调地址</p><p>详见<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/tong-zhi-hui-tiao-shuo-ming">通知回调说明</a></p></td></tr><tr><td>countryId</td><td>String</td><td>是</td><td>国家编号<br>参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#afwzp">字典表-国家编号</a><br>墨西哥：<code>MEX</code></td></tr><tr><td>currency</td><td>String</td><td>是</td><td>币种<br>参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#huo-bi-currency">字典表-货币</a><br>墨西哥比索：<code>MXN</code></td></tr><tr><td>customerName</td><td>String</td><td>是</td><td><p>收款人姓名</p><p>名字长度不能超过40个字符，首尾不得包含空格，但姓名之间可以有空格</p></td></tr><tr><td>description</td><td>String</td><td>是</td><td>订单描述<br>长度不能超过200个字符，不能包含特殊符号</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>orderAmount</td><td>String</td><td>是</td><td>订单金额</td></tr><tr><td>payProduct</td><td>String</td><td>是</td><td><p><a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#mfocd">支付类型</a><br>Clabe号：<code>15</code></p><p>银行卡号：<code>16</code></p><p>当收款方账户号属于CLABE的时候，示例为<code>15</code></p><p>当bankId是90646-STP、90706-ARCUS FI、90684-TRANSFER、90659-ASP INTEGRA OPC时，payProduct只支持<code>15</code></p><p></p></td></tr><tr><td>sign</td><td>String</td><td>是</td><td>签名<br><a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/qian-ming-suan-fa">具体参照：签名算法</a></td></tr></tbody></table>

#### 请求示例<br>

{% code fullWidth="true" %}

```json
{
	"account": "646150996402711110",
	"bankId": "40138",
	"callbackUrl": "https://test.com",
	"countryId": "MEX",
	"currency": "MXN",
	"customerName": "Test Name",
	"description": "1",
	"merId": "8302921196770572",
	"merOrderNo": "2025072420155193221792292",
	"nonceStr": "80932b4fe9e74164ba533d7384986986",
	"orderAmount": "100.00",
	"payProduct": "15",
	"sign": "2245B9ED46F8BC88E691D9D8AF8FB598"// 大写
}
```

{% endcode %}

签名组装字符串

account=646150996402711110\&bankId=40138\&callbackUrl=<https://test.com\\&countryId=MEX\\&currency=MXN\\&customerName=Test> Name\&description=1\&merId=8302921196770572\&merOrderNo=2025072420155193221792292\&nonceStr=80932b4fe9e74164ba533d7384986986\&orderAmount=100.00\&payProduct=15\&key=cf5fe06851e84cd7ab227dbbf16f4bf1

&#x20;

&#x20;

&#x20;

### 响应参数

<table data-full-width="true"><thead><tr><th width="198">变量名</th><th width="133">类型</th><th width="470">描述</th></tr></thead><tbody><tr><td>code</td><td>String</td><td>响应编码<br>具体参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/xiang-ying-zhuang-tai-ma">响应状态码</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>fee</td><td>BigDecimal</td><td>预收手续费</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>supefinaOrderNo</td><td>String</td><td>supefina订单号</td></tr><tr><td>transactionStatus</td><td>String</td><td>下单状态<br>该笔订单的的发起状态是否成功，与订单真正的交易状态无关。<br><code>00</code>：下单成功<br><code>04</code>：下单失败</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": "2025072420155193221792292",
		"supefinaOrderNo": "2025072403020005f7bbf5509a843",
		"amount": 100.0,
		"fee": 1.0,
		"transactionStatus": "00"
	}
}
```

{% endcode %}

### 回调通知

<mark style="color:red;">**注意：**</mark>SPEI代付存在两次回调的情况：代付订单收到成功回调事件后，仍然可能接收到代付状态改变的回调事件，交易状态由成功变为失败。

原因是：付款银行会进行两次账户检查：首次通过后，渠道回调成功并将款项交给发卡行，发卡行进行第二次校验。如果收款账户错误、过期或被锁定，发卡行将不付款并回调**失败**。

针对这种先成功后失败的情况，建议商户以最后一次收到的回调状态为准。

由于银行处理时间的不确定性，Supefina系统无法预测是否会有第二次回调及具体时间。历史数据显示，两次回调间隔通常为20秒至数小时，个别订单可能超过2天。

**提交方式：**`POST`

<table data-full-width="true"><thead><tr><th width="198">变量名</th><th width="142">类型</th><th width="470">描述</th></tr></thead><tbody><tr><td>amount</td><td>String</td><td>订单金额</td></tr><tr><td>countryId</td><td>String</td><td>国家编号<br>参照：字典表-国家编号<br>墨西哥：MEX</td></tr><tr><td>customerName</td><td>String</td><td>收款人姓名</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>交易状态<br>具体参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#kxzkj">字典表——交易订单状态</a></td></tr><tr><td>successTime</td><td>String</td><td>交易成功时间</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": "100.00",
	"countryId": "MEX",
	"customerName": "Test Name",
	"fee": "1.00",
	"identifier": "717640140822529316",
	"merId": "8302921196770572",
	"merOrderId": "2025072420155193221792292",
	"msg": "交易成功",
	"nonceStr": "366a0040-5776-43fc-ae2c-220723",
	"realityAmount": "100.00",
	"realityFee": "1.00",
	"reference": "PTJ19GS5HJZL36LWZX1Z9K1U7OQ0US1",
	"sign": "187617174CFC0A50E26CD03B884FAE69",// 大写
	"status": "01",
	"successTime": 1753359354692,
	"supefinaOrderId": "2025072403020005f7bbf5509a843",
	"transactionType": "02"
}
```

{% endcode %}

签名组装字符串

account=646150996402711110\&bankId=40138\&callbackUrl=<https://test.com\\&countryId=MEX\\&currency=MXN\\&customerName=Test> Name\&description=1\&merId=8302921196770572\&merOrderNo=2025072420155193221792292\&nonceStr=80932b4fe9e74164ba533d7384986986\&orderAmount=100.00\&payProduct=15\&key=de53650e1a6b494087d8c472516cc1cb

**回调通知响应**

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

{% code fullWidth="true" %}

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

{% endcode %}

### 墨西哥代付银行列表

<table><thead><tr><th width="109">bankId</th><th width="330">bankName</th></tr></thead><tbody><tr><td>40138</td><td>ABC CAPITAL</td></tr><tr><td>40133</td><td>ACTINVER</td></tr><tr><td>40062</td><td>AFIRME</td></tr><tr><td>90661</td><td>Klar</td></tr><tr><td>90706</td><td>ARCUS FI</td></tr><tr><td>90659</td><td>ASP INTEGRA OPC</td></tr><tr><td>40128</td><td>AUTOFIN</td></tr><tr><td>40127</td><td>AZTECA</td></tr><tr><td>37166</td><td>BaBien</td></tr><tr><td>40030</td><td>BAJIO</td></tr><tr><td>40002</td><td>BANAMEX</td></tr><tr><td>40154</td><td>BANCO COVALTO</td></tr><tr><td>37006</td><td>BANCOMEXT</td></tr><tr><td>40137</td><td>BANCOPPEL</td></tr><tr><td>40160</td><td>BANCO S3</td></tr><tr><td>40152</td><td>BANCREA</td></tr><tr><td>37019</td><td>BANJERCITO</td></tr><tr><td>40147</td><td>BANKAOOL</td></tr><tr><td>40106</td><td>BANK OF AMERICA</td></tr><tr><td>40159</td><td>BANK OF CHINA</td></tr><tr><td>37009</td><td>BANOBRAS</td></tr><tr><td>40072</td><td>BANORTE</td></tr><tr><td>40058</td><td>BANREGIO</td></tr><tr><td>40060</td><td>BANSI</td></tr><tr><td>40129</td><td>BARCLAYS</td></tr><tr><td>40145</td><td>BBASE</td></tr><tr><td>40012</td><td>BBVA MEXICO</td></tr><tr><td>40112</td><td>BMONEX</td></tr><tr><td>90677</td><td>CAJA POP MEXICA</td></tr><tr><td>90683</td><td>CAJA TELEFONIST</td></tr><tr><td>90630</td><td>CB INTERCAM</td></tr><tr><td>90631</td><td>CI BOLSA</td></tr><tr><td>90901</td><td>CLS</td></tr><tr><td>40130</td><td>COMPARTAMOS</td></tr><tr><td>40140</td><td>CONSUBANCO</td></tr><tr><td>90652</td><td>CREDICAPITAL</td></tr><tr><td>90688</td><td>CREDICLUB</td></tr><tr><td>90680</td><td>CRISTOBAL COLON</td></tr><tr><td>90723</td><td>Cuenca</td></tr><tr><td>40151</td><td>DONDE</td></tr><tr><td>90616</td><td>FINAMEX</td></tr><tr><td>90634</td><td>FINCOMUN</td></tr><tr><td>90685</td><td>FONDO (FIRA)</td></tr><tr><td>90601</td><td>GBM</td></tr><tr><td>37168</td><td>HIPOTECARIA FED</td></tr><tr><td>40021</td><td>HSBC</td></tr><tr><td>40155</td><td>ICBC</td></tr><tr><td>40036</td><td>INBURSA</td></tr><tr><td>90902</td><td>INDEVAL</td></tr><tr><td>40150</td><td>INMOBILIARIO</td></tr><tr><td>40136</td><td>INTERCAM BANCO</td></tr><tr><td>40059</td><td>INVEX</td></tr><tr><td>40110</td><td>JP MORGAN</td></tr><tr><td>90653</td><td>KUSPIT</td></tr><tr><td>90670</td><td>LIBERTAD</td></tr><tr><td>90602</td><td>MASARI</td></tr><tr><td>90722</td><td>Mercado Pago W</td></tr><tr><td>40042</td><td>MIFEL</td></tr><tr><td>40158</td><td>MIZUHO BANK</td></tr><tr><td>90600</td><td>MONEXCB</td></tr><tr><td>40108</td><td>MUFG</td></tr><tr><td>40132</td><td>MULTIVA BANCO</td></tr><tr><td>37135</td><td>NAFIN</td></tr><tr><td>90638</td><td>NU MEXICO</td></tr><tr><td>90710</td><td>NVIO</td></tr><tr><td>40148</td><td>PAGATODO</td></tr><tr><td>90620</td><td>PROFUTURO</td></tr><tr><td>40156</td><td>SABADELL</td></tr><tr><td>40014</td><td>SANTANDER</td></tr><tr><td>40044</td><td>SCOTIABANK</td></tr><tr><td>40157</td><td>SHINHAN</td></tr><tr><td>90646</td><td>STP</td></tr><tr><td>90703</td><td>TESORED</td></tr><tr><td>90684</td><td>TRANSFER</td></tr><tr><td>90656</td><td>UNAGRA</td></tr><tr><td>90617</td><td>VALMEX</td></tr><tr><td>90605</td><td>VALUE</td></tr><tr><td>90608</td><td>VECTOR</td></tr><tr><td>40113</td><td>VE POR MAS</td></tr><tr><td>40141</td><td>VOLKSWAGEN</td></tr><tr><td>40124</td><td>CITI MEXICO</td></tr><tr><td>90699</td><td>FONDEADORA</td></tr><tr><td>90732</td><td>PEIBO</td></tr><tr><td>90728</td><td>SPIN BY OXXO</td></tr><tr><td>2001</td><td>BANXICO</td></tr><tr><td>90903</td><td>CoDi Valida</td></tr><tr><td>90734</td><td>FINCO PAY</td></tr><tr><td>40167</td><td>HEY BANCO</td></tr><tr><td>90721</td><td>ALBO</td></tr><tr><td>90729</td><td>Dep y Pag Dig</td></tr></tbody></table>


# 代付失败原因说明

#### 注意：

<sub>代付请求超时仅代表未能在预定时间内获得响应，这并不意味着业务失败。遇到超时情况时，商户应采取以下标准流程：</sub>\ <sub>首先将相关订单标记为挂起状态，随后等待至少2分钟后通过查询接口检索订单状态。切勿在超时后立即尝试重新提交请求，这可能导致重复交易。</sub>\ <sub>因未遵循上述规定流程而造成的任何资金损失，将由责任方全权承担，我司概不负责。</sub>

| Msg                                                                                      | 释义                                                                                                                                     | 建议处理办法                                                                                                                                                                                  |
| ---------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Destination account doesn't exist                                                        | 目标账户不存在                                                                                                                                | 请检查收款账户是否真实有效，或更换其他收款账号                                                                                                                                                                 |
| Exceeding the authorized balance limit for destination accounts                          | 超出目标账户授权余额限额                                                                                                                           | 超过收款账户限额，请更换其他收款账号                                                                                                                                                                      |
| Transaction failed, please try again later                                               | 交易失败，请稍后重试                                                                                                                             | 请联系运营核实具体失败原因                                                                                                                                                                           |
| Exceeding the maximum amount of credit allowed for the destination account for the month | 超出目标账户当月允许的最大信用额度                                                                                                                      | 超过收款账户限额，请更换其他收款账号                                                                                                                                                                      |
| accountNo doesn't match financial institutions                                           | 【收款账户 account】与【bankld】不匹配                                                                                                             | 请与用户核实信息是否准确                                                                                                                                                                            |
| Missing mandatory information to complete the payment                                    | <p>缺少完成付款的必要信息。用户收款银行需要特定的信息来确认订单，例如完整的 CLABE、RFC、姓名和姓氏；但由于每个银行和机构都有自己的业务规则，并且不会共享这些信息，因此需要用户咨询银行缺少哪些信息，并提供完整的信息以避免出现此类问题。<br><br></p> | <p><br>建议用户联系银行确认缺少的信息，或更换其他收款账号<br></p>                                                                                                                                                |
| The pay out was successful but the bank refunded                                         | 付款已成功但被银行退回                                                                                                                            | 请联系运营核实具体失败原因                                                                                                                                                                           |
| Destination account is canceled                                                          | 目标账户已注销                                                                                                                                | 收款账户已被注销，请更换其他收款账号                                                                                                                                                                      |
| Incorrect operation type                                                                 | 操作类型错误                                                                                                                                 | 用户收款行处理订单出现错误导致，需用户联系收款银行，或更换其他收款账号                                                                                                                                                     |
| Cuenta inexistente                                                                       | 账户不存在                                                                                                                                  | 请检查收款账户号码是否正确，或更换其他收款账户进行收款                                                                                                                                                             |
| Account doesn't belong to the destination participant                                    | 收款账号不属于收款银行                                                                                                                            | 请确认收款银行是否与收款账号对应，或更换其他收款账号                                                                                                                                                              |
| Destination account is blocked                                                           | 收款账户被冻结                                                                                                                                | 请更换其他收款账号                                                                                                                                                                               |
| Excede el límite de saldo autorizado de la cuenta                                        | 超出账户授权余额限额                                                                                                                             | 超过收款账户限额，请更换收款账号                                                                                                                                                                        |
| Cuenta no pertenece al Participante Receptor                                             | 【收款账户 account】与【bankld】不匹配                                                                                                             | 请与用户核实信息是否准确                                                                                                                                                                            |
| Cuenta cancelada                                                                         | 收款账户已注销                                                                                                                                | 请更换其他收款账户                                                                                                                                                                               |
| Excede el límite de abonos permitidos en el mes en la cuenta                             | 超过收款账户限额                                                                                                                               | 请更换收款账号                                                                                                                                                                                 |
| Incorrect account type                                                                   | 【 payProduct 支付类型】错误                                                                                                                   | 请检查支付类型是否正确，或更换其他收款账户                                                                                                                                                                   |
| Tipo de cuenta no corresponde                                                            | 收款账号与账户类型不符                                                                                                                            | 请检查账户类型是否正确，或更换其他收款账户                                                                                                                                                                   |
| Cuenta bloqueada                                                                         | 账户已冻结                                                                                                                                  | 收款账户已被冻结，请更换其他收款账户                                                                                                                                                                      |
| Destination Account is not available                                                     | 目标账户不可用                                                                                                                                | 收款账户不可用，请更换其他收款账户                                                                                                                                                                       |
| Incorrect payment type                                                                   | 【 payProduct 支付类型】错误                                                                                                                   | 请检查支付类型是否正确，或更换其他收款账户                                                                                                                                                                   |
| Cuenta adicional no recibe pagos que no proceden de Banxico                              | 附属账户仅限接收墨西哥央行(Banxico)系统付款                                                                                                             | 收款账户仅接收银行付款，请更换其他收款账户                                                                                                                                                                   |
| Account's montly credit transactions exceeded                                            | 超出账户当月贷记交易限额                                                                                                                           | 超过收款账户限额，请更换收款账号                                                                                                                                                                        |
| param error the length of the account should be 16 characters                            | 收款账户长度应为 16 个字符。                                                                                                                       | <p>当【payProduct 支付类型】传<code>16</code>，则【收款账户 account】只能是16位的银行卡<br>当【payProduct 支付类型】传<br><code>15</code>，则【收款账户 account】只能是18位纯数字的CLABE<br>请检查【account 收款方账户号】是否真实正确，或更换其他收款账号<br></p> |
| Falta información mandatoria para completar el pago                                      | 缺少完成付款的必要信息                                                                                                                            | 收款银行需要特定的数据来批准收款操作，需要收款用户向银行提供所需的数据                                                                                                                                                     |
| pthId:09;io:02;code:40008;msg:**accountNo or accountName is invalid**                    | 帐户号码或帐户名称无效                                                                                                                            | 请检查【account 收款方账户号】是否真实正确，或更换其他收款账号                                                                                                                                                     |


# 哥伦比亚

哥伦比亚的代付分为两种，一种是基于ACH的银行转账（Transfer），目的账户为银行账户，但无法实时到账，需要根据ACH的处理周期来分阶段处理，一般工作日期间1-3小时到账，非工作日部分银行无法进行处理，需等到工作日才能代付成功。

另一种是Bre-B，可以7\*24全天进行代付，实时到账。目的账户为用户的手机号或身份证号、电子邮件地址和其他自定义字符串。

{% content-ref url="/pages/1dkOzxAZNjC49nAh9I4M" %}
[Transfer](/huan-ying-shi-yong-supefina-de-api-wen-dang/dai-fu/ge-lun-bi-ya/transfer)
{% endcontent-ref %}

{% content-ref url="/pages/FjTu50Ncaicg0uiIHoll" %}
[Transfiya](/huan-ying-shi-yong-supefina-de-api-wen-dang/dai-fu/ge-lun-bi-ya/transfiya)
{% endcontent-ref %}

{% content-ref url="/pages/dhDoJSgdpUdcIDP5dOPF" %}
[代付失败原因说明](/huan-ying-shi-yong-supefina-de-api-wen-dang/dai-fu/ge-lun-bi-ya/dai-fu-shi-bai-yuan-yin-shuo-ming)
{% endcontent-ref %}

{% content-ref url="/pages/31UdwVDt9Dqb0N417CDF" %}
[Broken mention](broken://pages/31UdwVDt9Dqb0N417CDF)
{% endcontent-ref %}


# Transfer

（payProduct=12）

### 请求地址

<table data-full-width="true"><thead><tr><th width="114">环境名称</th><th width="619">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/payout</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/payout</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="222">变量名</th><th width="159">类型</th><th width="142">必填</th><th width="528">描述</th></tr></thead><tbody><tr><td>countryId</td><td>String</td><td>是</td><td>国家编号<br>参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#afwzp">字典表-国家编号</a><br>哥伦比亚，<code>COL</code></td></tr><tr><td>orderAmount</td><td>String</td><td>是</td><td>订单金额<br>3,000 &#x3C;= <code>orderAmount</code> &#x3C;= 3,000,000,不支持小数</td></tr><tr><td>payProduct</td><td>String</td><td>是</td><td><a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#mfocd">支付类型</a><br>Transfer：<code>12</code></td></tr><tr><td>merId</td><td>String</td><td>是</td><td>商户ID<br>商户ID获取路径：Supefina商户后台-商户管理-基本信息-商户ID</td></tr><tr><td>currency</td><td>String</td><td>是</td><td>币种<br>参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#huo-bi-currency">字典表-货币</a><br>哥伦比亚比索：<code>COP</code></td></tr><tr><td>merOrderNo</td><td>String</td><td>是</td><td>商户订单号</td></tr><tr><td>customerName</td><td>String</td><td>是</td><td><p>用户名字</p><p>首尾不得包含空格，但姓名之间可以有空格</p></td></tr><tr><td>customerAddress</td><td>String</td><td>是</td><td>用户地址</td></tr><tr><td>customerIdentification</td><td>String</td><td>是</td><td><p>用户证件号</p><p><code>00</code>：身份证（CC/TI）--最多10位<br><code>01</code>：外国人身份证（CE）--6位</p></td></tr><tr><td>sign</td><td>String</td><td>是</td><td>签名<br><a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/qian-ming-suan-fa">具体参照：签名算法</a></td></tr><tr><td>nonceStr</td><td>String</td><td>是</td><td>随机字符串<br>长度不能超过32位</td></tr><tr><td>customerEmail</td><td>String</td><td>是</td><td>用户邮箱</td></tr><tr><td>lastName</td><td>String</td><td>是</td><td>用户姓氏</td></tr><tr><td>customerPhone</td><td>String</td><td>是</td><td><p>用户电话</p><p>不含区号的10位数字</p><ul><li>3005102545</li></ul></td></tr><tr><td>customerIdentificationType</td><td>String</td><td>是</td><td><p>用户证件号类型</p><p><code>00</code>：身份证（CC/TI）<br><code>01</code>：外国人身份证（CE）<br><code>02</code>：税号<br><code>03</code>：护照<br><code>06</code>：其他<br><code>07</code>：公民身份证明<br><code>08</code>：居留许可证</p></td></tr><tr><td>accountType</td><td>Strin</td><td>是</td><td>账户类型<br><code>00</code>：活期账户<br><code>01</code>：储蓄账户</td></tr><tr><td>account</td><td>String</td><td>是</td><td>收款方账户号</td></tr><tr><td>bankId</td><td>String</td><td>是</td><td>银行编码<br>具体参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/xia-zai">哥伦比亚银行列表</a></td></tr><tr><td>bankName</td><td>String</td><td>是</td><td>银行名称<br>具体参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/xia-zai">哥伦比亚银行列表</a></td></tr><tr><td>callbackUrl</td><td>String</td><td>是</td><td><p>回调地址</p><p>详见<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/tong-zhi-hui-tiao-shuo-ming">通知回调说明</a></p></td></tr><tr><td>requestData</td><td>JSONObject</td><td>否</td><td>交易额外参数<br>此字段为json对象，不需要可以不传或者传“null”</td></tr><tr><td>description</td><td>String</td><td>是</td><td><p>描述</p><p>不能带特殊符号,长度不超过200字符</p></td></tr></tbody></table>

#### 请求示例<br>

{% code fullWidth="true" %}

```json
{
	"account": "3011268353",
	"accountType": "01",
	"bankId": "27",
	"bankName": "BANCOLOMBIA",
	"callbackUrl": "https://api.datasvc.link/data-service//api/skip/co/supefina/cb",
	"countryId": "COL",
	"currency": "COP",
	"customerAddress": "Unknown",
	"customerEmail": "carlos.6t146@gmail.com",
	"customerIdentification": "71706984",
	"customerIdentificationType": "00",
	"customerName": "ATTELLITIOS ORTIZ HERNANDEZ",
	"customerPhone": "3011268353",
	"description": "Supefina",
	"lastName": "ATTELLITIOS",
	"merId": "8302490290654651",
	"merOrderNo": "2025072518142194176818118",
	"nonceStr": "4cb84e54647149dab561cbcad8c69a6f",
	"orderAmount": "62876",
	"payProduct": "12",
	"sign": "733162BD369CC464575254D176A8CFC4"// 大写
}
```

{% endcode %}

签名组装字符串

account=3011268353\&accountType=01\&bankId=27\&bankName=BANCOLOMBIA\&callbackUrl=<https://api.datasvc.link/data-service//api/skip/co/supefina/cb\\&countryId=COL\\&currency=COP\\&customerAddress=Unknown\\&customerEmail=carlos.6t146@gmail.com\\&customerIdentification=71706984\\&customerIdentificationType=00\\&customerName=ATTELLITIOS> ORTIZ HERNANDEZ\&customerPhone=3011268353\&description=Supefina\&lastName=ATTELLITIOS\&merId=8302490290654651\&merOrderNo=2025072518142194176818118\&nonceStr=4cb84e54647149dab561cbcad8c69a6f\&orderAmount=62876\&payProduct=12\&key=e8548e70a8ba4a658b0da4ef50600d42

### 响应参数

<table data-full-width="true"><thead><tr><th width="222">变量名</th><th width="159">类型</th><th width="661">描述</th></tr></thead><tbody><tr><td>code</td><td>String</td><td>响应编码<br>具体参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/xiang-ying-zhuang-tai-ma">响应状态码</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>fee</td><td>BigDecimal</td><td>预收手续费</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>supefinaOrderNo</td><td>String</td><td>supefina订单号</td></tr><tr><td>transactionStatus</td><td>String</td><td>下单状态<br>该笔订单的的发起状态是否成功，与订单真正的交易状态无关。<br><code>00</code>：下单成功<br><code>04</code>：下单失败</td></tr><tr><td>msg</td><td>String</td><td>响应信息</td></tr></tbody></table>

#### 响应示例

{% code fullWidth="true" %}

```json
{
	"code": "200",
	"msg": "success ",
	"data": {
		"merCode": "8302490290654651",
		"merOrderNo": "2025072518142194176818118",
		"supefinaOrderNo": "20250725101424005000038026",
		"amount": 62876,
		"transactionStatus": "00"
	}
}
```

{% endcode %}

### 回调通知

提交方式：`POST`

<table data-full-width="true"><thead><tr><th width="222">变量名</th><th width="159">类型</th><th width="638">描述</th></tr></thead><tbody><tr><td>amount</td><td>String</td><td>订单金额</td></tr><tr><td>countryId</td><td>String</td><td>国家编号<br>参照：字典表-国家编号<br>哥伦比亚，COL</td></tr><tr><td>customerName</td><td>String</td><td>收款人姓名</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>sign</td><td>String</td><td>签名</td></tr><tr><td>status</td><td>String</td><td>交易状态<br>具体参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#kxzkj">字典表——交易订单状态</a></td></tr><tr><td>successTime</td><td>String</td><td>交易成功时间</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>

#### 回调通知示例

```json
{
	"amount": "62876.00",
	"countryId": "COL",
	"customerName": "ATTELLITIOS ORTIZ HERNANDEZ",
	"fee": "1886.28",
	"identifier": "",
	"merId": "8302490290654651",
	"merOrderId": "2025072518142194176818118",
	"msg": "SUCCESS",
	"nonceStr": "8bcbb47e-c6c3-48e5-82c1-234d6b",
	"realityAmount": "62876.00",
	"realityFee": "1886.28",
	"reference": "56f6eb3f-7ffb-4b",
	"sign": "2D2CC0ADC2CF347515F7BD7640447735",// 大写
	"status": "01",
	"supefinaOrderId": "20250725101424005000038026",
	"transactionType": "02"
}
```

签名组装字符串

amount=62876.00\&countryId=COL\&customerName=ATTELLITIOS ORTIZ HERNANDEZ\&fee=1886.28\&merId=8302490290654651\&merOrderId=2025072518142194176818118\&msg=SUCCESS\&nonceStr=8bcbb47e-c6c3-48e5-82c1-234d6b\&realityAmount=62876.00\&realityFee=1886.28\&reference=56f6eb3f-7ffb-4b\&status=01\&supefinaOrderId=20250725101424005000038026\&transactionType=02\&key=e8548e70a8ba4a658b0da4ef50600d42

**回调通知响应**

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

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


# Transfiya

（payProduct=08）

### 请求地址

<table data-full-width="true"><thead><tr><th width="114">环境名称</th><th width="619">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/payout</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/payout</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="222">变量名</th><th width="128">类型</th><th width="122">必填</th><th width="542">描述</th></tr></thead><tbody><tr><td>countryId</td><td>String</td><td>是</td><td>国家编号<br>参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#afwzp">字典表-国家编号</a><br>哥伦比亚，<code>COL</code></td></tr><tr><td>orderAmount</td><td>String</td><td>是</td><td>订单金额<br>3,000&#x3C;=  <code>orderAmount</code> &#x3C;= 3,000,000,不支持小数</td></tr><tr><td>payProduct</td><td>String</td><td>是</td><td><a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#mfocd">支付类型</a><br>Transfiya：<code>08</code></td></tr><tr><td>merId</td><td>String</td><td>是</td><td>商户ID<br>商户ID获取路径：Supefina商户后台-商户管理-基本信息-商户ID</td></tr><tr><td>currency</td><td>String</td><td>是</td><td>币种<br>参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#huo-bi-currency">字典表-货币</a><br>哥伦比亚比索：<code>COP</code></td></tr><tr><td>merOrderNo</td><td>String</td><td>是</td><td>商户订单号</td></tr><tr><td>customerName</td><td>String</td><td>是</td><td><p>用户名字</p><p>首尾不得包含空格，但姓名之间可以有空格</p></td></tr><tr><td>customerAddress</td><td>String</td><td>否</td><td>用户地址</td></tr><tr><td>customerIdentification</td><td>String</td><td>是</td><td><p>用户证件号</p><p><code>00</code>：身份证（CC/TI）--最多10位<br><code>01</code>：外国人身份证（CE）--6位</p></td></tr><tr><td>sign</td><td>String</td><td>是</td><td>签名<br><a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/qian-ming-suan-fa">具体参照：签名算法</a></td></tr><tr><td>nonceStr</td><td>String</td><td>是</td><td>随机字符串<br>长度不能超过32位</td></tr><tr><td>customerEmail</td><td>String</td><td>否</td><td>用户邮箱</td></tr><tr><td>lastName</td><td>String</td><td>否</td><td>用户姓氏</td></tr><tr><td>customerPhone</td><td>String</td><td>否</td><td>用户电话</td></tr><tr><td>customerIdentificationType</td><td>String</td><td>是</td><td><p>用户证件号类型</p><p><code>00</code>：身份证（CC/TI）<br><code>01</code>：外国人身份证（CE）<br><code>02</code>：税号<br><code>03</code>：护照<br><code>06</code>：其他<br><code>07</code>：公民身份证明<br><code>08</code>：居留许可证</p></td></tr><tr><td>accountType</td><td>String</td><td>是</td><td>账户类型<br><code>05</code>：PHONE</td></tr><tr><td>account</td><td>String</td><td>是</td><td>收款方账户号。<br>代付发起后，用户需在12小时内前往目的地APP进行确认，否则资金将会原路退回并回调交易失败。</td></tr><tr><td>bankName</td><td>String</td><td>是</td><td>银行名称<br>具体参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/xia-zai#ge-lun-bi-ya-yin-hang-lie-biao">哥伦比亚银行列表</a><br></td></tr><tr><td>callbackUrl</td><td>String</td><td>是</td><td><p>回调地址</p><p>详见<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/tong-zhi-hui-tiao-shuo-ming">通知回调说明</a></p></td></tr><tr><td>requestData</td><td>JSONObject</td><td>否</td><td>交易额外参数<br>此字段为json对象，不需要可以不传或者传“null”</td></tr></tbody></table>

#### 请求示例<br>

{% code fullWidth="true" %}

```json
{
	"account": "3234517213",
	"accountType": "05",
	"bankName": "NEQUI",
	"callbackUrl": "https://www.3spicy.bet/api/pay_notice/out_payback/payId/5739B8C9398C4B5494A355B16D0F154C",
	"countryId": "COL",
	"currency": "COP",
	"customerAddress": "EZzpXldfRI",
	"customerEmail": "sebbyhola1@gmail.com",
	"customerIdentification": "45550444",
	"customerIdentificationType": "00",
	"customerName": "soraya",
	"customerPhone": "3234517213",
	"lastName": "cc",
	"merId": "8302490290654651",
	"merOrderNo": "2025072518394772565086215",
	"nonceStr": "d277d76219314c13ad6566b626aadd9d",
	"orderAmount": "190000",
	"payProduct": "08",
	"sign": "15BFDC4D172274EA8808B16FB8D62EB7"// 大写
}
```

{% endcode %}

签名组装字符串

account=3234517213\&accountType=05\&bankName=NEQUI\&callbackUrl=<https://www.3spicy.bet/api/pay\\_notice/out\\_payback/payId/5739B8C9398C4B5494A355B16D0F154C\\&countryId=COL\\&currency=COP\\&customerAddress=EZzpXldfRI\\&customerEmail=sebbyhola1@gmail.com\\&customerIdentification=45550444\\&customerIdentificationType=00\\&customerName=soraya\\&customerPhone=3234517213\\&lastName=cc\\&merId=8302490290654651\\&merOrderNo=2025072518394772565086215\\&nonceStr=d277d76219314c13ad6566b626aadd9d\\&orderAmount=190000\\&payProduct=08\\&key=e8548e70a8ba4a658b0da4ef50600d42>

### 响应参数

<table data-full-width="true"><thead><tr><th width="222">变量名</th><th width="159">类型</th><th width="423">描述</th></tr></thead><tbody><tr><td>code</td><td>String</td><td>响应编码<br>具体参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/xiang-ying-zhuang-tai-ma">响应状态码</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>fee</td><td>BigDecimal</td><td>预收手续费</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>supefinaOrderNo</td><td>String</td><td>supefina订单号</td></tr><tr><td>transactionStatus</td><td>String</td><td>下单状态<br>该笔订单的的发起状态是否成功，与订单真正的交易状态无关。<br><code>00</code>：下单成功<br><code>04</code>：下单失败</td></tr><tr><td>msg</td><td>String</td><td>响应信息</td></tr></tbody></table>

#### 响应示例

{% code fullWidth="true" %}

```json
{
	"code": "200",
	"msg": "success ",
	"data": {
		"merCode": "8302490290654651",
		"merOrderNo": "2025072518394772565086215",
		"supefinaOrderNo": "20250725103949372000038503",
		"amount": 190000,
		"transactionStatus": "00"
	}
}
```

{% endcode %}

### 回调通知

提交方式：`POST`

<table data-full-width="true"><thead><tr><th width="207">变量名</th><th width="159">类型</th><th width="655">描述</th></tr></thead><tbody><tr><td>amount</td><td>String</td><td>订单金额</td></tr><tr><td>countryId</td><td>String</td><td>国家编号<br>参照：字典表-国家编号<br>哥伦比亚，COL</td></tr><tr><td>customerName</td><td>String</td><td>收款人姓名</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>sign</td><td>String</td><td>签名</td></tr><tr><td>status</td><td>String</td><td>交易状态<br>具体参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#kxzkj">字典表——交易订单状态</a></td></tr><tr><td>successTime</td><td>String</td><td>交易成功时间</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": "190000.00",
	"countryId": "COL",
	"customerName": "soraya",
	"fee": "5.00",
	"identifier": "",
	"merId": "8302490290654651",
	"merOrderId": "2025072518394772565086215",
	"msg": "SUCCESS",
	"nonceStr": "bc41d5f8-e628-45c1-862f-2451c9",
	"realityAmount": "190000.00",
	"realityFee": "5.00",
	"reference": "0f211169-f266-4d",
	"sign": "17829110C3136000A18BEAAA0621F511",// 大写
	"status": "01",
	"supefinaOrderId": "20250725103949372000038503",
	"transactionType": "02"
}
```

{% endcode %}

签名组装字符串

amount=190000.00\&countryId=COL\&customerName=soraya\&fee=5.00\&merId=8302490290654651\&merOrderId=2025072518394772565086215\&msg=SUCCESS\&nonceStr=bc41d5f8-e628-45c1-862f-2451c9\&realityAmount=190000.00\&realityFee=5.00\&reference=0f211169-f266-4d\&status=01\&supefinaOrderId=20250725103949372000038503\&transactionType=02\&key=e8548e70a8ba4a658b0da4ef50600d42

**回调通知响应**

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

{% code fullWidth="true" %}

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

{% endcode %}


# Bre-B

（payProduct=31）

### 请求地址

<table data-full-width="true"><thead><tr><th width="114">环境名称</th><th width="619">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/payout</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/payout</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="222">变量名</th><th width="128">类型</th><th width="122">必填</th><th width="542">描述</th></tr></thead><tbody><tr><td>countryId</td><td>String</td><td>是</td><td>国家编号<br>参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#afwzp">字典表-国家编号</a><br>哥伦比亚，<code>COL</code></td></tr><tr><td>orderAmount</td><td>String</td><td>是</td><td>订单金额<br>3,000&#x3C;=  <code>orderAmount</code> &#x3C;= 3,000,000,不支持小数</td></tr><tr><td>payProduct</td><td>String</td><td>是</td><td><a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#mfocd">支付类型</a><br>Bre-B：<code>31</code></td></tr><tr><td>merId</td><td>String</td><td>是</td><td>商户ID<br>商户ID获取路径：Supefina商户后台-商户管理-基本信息-商户ID</td></tr><tr><td>currency</td><td>String</td><td>是</td><td>币种<br>参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#huo-bi-currency">字典表-货币</a><br>哥伦比亚比索：<code>COP</code></td></tr><tr><td>merOrderNo</td><td>String</td><td>是</td><td>商户订单号</td></tr><tr><td>customerName</td><td>String</td><td>是</td><td><p>用户名字</p><p>首尾不得包含空格，但姓名之间可以有空格</p></td></tr><tr><td>customerAddress</td><td>String</td><td>否</td><td>用户地址</td></tr><tr><td>customerIdentification</td><td>String</td><td>是</td><td><p>用户证件号</p><p><code>00</code>：身份证（CC/TI）--最多10位<br><code>01</code>：外国人身份证（CE）--6位</p></td></tr><tr><td>sign</td><td>String</td><td>是</td><td>签名<br><a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/qian-ming-suan-fa">具体参照：签名算法</a></td></tr><tr><td>nonceStr</td><td>String</td><td>是</td><td>随机字符串<br>长度不能超过32位</td></tr><tr><td>customerEmail</td><td>String</td><td>否</td><td>用户邮箱</td></tr><tr><td>lastName</td><td>String</td><td>否</td><td>用户姓氏</td></tr><tr><td>customerPhone</td><td>String</td><td>否</td><td>用户电话</td></tr><tr><td>customerIdentificationType</td><td>String</td><td>是</td><td><p>用户证件号类型</p><p><code>00</code>：身份证（CC/TI）<br><code>01</code>：外国人身份证（CE）<br><code>02</code>：税号<br><code>03</code>：护照<br><code>06</code>：其他<br><code>07</code>：公民身份证明<br><code>08</code>：居留许可证</p></td></tr><tr><td>accountType</td><td>String</td><td>是</td><td>账户类型<br><code>05</code>：PHONE</td></tr><tr><td>account</td><td>String</td><td>是</td><td>收款方账户号。接受以下三种Bre-B账号，手机号或身份证号（格式为：纯数字），邮箱，还有字母数字标识符（格式为：@后加llave，示例：@TESTABC123）。</td></tr><tr><td>bankName</td><td>String</td><td>是</td><td>银行名称<br>具体参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/xia-zai#ge-lun-bi-ya-yin-hang-lie-biao">哥伦比亚银行列表</a><br></td></tr><tr><td>callbackUrl</td><td>String</td><td>是</td><td><p>回调地址</p><p>详见<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/tong-zhi-hui-tiao-shuo-ming">通知回调说明</a></p></td></tr><tr><td>requestData</td><td>JSONObject</td><td>否</td><td>交易额外参数<br>此字段为json对象，不需要可以不传或者传“null”</td></tr></tbody></table>

#### 请求示例<br>

{% code fullWidth="true" %}

```json
{
	"account": "3234517213",
	"accountType": "05",
	"bankName": "NEQUI",
	"callbackUrl": "https://www.3spicy.bet/api/pay_notice/out_payback/payId/5739B8C9398C4B5494A355B16D0F154C",
	"countryId": "COL",
	"currency": "COP",
	"customerAddress": "EZzpXldfRI",
	"customerEmail": "sebbyhola1@gmail.com",
	"customerIdentification": "45550444",
	"customerIdentificationType": "00",
	"customerName": "soraya",
	"customerPhone": "3234517213",
	"lastName": "cc",
	"merId": "8302490290654651",
	"merOrderNo": "2025072518394772565086215",
	"nonceStr": "d277d76219314c13ad6566b626aadd9d",
	"orderAmount": "190000",
	"payProduct": "31",
	"sign": "15BFDC4D172274EA8808B16FB8D62EB7"// 大写
}
```

{% endcode %}

签名组装字符串

account=3234517213\&accountType=05\&bankName=NEQUI\&callbackUrl=<https://www.3spicy.bet/api/pay\\_notice/out\\_payback/payId/5739B8C9398C4B5494A355B16D0F154C\\&countryId=COL\\&currency=COP\\&customerAddress=EZzpXldfRI\\&customerEmail=sebbyhola1@gmail.com\\&customerIdentification=45550444\\&customerIdentificationType=00\\&customerName=soraya\\&customerPhone=3234517213\\&lastName=cc\\&merId=8302490290654651\\&merOrderNo=2025072518394772565086215\\&nonceStr=d277d76219314c13ad6566b626aadd9d\\&orderAmount=190000\\&payProduct=08\\&key=e8548e70a8ba4a658b0da4ef50600d42>

### 响应参数

<table data-full-width="true"><thead><tr><th width="222">变量名</th><th width="159">类型</th><th width="423">描述</th></tr></thead><tbody><tr><td>code</td><td>String</td><td>响应编码<br>具体参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/xiang-ying-zhuang-tai-ma">响应状态码</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>fee</td><td>BigDecimal</td><td>预收手续费</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>supefinaOrderNo</td><td>String</td><td>supefina订单号</td></tr><tr><td>transactionStatus</td><td>String</td><td>下单状态<br>该笔订单的的发起状态是否成功，与订单真正的交易状态无关。<br><code>00</code>：下单成功<br><code>04</code>：下单失败</td></tr><tr><td>msg</td><td>String</td><td>响应信息</td></tr></tbody></table>

#### 响应示例

{% code fullWidth="true" %}

```json
{
	"code": "200",
	"msg": "success ",
	"data": {
		"merCode": "8302490290654651",
		"merOrderNo": "2025072518394772565086215",
		"supefinaOrderNo": "20250725103949372000038503",
		"amount": 190000,
		"transactionStatus": "00"
	}
}
```

{% endcode %}

### 回调通知

提交方式：`POST`

<table data-full-width="true"><thead><tr><th width="207">变量名</th><th width="159">类型</th><th width="655">描述</th></tr></thead><tbody><tr><td>amount</td><td>String</td><td>订单金额</td></tr><tr><td>countryId</td><td>String</td><td>国家编号<br>参照：字典表-国家编号<br>哥伦比亚，COL</td></tr><tr><td>customerName</td><td>String</td><td>收款人姓名</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>sign</td><td>String</td><td>签名</td></tr><tr><td>status</td><td>String</td><td>交易状态<br>具体参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#kxzkj">字典表——交易订单状态</a></td></tr><tr><td>successTime</td><td>String</td><td>交易成功时间</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": "190000.00",
	"countryId": "COL",
	"customerName": "soraya",
	"fee": "5.00",
	"identifier": "",
	"merId": "8302490290654651",
	"merOrderId": "2025072518394772565086215",
	"msg": "SUCCESS",
	"nonceStr": "bc41d5f8-e628-45c1-862f-2451c9",
	"realityAmount": "190000.00",
	"realityFee": "5.00",
	"reference": "0f211169-f266-4d",
	"sign": "17829110C3136000A18BEAAA0621F511",// 大写
	"status": "01",
	"supefinaOrderId": "20250725103949372000038503",
	"transactionType": "02"
}
```

{% endcode %}

签名组装字符串

amount=190000.00\&countryId=COL\&customerName=soraya\&fee=5.00\&merId=8302490290654651\&merOrderId=2025072518394772565086215\&msg=SUCCESS\&nonceStr=bc41d5f8-e628-45c1-862f-2451c9\&realityAmount=190000.00\&realityFee=5.00\&reference=0f211169-f266-4d\&status=01\&supefinaOrderId=20250725103949372000038503\&transactionType=02\&key=e8548e70a8ba4a658b0da4ef50600d42

**回调通知响应**

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

{% code fullWidth="true" %}

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

{% endcode %}


# 代付失败原因说明

#### 注意：

<sub>代付请求超时仅代表未能在预定时间内获得响应，这并不意味着业务失败。遇到超时情况时，商户应采取以下标准流程：</sub>\ <sub>首先将相关订单标记为挂起状态，随后等待至少2分钟后通过查询接口检索订单状态。切勿在超时后立即尝试重新提交请求，这可能导致重复交易。</sub>\ <sub>因未遵循上述规定流程而造成的任何资金损失，将由责任方全权承担，我司概不负责。</sub>

<table><thead><tr><th width="582">Msg</th><th width="582">释义</th><th width="582">建议处理办法</th></tr></thead><tbody><tr><td>accountNumber must match /^3[0-9]+$/ regular expression</td><td>收款账号必须以3开头，且10位数字<br>【account 收款方账户号】需满足以下要求：1. 需为 10 位数，且需要以数 3 字开头2. 不需要传区号+57，只要 10 位电话号码就行</td><td>请检查收款账户号码是否正确或更换其他收款账号</td></tr><tr><td>Se excede el plazo de la transferencia</td><td>转账期限已过</td><td>用户未在12小时内在电子钱包APP中确认收款，因此款项退回，交易失败。</td></tr><tr><td>TimeOut de transferencia</td><td>渠道服务响应超时，导致交易被拒绝。</td><td>服务恢复后，建议重试</td></tr><tr><td>Cuenta inactiva.</td><td>账户已停用。</td><td>请更换其他收款账号</td></tr><tr><td>Account and identification provide does not coincide</td><td>收款账户与预留在银行的身份信息不符</td><td>收款账户与预留在银行的身份信息不符，请检查身份信息是否真实有效，或更换其他收款账户</td></tr><tr><td>Se excede el plazo de la transferencia.</td><td>用户未在12小时内在电子钱包APP中确认收款，因此款项退回，交易失败</td><td>可重新发起订单</td></tr><tr><td>Cuenta inactiva.</td><td>账户未激活。</td><td>请更换其他收款账号</td></tr><tr><td>Inactive or blocked account</td><td>账户未激活或已被冻结。</td><td>请更换其他收款账号</td></tr><tr><td>Error inesperado en conexión con el banco.</td><td>银行连接发生意外错误。</td><td>请稍后重试，或更换其他收款账号</td></tr><tr><td>ID not valid</td><td>身份证号无效。</td><td>请检查证件号是否真实有效</td></tr><tr><td>No transaction failure reason</td><td>无交易失败原因。</td><td>请联系运营</td></tr><tr><td>Invalid Account type</td><td>账户类型无效。</td><td>accountType无效，请更换其他账户类型，或更换其他收款账号</td></tr><tr><td>Account does not exist</td><td>账户不存在。</td><td>请检查收款账户号码是否正确或更换其他收款账号</td></tr><tr><td>Cuenta no existe.</td><td>账户不存在。</td><td>请检查收款账户号码是否正确或更换其他收款账号</td></tr><tr><td>Invalid account number</td><td>账号无效。</td><td>请检查收款账户号码是否正确或更换其他收款账号</td></tr><tr><td>Usuario excede límite de transacciones autorizadas por el banco.</td><td>用户超出银行授权的交易限额。</td><td>请更换其他收款账号</td></tr><tr><td>Account not authorized to be credited</td><td>账户未获授权进行入账。</td><td>请更换其他收款账号</td></tr><tr><td>Banco no disponible.</td><td>银行服务不可用。</td><td>请更换其他收款账号</td></tr><tr><td>Información de transferencia invalida.</td><td>转账信息无效。</td><td>请检查收款账号是否真实有效，或更换其他收款账号</td></tr><tr><td>Transferencia marcada como fraude.</td><td>转账被标记为欺诈。</td><td>该笔交易存在欺诈风险</td></tr><tr><td>Account exceeds the maximum allowed transaction limit</td><td>账户超出最大允许交易限额。</td><td>请更换其他收款账号</td></tr><tr><td>Could not process the money movement at this time.</td><td>渠道当前无法处理资金转移。</td><td>请稍后重试</td></tr><tr><td>Payment processing failed please try again</td><td>渠道支付处理失败，请重试。</td><td>请稍后重试</td></tr><tr><td>Banco respondió respuesta inválida.</td><td>银行返回无效响应。</td><td>请稍后重试，或更换其他收款账号</td></tr><tr><td>Cuenta no habilitada.</td><td>账户未启用。</td><td>请更换其他收款账号</td></tr></tbody></table>


# 秘鲁

秘鲁银行转账（Transfer）主要依托于银行进行，由于各个银行的处理时间不同，所以到账时间也有所不同。工作日期间，BCP，BBVA，Interbank，Scotiabak可在0.5-1小时左右到账，而其他的银行需要1-3个小时到账。非工作日期间，只有部分银行可进行代付，其他的银行需要等到下个工作日进行处理。

{% content-ref url="/pages/BH7N6tSCm1PbXslmxx8l" %}
[Transfer](/huan-ying-shi-yong-supefina-de-api-wen-dang/dai-fu/bi-lu/transfer)
{% endcontent-ref %}

{% content-ref url="/pages/Ejj0NaeYXAlQnETeOgwH" %}
[代付失败原因说明](/huan-ying-shi-yong-supefina-de-api-wen-dang/dai-fu/bi-lu/dai-fu-shi-bai-yuan-yin-shuo-ming)
{% endcontent-ref %}

{% content-ref url="/pages/cYCDgnjYrkmGygwpQmVh" %}
[Broken mention](broken://pages/cYCDgnjYrkmGygwpQmVh)
{% endcontent-ref %}


# Transfer

（payProduct=20）

### 请求地址

<table data-full-width="true"><thead><tr><th width="114">环境名称</th><th width="745">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/payout</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/payout</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="213">变量名</th><th width="84">类型</th><th width="71">必填</th><th width="535">描述</th></tr></thead><tbody><tr><td>account</td><td>String</td><td>是</td><td><p>收款方账户号</p><p>1、秘鲁四大银行账户类型及位数：</p><p><code>03</code>--BBVA，活期账户和储蓄账户位数18位或20位；</p><p><code>04</code>--SCOTIABANK，活期账户和储蓄账户位数10位；</p><p><code>02</code>--INTERBANK，活期账户和储蓄账户位数13位；</p><p><code>01</code>--BCP，<code>00</code>（活期账户）位数13位且在第11位为0；<code>01</code>（储蓄账户）位数14位且在第12位为0。</p><p>2、不能带小数点和"-"等特殊符号，只能纯数字。</p><p>3、<mark style="color:red;">示例：1110333711</mark></p></td></tr><tr><td>accountType</td><td>Strin</td><td>是</td><td><p>收款方账户类型<br><code>00</code>：CORRIENTE(活期账户)<br><code>01</code>：AHORROS(储蓄账户)</p><p>示例：<code>00</code></p></td></tr><tr><td>app</td><td>String</td><td>是</td><td>订单app名称</td></tr><tr><td>bankName</td><td>String</td><td>是</td><td><p>银行名称</p><p>示例：<code>01</code>，具体参照：<a href="#cs3po">秘鲁代付银行列表</a></p></td></tr><tr><td>callbackUrl</td><td>String</td><td>是</td><td><p>回调地址</p><p>详见<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/tong-zhi-hui-tiao-shuo-ming">通知回调说明</a></p></td></tr><tr><td>cciNumber</td><td>String</td><td>否</td><td><p>收款人中转账户<br>1、当<code>bankName</code>为非四大行（BCP、Interbank、BBVA、Scotiabank），该字段必传。</p><p>2、<code>cciNumber</code>位数20位。</p><p>3、不能带小数点和"-"等特殊符号，只能纯数字。</p><p>4、<mark style="color:red;">示例：00911120111033371164</mark></p></td></tr><tr><td>countryId</td><td>String</td><td>是</td><td>国家编号<br>参照：字典表-国家编号<br>秘鲁，<code>PER</code></td></tr><tr><td>currency</td><td>String</td><td>是</td><td>币种<br>参照：字典表-货币<br>秘鲁比索：<code>PEN</code></td></tr><tr><td>customerEmail</td><td>String</td><td>是</td><td>收款人邮箱，长度 &#x3C;= 50个字符</td></tr><tr><td>customerIdentification</td><td>String</td><td>是</td><td><p>用户证件号<br><code>00</code>：身份证（DNI），8位<br><code>01</code>：外国人身份证（CE），≥9位<br><code>02</code>：税号（RUC），11位</p><p><code>03</code>：护照（PAS），≥9位</p><p><mark style="color:red;"><strong>注意：</strong></mark>不能带小数点和"-"等特殊符号，只能纯数字。</p><p><mark style="color:red;">示例：42340816</mark></p></td></tr><tr><td>customerIdentificationType</td><td>String</td><td>是</td><td><p>用户证件类型<br><code>00</code>：身份证（DNI）<br><code>01</code>：外国人身份证（CE）<br><code>02</code>：税号（RUC）</p><p><code>03</code>：护照（PAS）</p><p><mark style="color:red;">示例</mark>：<code>00</code></p></td></tr><tr><td>customerName</td><td>String</td><td>是</td><td><p>收款人姓名</p><p>建议都大写，首尾不得包含空格，但姓名之间可以有空格</p></td></tr><tr><td>customerPhone</td><td>String</td><td>是</td><td><p>收款人电话<br>区号（+51、51）+<mark style="color:red;"><strong>9位数字</strong></mark>手机号，区号可传可不传<br><mark style="color:red;">示例：</mark></p><p>+51123456789（含区号+51）<br>51123456789（含区号51）<br>123456789（不包含区号的电话号码）</p></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>orderAmount</td><td>String</td><td>是</td><td><p>订单金额</p><p>传入100，为100 PEN，支持2位小数</p></td></tr><tr><td>payProduct</td><td>String</td><td>是</td><td><a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#mfocd">支付类型</a><br>Transfer：<code>20</code></td></tr><tr><td>sign</td><td>String</td><td>是</td><td>签名<br><a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/qian-ming-suan-fa">具体参照：签名算法</a></td></tr></tbody></table>

#### 请求示例<br>

{% code fullWidth="true" %}

```json
{
	"account": "19299172588073",
	"accountType": "01",
	"app": "supefina",
	"bankName": "01",
	"callbackUrl": "https://test.com",
	"countryId": "PER",
	"currency": "PEN",
	"customerEmail": "test@gmail.com",
	"customerIdentification": "73313761",
	"customerIdentificationType": "00",
	"customerName": "Test Name",
	"customerPhone": "52173996789",
	"merId": "8302258550224656",
	"merOrderNo": "2025072518152505935270779",
	"nonceStr": "35593a53cda549abb68e02534dfae262",
	"orderAmount": "105.00",
	"payProduct": "20",
	"sign": "5A33769EB1ECE3FDA141A8F887C8BBA0"// 大写
}
```

{% endcode %}

签名组装字符串

account=19299172588073\&accountType=01\&app=supefina\&bankName=01\&callbackUrl=<https://test.com\\&countryId=PER\\&currency=PEN\\&customerEmail=test@gmail.com\\&customerIdentification=73313761\\&customerIdentificationType=00\\&customerName=Test> Name\&customerPhone=52173996789\&merId=8302258550224656\&merOrderNo=2025072518152505935270779\&nonceStr=35593a53cda549abb68e02534dfae262\&orderAmount=105.00\&payProduct=20\&key=10c44658d50e4d0da0fe1e5f7c9074a7

### 响应参数

<table data-full-width="true"><thead><tr><th width="203">变量名</th><th width="203">类型</th><th width="632">描述</th></tr></thead><tbody><tr><td>code</td><td>String</td><td>响应编码<br>具体参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/xiang-ying-zhuang-tai-ma">响应状态码</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>fee</td><td>BigDecimal</td><td>预收手续费</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>supefinaOrderNo</td><td>String</td><td>supefina订单号</td></tr><tr><td>transactionStatus</td><td>String</td><td>下单状态<br>该笔订单的的发起状态是否成功，与订单真正的交易状态无关。<br><code>00</code>：下单成功<br><code>04</code>：下单失败</td></tr><tr><td>msg</td><td>String</td><td>响应信息</td></tr></tbody></table>

#### 响应示例

{% code fullWidth="true" %}

```json
{
	"code": "200",
	"msg": "success ",
	"data": {
		"merCode": "8302258550224656",
		"merOrderNo": "2025072518152505935270779",
		"supefinaOrderNo": "202507250102000fe532cb5f9ba44",
		"amount": 105.0,
		"fee": 2.05,
		"transactionStatus": "00"
	}
}
```

{% endcode %}

### 回调通知

提交方式：`POST`

代付存在两次回调通知状态。代付成功收到成功回调事件后，仍然可能接收到代付状态改变的回调事件，代付状态由成功变为失败，这种订单只会出现在秘鲁跨行转账中，执行付款银行会检查账户信息两次，初次通过后渠道就回调成功了，银行第二次检查时，发现账户可能被锁定、账户类型不能转账等，银行不会付款，会一周/一月通知渠道一次。

<table data-full-width="true"><thead><tr><th width="203">变量名</th><th width="203">类型</th><th width="622">描述</th></tr></thead><tbody><tr><td>amount</td><td>String</td><td>订单金额</td></tr><tr><td>countryId</td><td>String</td><td>国家编号<br>参照：字典表-国家编号<br>秘鲁，PER</td></tr><tr><td>customerName</td><td>String</td><td>收款人姓名</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>sign</td><td>String</td><td>签名</td></tr><tr><td>status</td><td>String</td><td>交易状态<br>具体参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#kxzkj">字典表——交易订单状态</a></td></tr><tr><td>successTime</td><td>String</td><td>交易成功时间</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": "105.00",
	"countryId": "PER",
	"customerName": "Test Name",
	"fee": "2.05",
	"identifier": "784379984920623893",
	"merId": "8302258550224656",
	"merOrderId": "2025072518152505935270779",
	"msg": "交易成功",
	"nonceStr": "e459f839-e1fa-4f47-ba72-135d4d",
	"realityAmount": "105.00",
	"realityFee": "2.05",
	"reference": "PTJNPQ9IGNOH9EX2W94HECSK990O5O4",
	"sign": "FEB61E96EFE1799D0393A29419106319",// 大写
	"status": "01",
	"successTime": 1753438534867,
	"supefinaOrderId": "202507250102000fe532cb5f9ba44",
	"transactionType": "02"
}
```

{% endcode %}

签名组装字符串

amount=105.00\&countryId=PER\&customerName=Test Name\&fee=2.05\&identifier=784379984920623893\&merId=8302258550224656\&merOrderId=2025072518152505935270779\&msg=交易成功\&nonceStr=e459f839-e1fa-4f47-ba72-135d4d\&realityAmount=105.00\&realityFee=2.05\&reference=PTJNPQ9IGNOH9EX2W94HECSK990O5O4\&status=01\&successTime=1753438534867\&supefinaOrderId=202507250102000fe532cb5f9ba44\&transactionType=02\&key=10c44658d50e4d0da0fe1e5f7c9074a7

**回调通知响应**

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

{% code fullWidth="true" %}

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

{% endcode %}

## 秘鲁代付银行列表 <a href="#cs3po" id="cs3po"></a>

| 01 | bcp                                       |
| -- | ----------------------------------------- |
| 02 | interbank                                 |
| 03 | bbva                                      |
| 04 | scotiabank                                |
| 05 | Banco de Comercio                         |
| 06 | BanBif (Banco Interamericano de Finanzas) |
| 07 | Banco Pichincha                           |
| 08 | Citibank                                  |
| 09 | Banco GNB                                 |
| 10 | Banco Santander                           |
| 11 | Banco Azteca                              |
| 12 | Banco Cencosud                            |
| 13 | ICBC PERU BANK                            |
| 14 | Banco de la Nación                        |
| 15 | Caja Cusco                                |
| 16 | Caja Huancayo                             |
| 17 | Caja Maynas                               |
| 18 | Caja Metropolitana                        |
| 19 | Caja Municipal Ica                        |
| 20 | Caja Sullana                              |
| 21 | Caja Tacna                                |
| 22 | Caja Trujillo                             |


# 代付失败原因说明

#### 注意：

<sub>代付请求超时仅代表未能在预定时间内获得响应，这并不意味着业务失败。遇到超时情况时，商户应采取以下标准流程：</sub>\ <sub>首先将相关订单标记为挂起状态，随后等待至少2分钟后通过查询接口检索订单状态。切勿在超时后立即尝试重新提交请求，这可能导致重复交易。</sub>\ <sub>因未遵循上述规定流程而造成的任何资金损失，将由责任方全权承担，我司概不负责。</sub>

<table><thead><tr><th width="321">Msg</th><th width="556">释义</th><th width="556">建议处理办法</th></tr></thead><tbody><tr><td>CLIENTE NO ES TITULAR DE LA CUENTA</td><td>用户不是账户持有人，账户和用户的信息不匹配客户身份 (PIN)与银行登记的账户所有者信息不匹配</td><td>检查用户信息是否正确</td></tr><tr><td>INFORMACIÓN INCOMPLETA FALTA CCI</td><td>信息不完整，缺少 Cci</td><td>请提供CCinumber</td></tr><tr><td>CUENTA DE ABONO NO EXISTE</td><td>用户账户不存在银行账户未在银行注册已被账户持有人或金融机构永久关闭</td><td>确认收款账号是否正确或者更换银行卡</td></tr><tr><td>NÚMERO DE CUENTA INCORRECTO</td><td>账号不正确</td><td>请检查收款账号是否正确，或更换其他收款账号</td></tr><tr><td>CLIENTE OBSERVADO NO PUEDE RECIBIR PAGOS</td><td>客户被标记观察 - 无法接收付款</td><td>更换银行卡</td></tr><tr><td>VERIFICAR TIPO Y NÚMERO DE CUENTA</td><td>请核实账户类型及账号</td><td>请核实账户类型及账号是否准确及对应</td></tr><tr><td>DOCUMENTO DE IDENTIDAD INCORRECTO</td><td>用户的证件号不准确</td><td>请联系用户检查</td></tr><tr><td>CUENTA CANCELADA</td><td>收款账号已被注销</td><td>请更换其他收款账号</td></tr><tr><td>Bank Rejection - Beneficiary is not the Account Owner;</td><td>银行拒绝 - 收款人非账户持有人</td><td>请检查用户名是否正确或更换其他收款账号</td></tr><tr><td>Bank Rejection - Account Number does not exist;</td><td>银行拒绝 - 账号不存在</td><td>请检查收款账号是否正确，或更换其他收款账号</td></tr><tr><td>Bank Rejection - Restricted Account Number;</td><td>银行拒绝 - 账号受限，收款账号被限制</td><td>请更换其他收款账号</td></tr><tr><td>Bank Rejection - Incorrect account information;</td><td>银行拒绝 - 账户信息错误</td><td>请检查账户号码、账户类型是否正确，或更换其他收款账号</td></tr></tbody></table>


# 智利

智利银行转账（Transfer）是7\*24全天进行的，可实时到账。

{% content-ref url="/pages/KxeV4AXrdvxS1dtc6osJ" %}
[Transfer](/huan-ying-shi-yong-supefina-de-api-wen-dang/dai-fu/zhi-li/transfer)
{% endcontent-ref %}

{% content-ref url="/pages/bkqNg9kmvQAN3fMg4k9y" %}
[Broken mention](broken://pages/bkqNg9kmvQAN3fMg4k9y)
{% endcontent-ref %}


# Transfer

（payProduct=12）

### 请求地址

<table data-full-width="true"><thead><tr><th width="114">环境名称</th><th width="619">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/payout</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/payout</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="223">变量名</th><th width="140">类型</th><th width="139">必填</th><th width="546">描述</th></tr></thead><tbody><tr><td>countryId</td><td>String</td><td>是</td><td>国家编号<br>参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#afwzp">字典表-国家编号</a><br>智利，<code>CHL</code></td></tr><tr><td>merId</td><td>String</td><td>是</td><td>商户ID<br>商户ID获取路径：Supefina商户后台-商户管理-基本信息-商户ID</td></tr><tr><td>payProduct</td><td>String</td><td>是</td><td><a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#mfocd">支付类型</a><br>Transfer：<code>12</code></td></tr><tr><td>currency</td><td>String</td><td>是</td><td>币种<br>参照：字典表-货币<br>智利比索：<code>CLP</code></td></tr><tr><td>merOrderNo</td><td>String</td><td>是</td><td>商户订单号</td></tr><tr><td>orderAmount</td><td>String</td><td>是</td><td>订单金额<br>单位比索，只支持整数</td></tr><tr><td>customerName</td><td>String</td><td>是</td><td><p>用户名字</p><p>首尾不得包含空格，但姓名之间可以有空格</p></td></tr><tr><td>customerEmail</td><td>String</td><td>是</td><td>用户邮箱，长度 &#x3C;= 50个字符</td></tr><tr><td>customerPhone</td><td>String</td><td>是</td><td>用户电话</td></tr><tr><td>customerIdentification</td><td>String</td><td>是</td><td><p>用户证件号(RUT证件号位数8位或9位)，</p><p>最后一位可以是0-9的数字或字母K，现已支持特殊字符</p><p>示例：13251657-K</p></td></tr><tr><td>customerAddress</td><td>String</td><td>是</td><td>用户地址</td></tr><tr><td>accountType</td><td>Strin</td><td>是</td><td><p>收款方账户类型<br><code>00</code>--Corriente（活期账户）<br><code>01</code>--Ahorro（储蓄账户）<br><code>02</code>-- RUT<del>（只有0012-banco estado有这个类型）</del></p><p><code>07</code>--Vista/Cuenta</p><p><code>08</code>--SALARY ACCOUNT</p></td></tr><tr><td>account</td><td>String</td><td>是</td><td>收款方账户号（当'bankId'是0012-<strong>banco estado,</strong>银行位数最多是12位，且当0012-<strong>banco estado的</strong><code>accountType</code>是<code>02</code>时，<code>account</code>是<code>customerIdentification</code>的前8位数字，示例：26484404）</td></tr><tr><td>bankId</td><td>String</td><td>是</td><td>收款人银行编号<br>参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/xia-zai">“下载”>智利银行编码"</a></td></tr><tr><td>bankName</td><td>String</td><td>是</td><td>收款人银行名称<br>参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/xia-zai">“下载”>智利银行编码"</a></td></tr><tr><td>nonceStr</td><td>String</td><td>是</td><td>随机字符串<br>长度不能超过32位</td></tr><tr><td>description</td><td>String</td><td>是</td><td>订单描述</td></tr><tr><td>sign</td><td>String</td><td>是</td><td>签名<br><a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/qian-ming-suan-fa">具体参照：签名算法</a></td></tr><tr><td>callbackUrl</td><td>String</td><td>是</td><td><p>回调地址</p><p>详见<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/tong-zhi-hui-tiao-shuo-ming">通知回调说明</a></p></td></tr><tr><td>customerIdentificationType</td><td>String</td><td>是</td><td><p>用户证件类型</p><p><code>02</code>: 税号 --RUT</p><p><code>03</code>：护照</p></td></tr></tbody></table>

#### 请求示例<br>

{% code fullWidth="true" %}

```json
{
	"account": "50257382",
	"accountType": "00",
	"bankId": "0016",
	"bankName": "BCI",
	"callbackUrl": "https://d3n6sxxacbzd9u.cloudfront.net/apigate/uwjhah/api/pay_notice/out_payback?payId=4CB565C10F994CDBBCB1D1E8715C458A",
	"countryId": "CHL",
	"currency": "CLP",
	"customerAddress": "test online 01",
	"customerEmail": "davies.zhai@supefina.net",
	"customerIdentification": "111111111",
	"customerIdentificationType": "00",
	"customerName": "Ignacio Andres Donoso Pinochet",
	"customerPhone": "923122312",
	"description": "111111",
	"merId": "8302024214514649",
	"merOrderNo": "2025072517282053634358904",
	"nonceStr": "5749e4b8f0764fe4b62f6081ac6a46cc",
	"orderAmount": "1000",
	"payProduct": "12",
	"sign": "DB06FF061B7CE8CE920AAB5766233AE5"// 大写
}
```

{% endcode %}

签名组装字符串

account=50257382\&accountType=00\&bankId=0016\&bankName=BCI\&callbackUrl=<https://d3n6sxxacbzd9u.cloudfront.net/apigate/uwjhah/api/pay\\_notice/out\\_payback?payId=4CB565C10F994CDBBCB1D1E8715C458A\\&countryId=CHL\\&currency=CLP\\&customerAddress=test> online 01\&customerEmail=<davies.zhai@supefina.net>\&customerIdentification=111111111\&customerIdentificationType=00\&customerName=Ignacio Andres Donoso Pinochet\&customerPhone=923122312\&description=111111\&merId=8302024214514649\&merOrderNo=2025072517282053634358904\&nonceStr=5749e4b8f0764fe4b62f6081ac6a46cc\&orderAmount=1000\&payProduct=12\&key=bb01dd04d967425ab194fff9fe8a9501

### 响应参数

<table data-full-width="true"><thead><tr><th width="195">变量名</th><th width="195">类型</th><th width="541">描述</th></tr></thead><tbody><tr><td>code</td><td>String</td><td>响应编码<br>具体参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/xiang-ying-zhuang-tai-ma">响应状态码</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>fee</td><td>BigDecimal</td><td>预收手续费</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>supefinaOrderNo</td><td>String</td><td>supefina订单号</td></tr><tr><td>transactionStatus</td><td>String</td><td>下单状态<br>该笔订单的的发起状态是否成功，与订单真正的交易状态无关。<br><code>00</code>：下单成功<br><code>04</code>：下单失败</td></tr><tr><td>msg</td><td>String</td><td>响应信息</td></tr></tbody></table>

#### 响应示例

{% code fullWidth="true" %}

```json
{
	"code": "200",
	"msg": "success ",
	"data": {
		"merCode": "8302024214514649",
		"merOrderNo": "2025072517282053634358904",
		"supefinaOrderNo": "20250725092820898000038028",
		"amount": 1000,
		"transactionStatus": "00"
	}
}
```

{% endcode %}

### 回调通知

提交方式：`POST`

<table data-full-width="true"><thead><tr><th width="195">变量名</th><th width="195">类型</th><th width="632">描述</th></tr></thead><tbody><tr><td>amount</td><td>String</td><td>订单金额</td></tr><tr><td>countryId</td><td>String</td><td>国家编号<br>参照：字典表-国家编号<br>秘鲁，PER</td></tr><tr><td>customerName</td><td>String</td><td>收款人姓名</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>sign</td><td>String</td><td>签名</td></tr><tr><td>status</td><td>String</td><td>交易状态<br>具体参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#kxzkj">字典表——交易订单状态</a></td></tr><tr><td>successTime</td><td>String</td><td>交易成功时间</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": "1000.00",
	"countryId": "CHL",
	"customerName": "Ignacio Andres Donoso Pinochet",
	"fee": "5.00",
	"identifier": "",
	"merId": "8302024214514649",
	"merOrderId": "2025072517282053634358904",
	"msg": "SUCCESS",
	"nonceStr": "5bb977b2-aa05-47e5-bc3f-2b4b57",
	"realityAmount": "1000.00",
	"realityFee": "5.00",
	"reference": "0d34aac0-6af7-49",
	"sign": "9F34FD9A25A43A4209B913AF02409DA0",// 大写
	"status": "01",
	"supefinaOrderId": "20250725092820898000038028",
	"transactionType": "02"
}
```

{% endcode %}

签名组装字符串

amount=1000.00\&countryId=CHL\&customerName=Ignacio Andres Donoso Pinochet\&fee=5.00\&merId=8302024214514649\&merOrderId=2025072517282053634358904\&msg=SUCCESS\&nonceStr=5bb977b2-aa05-47e5-bc3f-2b4b57\&realityAmount=1000.00\&realityFee=5.00\&reference=0d34aac0-6af7-49\&status=01\&supefinaOrderId=20250725092820898000038028\&transactionType=02\&key=bb01dd04d967425ab194fff9fe8a9501

**回调通知响应**

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

{% code fullWidth="true" %}

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

{% endcode %}

### 智利代付银行列表

<table><thead><tr><th width="234">bankId</th><th width="365">bankName</th></tr></thead><tbody><tr><td>0504</td><td>Scotiabank Azul</td></tr><tr><td>0028</td><td>Banco Bice</td></tr><tr><td>0055</td><td>Banco Consorcio</td></tr><tr><td>0001</td><td>Banco de Chile</td></tr><tr><td>0012</td><td>Banco Estado</td></tr><tr><td>0051</td><td>Banco Falabella</td></tr><tr><td>0039</td><td>Banco Itau</td></tr><tr><td>0053</td><td>Banco Ripley</td></tr><tr><td>0049</td><td>Banco Security</td></tr><tr><td>0016</td><td>BCI</td></tr><tr><td>729</td><td>Caja Los Heroes</td></tr><tr><td>0672</td><td>Coopeuch</td></tr><tr><td>732</td><td>Los Andes</td></tr><tr><td>875</td><td>Mercado Pago</td></tr><tr><td>0037</td><td>Santander</td></tr><tr><td>0014</td><td>Scotiabank</td></tr><tr><td>730</td><td>Tenpo</td></tr><tr><td>0507</td><td>Banco del desarrollo</td></tr><tr><td>0009</td><td>Banco Internacional</td></tr><tr><td>027</td><td>Itau-Corpbanca</td></tr><tr><td>031</td><td>Hsbc Bank</td></tr><tr><td>057</td><td>Banco Paris</td></tr><tr><td>0152</td><td>Prepago Los Heroes</td></tr><tr><td>0738</td><td>Global 66</td></tr></tbody></table>


# 代付失败原因说明

#### 注意：

<sub>代付请求超时仅代表未能在预定时间内获得响应，这并不意味着业务失败。遇到超时情况时，商户应采取以下标准流程：</sub>\ <sub>首先将相关订单标记为挂起状态，随后等待至少2分钟后通过查询接口检索订单状态。切勿在超时后立即尝试重新提交请求，这可能导致重复交易。</sub>\ <sub>因未遵循上述规定流程而造成的任何资金损失，将由责任方全权承担，我司概不负责。</sub>

<table><thead><tr><th width="394">Msg</th><th width="421">释义</th><th width="421">建议处理办法</th></tr></thead><tbody><tr><td>banking_error</td><td>用户的收款账户有金额限制、账户不存在或目标银行超时导致的，</td><td>建议用户检查收款账户是否正确或更换收款账户后重试</td></tr><tr><td>accountbanknum: is empty</td><td>收款账号account为必填项</td><td>请填写收款账号</td></tr><tr><td>accountbanknum:invalid, max 12 characters</td><td>收款账号account最长为12位</td><td>建议用户检查收款账户是否正确或更换收款账户后重试</td></tr><tr><td>accountbankrut: invalid rut</td><td>证件号customerIdentification无效</td><td>请检查证件号是否真实有效</td></tr><tr><td>accountbankrut: invalid, long or less rut</td><td>证件号customerIdentification不正确，太长或者太短</td><td>请检查证件号是否真实有效</td></tr><tr><td>amount: value greater than or equal to 1.000 clp</td><td>订单金额orderAmount必须大于等于1000 CLP</td><td>请更换其他符合要求的金额</td></tr><tr><td>email:is invalid</td><td>用户邮箱customerEmail无效</td><td>请检查邮箱是否有效，或格式是否正确，或更换其他邮箱</td></tr><tr><td>phone: invalid, is not numeric</td><td>用户电话customerPhone无效，不是数字</td><td>请检查电话号码是否真实有效，或更换其他手机号</td></tr><tr><td>phone: invalid, min 8 characters</td><td>用户电话customerPhone无效，最小8位</td><td>请检查电话号码是否真实有效，或更换其他手机号</td></tr></tbody></table>


# 巴西

巴西银行转账（PIX）是一种即时支付方式，可实现7\*24全天进行，且实时到账。

{% content-ref url="/pages/PNKHfYPxKiWkJRyLuu6O" %}
[PIX](/huan-ying-shi-yong-supefina-de-api-wen-dang/dai-fu/ba-xi/pix)
{% endcontent-ref %}

{% content-ref url="/pages/GViBy9pGO5ySEauEJitm" %}
[代付失败原因说明](/huan-ying-shi-yong-supefina-de-api-wen-dang/dai-fu/ba-xi/dai-fu-shi-bai-yuan-yin-shuo-ming)
{% endcontent-ref %}

{% content-ref url="/pages/CSy92qzpwhAUAtNJmF2G" %}
[Broken mention](broken://pages/CSy92qzpwhAUAtNJmF2G)
{% endcontent-ref %}


# PIX

（payProduct=24）

请注意：在使用PIX代付时，可能会出现两次回调的情况。尽管订单已收到成功回调，后续仍可能收到状态更改为失败的回调。出现这种情况的原因可能是用户主动发起退款或用户银行系统波动导致退款。这种情况发生概率较小。

对于这种先成功后失败的情况，我们建议商户以最后一次收到的回调状态为准。由于用户行为和银行处理时间的不确定性，Supefina系统无法预测是否会有第二次回调及其具体时间。

### 请求地址

<table data-full-width="true"><thead><tr><th width="114">环境名称</th><th width="619">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/payout</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/payout</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="225">变量名</th><th width="96">类型</th><th width="128">必填</th><th width="602">描述</th></tr></thead><tbody><tr><td>account</td><td>String</td><td>是</td><td>收款方账户号<br>509.281.038-62（CPF）<br>12345@qq.com(EMAIL）<br>12345678911（PHONE）<br>01eb9090-73e5-4187-b43d-0d80a149e1dc（EVP：类似UUID的字符串</td></tr><tr><td>accountType</td><td>String</td><td>是</td><td>收款方账户类型<br><code>03</code>：CPF<br><code>04</code>：EMAIL<br><code>05</code>：PHONE<br><code>06</code>：EVP</td></tr><tr><td>callbackUrl</td><td>String</td><td>是</td><td><p>回调地址</p><p>详见<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/tong-zhi-hui-tiao-shuo-ming">通知回调说明</a></p></td></tr><tr><td>countryId</td><td>String</td><td>是</td><td>国家编号<br>参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#afwzp">字典表-国家编号</a><br>巴西，<code>BRA</code></td></tr><tr><td>currency</td><td>String</td><td>是</td><td>币种<br>参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#huo-bi-currency">字典表-货币</a><br>雷亚尔：<code>BRL</code></td></tr><tr><td>customerName</td><td>String</td><td>是</td><td><p>收款人姓名</p><p>首尾不得包含空格，但姓名之间可以有空格</p></td></tr><tr><td>customerIdentification</td><td>String</td><td>否</td><td>用户证件号（CPF）</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>orderAmount</td><td>String</td><td>是</td><td>订单金额</td></tr><tr><td>payProduct</td><td>String</td><td>是</td><td><a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#mfocd">支付类型</a><br>PIX：<code>24</code></td></tr><tr><td>sign</td><td>String</td><td>是</td><td>签名<br><a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/qian-ming-suan-fa">具体参照：签名算法</a></td></tr></tbody></table>

#### 请求示例<br>

{% code fullWidth="true" %}

```json
{
	"account": "509.281.038-62",
	"accountType": "03",
	"callbackUrl": "http://test.com",
	"countryId": "BRA",
	"currency": "BRL",
	"customerIdentification": "45143065844",
	"customerName": "Arjun Choudhury",
	"merId": "8302996847200585",
	"merOrderNo": "2025072513360034120802820",
	"nonceStr": "3652d4090aab4b2ea41aab3faf5ddb37",
	"orderAmount": "5.00",
	"payProduct": "24",
	"sign": "B957D315EA6E6887B3D032EE6CAA66FA"// 大写
}
```

{% endcode %}

签名组装字符串

account=509.281.038-62\&accountType=03\&callbackUrl=<http://test.com\\&countryId=BRA\\&currency=BRL\\&customerIdentification=45143065844\\&customerName=Arjun> Choudhury\&merId=8302996847200585\&merOrderNo=2025072513360034120802820\&nonceStr=3652d4090aab4b2ea41aab3faf5ddb37\&orderAmount=5.00\&payProduct=24\&key=9dbb958a68f04252bae26a6b6d98e0ab

### 响应参数

<table data-full-width="true"><thead><tr><th width="225">变量名</th><th width="140">类型</th><th width="503">描述</th></tr></thead><tbody><tr><td>code</td><td>String</td><td>响应编码<br>具体参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/xiang-ying-zhuang-tai-ma">响应状态码</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>fee</td><td>BigDecimal</td><td>预收手续费</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>supefinaOrderNo</td><td>String</td><td>supefina订单号</td></tr><tr><td>transactionStatus</td><td>String</td><td>下单状态<br>该笔订单的的发起状态是否成功，与订单真正的交易状态无关。<br><code>00</code>：下单成功<br><code>04</code>：下单失败</td></tr><tr><td>msg</td><td>String</td><td>响应信息</td></tr></tbody></table>

#### 响应示例

{% code fullWidth="true" %}

```json
{
	"code": "200",
	"msg": "success ",
	"data": {
		"merCode": "8302996847200585",
		"merOrderNo": "2025072513360034120802820",
		"supefinaOrderNo": "20250725053600755000038489",
		"amount": 5.0,
		"transactionStatus": "00"
	}
}
```

{% endcode %}

### 回调通知

提交方式：`POST`

<table data-full-width="true"><thead><tr><th width="225">变量名</th><th width="96">类型</th><th width="722">描述</th></tr></thead><tbody><tr><td>amount</td><td>String</td><td>订单金额</td></tr><tr><td>countryId</td><td>String</td><td>国家编号<br>参照：字典表-国家编号<br>秘鲁，<code>PER</code></td></tr><tr><td>customerName</td><td>String</td><td>收款人姓名</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>sign</td><td>String</td><td>签名</td></tr><tr><td>status</td><td>String</td><td>交易状态<br>具体参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#kxzkj">字典表——交易订单状态</a></td></tr><tr><td>successTime</td><td>String</td><td>交易成功时间</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": "5.00",
	"countryId": "BRA",
	"customerName": "Arjun Choudhury",
	"fee": "5.25",
	"identifier": "",
	"merId": "8302996847200585",
	"merOrderId": "2025072513360034120802820",
	"msg": "SUCCESS",
	"nonceStr": "a14bfa37-4434-4b97-ba3c-46a722",
	"realityAmount": "5.00",
	"realityFee": "5.25",
	"reference": "7d7376fb-e369-4b",
	"sign": "81ECA00FD49087CE4DD23B8C61F91A72",// 大写
	"status": "01",
	"supefinaOrderId": "20250725053600755000038489",
	"transactionType": "02"
}
```

{% endcode %}

签名组装字符串

amount=5.00\&countryId=BRA\&customerName=Arjun Choudhury\&fee=5.25\&merId=8302996847200585\&merOrderId=2025072513360034120802820\&msg=SUCCESS\&nonceStr=a14bfa37-4434-4b97-ba3c-46a722\&realityAmount=5.00\&realityFee=5.25\&reference=7d7376fb-e369-4b\&status=01\&supefinaOrderId=20250725053600755000038489\&transactionType=02\&key=9dbb958a68f04252bae26a6b6d98e0ab

**回调通知响应**

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

{% code fullWidth="true" %}

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

{% endcode %}


# 代付失败原因说明

#### 注意：

<sub>代付请求超时仅代表未能在预定时间内获得响应，这并不意味着业务失败。遇到超时情况时，商户应采取以下标准流程：</sub>\ <sub>首先将相关订单标记为挂起状态，随后等待至少2分钟后通过查询接口检索订单状态。切勿在超时后立即尝试重新提交请求，这可能导致重复交易。</sub>\ <sub>因未遵循上述规定流程而造成的任何资金损失，将由责任方全权承担，我司概不负责。</sub>

<table><thead><tr><th width="331">Msg</th><th width="429.818115234375">释义</th><th width="592">建议处理办法</th></tr></thead><tbody><tr><td>Maximum amount exceeded</td><td>超出最大金额</td><td>请检查订单金额是否超过最大限制，或更换其他收款账号</td></tr><tr><td>Minimum amount exceeded</td><td>超出最小金额</td><td>请检查订单金额是否超过最低限制，或更换其他收款账号</td></tr><tr><td>Pix not found</td><td>pix号码不存在</td><td>验证用户账号信息是否正确</td></tr><tr><td>Settlement timeout</td><td>用户银行波动导致的拉单超时失败</td><td>建议稍后重试，或更换其他收款账号</td></tr><tr><td>Account blocked</td><td>用户收款账户被冻结</td><td>建议更换银行账户</td></tr><tr><td>The transaction was rejected by the settlement bank</td><td>该交易被银行拒绝。</td><td>建议用户联系银行确认具体拒绝原因，或更换其他收款账号</td></tr><tr><td>SPI error</td><td>用户银行波动导致的拉单超时失败</td><td>建议稍后重试，或更换其他收款账号</td></tr><tr><td>Declined by beneficiary bank</td><td>被收款银行拒绝</td><td>建议用户联系银行确认具体拒绝原因，或更换其他收款账号</td></tr><tr><td>The transaction was failed due to error on settlement bank</td><td>该交易因结算银行错误而失败</td><td>建议用户联系银行确认具体失败原因，或更换其他收款账号</td></tr><tr><td>Pix format error</td><td>账号错误/格式错误</td><td>检查pix是否正确，或者更换其他收款账号</td></tr><tr><td>Cash-outs are not allowed for legal entities</td><td>法律实体不允许进行现金提取。</td><td>更换其他收款账号</td></tr><tr><td>Settlement failed</td><td>用户银行波动</td><td>请稍后重试，或者更换其他收款账号</td></tr><tr><td>Pix key not exists</td><td>Pix密钥不存在</td><td>请检查收款账号和收款账号吧类型是否不匹配，或者更换其他收款账号</td></tr><tr><td>Invalid account uuid</td><td>无效的uuid</td><td>检查uuid是否正确，或者更换其他收款账号</td></tr><tr><td>account blacklist intercept</td><td>账号被禁用</td><td>更换其他收款账号</td></tr><tr><td>idNumber blacklist intercept</td><td>cpf账号被禁用</td><td>更换其他收款账号</td></tr><tr><td>account blacklist risk control intercept</td><td>账号被风控</td><td>更换其他收款账号</td></tr><tr><td>Account unavailable</td><td>账户不可用</td><td>更换其他收款账号</td></tr><tr><td>Internal server error</td><td>服务器错误</td><td>请稍后重试</td></tr><tr><td>Query dict limit</td><td>因发送无效账号过多，pix查询暂时受限</td><td>请稍后重试</td></tr><tr><td>Account closed</td><td>收款账户已关户</td><td>更换其他收款账号</td></tr><tr><td>Bank system occurred error</td><td>银行系统发生错误</td><td>请稍后重试</td></tr><tr><td>Receipt account exceeds limit</td><td>收款账户超出限额</td><td>更换其他收款账号</td></tr><tr><td>Transação não autorizada</td><td>银行风控</td><td>更换其他收款账号</td></tr><tr><td>title: Limite de consultas excedido, detail: Limite de consultas excedido</td><td>受央行pix限制导致代付失败，失败订单重新提交即可</td><td>请稍后重试</td></tr></tbody></table>


# 厄瓜多尔

厄瓜多尔银行转账（Transfer），由于本地银行的限制，只能在工作日进行，工作日期间提交的订单，当天可以处理完成，非工作日期间的订单需要等到下个工作进行处理。

{% content-ref url="/pages/X5EYavtOTGsS0k2k7xda" %}
[Transfer](/huan-ying-shi-yong-supefina-de-api-wen-dang/dai-fu/e-gua-duo-er/transfer)
{% endcontent-ref %}

{% content-ref url="/pages/6OLsqgtQBr2yNyFKwjnE" %}
[Broken mention](broken://pages/6OLsqgtQBr2yNyFKwjnE)
{% endcontent-ref %}


# Transfer

（payProduct=12）

### 请求地址

<table data-full-width="true"><thead><tr><th width="114">环境名称</th><th width="619">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/payout</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/payout</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="210">变量名</th><th width="137">类型</th><th width="125">必填</th><th width="514">描述</th></tr></thead><tbody><tr><td>countryId</td><td>String</td><td>是</td><td>国家编号<br>参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#afwzp">字典表-国家编号</a><br>厄瓜多尔，<code>ECU</code></td></tr><tr><td>merId</td><td>String</td><td>是</td><td>商户ID<br>商户ID获取路径：Supefina商户后台-商户管理-基本信息-商户ID</td></tr><tr><td>payProduct</td><td>String</td><td>是</td><td>支付类型<br>Transfer：<code>12</code></td></tr><tr><td>currency</td><td>String</td><td>是</td><td>币种<br>参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#huo-bi-currency">字典表-货币</a><br>美元：<code>USD</code></td></tr><tr><td>merOrderNo</td><td>String</td><td>是</td><td>商户订单号</td></tr><tr><td>orderAmount</td><td>String</td><td>是</td><td>订单金额<br>0>= <code>orderAmount</code> &#x3C;= 10,000</td></tr><tr><td>customerEmail</td><td>String</td><td>是</td><td>收款人邮箱</td></tr><tr><td>customerPhone</td><td>String</td><td>是</td><td>收款人电话</td></tr><tr><td>customerName</td><td>String</td><td>是</td><td>收款人姓名</td></tr><tr><td>customerIdentificationType</td><td>String</td><td>是</td><td>收款人证件类型<br><code>07</code>：身份证件（CI）<br><code>10</code>：护照号码（PP）(only for Cash)<br><code>03</code>：护照标识（PAS）(only for BankTransfer)<br><code>02</code>：税号（RUC）</td></tr><tr><td>customerIdentification</td><td>String</td><td>是</td><td>收款人证件号</td></tr><tr><td>bankId</td><td>String</td><td>是</td><td><p>收款人银行编号<br>参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/xia-zai#e-gua-duo-er-yin-hang-bian-ma">见“下载”>"厄瓜多尔银行编码"</a></p><p>注意：测试环境代付仅支持四家银行</p><p>0010 BANCO PICHINCHA C.A.</p><p>0017 BANCO DE GUAYAQUIL S.A</p><p>0024 BANCO CITY BANK</p><p>0025 BANCO MACHALA</p></td></tr><tr><td>bankName</td><td>String</td><td>是</td><td><p>收款人银行名称 </p><p>参照：<a href="https://www.notion.so/o/OPlN6h4N4bqqRA40kWgo/s/uukVORWjXBgcGu8MirPR/~/changes/163/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/xia-zai#e-gua-duo-er-yin-hang-bian-ma">见“下载”>"厄瓜多尔银行编码"</a></p></td></tr><tr><td>accountType</td><td>Strin</td><td>是</td><td>账户类型<br><code>00</code>：活期账户<br><code>01</code>：储蓄账户</td></tr><tr><td>account</td><td>String</td><td>是</td><td>收款方账户号</td></tr><tr><td>app</td><td>String</td><td>是</td><td>订单app名称</td></tr><tr><td>nonceStr</td><td>String</td><td>是</td><td>随机字符串<br>长度不能超过32位</td></tr><tr><td>sign</td><td>String</td><td>是</td><td>签名<br><a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/qian-ming-suan-fa">具体参照：签名算法</a></td></tr><tr><td>callbackUrl</td><td>String</td><td>是</td><td><p>回调地址</p><p>详见<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/tong-zhi-hui-tiao-shuo-ming">通知回调说明</a></p></td></tr><tr><td>customerAddress</td><td>String</td><td>否</td><td>顾客地址</td></tr><tr><td>description</td><td>String</td><td>否</td><td>订单描述</td></tr></tbody></table>

#### 请求示例<br>

{% code fullWidth="true" %}

```json
{
	"account": "89831914679785",
	"accountType": "01",
	"app": "supefina",
	"bankId": "0010",
	"bankName": "BANCO PICHINCHA C.A.",
	"countryId": "ECU",
	"currency": "USD",
	"customerEmail": "test@mail.com",
	"customerIdentification": "7588708477",
	"customerIdentificationType": "07",
	"customerName": "testName",
	"customerPhone": "123456789",
	"merId": "8302748528064643",
	"merOrderNo": "2025072517181971561328505",
	"nonceStr": "58e3d1fc5f4f42a79b3b68d329954f88",
	"orderAmount": "5",
	"payProduct": "12",
	"sign": "CA73EDD08336EBEEE45141142BF3870E"// 大写
}
```

{% endcode %}

签名组装字符串

account=89831914679785\&accountType=01\&app=supefina\&bankId=0010\&bankName=BANCO PICHINCHA C.A.\&countryId=ECU\&currency=USD\&customerEmail=<test@mail.com>\&customerIdentification=7588708477\&customerIdentificationType=07\&customerName=testName\&customerPhone=123456789\&merId=8302748528064643\&merOrderNo=2025072517181971561328505\&nonceStr=58e3d1fc5f4f42a79b3b68d329954f88\&orderAmount=5\&payProduct=12\&key=bb01dd04d967425ab194fff9fe8a9501

### 响应参数

<table data-full-width="true"><thead><tr><th width="210">变量名</th><th width="161">类型</th><th width="539">描述</th></tr></thead><tbody><tr><td>code</td><td>String</td><td>响应编码<br>具体参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/xiang-ying-zhuang-tai-ma">响应状态码</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>fee</td><td>BigDecimal</td><td>预收手续费</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>supefinaOrderNo</td><td>String</td><td>supefina订单号</td></tr><tr><td>transactionStatus</td><td>String</td><td>下单状态<br>该笔订单的的发起状态是否成功，与订单真正的交易状态无关。<br><code>00</code>：下单成功<br><code>04</code>：下单失败</td></tr><tr><td>msg</td><td>String</td><td>响应信息</td></tr></tbody></table>

#### 响应示例

{% code fullWidth="true" %}

```json
{
	"code": "200",
	"msg": "success ",
	"data": {
		"merCode": "8302748528064643",
		"merOrderNo": "2025072517181971561328505",
		"supefinaOrderNo": "202507250602000f0c871b207a64d",
		"amount": 5,
		"fee": 5.0,
		"transactionStatus": "00"
	}
}
```

{% endcode %}

### 回调通知

提交方式：`POST`

<table data-full-width="true"><thead><tr><th width="210">变量名</th><th width="161">类型</th><th width="673">描述</th></tr></thead><tbody><tr><td>amount</td><td>String</td><td>订单金额</td></tr><tr><td>countryId</td><td>String</td><td>国家编号<br>参照：字典表-国家编号<br>秘鲁，<code>PER</code></td></tr><tr><td>customerName</td><td>String</td><td>收款人姓名</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>sign</td><td>String</td><td>签名</td></tr><tr><td>status</td><td>String</td><td>交易状态<br>具体参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#kxzkj">字典表——交易订单状态</a></td></tr><tr><td>successTime</td><td>String</td><td>交易成功时间</td></tr></tbody></table>

#### 回调通知示例

{% code fullWidth="true" %}

```json
{
	"amount": "5.00",
	"countryId": "ECU",
	"customerName": "testName",
	"fee": "5.00",
	"identifier": "757119999457266637",
	"merId": "8302748528064643",
	"merOrderId": "2025072517181971561328505",
	"msg": "交易成功",
	"nonceStr": "66e9d86a-41db-4573-8c1c-e8bb7a",
	"realityAmount": "5.00",
	"realityFee": "5.00",
	"reference": "PTJV2NQHKEPE14L1PD3NBIAK8KSEBIU",
	"sign": "A91E529AD2F83C5BC5C8204F2EC46F5C",// 大写
	"status": "01",
	"successTime": 1753435107907,
	"supefinaOrderId": "202507250602000f0c871b207a64d",
	"transactionType": "02"
}
```

{% endcode %}

签名组装字符串

account=89831914679785\&accountType=01\&app=supefina\&bankId=0010\&bankName=BANCO PICHINCHA C.A.\&countryId=ECU\&currency=USD\&customerEmail=<test@mail.com>\&customerIdentification=7588708477\&customerIdentificationType=07\&customerName=testName\&customerPhone=123456789\&merId=8302748528064643\&merOrderNo=2025072517181971561328505\&nonceStr=58e3d1fc5f4f42a79b3b68d329954f88\&orderAmount=5\&payProduct=12\&key=bb01dd04d967425ab194fff9fe8a9501

**回调通知响应**

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

{% code fullWidth="true" %}

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

{% endcode %}


# EC Transfer

（payProduct=25）

### 请求地址

<table data-full-width="true"><thead><tr><th width="114">环境名称</th><th width="619">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/payout</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/payout</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="210">变量名</th><th width="137">类型</th><th width="125">必填</th><th width="514">描述</th></tr></thead><tbody><tr><td>countryId</td><td>String</td><td>是</td><td>国家编号<br>参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#afwzp">字典表-国家编号</a><br>厄瓜多尔，<code>ECU</code></td></tr><tr><td>merId</td><td>String</td><td>是</td><td>商户ID<br>商户ID获取路径：Supefina商户后台-商户管理-基本信息-商户ID</td></tr><tr><td>payProduct</td><td>String</td><td>是</td><td>支付类型<br>Transfer：<code>25</code></td></tr><tr><td>currency</td><td>String</td><td>是</td><td>币种<br>参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#huo-bi-currency">字典表-货币</a><br>美元：<code>USD</code></td></tr><tr><td>merOrderNo</td><td>String</td><td>是</td><td>商户订单号</td></tr><tr><td>orderAmount</td><td>String</td><td>是</td><td>订单金额<br>0>= <code>orderAmount</code> &#x3C;= 10,000</td></tr><tr><td>customerEmail</td><td>String</td><td>是</td><td>收款人邮箱</td></tr><tr><td>customerPhone</td><td>String</td><td>是</td><td>收款人电话</td></tr><tr><td>customerName</td><td>String</td><td>是</td><td>收款人姓名</td></tr><tr><td>customerIdentificationType</td><td>String</td><td>是</td><td>收款人证件类型<br><code>07</code>：身份证件（CI）<br><code>10</code>：护照号码（PP）(only for Cash)<br><code>03</code>：护照标识（PAS）(only for BankTransfer)<br><code>02</code>：税号（RUC）</td></tr><tr><td>customerIdentification</td><td>String</td><td>是</td><td>收款人证件号</td></tr><tr><td>bankId</td><td>String</td><td>是</td><td><p>收款人银行编号<br>参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/xia-zai#e-gua-duo-er-yin-hang-bian-ma">见“下载”>"厄瓜多尔银行编码"</a></p><p>注意：测试环境代付仅支持四家银行</p><p>0010 BANCO PICHINCHA C.A.</p><p>0017 BANCO DE GUAYAQUIL S.A</p><p>0024 BANCO CITY BANK</p><p>0025 BANCO MACHALA</p></td></tr><tr><td>bankName</td><td>String</td><td>是</td><td>收款人银行名称<br>参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/xia-zai#e-gua-duo-er-yin-hang-bian-ma">见“下载”>"厄瓜多尔银行编码"</a></td></tr><tr><td>accountType</td><td>Strin</td><td>是</td><td>账户类型<br><code>00</code>：活期账户<br><code>01</code>：储蓄账户</td></tr><tr><td>account</td><td>String</td><td>是</td><td>收款方账户号</td></tr><tr><td>app</td><td>String</td><td>是</td><td>订单app名称</td></tr><tr><td>nonceStr</td><td>String</td><td>是</td><td>随机字符串<br>长度不能超过32位</td></tr><tr><td>sign</td><td>String</td><td>是</td><td>签名<br><a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/qian-ming-suan-fa">具体参照：签名算法</a></td></tr><tr><td>callbackUrl</td><td>String</td><td>是</td><td><p>回调地址</p><p>详见<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/tong-zhi-hui-tiao-shuo-ming">通知回调说明</a></p></td></tr><tr><td>customerAddress</td><td>String</td><td>否</td><td>顾客地址</td></tr><tr><td>description</td><td>String</td><td>否</td><td>订单描述</td></tr></tbody></table>

#### 请求示例<br>

{% code fullWidth="true" %}

```json
{
	"account": "89831914679785",
	"accountType": "01",
	"app": "supefina",
	"bankId": "0010",
	"bankName": "BANCO PICHINCHA C.A.",
	"countryId": "ECU",
	"currency": "USD",
	"customerEmail": "test@mail.com",
	"customerIdentification": "7588708477",
	"customerIdentificationType": "07",
	"customerName": "testName",
	"customerPhone": "123456789",
	"merId": "8302748528064643",
	"merOrderNo": "2025072517054800138754256",
	"nonceStr": "c8b31f7585194e3dae75f47992396f44",
	"orderAmount": "5",
	"payProduct": "25",
	"sign": "080F37F39DD4F0C80EF4C16401236C0D"// 大写
}
```

{% endcode %}

签名组装字符串

account=89831914679785\&accountType=01\&app=supefina\&bankId=0010\&bankName=BANCO PICHINCHA C.A.\&countryId=ECU\&currency=USD\&customerEmail=<test@mail.com>\&customerIdentification=7588708477\&customerIdentificationType=07\&customerName=testName\&customerPhone=123456789\&merId=8302748528064643\&merOrderNo=2025072517054800138754256\&nonceStr=c8b31f7585194e3dae75f47992396f44\&orderAmount=5\&payProduct=25\&key=bb01dd04d967425ab194fff9fe8a9501

### 响应参数

<table data-full-width="true"><thead><tr><th width="210">变量名</th><th width="161">类型</th><th width="539">描述</th></tr></thead><tbody><tr><td>code</td><td>String</td><td>响应编码<br>具体参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/xiang-ying-zhuang-tai-ma">响应状态码</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>fee</td><td>BigDecimal</td><td>预收手续费</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>supefinaOrderNo</td><td>String</td><td>supefina订单号</td></tr><tr><td>transactionStatus</td><td>String</td><td>下单状态<br>该笔订单的的发起状态是否成功，与订单真正的交易状态无关。<br><code>00</code>：下单成功<br><code>04</code>：下单失败</td></tr><tr><td>msg</td><td>String</td><td>响应信息</td></tr></tbody></table>

#### 响应示例

{% code fullWidth="true" %}

```json
{
	"code": "200",
	"msg": "success ",
	"data": {
		"merCode": "8302748528064643",
		"merOrderNo": "2025072517054800138754256",
		"supefinaOrderNo": "202507250602000ec816ce99b7844",
		"amount": 5,
		"fee": 5.0,
		"transactionStatus": "00"
	}
}
```

{% endcode %}

### 回调通知

提交方式：`POST`

<table data-full-width="true"><thead><tr><th width="210">变量名</th><th width="161">类型</th><th width="673">描述</th></tr></thead><tbody><tr><td>amount</td><td>String</td><td>订单金额</td></tr><tr><td>countryId</td><td>String</td><td>国家编号<br>参照：字典表-国家编号<br>秘鲁，<code>PER</code></td></tr><tr><td>customerName</td><td>String</td><td>收款人姓名</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>sign</td><td>String</td><td>签名</td></tr><tr><td>status</td><td>String</td><td>交易状态<br>具体参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#kxzkj">字典表——交易订单状态</a></td></tr><tr><td>successTime</td><td>String</td><td>交易成功时间</td></tr></tbody></table>

#### 回调通知示例

{% code fullWidth="true" %}

```json
{
	"amount": "5.00",
	"countryId": "ECU",
	"customerName": "testName",
	"fee": "5.00",
	"identifier": "769816091127438913",
	"merId": "8302748528064643",
	"merOrderId": "2025072517054800138754256",
	"msg": "交易成功",
	"nonceStr": "aedf7094-0c53-4f64-a99a-f4ff78",
	"realityAmount": "5.00",
	"realityFee": "5.00",
	"reference": "PTJ2R466SGOMRBVSTBAPIKHKJQDR0Z5",
	"sign": "2DEC7F10AE75955116BBD7B2ADE63E95",// 大写
	"status": "01",
	"successTime": 1753434356491,
	"supefinaOrderId": "202507250602000ec816ce99b7844",
	"transactionType": "02"
}
```

{% endcode %}

签名组装字符串

account=89831914679785\&accountType=01\&app=supefina\&bankId=0010\&bankName=BANCO PICHINCHA C.A.\&countryId=ECU\&currency=USD\&customerEmail=<test@mail.com>\&customerIdentification=7588708477\&customerIdentificationType=07\&customerName=testName\&customerPhone=123456789\&merId=8302748528064643\&merOrderNo=2025072517054800138754256\&nonceStr=c8b31f7585194e3dae75f47992396f44\&orderAmount=5\&payProduct=25\&key=bb01dd04d967425ab194fff9fe8a9501

**回调通知响应**

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

{% code fullWidth="true" %}

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

{% endcode %}


# 阿根廷

在阿根廷，我们提供银行转账（Transfer）支付产品。

{% content-ref url="/pages/ENuwGpl4qZ8pydvFvkfA" %}
[Transfer](/huan-ying-shi-yong-supefina-de-api-wen-dang/dai-fu/a-gen-ting/transfer)
{% endcontent-ref %}


# Transfer

（payProduct=12）

### 请求地址

<table data-full-width="true"><thead><tr><th width="114">环境名称</th><th width="619">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/payout</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/payout</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="252">变量名</th><th width="96">类型</th><th width="127">必填</th><th width="511">描述</th></tr></thead><tbody><tr><td>countryId</td><td>String</td><td>是</td><td>国家编号<br>参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#afwzp">字典表-国家编号</a><br>阿根廷：<code>ARG</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>payProduct</td><td>String</td><td>是</td><td><a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#mfocd">支付类型</a><br>Transfer：<code>12</code></td></tr><tr><td>currency</td><td>String</td><td>是</td><td>币种<br>参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#huo-bi-currency">字典表-货币</a><br>阿根廷比索：<code>ARS</code></td></tr><tr><td>orderAmount</td><td>String</td><td>是</td><td>订单金额<br>只支持整数</td></tr><tr><td>customerEmail</td><td>String</td><td>否</td><td><p>用户邮箱</p><p>邮箱用户名不能只有数字（例如abc@gmail.com）且同一个邮箱一天支付请求不能超过20次。</p></td></tr><tr><td>customerName</td><td>String</td><td>否</td><td>用户姓名</td></tr><tr><td>customerPhone</td><td>String</td><td>否</td><td>用户电话</td></tr><tr><td>customerIdentificationType</td><td>String</td><td>否</td><td><p>用户证件类型 </p><p><code>00</code>：身份证（DNI）</p><p><code>02</code>：税号（CUIT）</p><p><code>11</code>：社会保障号（CUIL）</p><p><code>12</code>：外国人税号（CDI）</p></td></tr><tr><td>customerIdentification</td><td>String</td><td>否</td><td>用户身份证件号</td></tr><tr><td>account</td><td>String</td><td>是</td><td>用户收款cbu或cvu账号</td></tr><tr><td>alias</td><td>String</td><td>否</td><td>用户收款cbu或cvu账号别名</td></tr><tr><td>nonceStr</td><td>String</td><td>是</td><td>随机字符串<br>长度不能超过32位</td></tr><tr><td>sign</td><td>String</td><td>是</td><td><p>签名</p><p><a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/qian-ming-suan-fa">具体参照：签名算法</a></p></td></tr><tr><td>description</td><td>String</td><td>否</td><td><p>描述</p><p>不能带特殊符号,长度不超过200字符</p></td></tr><tr><td>callbackUrl</td><td>String</td><td>是</td><td><p>回调地址</p><p>详见<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/tong-zhi-hui-tiao-shuo-ming">通知回调说明</a></p></td></tr></tbody></table>

#### 请求示例<br>

{% code fullWidth="true" %}

```json
{
	"account": "0000001700000000111117",
	"alias": "test",
	"callbackUrl": "http://127.0.0.1:8080/test",
	"countryId": "ARG",
	"currency": "ARS",
	"customerEmail": "abc@gmail.com",
	"customerIdentification": "11111111-1",
	"customerIdentificationType": "02",
	"customerName": "test name",
	"customerPhone": "123456789",
	"description": "test",
	"merId": "8302709349110631",
	"merOrderNo": "2025072513190094096898893",
	"nonceStr": "c220f0ce89ae4c55a888347ba73d64a7",
	"orderAmount": "100",
	"payProduct": "12",
	"sign": "E0510448F23ED5947BDEF5BAA3185BC7"// 大写
}
```

{% endcode %}

&#x20;签名组装字符串

account=0000001700000000111117\&alias=test\&callbackUrl=<http://127.0.0.1:8080/test\\&countryId=ARG\\&currency=ARS\\&customerEmail=abc@gmail.com\\&customerIdentification=11111111-1\\&customerIdentificationType=02\\&customerName=test> name\&customerPhone=123456789\&description=test\&merId=8302709349110631\&merOrderNo=2025072513190094096898893\&nonceStr=c220f0ce89ae4c55a888347ba73d64a7\&orderAmount=100\&payProduct=12\&key=e200749bb5914603ad05a03d9b1b6445

### 响应参数

<table data-full-width="true"><thead><tr><th width="210">变量名</th><th width="161">类型</th><th width="539">描述</th></tr></thead><tbody><tr><td>code</td><td>String</td><td>响应编码<br>具体参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/xiang-ying-zhuang-tai-ma">响应状态码</a></td></tr><tr><td>msg</td><td>String</td><td>信息</td></tr><tr><td>data</td><td>Object</td><td>响应数据</td></tr><tr><td>amount</td><td>BigDecimal</td><td>订单金额</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>supefinaOrderNo</td><td>String</td><td>supefina订单号</td></tr><tr><td>transactionStatus</td><td>String</td><td>下单状态<br>该笔订单的的发起状态是否成功，与订单真正的交易状态无关。<br><code>00</code>：下单成功<br><code>04</code>：下单失败</td></tr></tbody></table>

#### 响应示例

{% code fullWidth="true" %}

```json
{
	"code": "200",
	"msg": "success ",
	"data": {
		"merCode": "8302709349110631",
		"merOrderNo": "2025072513190094096898893",
		"supefinaOrderNo": "20250725051901715000038387",
		"amount": 100,
		"transactionStatus": "00"
	}
}
```

{% endcode %}

### 回调通知

提交方式：`POST`

<table data-full-width="true"><thead><tr><th width="210">变量名</th><th width="161">类型</th><th width="673">描述</th></tr></thead><tbody><tr><td>amount</td><td>String</td><td>订单金额</td></tr><tr><td>countryId</td><td>String</td><td>国家编号<br>参照：字典表-国家编号<br>秘鲁，<code>PER</code></td></tr><tr><td>customerName</td><td>String</td><td>收款人姓名</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>交易状态<br>具体参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#kxzkj">字典表——交易订单状态</a></td></tr><tr><td>successTime</td><td>String</td><td>交易成功时间</td></tr></tbody></table>

#### 回调通知示例

{% code fullWidth="true" %}

```json
{
	"amount": "100.00",
	"countryId": "ARG",
	"customerName": "test name",
	"fee": "2.00",
	"identifier": "",
	"merId": "8302709349110631",
	"merOrderId": "2025072513190094096898893",
	"msg": "SUCCESS",
	"nonceStr": "1818b763-774c-4c19-950e-c8d59b",
	"realityAmount": "100.00",
	"realityFee": "2.00",
	"reference": "94af3440-1176-48",
	"sign": "F4FB74475EF7EB0AE1D111B3D2296311",// 大写
	"status": "01",
	"supefinaOrderId": "20250725051901715000038387",
	"transactionType": "02"
}
```

{% endcode %}

签名组装字符串

amount=100.00\&countryId=ARG\&customerName=test name\&fee=2.00\&merId=8302709349110631\&merOrderId=2025072513190094096898893\&msg=SUCCESS\&nonceStr=1818b763-774c-4c19-950e-c8d59b\&realityAmount=100.00\&realityFee=2.00\&reference=94af3440-1176-48\&status=01\&supefinaOrderId=20250725051901715000038387\&transactionType=02\&key=e200749bb5914603ad05a03d9b1b6445

**回调通知响应**

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

{% code fullWidth="true" %}

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

{% endcode %}


# 查询

我们提供相关查询接口，以便您直接进行集成，目前有：交易查询，余额查询，凭证查询，结算状态查询。

{% content-ref url="/pages/QFtbKxuhjRnU8PNLuQJN" %}
[交易查询](/huan-ying-shi-yong-supefina-de-api-wen-dang/cha-xun/jiao-yi-cha-xun)
{% endcontent-ref %}

{% content-ref url="/pages/nINdYhyOBa2aOk5whDZj" %}
[余额查询](/huan-ying-shi-yong-supefina-de-api-wen-dang/cha-xun/yuecha-xun)
{% endcontent-ref %}

{% content-ref url="/pages/IRg0j1LPHJCjIZJ9kmnc" %}
[凭证查询](/huan-ying-shi-yong-supefina-de-api-wen-dang/cha-xun/ping-zheng-cha-xun)
{% endcontent-ref %}

{% content-ref url="/pages/7N8XY3HWAif0Cbz1BTVF" %}
[结算状态查询](/huan-ying-shi-yong-supefina-de-api-wen-dang/cha-xun/jie-suan-zhuang-tai-cha-xun)
{% endcontent-ref %}


# 交易查询

#### 注意：

<sub>代付请求超时仅代表未能在预定时间内获得响应，这并不意味着业务失败。遇到超时情况时，商户应采取以下标准流程：</sub>\ <sub>首先将相关订单标记为挂起状态，随后等待至少2分钟后通过查询接口检索订单状态。切勿在超时后立即尝试重新提交请求，这可能导致重复交易。</sub>\ <sub>因未遵循上述规定流程而造成的任何资金损失，将由责任方全权承担，我司概不负责。</sub>

### 请求地址

<table><thead><tr><th width="138">环境名称</th><th width="607">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/search-status</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/search-status</mark></td></tr></tbody></table>

### 请求参数

| Key            | Value              |
| -------------- | ------------------ |
| `Content-Type` | `application/json` |

#### 请求体

<table data-full-width="true"><thead><tr><th width="168">变量名</th><th width="72">必填</th><th width="108">类型</th><th width="259">描述</th></tr></thead><tbody><tr><td>merId</td><td><mark style="color:red;"><code>是</code></mark></td><td><code>String</code></td><td>商户ID<br>商户ID获取路径：Supefina商户后台-商户管理-基本信息-商户ID</td></tr><tr><td>countryId</td><td><mark style="color:red;"><code>是</code></mark></td><td><code>String</code></td><td>国家编号<br>参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#afwzp">字典表-国家编号</a><br>墨西哥：<code>MEX</code></td></tr><tr><td>merOrderNo</td><td><mark style="color:red;"><code>是</code></mark></td><td><code>String</code></td><td>商户订单号</td></tr><tr><td>nonceStr</td><td><mark style="color:red;"><code>是</code></mark></td><td><code>String</code></td><td>随机字符串<br>长度不能超过32位</td></tr><tr><td>supefinaOrderId</td><td><mark style="color:red;"><code>否</code></mark></td><td><code>String</code></td><td>supefina订单号</td></tr><tr><td>sign</td><td><mark style="color:red;"><code>是</code></mark></td><td><code>String</code></td><td>签名<br><a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/qian-ming-suan-fa">具体参照：签名算法</a></td></tr></tbody></table>

#### 请求示例

```json
{
	"countryId": "BRA",
	"merId": "8302996847200585",
	"merOrderNo": "P02024051517452550031527899",
	"nonceStr": "9ad3edf6d8084801bae04bfbdb788cc5",
	"sign": "8A3B428CE13F9DAB27E41C70F825B5D6",
	"supefinaOrderId": "20250623060617181000059022"
}
```

签名组装字符串

countryId=BRA\&merId=8302996847200585\&merOrderNo=P02024051517452550031527899\&nonceStr=9ad3edf6d8084801bae04bfbdb788cc5\&supefinaOrderId=20250623060617181000059022\&key=9dbb958a68f04252bae26a6b6d98e0ab

### 响应参数

<table data-full-width="true"><thead><tr><th width="193">变量名</th><th width="126">类型</th><th>描述</th></tr></thead><tbody><tr><td>code</td><td><code>String</code></td><td>响应编码<br>具体参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/xiang-ying-zhuang-tai-ma">响应状态码</a></td></tr><tr><td>msg</td><td><code>String</code></td><td>响应信息</td></tr><tr><td>data</td><td>Object</td><td>响应数据</td></tr><tr><td>transactionStatus</td><td><code>String</code></td><td><p>交易状态</p><p><a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#kxzkj">字典表——交易订单状态</a></p></td></tr><tr><td>supefinaOrderId</td><td><code>String</code></td><td>supefina订单号</td></tr><tr><td>merOrderId</td><td><code>String</code></td><td>商户订单号</td></tr><tr><td>merId</td><td><code>String</code></td><td>商户ID</td></tr><tr><td>transactionType</td><td><code>String</code></td><td>交易类型<br><code>01</code>：代收<br><code>02</code>：代付</td></tr><tr><td>amount</td><td>BigDecimal</td><td>订单金额</td></tr><tr><td>realityAmount</td><td>BigDecimal</td><td>实收金额</td></tr><tr><td>fee</td><td>BigDecimal</td><td>预收手续费</td></tr><tr><td>realityFee</td><td>BigDecimal</td><td>实收手续费</td></tr><tr><td>successTime</td><td>Date</td><td>交易成功时间</td></tr><tr><td>identifier</td><td><code>String</code></td><td>付款参考标识符</td></tr><tr><td>stampTime</td><td><code>String</code></td><td>交易成功时间（时间戳格式，精确到秒）</td></tr><tr><td>clave</td><td><code>String</code></td><td>央行流水标识符</td></tr><tr><td>errorMsg</td><td><code>String</code></td><td>失败原因（交易失败和下单失败状态返回）</td></tr></tbody></table>

#### 响应示例

```json
{
	"code": "200",
	"msg": "success ",
	"data": {
		"transactionStatus": "01",
		"supefinaOrderId": "20250623060617181000059022",
		"merOrderId": "P02024051517452550031527899",
		"merId": "8302996847200585",
		"transactionType": "02",
		"amount": "1300.00",
		"realityAmount": "1300.00",
		"fee": "70.00",
		"realityFee": "70.00",
		"successTime": "2025-06-23 06:23:56",
		"identifier": "",
		"stampTime": 1750659836000,
		"clave": "E3038525920250601124521530b8bdb4"
	}
}
```


# 余额查询

### 请求地址

<table><thead><tr><th width="138">环境名称</th><th width="607">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/search-balance</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/search-balance</mark></td></tr></tbody></table>

### 请求参数

| Key            | Value              |
| -------------- | ------------------ |
| `Content-Type` | `application/json` |

#### 请求体

<table data-full-width="true"><thead><tr><th width="153">变量名</th><th width="72">必填</th><th width="102">类型</th><th width="259">描述</th></tr></thead><tbody><tr><td>merId</td><td><mark style="color:red;"><code>是</code></mark></td><td><code>String</code></td><td>商户ID<br>商户ID获取路径：Supefina商户后台-商户管理-基本信息-商户ID</td></tr><tr><td>countryId</td><td><mark style="color:red;"><code>是</code></mark></td><td><code>String</code></td><td>国家编号<br>参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#afwzp">字典表-国家编号</a><br>墨西哥：<code>MEX</code></td></tr><tr><td>nonceStr</td><td><mark style="color:red;"><code>是</code></mark></td><td><code>String</code></td><td>随机字符串<br>长度不能超过32位</td></tr><tr><td>sign</td><td><mark style="color:red;"><code>是</code></mark></td><td><code>String</code></td><td>签名<br><a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/qian-ming-suan-fa">具体参照：签名算法</a></td></tr></tbody></table>

#### 请求示例

```json
{
	"countryId": "BRA",
	"merId": "8302996847200585",
	"nonceStr": "1bc75dd17df54bb49694ed0e8a705218",
	"sign": "0D54CE20B1E9CD7E454275F5A6BC5679"
}
```

签名组装字符串

countryId=BRA\&merId=8302996847200585\&nonceStr=1bc75dd17df54bb49694ed0e8a705218\&key=9dbb958a68f04252bae26a6b6d98e0ab

&#x20;

&#x20;

### 响应参数

<table data-full-width="true"><thead><tr><th width="194">变量名</th><th width="166">类型</th><th>描述</th></tr></thead><tbody><tr><td>code</td><td><code>String</code></td><td>响应编码</td></tr><tr><td>msg</td><td><code>String</code></td><td>响应信息</td></tr><tr><td>data</td><td>Object</td><td>响应数据</td></tr><tr><td>balance</td><td>BigDecimal</td><td>商户账户余额</td></tr><tr><td>availableBalance</td><td>BigDecimal</td><td>商户账户可用余额</td></tr><tr><td>holdBal</td><td>BigDecimal</td><td>商户账户冻结金额</td></tr><tr><td>unsettleBal</td><td>BigDecimal</td><td>商户账户未结算金额</td></tr></tbody></table>

#### 响应示例

```json
{
	"code": "200",
	"msg": "success ",
	"data": {
		"balance": "345344310.24",
		"availableBalance": "345357287.80",
		"holdBal": "7060.39",
		"unsettleBal": "-20037.95"
	}
}
```


# 凭证查询

### 请求地址

<table><thead><tr><th width="138">环境名称</th><th width="607">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/search-voucher</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/search-voucher</mark></td></tr></tbody></table>

### 请求参数

| Key            | Value              |
| -------------- | ------------------ |
| `Content-Type` | `application/json` |

#### 请求体

<table data-full-width="true"><thead><tr><th width="183">变量名</th><th width="72">必填</th><th width="108">类型</th><th width="259">描述</th></tr></thead><tbody><tr><td>merId</td><td><mark style="color:red;"><code>是</code></mark></td><td><code>String</code></td><td>商户ID<br>商户ID获取路径：Supefina商户后台-商户管理-基本信息-商户ID</td></tr><tr><td>countryId</td><td><mark style="color:red;"><code>是</code></mark></td><td><code>String</code></td><td>国家编号<br>参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#afwzp">字典表-国家编号</a><br>墨西哥：<code>MEX</code></td></tr><tr><td>merOrderNo</td><td><mark style="color:red;"><code>是</code></mark></td><td><code>String</code></td><td>商户订单号</td></tr><tr><td>supefinaOrderId</td><td><mark style="color:red;"><code>是</code></mark></td><td><code>String</code></td><td>supefina订单号</td></tr><tr><td>nonceStr</td><td><mark style="color:red;"><code>是</code></mark></td><td><code>String</code></td><td>随机字符串<br>长度不能超过32位</td></tr><tr><td>sign</td><td><mark style="color:red;"><code>是</code></mark></td><td><code>String</code></td><td>签名<br><a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/qian-ming-suan-fa">具体参照：签名算法</a></td></tr></tbody></table>

#### 请求示例

```json
{
	"countryId": "BRA",
	"merId": "8302996847200585",
	"merOrderNo": "P02024051517452550031527899",
	"nonceStr": "d36d0832e81845158559c30d35a84942",
	"sign": "381DD9CFDB603CB804E5467FE55D0144",
	"supefinaOrderId": "20250623060617181000059022"
}
```

签名组装字符串

countryId=BRA\&merId=8302996847200585\&merOrderNo=P02024051517452550031527899\&nonceStr=d36d0832e81845158559c30d35a84942\&supefinaOrderId=20250623060617181000059022\&key=9dbb958a68f04252bae26a6b6d98e0ab

### 响应参数

<table data-full-width="true"><thead><tr><th width="149">变量名</th><th>类型</th><th>描述</th></tr></thead><tbody><tr><td>code</td><td><code>String</code></td><td>响应编码<br>具体参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/xiang-ying-zhuang-tai-ma">响应状态码</a></td></tr><tr><td>msg</td><td><code>String</code></td><td>响应信息</td></tr><tr><td>data</td><td>Object</td><td>响应数据</td></tr><tr><td>multiple</td><td>Boolean</td><td><p>是否多条数据</p><p>是:<code>true</code></p><p>否:<code>false</code></p></td></tr><tr><td>target</td><td>Array</td><td>目标数组</td></tr><tr><td>voucher</td><td><code>String</code></td><td><p>凭证链接</p><p>一条或者多条</p></td></tr></tbody></table>

#### 响应示例

{% code fullWidth="true" %}

```json
{
	"code": 200,
	"msg": "success",
	"data": {
		"multiple": false,
		"target": [
			{
				"voucher": "https://supefina-official-new.s3.us-west-2.amazonaws.com/PaymentVoucher-dev/20250623/CEP20250623060617181000059022.pdf"
			}
		]
	}
}
```

{% endcode %}


# 结算状态查询

### supefina结算状态请求地址

<table><thead><tr><th width="138">环境名称</th><th width="607">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/search-order</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/search-order</mark></td></tr></tbody></table>

### 请求参数

| Key            | Value              |
| -------------- | ------------------ |
| `Content-Type` | `application/json` |

#### 请求体

<table data-full-width="true"><thead><tr><th width="183">变量名</th><th width="155">字段名</th><th width="72">必填</th><th width="108">类型</th><th width="308">描述</th><th>示例值</th></tr></thead><tbody><tr><td>merId</td><td>商户编号</td><td><mark style="color:red;"><code>是</code></mark></td><td><code>String</code></td><td>商户ID<br>商户ID获取路径：Supefina商户后台-商户管理-基本信息-商户ID</td><td></td></tr><tr><td>countryId</td><td>国家编号</td><td><mark style="color:red;"><code>是</code></mark></td><td><code>String</code></td><td>国家编号<br>参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#afwzp">字典表-国家编号</a><br>墨西哥：<code>MEX</code></td><td><ul><li>MEX</li></ul></td></tr><tr><td>merOrderNo</td><td>商户订单号</td><td><mark style="color:red;"><code>是</code></mark></td><td><code>String</code></td><td>商户订单号</td><td></td></tr><tr><td>supefinaOrderId</td><td>supefina订单号</td><td><mark style="color:red;"><code>是</code></mark></td><td><code>String</code></td><td>supefina订单号</td><td></td></tr><tr><td>nonceStr</td><td>随机字符串</td><td><mark style="color:red;"><code>是</code></mark></td><td><code>String</code></td><td>随机字符串<br>长度不能超过32位</td><td></td></tr><tr><td>sign</td><td>签名</td><td><mark style="color:red;"><code>是</code></mark></td><td><code>String</code></td><td>签名<br><a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/qian-ming-suan-fa">具体参照：签名算法</a></td><td></td></tr></tbody></table>

#### 请求示例

```json
{
	"countryId": "BRA",
	"merId": "8302996847200585",
	"merOrderNo": "P02024051517452550031527899",
	"nonceStr": "11b2a7f327e946b3aa52bb713332a366",
	"sign": "507D97968509B32B224326D0F7E2047C",
	"supefinaOrderId": "20250623060617181000059022"
}
```

签名组装字符串

countryId=BRA\&merId=8302996847200585\&merOrderNo=P02024051517452550031527899\&nonceStr=11b2a7f327e946b3aa52bb713332a366\&supefinaOrderId=20250623060617181000059022\&key=9dbb958a68f04252bae26a6b6d98e0ab

### 响应参数

<table data-full-width="true"><thead><tr><th width="181">变量名</th><th width="135">类型</th><th width="281">描述</th></tr></thead><tbody><tr><td>code</td><td><code>String</code></td><td>响应编码<br>具体参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/xiang-ying-zhuang-tai-ma">响应状态码</a></td></tr><tr><td>msg</td><td><code>String</code></td><td>响应信息</td></tr><tr><td>data</td><td>Object</td><td>响应数据</td></tr><tr><td>multiple</td><td>Boolean</td><td><p>是否多条数据</p><p>是:<code>true</code></p><p>否:<code>false</code></p></td></tr><tr><td>target</td><td>Array</td><td>目标数组</td></tr><tr><td>settleStatus</td><td><code>String</code></td><td><p>结算状态</p><p><code>01</code>：已结算<br><code>02</code>：未结算</p></td></tr><tr><td>supefinaOrderId</td><td><code>String</code></td><td>supefina订单号</td></tr><tr><td>merOrderId</td><td><code>String</code></td><td>商户订单号</td></tr><tr><td>merId</td><td><code>String</code></td><td>商户编号</td></tr><tr><td>transactionType</td><td><code>String</code></td><td>交易类型<br><code>01</code>：代收<br><code>02</code>：代付</td></tr><tr><td>amount</td><td><code>String</code></td><td>订单金额</td></tr><tr><td>realityAmount</td><td><code>String</code></td><td>实收金额</td></tr><tr><td>fee</td><td><code>String</code></td><td>预收手续费</td></tr><tr><td>realityFee</td><td><code>String</code></td><td>实收手续费</td></tr><tr><td>successTime</td><td>Date</td><td>交易成功时间</td></tr><tr><td>identifier</td><td><code>String</code></td><td>付款参考标识符</td></tr></tbody></table>

#### 响应示例

```json
{
	"code": 200,
	"msg": "success",
	"data": {
		"multiple": false,
		"target": [
			{
				"supefinaOrderId": "20250623060617181000059022",
				"merOrderId": "P02024051517452550031527899",
				"merId": "8302996847200585",
				"transactionType": "02",
				"amount": "1300.00",
				"realityAmount": "1300.00",
				"fee": "70.00",
				"realityFee": "70.00",
				"successTime": "2025-06-23 03:23:56",
				"identifier": ""
			}
		]
	}
}
```


# 对账查询

只支持查询近3年数据；当地时间0点之后可查询交易时间前一天的订单；不支持支付中的订单

### 请求地址

<table><thead><tr><th width="138">环境名称</th><th width="607">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/search-reconciliation</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/search-</mark>reconciliation</td></tr></tbody></table>

### 请求参数

| Key            | Value              |
| -------------- | ------------------ |
| `Content-Type` | `application/json` |

#### 请求体

<table data-full-width="true"><thead><tr><th width="168">变量名</th><th width="72">必填</th><th width="108">类型</th><th width="259">描述</th></tr></thead><tbody><tr><td>merId</td><td><mark style="color:red;"><code>是</code></mark></td><td><code>String</code></td><td>商户ID<br>商户ID获取路径：Supefina商户后台-商户管理-基本信息-商户ID</td></tr><tr><td>countryId</td><td><mark style="color:red;"><code>是</code></mark></td><td><code>String</code></td><td>国家编号<br>参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#afwzp">字典表-国家编号</a><br>墨西哥：<code>MEX</code></td></tr><tr><td>pageNo</td><td><mark style="color:red;"><code>是</code></mark></td><td><code>int</code></td><td>当前页。默认1</td></tr><tr><td>pageSize</td><td><mark style="color:red;"><code>是</code></mark></td><td><code>int</code></td><td>每页大小。范围：1~800。默认100</td></tr><tr><td>transTime</td><td><mark style="color:red;"><code>是</code></mark></td><td><code>String</code></td><td><p>交易时间。格式：yyyyMMdd，查询当地时间前一天的交易数据。</p><p>如传递20251225则查询20251224的交易数据</p></td></tr><tr><td>transactionType</td><td><mark style="color:red;"><code>是</code></mark></td><td><code>String</code></td><td>交易类型。01代收，02代付</td></tr><tr><td>sign</td><td><mark style="color:red;"><code>是</code></mark></td><td><code>String</code></td><td><a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/qian-ming-suan-fa">具体参照：签名算法</a></td></tr></tbody></table>

#### 请求示例

```json
{
    "countryId": "MEX",			
    "merId": "8101930582444795",	
    "pageNo": "1",				
    "pageSize": "100",
    "sign": "C4E3529DA55FD69D79449F3918B19493",
    "transTime": "20250902",	
    "transactionType": "02"		
}

```

签名组装字符串

### 响应参数

<table data-full-width="true"><thead><tr><th width="193">变量名</th><th width="126">类型</th><th>描述</th></tr></thead><tbody><tr><td>code</td><td><code>String</code></td><td>响应编码<br>具体参照：<a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/xiang-ying-zhuang-tai-ma">响应状态码</a></td></tr><tr><td>msg</td><td><code>String</code></td><td>响应信息</td></tr><tr><td>data</td><td>Object</td><td>响应数据</td></tr><tr><td>pageNo</td><td><code>int</code></td><td>当前页</td></tr><tr><td>pageSize</td><td><code>int</code></td><td>分页大小</td></tr><tr><td>total</td><td><code>int</code></td><td>总分页数</td></tr><tr><td>list</td><td><code>list</code></td><td>分页数据结果集</td></tr><tr><td>transTime</td><td><code>String</code></td><td>交易时间。格式：yyyy-mm-dd HH:mm:ss</td></tr><tr><td>transactionType</td><td><code>String</code></td><td><code>01</code>：代收<br><code>02</code>：代付</td></tr><tr><td>merId</td><td><code>String</code></td><td>商户ID</td></tr><tr><td>merOrderNo</td><td><code>String</code></td><td>商户订单号</td></tr><tr><td>supefinaOrderId</td><td><code>String</code></td><td>supefina订单号</td></tr><tr><td>transactionStatus</td><td><code>String</code></td><td><p>交易状态</p><p><a href="/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#kxzkj">字典表——交易订单状态</a></p></td></tr><tr><td>orderAmount</td><td>BigDecimal</td><td>订单金额</td></tr><tr><td>realityAmount</td><td>BigDecimal</td><td>实收金额</td></tr><tr><td>fee</td><td>BigDecimal</td><td>预收手续费</td></tr><tr><td>realityFee</td><td>BigDecimal</td><td>实收手续费</td></tr></tbody></table>

#### 响应示例

```json
{
    "code": "200",
    "msg": "success ",
    "data": {
        "pageNo": 1,				
        "pageSize": 100,			
        "total": 1,					
        "list": [
            {
                "transDate": "2025-09-01 07:51:41",
                "transTime": "2025-09-01 07:51:41",	
                "transactionType": "02",
                "merId": "8101930582444795",
                "merOrderNo": "R20250901183100001",	
                "supefinaOrderId": "2025090105020150525a9039dcd4c",	
                "transactionStatus": "01",			
                "orderAmount": "9800.00",			
                "realityAmount": "9800.00",			
                "fee": "990.00",					
                "realityFee": "990.00"				
            },
            {
                "transDate": "2025-09-01 07:52:57",
                "transTime": "2025-09-01 07:52:57",
                "transactionType": "02",
                "merId": "8101930582444795",
                "merOrderNo": "R20250901183100002",
                "supefinaOrderId": "202509010502015cb7a55e4872340",
                "transactionStatus": "01",
                "orderAmount": "4690.00",
                "realityAmount": "4690.00",
                "fee": "479.00",
                "realityFee": "479.00"
            }
        ]
    }
}
```


# 字典和资源

响应状态码，字典表，SDK，各国家代付银行列表等。

{% content-ref url="/pages/j56ENY9y4TEhx8ssOv8a" %}
[响应状态码](/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/xiang-ying-zhuang-tai-ma)
{% endcontent-ref %}

{% content-ref url="/pages/17IKBEvxR4cpZue8BRdD" %}
[字典表](/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao)
{% endcontent-ref %}

{% content-ref url="/pages/8YRD2SP9Grp9K4fNoIZS" %}
[下载](/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/xia-zai)
{% endcontent-ref %}


# 响应状态码

<table><thead><tr><th width="128">状态码</th><th>描述</th></tr></thead><tbody><tr><td>200</td><td>请求成功</td></tr><tr><td>201</td><td>数据不存在</td></tr><tr><td>400</td><td>请求参数错误</td></tr><tr><td>500</td><td>请求失败</td></tr><tr><td>501</td><td>商户不存在</td></tr><tr><td>502</td><td>商户已禁用</td></tr><tr><td>503</td><td>智能路由异常</td></tr><tr><td>504</td><td>获取渠道和账户异常</td></tr><tr><td>505</td><td>区间最低金额对应的手续费小于区间最低金额</td></tr><tr><td>506</td><td>手续费小于订单金额（固定金额）</td></tr><tr><td>507</td><td><p>风险管控/限额问题：</p><ul><li>没有设置限额 </li><li>当前时间不能交易</li><li>单笔金额超过限额 </li><li>当日金额超过限额 </li><li>当月金额超过限额</li></ul></td></tr><tr><td>508</td><td>服务异常</td></tr><tr><td>509</td><td>服务异常</td></tr><tr><td>510</td><td>服务异常</td></tr><tr><td>511</td><td>服务异常</td></tr><tr><td>512</td><td>服务异常</td></tr><tr><td>513</td><td>服务异常</td></tr><tr><td>514</td><td>服务异常</td></tr><tr><td>515</td><td>商户密钥未设置</td></tr><tr><td>516</td><td>签名验证失败</td></tr><tr><td>517</td><td>收银台代收订单已过期</td></tr><tr><td>518</td><td>未配置且未传入回调地址</td></tr><tr><td>519</td><td>冻结金额错误</td></tr><tr><td>520</td><td>冻结账户不存在</td></tr><tr><td>521</td><td>账户可用金额不足,冻结失败</td></tr><tr><td>522</td><td>不存在余额充足且状态启用的账户</td></tr><tr><td>523</td><td>不存在支持此支付产品且状态启用的渠道</td></tr><tr><td>524</td><td>匹配渠道余额不足或账户状态异常</td></tr><tr><td>525</td><td>不存在已启用路由的支付产品</td></tr><tr><td>526</td><td>匹配渠道未启用路由</td></tr><tr><td>527</td><td>匹配账户代收/代付被冻结</td></tr></tbody></table>


# 字典表

### 国家编号（countryId） <a href="#afwzp" id="afwzp"></a>

<table data-full-width="true"><thead><tr><th width="137">id</th><th width="594">desc</th></tr></thead><tbody><tr><td>MEX</td><td>墨西哥</td></tr><tr><td>COL</td><td>哥伦比亚</td></tr><tr><td>PER</td><td>秘鲁</td></tr><tr><td>CHL</td><td>智利</td></tr><tr><td>ARG</td><td>阿根廷</td></tr><tr><td>BRA</td><td>巴西</td></tr><tr><td>ECU</td><td>厄瓜多尔</td></tr></tbody></table>

### 支付产品（payProduct） <a href="#mfocd" id="mfocd"></a>

墨西哥

<table data-full-width="true"><thead><tr><th width="137">id</th><th width="603">desc</th></tr></thead><tbody><tr><td>03</td><td>Cash</td></tr><tr><td>15</td><td>SPEI/Clabe号</td></tr><tr><td>16</td><td>银行卡号</td></tr><tr><td>18</td><td>Card</td></tr><tr><td>32</td><td>oxxo</td></tr></tbody></table>

秘鲁

<table data-full-width="true"><thead><tr><th width="137">id</th><th width="603">desc</th></tr></thead><tbody><tr><td>03</td><td>Cash</td></tr><tr><td>12</td><td>Transfer（Payin）</td></tr><tr><td>23</td><td>Wallet</td></tr><tr><td>20</td><td>Transfer（Payout）</td></tr></tbody></table>

智利

<table data-full-width="true"><thead><tr><th width="140">id</th><th width="657">desc</th></tr></thead><tbody><tr><td>03</td><td>Cash</td></tr><tr><td>12</td><td>Transfer</td></tr><tr><td>23</td><td>Wallet</td></tr><tr><td>21</td><td>Card</td></tr><tr><td>05</td><td>All-Checkout</td></tr></tbody></table>

哥伦比亚

<table data-full-width="true"><thead><tr><th width="141">id</th><th width="671">desc</th></tr></thead><tbody><tr><td>03</td><td>Cash</td></tr><tr><td>12</td><td>PSE/Transfer</td></tr><tr><td>05</td><td>All-Checkout</td></tr><tr><td>08</td><td>Transfiya</td></tr><tr><td>28</td><td>Bancolombia</td></tr><tr><td>31</td><td>Bre-B</td></tr></tbody></table>

巴西

<table data-full-width="true"><thead><tr><th width="145">id</th><th width="681">desc</th></tr></thead><tbody><tr><td>24</td><td>PIX</td></tr></tbody></table>

厄瓜多尔

<table data-full-width="true"><thead><tr><th width="144">id</th><th width="688">desc</th></tr></thead><tbody><tr><td>03</td><td>Cash</td></tr><tr><td>12</td><td>Transfer</td></tr><tr><td>21</td><td>Card</td></tr><tr><td>23</td><td>Wallet</td></tr></tbody></table>

阿根廷

<table data-full-width="true"><thead><tr><th width="144">id</th><th width="688">desc</th></tr></thead><tbody><tr><td>12</td><td>Transfer（Payout）</td></tr><tr><td>29</td><td>Debin</td></tr></tbody></table>

### 货币（currency）

<table data-full-width="true"><thead><tr><th width="137">id</th><th width="603">desc</th></tr></thead><tbody><tr><td>COP</td><td>哥伦比亚比索</td></tr><tr><td>PEN</td><td>秘鲁索尔</td></tr><tr><td>MXN</td><td>墨西哥比索</td></tr><tr><td>CLP</td><td>智利比索</td></tr><tr><td>BRL</td><td>巴西雷亚尔</td></tr><tr><td>USD</td><td>厄瓜多尔美元</td></tr></tbody></table>

### 账户类型（代付）（accountType）

<table data-full-width="true"><thead><tr><th width="137">id</th><th width="603">desc</th></tr></thead><tbody><tr><td>00</td><td>活期账户</td></tr><tr><td>01</td><td>储蓄账户</td></tr></tbody></table>

### 客户识别号类型（customerIdentificationType）

<table data-full-width="true"><thead><tr><th width="137">id</th><th width="603">desc</th></tr></thead><tbody><tr><td>00</td><td>身份证</td></tr><tr><td>01</td><td>外国人身份证</td></tr><tr><td>02</td><td>税号</td></tr><tr><td>03</td><td>护照</td></tr><tr><td>04</td><td>离境证</td></tr><tr><td>05</td><td>军官证</td></tr><tr><td>06</td><td>其他</td></tr></tbody></table>

### 交易订单状态（transactionStatus） <a href="#kxzkj" id="kxzkj"></a>

<table data-full-width="true"><thead><tr><th width="137">id</th><th width="603">desc</th></tr></thead><tbody><tr><td>00</td><td>支付中</td></tr><tr><td>01</td><td>交易成功</td></tr><tr><td>02</td><td>交易失败</td></tr><tr><td>03</td><td>支付拒绝</td></tr><tr><td>04</td><td>下单失败</td></tr><tr><td>05</td><td>退款</td></tr></tbody></table>

### 交易类型（transactionType）

<table data-full-width="true"><thead><tr><th width="137">id</th><th width="603">desc</th></tr></thead><tbody><tr><td>01</td><td>代收</td></tr><tr><td>02</td><td>代付</td></tr></tbody></table>


# 下载

### 代码Demo

[java版本](https://supefina-official-new.s3.dualstack.us-west-2.amazonaws.com/document/supefina-demo.rar)

### 签名SDK

[签名SDK下载](https://supefina-official.s3.us-west-2.amazonaws.com/supefina-sign-1.0.0.jar)

***

### 墨西哥银行列表

{% file src="/files/c4TbLZOnWEKR0T3EQQbL" %}

***

### 哥伦比亚银行列表

{% file src="/files/WIYul67mhFddJ4sZAclW" %}

### 秘鲁银行列表

{% file src="/files/wZV0Lys6EjKn7CJeQWsv" %}

### 智利银行列表<br>

{% file src="/files/onjCdmwzj5d3uqVysbv5" %}

### 厄瓜多尔银行列表

{% file src="/files/h45wSwRwmQhUNEJa1RWh" %}

### 阿根廷银行列表

{% file src="/files/YCvgCQ8aBLANRgZox30i" %}


# 测试参数

## 墨西哥

### SPEI

测试1：

Merchant ID：8302921196770572

Merchant Key：de53650e1a6b494087d8c472516cc1cb

测试2：

Merchant ID：8302035388384581

Merchant Key：47ac984f5b0748cb9d6529a539f4065b

### Cash

Merchant ID：8302109931230575

Merchant Key：10b8a891ff6a479e8135f3367c17e87d

### Card

测试1：

Merchant ID：8302035388384581<mark style="color:red;">（游戏行业）</mark>

Merchant Key：47ac984f5b0748cb9d6529a539f4065b

测试2：

Merchant ID：8102048462634665<mark style="color:red;">（电商行业）</mark>

Merchant Key：cf5fe06851e84cd7ab227dbbf16f4bf1

### OXXO

Merchant ID：8102401785904873

Merchant Key：d0e38ad086ea48e4a81c502d5194b953

## 哥伦比亚

Merchant ID：8302490290654651

Merchant Key：e8548e70a8ba4a658b0da4ef50600d42

## 秘鲁

测试1：

Merchant ID：8302258550224656<mark style="color:red;">（代收：transfer/Cash/wallet和代付：transfer）</mark>

Merchant Key：10c44658d50e4d0da0fe1e5f7c9074a7

测试2：

Merchant ID：8302281133604568<mark style="color:red;">（代收：transfer/Cash和代付：transfer）</mark>

Merchant Key：db7cbf4b354f480a9ea8b9635ccd4ae2

测试3：

Merchant ID：8302536166434654<mark style="color:red;">（代收：transfer/Cash/wallet）</mark>

Merchant Key：7f98818fe70f48debb996de7dc8f4424

## 智利

Merchant ID：8301893137974691（<mark style="color:red;">代收：transfer/Cash/Card和代付：transfer</mark>）

Merchant Key：764e7f81217541658f1ccc993b39d9e3

Merchant ID：8101386220950494（<mark style="color:red;">代收：wallet/all-checkout和代付：transfer</mark>）

Merchant Key：bb01dd04d967425ab194fff9fe8a9501

## 巴西

Merchant ID：8302996847200585

Merchant Key：9dbb958a68f04252bae26a6b6d98e0ab

## 厄瓜多尔

Merchant ID：8302748528064643

Merchant Key：bb01dd04d967425ab194fff9fe8a9501

## 阿根廷

Merchant ID：8302709349110631

Merchant Key：e200749bb5914603ad05a03d9b1b6445


# 更新记录

## 2025-**10-28** <a href="#id-2023-7-7" id="id-2023-7-7"></a>

**墨西哥代付银行列表变更，变更如下：**

* 新增支持银行&#x20;

<table><thead><tr><th width="96">bankId</th><th width="170.9091796875">bankName</th></tr></thead><tbody><tr><td>2001</td><td>BANXICO</td></tr><tr><td>90903</td><td>CoDi Valida</td></tr><tr><td>90734</td><td>FINCO PAY</td></tr><tr><td>40167</td><td>HEY BANCO</td></tr><tr><td>90721</td><td>ALBO</td></tr><tr><td>90729</td><td>Dep y Pag Dig</td></tr></tbody></table>

* 原银行名称调整&#x20;

90661，原名称ALTERNATIVOS**调整为Klar**

90732，原名称Peibo**调整为PEIBO**（小写改为大写）

## 2025-**7-25** <a href="#id-2023-7-7" id="id-2023-7-7"></a>

修正示例

添加签名组装字符串

哥伦比亚、智利、巴西 响应参数添加了orderExpirationTime 渠道收银台过期时间

秘鲁 Transfer、Cash、Wallet 添加 description 参数

## 2025-**7-18** <a href="#id-2023-7-7" id="id-2023-7-7"></a>

&#x20;修正全部国家的回调通知的identifier字段和描述

## 2025-6-13 <a href="#id-2023-7-7" id="id-2023-7-7"></a>

智利放款接口增加 bankName

## 2025-6-11 <a href="#id-2023-7-7" id="id-2023-7-7"></a>

修改访问沙箱环境的地址从ip改成域名

## 2025-2-11 <a href="#id-2023-7-7" id="id-2023-7-7"></a>

#### 修订记录生效日期：2025-2-11

#### 【新增】

巴西代收&代付`customerIdentification`用户证件号由必填调整为非必填。

哥伦比亚代付产品`Transfer`新增必填参数`description`、`bankId`。

## 2025-1-20 <a href="#id-2023-7-7" id="id-2023-7-7"></a>

#### 修订记录生效日期：2025-1-20

#### 【新增】

* 智利代收新增字段

`customerName`

`lastName`

`customerIdentification`

`customerIdentificationType`

* 智利代付新增字段

`customerIdentificationType`

`accountType`新增类型 `07`VISTA ，`08`SALARY ACCOUNT

* 智利代付银行列表新增以下银行：

<table><thead><tr><th width="119">bankId</th><th width="181">bankName</th><th width="258">Note</th></tr></thead><tbody><tr><td>027</td><td>Itau-Corpbanca</td><td>新增</td></tr><tr><td>031</td><td>Hsbc Bank</td><td>新增</td></tr><tr><td>057</td><td>Banco Paris</td><td>新增</td></tr><tr><td>0152</td><td>Prepago Los Heroes</td><td>新增</td></tr><tr><td>0738</td><td>Global 66</td><td>新增</td></tr></tbody></table>

## 2025-1-14 <a href="#id-2023-7-7" id="id-2023-7-7"></a>

#### 修订记录生效日期：2025-1-15

墨西哥代收Card支付请求参数新增`customerName`和`description`

## 2024-12-25 <a href="#id-2023-7-7" id="id-2023-7-7"></a>

#### 修订记录生效日期：2024-12-25

[哥伦比亚代付](/huan-ying-shi-yong-supefina-de-api-wen-dang/dai-fu/ge-lun-bi-ya/transfiya) `Transfiya`支付请求参数`accountType`设置为**必填**.

## 2024-12-23 <a href="#id-2023-7-7" id="id-2023-7-7"></a>

#### 修订记录生效日期：2024-12-24

#### 【新增】

哥伦比亚新增代收支付产品[`Bancolombia`](/huan-ying-shi-yong-supefina-de-api-wen-dang/dai-shou/ge-lun-bi-ya)  （payProduct=28）

## 2024-11-29 <a href="#id-2023-7-7" id="id-2023-7-7"></a>

#### 修订记录生效日期：2024-11-29

#### 【新增】

[交易查询](/huan-ying-shi-yong-supefina-de-api-wen-dang/cha-xun/jiao-yi-cha-xun)接口响应参数新增`stampTime`、 `clave`、`errorMsg`

<figure><img src="https://3631787624-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FuukVORWjXBgcGu8MirPR%2Fuploads%2FGbKShwcwVgDEbDGZ3wtR%2Fimage.png?alt=media&amp;token=60ed6541-cdd1-4d07-b206-64f1904ebae6" alt=""><figcaption></figcaption></figure>

## 2024-11-26 <a href="#id-2023-7-7" id="id-2023-7-7"></a>

#### 修订记录生效日期：2024-11-26

#### 【新增】

[厄瓜多尔代付](/huan-ying-shi-yong-supefina-de-api-wen-dang/dai-fu/e-gua-duo-er)Transfer的payProduct修订为12，即payProduct=12；

原Transfer调整为EC Transfer，payProduct=25。

## 2024-11-19 <a href="#id-2023-7-7" id="id-2023-7-7"></a>

#### 修订记录生效日期：2024-11-20

#### 【新增】

* [哥伦比亚](/huan-ying-shi-yong-supefina-de-api-wen-dang/dai-shou/ge-lun-bi-ya)代收新增参数`description`

## 2024-11-13 <a href="#id-2023-7-7" id="id-2023-7-7"></a>

#### 修订记录生效日期：2024-11-13

#### 【新增】

* 各国家[测试参数](/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/ce-shi-can-shu)（包含测试商户ID和Key信息）
* 路径：`字典和资源`——`测试参数`

## 2024-10-9 <a href="#id-2023-7-7" id="id-2023-7-7"></a>

#### 修订记录生效日期：2024-10-9

#### 【新增】

* 巴西支付产品PIX新增customerIdentification参数(cpf)

<table><thead><tr><th>变量名</th><th width="288">类型</th><th>必填</th><th>描述</th></tr></thead><tbody><tr><td>customerPhone</td><td>String</td><td>否</td><td>手机号</td></tr><tr><td>customerIdentification</td><td>String</td><td>是</td><td>用户证件号（CPF）</td></tr></tbody></table>

## 2024-10-8 <a href="#id-2023-7-7" id="id-2023-7-7"></a>

#### 修订记录生效日期：2024-10-8

#### 【新增】

* 墨西哥支付产品[Card](/huan-ying-shi-yong-supefina-de-api-wen-dang/dai-shou/mo-xi-ge/card)新增卡信息的测试数据

## 2024-9-27 <a href="#id-2023-7-7" id="id-2023-7-7"></a>

#### 修订记录生效日期：2024-10-8

#### 【新增】

* 墨西哥支付产品[Card](/huan-ying-shi-yong-supefina-de-api-wen-dang/dai-shou/mo-xi-ge/card)支付请求新增以下参数：

| 变量名                  | 类型      | 必填 | 描述                                                                                                                                                |
| -------------------- | ------- | -- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| productName          | String  | 是  | 商品名称 最大50个字符                                                                                                                                      |
| productQuantity      | Integer | 否  | 商品数量 范围\[0,1000]                                                                                                                                  |
| email                | String  | 否  | 顾客邮箱 3-256个字符 **电商行业必传**                                                                                                                          |
| receiverAddressMain  | String  | 否  | 收件地址，街道 0-50个字符 **电商行业必传**                                                                                                                        |
| receiverAddressExtra | String  | 否  | 收件地址，小区，门牌号 0-50个字符 **电商行业必传**                                                                                                                    |
| receiverCity         | String  | 否  | 收件人城市 0-50个字符，可包括空格、连字符、撇号、逗号和点 **电商行业必传**                                                                                                        |
| receiverProvince     | String  | 否  | 收件人所在省 0-40个字符 参数：<https://en.wikipedia.org/wiki/ISO_3166-2> 例：NY **电商行业必传**                                                                      |
| receiverCountry      | String  | 否  | 收件人国家 参照：[字典表-国家编号](https://docs.supefina.net/huan-ying-shi-yong-supefina-de-api-wen-dang/zi-dian-he-zi-yuan/zi-dian-biao#afwzp) 例：BRA **电商行业必传** |
| receiverZipCode      | String  | 否  | 邮政编码 0-12个字母或数字 **电商行业必传**                                                                                                                        |
| receiverPhone        | String  | 否  | 收件人电话 5-20个字符，区添加区号。如：+1 111111111 **电商行业必传**                                                                                                     |
| alias                | String  | 否  | 用户名 0-60个字符 **游戏行业必传**                                                                                                                            |
| newUser              | Boolean | 否  | 是否一个月内的用户 true：新用户 false：老用户 **游戏行业必传**                                                                                                           |
| hasDispute           | Boolean | 否  | 是否有过历史争议，包含以下任一条： 1、利用作弊工具、游戏漏洞等进行不正当行为； 2、骚扰其他玩家、进行恶意行为或破坏游戏体验的行为； 3、玩家有不当言论、违反游戏规则、频繁被举报； true：有过 false：没有 **游戏行业必传**                           |
| hasRefund            | Boolean | 否  | 是否有过退款 true：有过 false：没有 **游戏行业必传**                                                                                                                |
| hasSingedLong        | Boolean | 否  | 注册时间是否超过三个月 true：超过 false：未超过 **游戏行业必传**                                                                                                          |