API 收款交易

请求

收款API使商户能够从客户启动支付交易。此API支持各种支付方式，包括PIX和巴西市场的其他数字支付解决方案。

请求路径：

沙盒: https://sandbox-gateway.smilepayz.com/v2.0/transaction/pay-in
生产: https://gateway.smilepayz.com/v2.0/transaction/pay-in

请求头参数

字段	必需	类型	描述
Content-Type	M	String	HTTP内容类型规范固定值：application/json 正确请求解析必需
X-TIMESTAMP	M	String	ISO 8601日期时间格式，带时区偏移格式：yyyy-MM-ddTHH:mm:ss±HH:mm 示例：2020-12-17T10:55:00+07:00 注意：必须是当前服务器时间，误差±5分钟内
X-SIGNATURE	M	String	请求认证的数字签名参见签名生成
X-PARTNER-ID	M	String	平台分配的唯一商户标识符格式：字母数字字符串用于商户认证和交易路由请输入merchantID

请求体参数

字段	必需	类型	描述
orderNo	M	String(32)	唯一交易标识符格式：字母数字字符串（仅数字和字母）长度：6-32个字符用于交易跟踪和参考
purpose	M	String(64)	交易目的或描述格式：UTF-8编码字符串最大长度：64个字符用于交易识别和报告
merchant	M	Object	商户信息容器包含商户识别和业务详情参见商户模型
merchantId	M	String	平台分配的主要商户标识符格式：字母数字字符串用于商户认证和交易路由
merchantName	O	String	商户业务名称或显示名称格式：UTF-8编码字符串用于交易识别和报告
subMerchantId	O	String	多级商户结构的子商户标识符格式：字母数字字符串用于子商户交易路由
subMerchantName	O	String	子商户业务名称或显示名称格式：UTF-8编码字符串用于子商户识别和报告
money	M	Object	带货币规格的交易金额详情包含支付金额和货币信息参见金额模型
currency	M	String	ISO 4217货币代码规范固定值：BRL（巴西雷亚尔）确定支付处理规则和结算货币
amount	M	Number	最小货币单位的交易金额格式：整数值示例：200表示BRL 200.00 范围：100-999999999
payer	M	Object	付款人信息容器包含客户识别和支付详情参见付款人模型
pixAccount	M	String	PIX账户标识符（CPF或CNPJ号码）格式：11位数字（CPF）或14位数字（CNPJ）示例："48982488880" 用于PIX支付处理
paymentMethod	M	String	支付方式规范固定值：PIX 确定支付处理渠道和规则参见支付方式列表
expiryPeriod	O	Number	支付过期时间（秒）格式：整数值默认：3600（1小时）范围：3600-86400（60分钟到24小时）
redirectUrl	O	String(256)	支付完成后客户重定向URL 格式：有效的HTTP/HTTPS URL 最大长度：256个字符用于支付后客户体验
callbackUrl	O	String(256)	支付状态更新的Webhook通知URL 格式：有效的HTTP/HTTPS URL 最大长度：256个字符用于实时支付状态通知

请求体示例 – 收款交易请求：

Content-type: application/json
X-TIMESTAMP: 2020-12-17T10:55:00+07:00
X-SIGNATURE: 7MHd9v5/m9JeqmDZVwWBZUZ5J5...7120QnFEny7Qm7uQR1G0TWCh10fsU6nVxiRoeoQ==
X-PARTNER-ID: 20001

{
    "merchant": {
        "merchantId": "20011"
    },
    "payer": {
        "pixAccount": "48982488880"
    },
    "money": {
      "amount": 20000,
        "currency": "BRL"
    },
    "orderNo": "200110edbb466abb04682968b40",
    "paymentMethod": "PIX",
    "purpose": "Purpose For Transaction from Java SDK",
    "redirectUrl": "https://www.google.com/webhp"
}

响应

HTTP响应

字段	必需	类型	描述
Content-Type	M	String	HTTP响应内容类型规范固定值：application/json 指示JSON响应格式
X-TIMESTAMP	M	String	ISO 8601日期时间格式，带时区偏移格式：yyyy-MM-ddTHH:mm:ss±HH:mm 示例：2020-12-17T10:55:00+07:00

响应体参数

字段	必需	类型	描述
code	M	String	API响应状态码，指示操作结果格式：两位数字字符串成功："00"，错误：其他代码用于程序化响应处理
message	M	String	人类可读的响应状态描述格式：UTF-8编码字符串提供操作结果的详细信息基于请求语言本地化
orderNo	M	String	商户交易参考号码格式：字母数字字符串与请求中提供的orderNo相同用于交易跟踪和参考
merchant	M	Object	商户信息容器包含商户识别和业务详情参见商户模型
merchantId	M	String	平台分配的主要商户标识符格式：字母数字字符串用于商户认证和交易路由
merchantName	O	String	商户业务名称或显示名称格式：UTF-8编码字符串用于交易识别和报告
subMerchantId	O	String	多级商户结构的子商户标识符格式：字母数字字符串用于子商户交易路由
subMerchantName	O	String	子商户业务名称或显示名称格式：UTF-8编码字符串用于子商户识别和报告
accountNo	O	String	交易结算的商户账户号码格式：字母数字字符串用于资金分配和结算
money	M	Object	带货币规格的交易金额详情包含确认的交易金额和货币参见金额模型
currency	M	String	ISO 4217货币代码规范固定值：BRL（巴西雷亚尔）确定支付处理规则和结算货币
amount	M	Number	最小货币单位的交易金额格式：整数值示例：200表示BRL 200.00 用于精确金额表示
transactionTime	M	String	交易创建时间戳格式：yyyy-MM-ddTHH:mm:ss-03:00（巴西时区）示例：2020-12-17T10:55:00-03:00 用于交易时间和审计
channel	M	Object	支付渠道信息容器包含支付方式详情和处理信息参见渠道模型
paymentMethod	M	String	用于交易处理的支付方式格式：预定义支付方式代码固定值：PIX 指示实际使用的支付渠道
paymentUrl	M	String	客户访问的支付处理URL 格式：有效的HTTP/HTTPS URL 用于客户支付完成和处理
qrString	O	String	移动支付应用的PIX二维码字符串格式：PIX二维码格式字符串用于移动支付处理和客户便利
additionalInfo	O	Object	额外的渠道特定信息格式：JSON对象包含可用的补充支付渠道详情
tradeNo	O	String	系统跟踪的内部交易参考号码格式：系统生成的字母数字字符串用于内部交易管理和支持
status	O	String	当前交易处理状态格式：预定义状态代码示例：PROCESSING、SUCCESS、FAILED、CANCELLED 指示交易的当前状态参见状态模型

