Developers

# IPN Notifications

IPN (Instant Payment Notification) is a notification sent from one server to another through an HTTP POST request informing your transactions.

In order to receive notifications about the events in your platform, you have to previously configure the notification when you do the POST of the payment, indicating the URL in the field notify_url(Checkout Redirect Payment or API Direct Payment).

# Events

Whenever an event occurs, we will send you a notification in json format using HTTP POST to the URL that you specified.

We will notify the following events:

Action Description
PROCESSING trade processing(payment information submitted by the user)
SUCCESS trade succeeded
EXPIRED trade expired（Initial）
CANCEL trade cancelled
RISK_CONTROLLING trade in risk control
DISPUTE dispute processing
REFUSED trade refused
REFUNDED refund occurred
CHARGEBACK chargeback occurred
REFUND_REVOKE Refund Rollback
REFUND_REFUSED Refund rejected
Status

Luxpag will send notifications with the following schedule of retries and confirmation awaiting times. You must return an HTTP STATUS 200 (OK) with reponse data "success" or "{"result":"success"}" before the corresponding time expires. If not, it will be assumed that you did not receive it correctly and you will be notified again.

Event Time after the first dispatch
Dispatch -
1st retry 10 minutes
2nd retry 30 minutes
3rd retry 60 minutes
4th retry 120 minutes
5th retry 360 minutes
6th retry 840 minutes

# Notification Body (JSON format)

Parameter Type Required Max Length(or Default Value) Description
app_id string yes 32 created app's id at dashboard
trade_no string yes 64 Luxpag trade NO.
out_trade_no string yes 64 ID given by the merchant in their system
out_request_no string no 64 refund number
method string yes 32 Payment methods
trade_status string yes 16 trade's status
currency string yes 3 BRL for brazil
amount string yes request payment amount
user.name string no user's name
user.email string no user's email
user.phone string no user's mobile phone number
user.identify.number string no user's ID number
user.identify.type string no user's ID type
card.card_no string no card number
channel string no Wallet channel
region string no region code
refused_reason.code string no refused reason code(not all have a reason)
refused_reason.msg string no refused reason
refused_reason.detail string no refused detail
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.

The notification sent has the following format:


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:The data sent to the merchant by post, and the payload is JSON string.

# What should I do when I receive a notification?

When you receive a notification on your platform, Luxpag waits for a response to validate that you received it correctly. For this, you must return an HTTP STATUS 200 (OK) with reponse data "success" or "{"result":"success"}".

It is recommended that you respond to the notification before executing business logic or prior to accessing external resources so as not to exceed the estimated response times.

This communication is exclusively between the servers of Luxpag and your server, so there will not be a physical user seeing any type of result.

# Check Signature(Optional)

Luxpag includes a signature in the Luxpag-Signature header of each event. You can verify the signature to enhance security.

We will use the merchant's private key to encrypt the callback payload with 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();
 }
}

# Security Policy

Suggestion: Perform whitelist verification on the Luxpag callback service IP;

Suggestion: After receiving the successful IPN notification of the order, check back on Luxpag, especially for virtual account orders.

← Payment Method →