代付账户类型
| 值 | 说明 |
|---|---|
| 0 | 活期账户(Corriente) |
| 1 | 储蓄账户(Ahorro) |
TIP
如果收款人银行为电子钱包，账户类型请使用1储蓄账户(Ahorro)。
代付收款人证件类型
idType 值 | 缩写 | 说明 |
|---|---|---|
| 1 | CC | 公民身份证 |
| 2 | CE | 外国人身份证 |
| 3 | TI | 未成年人身份证 |
| 4 | NIT | 纳税人识别号 |
| 5 | PA | 护照 |
TIP
关于idType字段，请以收款银行账户开设时使用的实际证件类型为准，不一致会导致代付失败。
举例：如果用户开户使用的是NIT证件，发起代付是透传的证件类型为CC, 此时会导致代付失败。
代付银行列表
TIP
银行支持列表以生产环境实际支持情况为准，建议您在进入生产环境前，调用我们的银行列表查询接口来确认生产银行支持情况。
| bankId | bankCode | bankName | bankType |
|---|---|---|---|
| 2 | 1059 | BANCAMIA S.A. | BANK |
| 3 | 1040 | BANCO AGRARIO | BANK |
| 4 | 1052 | BANCO AV VILLAS | BANK |
| 5 | 1013 | BANCO BBVA COLOMBIA S.A. | BANK |
| 6 | 1032 | BANCO CAJA SOCIAL | BANK |
| 7 | 1066 | BANCO COOPERATIVO COOPCENTRAL | BANK |
| 8 | 1558 | BANCO CREDIFINANCIERA | BANK |
| 9 | 1051 | BANCO DAVIVIENDA | BANK |
| 10 | 1001 | BANCO DE BOGOTA | BANK |
| 11 | 1023 | BANCO DE OCCIDENTE | BANK |
| 12 | 1062 | BANCO FALABELLA | BANK |
| 13 | 1012 | BANCO GNB SUDAMERIS | BANK |
| 15 | 1060 | BANCO PICHINCHA S.A. | BANK |
| 16 | 1002 | BANCO POPULAR | BANK |
| 17 | 1065 | BANCO SANTANDER COLOMBIA | BANK |
| 18 | 1069 | BANCO SERFINANZA | BANK |
| 19 | 1303 | BANCO UNION antes GIROS | BANK |
| 20 | 1007 | BANCOLOMBIA | BANK |
| 21 | 1061 | BANCOOMEVA S.A. | BANK |
| 22 | 1283 | CFA COOPERATIVA FINANCIERA | BANK |
| 23 | 1009 | CITIBANK | BANK |
| 24 | 1370 | COLTEFINANCIERA | BANK |
| 25 | 1292 | CONFIAR COOPERATIVA FINANCIERA | BANK |
| 26 | 1291 | COOFINEP COOPERATIVA FINANCIERA | BANK |
| 27 | 1289 | COTRAFA | BANK |
| 29 | 1551 | DAVIPLATA | EWALLET |
| 30 | 1637 | IRIS | BANK |
| 33 | 2209 | NEQUI | EWALLET |
| 34 | 1019 | SCOTIABANK COLPATRIA | BANK |
| 35 | 1067 | Mibanco S.A. | BANK |
| 37 | 1063 | Banco Finandina S.A | BANK |
| 38 | 1064 | Banco Multibank S.A. | BANK |
| 39 | 1058 | Banco Procredit Colombia | BANK |
| 40 | 1053 | Banco W S.A | BANK |
| 41 | 1031 | Bancóldex S.A. | BANK |
| 42 | 1121 | Financiara Juriscoop S.A. Compañía de Financiamiento | BANK |
| 43 | 1014 | Itaú* (Helm bank) | BANK |
| 44 | 1071 | Banco J.P. Morgan Colombia S.A. | BANK |
| 45 | 1047 | Banco Mundo Mujer | BANK |
代付订单状态枚举
| 值 | 说明 | 备注 |
|---|---|---|
| PROCESSING | 处理中 | |
| WAITING | 路由中 | |
| PAYING | 支付中 | |
| SUCCESS | 成功 | 订单终态 |
| FAIL | 失败 | 订单终态 |
| CANCEL | 驳回/取消 | 订单终态 |
TIP
注意，在处理来自Cashy的回调或者查询结果时，应对订单状态进行精确地判断。只有终态结果才能认为代付订单明确成功/失败。
代付订单状态描述
| 值 | 说明 |
|---|---|
| GATEWAY_TIMEOUT | 支付网关超时 |
| AMOUNT_ERROR | 金额错误 |
| PARAM_IS_NULL | 必要参数为空 |
| NONSUPPORT_PAY_CASH | 不支持现金支付 |
| NONSUPPORT_CREDIT_CARD | 不支持信用卡 |
| APPID_ERROR | 应用ID错误 |
| PARAM_ERROR | 参数错误 |
| SYSTEM_EXCEPTION | 上游系统异常 |
| PAYMENT_TRANSACTION_EXCEPTION | 付款交易异常 |
| PAYMENT_QUERY_FAIL | 支付查询失败 |
| BANK_NAME_ERROR | 银行名称错误 |
| BANK_CODE_ERROR | 银行编码错误 |
| BANK_ACCOUNT_ERROR | 银行账号错误 |
| PAYMENT_OFFSET | 支付冲正 |
| INFO_STRUCTURE_INVALID | 客户信息错误 |
| OUT_ACCOUNT_BALANCE | 超出账户金额限制 |
| ACCOUNT_NOT_EXIST | 账号不存在 |
| INVALID_ACCOUNT_NUMBER | 无效的账户号码 |
| ACCOUNTS_NOT_AUTHORISED_FOR_CREDITING | 未授权记入的账户 |
| NUMBER_AND_DOCUMENTS_NOT_MATCH | 账号和证件不匹配 |
| DOCUMENTS_INVALID | 证件号无效 |
| ACCOUNT_NOT_ENABLED | 帐户未启用 |
| BLOCKED_ACCOUNTS | 封锁的账户 |
| ACCOUNT_TYPE_NOT_VALID_FOR_TARGET_BANK | 账户类型对目标银行无效 |
| EACH_PAYMENT_LIMIT_EXCEEDED | 支付额度超过单次支付最大限额 |
| DAILY_PAYMENT_LIMIT_EXCEEDED | 支付额度超过日累计支付最大限额 |
| MONTHLY_PAYMENT_LIMIT_EXCEEDED | 支付额度超过月累计支付最大限额 |
| YEARLY_PAYMENT_LIMIT_EXCEEDED | 支付额度超过年累计支付最大限额 |
| AMOUNT_TOO_SMALL | 支付额度过低被银行拒绝 |
| ACCOUNTING_BILL_ERROR | 支付账单错误 |
| PHONE_NUMBER_INVALID | 手机号无效 |
| EMAIL_INVALID | 邮箱无效 |
| NAME_INVALID | 姓名无效 |
| PAYMENT_REJECTED_BY_BANK | 付款交易被银行拒绝 |
| UNKNOWN_ERROR | 未知错误 |
| CHANNEL_IB_TRY_AGAIN_LATER | 渠道异常，可稍后重试 |
代收用户类型
| userType | 缩写 | 说明 |
|---|---|---|
| 1 | NATURAL | NATURAL |
| 2 | LEGAL | LEGAL |
TIP
只有当idCard为NIT时，userType为LEGAL，其他情况都是NATURAL。
代收付款人证件类型
idType | 简称 | 说明 |
|---|---|---|
| 1 | CC | 公民身份证 |
| 2 | CE | 外国人身份证 |
| 3 | TI | 未成年人身份证 |
| 4 | NIT | 纳税人识别号 （2-14位数字） |
| 5 | PA | 护照 |
- CC:
Cedula de Ciudadania(公民身份证)是哥伦比亚用于居民身份证明的主要文件。它是居民用于证明身份和居住权的主要法定文件。 - CE:
Cedula de Extranjeria(外国人身份证)是用于在哥伦比亚境内居住的外国人的身份证明文件。它是外国人证明其身份和合法居留的主要文件。 - TI:
Tarjeta de ldentidad(身份证)是哥伦比亚用于证明未成年人身份的身份证明文件，它是18岁以下未成年人证明身份和享受权益的主要文件。 - NIT:
Numero deldentificacion Tributaria(纳税人识别号)是用于标识个人或法人实体的纳税人识别号码。在商业和税务领域中，NIT是用于识别纳税人的唯一标识。 - PA:
Pasaporte(护照) 是一种国际旅行证件，用于证明持有人的身份和国籍，并在国际旅行中被认可。它通常由国家的外交部门或领事馆颁发。
代收PayType枚举
| 支付方式 | payType | 类型说明 | 支持情况 |
|---|---|---|---|
| PayDesk | 153 | 聚合 | 暂不支持payin接口 |
| NEQUI_PUSH | 154 | Nequi-Push支付 | 暂不支持payin接口 |
| NEQUI | 155 | Nequi钱包支付 | |
| EFECTY | 156 | Efecty现金支付 | |
| PSE | 157 | PSE线上转账 | |
| BANCOLOMBIA_BUTTON | 158 | Bancolombia网银转账 | 暂不支持payin接口 |
| BANCOLOMBIA_CASH | 159 | Bancolombia-现金 | 暂不支持payin接口 |
| COBRU | 161 | Cobru扫码支付 | 暂不支持payin接口 |
| CORRESPONSAL_BANCOLOMBIA | 162 | 现金支付 |
代收订单状态枚举
| 值 | 说明 | 备注 |
|---|---|---|
| PAYING | 支付中 | |
| SUCCESS | 成功 | 订单终态 |
| FAIL | 失败 | 订单终态 |
TIP
注意，在处理来自Cashy的回调或者查询结果时，应对订单状态进行精确地判断。只有终态结果才能认为代收订单明确成功。
收银台代收订单状态枚举
| 值 | 说明 |
|---|---|
| PAYING | 支付中 |
| SUCCESS | 成功 |
常见报错信息
| 值 | 含义 | 覆盖国家 |
|---|---|---|
Permission_denied | 请求地址未授权（请求地址错误，检查下请求地址是否正确） | 全部 |
System_error | 系统错误 | 全部 |
System_busy | 系统繁忙（重试） | 全部 |
System_Maintenance | 系统维护（重试） | 全部 |
MerchantId_is_null | 商户Id为空 | 全部 |
Sign_verify_error | 商户签名验证错误 | 全部 |
RequestMethod_not_post | 不是POST请求 | 全部 |
RequestContentType_not_json | 不是application/json请求 | 全部 |
RequestBody_is_null | 请求体为空 | 全部 |
MerchantId_not_Number | 商户Id非数字 | 全部 |
MerchantId_is_error | 商户Id错误 | 全部 |
Request_ip_notWhiteList | 请求ip非白名单 | 全部 |
Params_jsonFormat_error | 请求体json格式错误 | 全部 |
Params_xxx_Required | 某参数未传递,请检查是否漏传。 | 全部 |
Params_xxx_error | 某参数错误，请检查参数是否合法。 | 全部 |
Params_accountNo_Format_isIncorrect | 银行账号格式不正确(银行卡号长度与银行不匹配) | 部分国家 |
Merchant_amount_notEnough | 商户余额不足 | 全部 |
Merchant_not_enabled | 商户未启用 | 全部 |
Merchant_not_exist | 商户不存在 | 全部 |
Params_order_notExist | 该平台订单号不存在 | 全部 |
Params_mchOrderNo_notExist | 该商户订单号不存在 | 全部 |
Params_mchOrderNo_repeat | 商户订单号重复 | 全部 |
Params_email_format_invalid | 邮箱格式错误 | 全部 |
Params_bankId_Disable | 此银行暂时不可用 | 全部 |
Params_IdCard_format_invalid | 证件号格式错误 | 全部 |
Params_idCard_Format_incorrect | 证件号格式错误 | 部分国家 |
Channel_Maintenance_time | 通道维护中 ，测试环境可联系技术支持 | 全部 |
Tran_risk_intercept | 交易风控拦截 ，检查金额是否满足限制条件 | 全部 |
COLLECTION_ACCOUNT_DAY_LIMIT | 收款卡号达到日限制上限次数 | 全部 |
COLLECTION_NAME_DAY_LIMIT | 收款姓名达到日限制上限次数 | 全部 |
LIMIT_MIN_AMOUNT | 订单金额低于最小金额限制 | 全部 |
LIMIT_MAX_AMOUNT | 订单金额高于最大金额限制 | 全部 |
BLACK_LIST_USER_LIMIT | 用户属于黑名单限制 | 全部 |
Params_realName_not_contain_Chinese | 账户名字不允许包含中文 | 全部 |
Params_accountName_not_contain_Chinese | 账户名字不允许包含中文 | 全部 |
Params_accountNo_Clabe_Invalidate | Clabe无效 | 墨西哥 |
Params_email_format_invalid | 邮箱格式无效 | 墨西哥 |
Params_email_length_exceeds<64>characters | 邮箱长度超过了64位（应当保证邮箱长度低于64位） | 全部 |
Params_accountName_Maximum<40>characters | 代付（受益人）收款人姓名过长 | 部分国家，MX为40 |
Params_idType_Exists_idCard_CPF_Invalidate | CPF证件号格式无效 | 巴西 |