Content-type: application/json
X-TIMESTAMP: 2020-12-17T10:55:00+07:00

{
    "channel": {
        "additionalInfo": {},
        "paymentMethod": "PIX",
        "paymentUrl": "https://gateway.smilepayz.com/cashier/#/loading?tradeNo=131200112412130836186234",
        "qrString": "00020101021226800014br.gov.bcb.pix2558pix.delbank.com.br/v2/cob/vcharge1f6aed0623644c24bbdc174ce5204000053039865802BR5907DELBANK6007ARACAJU62070503***6304BC39"
    },
    "code": "00",
    "merchant": {
        "accountNo": "11320011202402290943",
        "merchantId": "20011",
        "merchantName": "bradytest123www"
    },
    "message": "Successful",
    "money": {
      "amount": 2000,
        "currency": "BRL"
    },
    "orderNo": "20011db2773a6fb2542dfa5cb34c",
    "status": "PROCESSING",
    "tradeNo": "131200112412130836186234",
    "transactionTime": "2024-12-12T23:36:19-03:00"
}

{
    "channel": {
        "additionalInfo": {
            "paymentUrl": "https://gateway.smilepayz.com/cashier/#/transfer"
        },        
        "paymentMethod": "PIX",
        "paymentUrl": "https://gateway.smilepayz.com/cashier/#/loading?tradeNo=131200112412130836186234",
        "qrString": ""
    },
    "code": "00",
    "merchant": {
        "accountNo": "11320011202402290943",
        "merchantId": "20011",
        "merchantName": "bradytest123www"
    },
    "message": "Successful",
    "money": {
      "amount": 2000,
        "currency": "BRL"
    },
    "orderNo": "20011db2773a6fb2542dfa5cb34c",
    "status": "PROCESSING",
    "tradeNo": "131200112412130836186234",
    "transactionTime": "2024-12-12T23:36:19-03:00"
}

通知

HTTP请求

字段	必需	类型	描述
Content-Type	M	String	HTTP请求内容类型规范固定值：application/json 指示JSON请求格式
X-TIMESTAMP	M	String	ISO 8601日期时间格式，带时区偏移格式：yyyy-MM-ddTHH:mm:ss±HH:mm 示例：2020-12-17T10:55:00-03:00
X-SIGNATURE	M	String	通知认证的数字签名参见回调签名验证

请求体参数

字段	必需	类型	描述
orderNo	M	String	商户交易参考号码格式：字母数字字符串与请求中提供的orderNo相同用于交易跟踪和参考
tradeNo	M	String	系统跟踪的内部交易参考号码格式：系统生成的字母数字字符串用于内部交易管理和支持
merchantId	M	String	平台分配的主要商户标识符格式：字母数字字符串用于商户认证和交易路由
merchantName	M	String	商户业务名称或显示名称格式：UTF-8编码字符串用于交易识别和报告
subMerchantId	O	String	多级商户结构的子商户标识符格式：字母数字字符串用于子商户交易路由
subMerchantName	O	String	子商户业务名称或显示名称格式：UTF-8编码字符串用于子商户识别和报告
paymentMethod	M	String	用于交易处理的支付方式格式：预定义支付方式代码固定值：PIX 指示实际使用的支付渠道
transactionTime	M	String	交易完成时间戳格式：yyyy-MM-ddTHH:mm:ss 示例：2020-12-17T10:55:00-03:00 用于交易时间和审计
money	M	Object	带货币规格的交易金额详情包含确认的交易金额和货币参见金额模型
currency	M	String	ISO 4217货币代码规范固定值：BRL（巴西雷亚尔）确定支付处理规则和结算货币
amount	M	Number	最小货币单位的交易金额格式：整数值示例：100表示BRL 100.00 用于精确金额表示
status	M	String	最终交易处理状态格式：预定义状态代码示例：SUCCESS、FAILED、CANCELLED 指示交易的最终状态参见状态模型

重要

通知请仅返回字符串 SUCCESS

{
  "merchantId": "20001",
  "merchantName": "test",
  "money": {
    "amount": 100000,
    "currency": "BRL"
  },
  "orderNo": "2000102900000000000001",
  "status": "SUCCESS",
  "tradeNo": "101200012410241325417215",
  "transactionTime": "2020-12-17T10:55:00-03:00"
}

SUCCESS

API 收款交易

# 请求

# 请求路径：

# 请求头参数

# 请求体参数

# 请求体示例 – 收款交易请求：

# 响应

# HTTP响应

# 响应体参数

# 通知

# HTTP请求

# 请求体参数

# 返回

请求

请求路径：

请求头参数

请求体参数

请求体示例 – 收款交易请求：

响应

HTTP响应

响应体参数

通知

HTTP请求

请求体参数

返回