IPN通知

IPN（即时付款通知）是一种通过HTTP POST请求从一台服务器发送到另一台服务器的通知，用于通知您的交易。

为了接收有关您平台中事件的通知，您必须在进行付款POST时预先配置通知，并在字段notify_url(集成支付或直连支付)中指示URL。

事件

每当发生事件时，我们都会使用HTTP POST到您指定的URL的json格式发送通知给您。

我们将通知以下事件：

动作	描述
PROCESSING	支付处理中（用户提交支付申请）
SUCCESS	支付成功（用户完成付款）
EXPIRED	过期（Initial）
CANCEL	支付取消
RISK_CONTROLLING	风控处理中
DISPUTE	争议处理中
REFUSED	支付被拒
REFUNDED	发生退款
CHARGEBACK	发生拒付
REFUND_REVOKE	退款回滚
REFUND_REFUSED	退款被拒绝

Luxpag将发送通知，其中包含以下重试时间表和确认等待时间。 您必须在相应时间到期之前返回带有响应数据"success"或"{"result":"success"}"的HTTP STATUS 200（OK）。 否则，将假定您没有正确收到它，并且将再次通知您。

事件	距离第一次通知的时间
立即	-
1st retry	10 minutes
2nd retry	30 minutes
3rd retry	60 minutes
4th retry	120 minutes
5th retry	360 minutes
6th retry	840 minutes

通知参数（JSON格式）

参数名	类型	必须	最大长度/默认值	描述
app_id	string	yes	32	商户后台创建并获得
trade_no	string	yes	64	Luxpag 订单号
out_trade_no	string	yes	64	商户订单号
out_request_no	string	no	64	退款唯一单号
method	string	yes	32	支付方式
trade_status	string	yes	16	订单状态
currency	string	yes	3	币种：巴西（BRL）
amount	string	yes		订单金额
user.name	string	no		用户姓名
user.email	string	no		用户邮箱
user.phone	string	no		用户电话
user.identify.number	string	no		用户ID
user.identify.type	string	no		用户ID类型
card.card_no	string	no		卡号
channel	string	no		钱包渠道
region	string	no		区域编码
refused_reason.code	string	no		拒绝原因编码(不是都有原因)
refused_reason.msg	string	no		拒绝原因
refused_reason.detail	string	no		拒绝详细
payer.account.number	string	no		Currently only PIX and SPEI return the payer's information.
payer.account.type	string	no		Currently only PIX and SPEI return the payer's information.
payer.identification.number	string	no		Currently only PIX and SPEI return the payer's information.
payer.identification.type	string	no		Currently only PIX and SPEI return the payer's information.
payer.username	string	no		Currently only PIX and SPEI return the payer's information.

发送的通知使用以下格式：

Method: POST
Header:Content-Type: application/json
Header:Luxpag-Signature: hmacSHA256(payload, secret_key)
Body:
  {
  	"amount":"",
  	"out_trade_no":"",
  	"method":"",
  	"trade_status":"",
  	"trade_no":"",
  	"currency":"",
  	"out_request_no":"",
  	"app_id":"",
    "user":{
      "identify":{
        "number":"",
        "type":""
      },
      "phone":"",
      "email":""
    },
    "card":{
      "card_no":"F6L4"
    },
     "refused_reason":{
      "code":"",
      "msg":"",
      "detail":""
    },
    // Currently only PIX and SPEI return the payer's information.
    payer: {
      account: {
        number: '',
        type: ''
      },
      identification: {
        number: '',
        type: ''
      },
      username: ''
    }
  }

payload：IPN通知POST给商户的数据，payload为JSON字符串。

收到通知后该怎么办？

当您在平台上收到通知时，Luxpag等待响应以验证您是否正确接收了该通知。 为此，您必须返回HTTP状态200（OK），其响应数据为“ success”或“ {” result“：” success“}”。

建议您在执行业务逻辑之前或在访问外部资源之前对通知做出响应，以免超出估计的响应时间。

该通信专门在Luxpag的服务器与您的服务器之间进行，因此不会有物理用户看到任何类型的结果。

检查回调签名（可选）

Luxpag在每个事件的Luxpag-Signature标头中都包含一个签名，您可对签名进行验证从而增强安全性。

我们会使用商户私钥（盐值）对回调payload进行hmacSHA256加密。

Header:Luxpag-Signature: SignHelper.hmacSHA256(payload, secret_key)

// Step 1
String payload = JSON.toJSONString(notify); 
String sign = SignHelper.macSha256(payload, secret_key);
// Step 2
Header:Luxpag-Signature: 5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd


import javax.crypto.Mac; 
import javax.crypto.spec.SecretKeySpec; 
import java.nio.charset.StandardCharsets; 
import java.security.InvalidKeyException; 
import java.security.NoSuchAlgorithmException; 
import java.util.*;

/** 
 * 
 */ 
public final class SignHelper{

 /**
  * HMAC with SHA-256
  *
  * @param content 
  * @param salt
  * @return
  */
 public static String macSha256(String content, String salt) {
    StringBuilder result = new StringBuilder();
    try {

        Mac mac = Mac.getInstance("HmacSHA256");
        mac.init(new SecretKeySpec(salt.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
        byte[] hash = mac.doFinal(content.getBytes(StandardCharsets.UTF_8));
        for (byte b : hash) {
            result.append(Integer.toString((b & 0xff) + 0x100, 16).substring(1));
        }

    } catch (NoSuchAlgorithmException | InvalidKeyException e) {
        e.printStackTrace();
    }
    return result.toString();
 }
}

安全策略

建议：对Luxpag回调服务IP进行白名单验证；

建议：收到订单成功IPN通知后回查下订单状态，尤其是虚拟账号订单。