Notification

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.

Post Notification

$notify_url which defined when submitting the payin transaction.

Notification Parameters

Parameters

Header

Content-Type*	string	application/json
transfersmile-Signature*	string	t=$timestamp,v2=HMAC SHA256($RequestBody)

Body

trade_no*	transfersmile transaction id
out_trade_no*	merchant out_trade_no
out_request_no	transfersmile refund transaction id. Only for refund order
app_id*
trade_status*	trade status.
amount*
method*
currency*
timestamp*

Responses

200:OK	Merchant process the callback, and response "success"

success

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	User has submitted the payment information
SUCCESS	Trade has been successful
CANCEL	Trade has been cancelled
RISK_CONTROLLING	Trade is considered high risk or there is unclear billing information
DISPUTE	Trade is in dispute
REFUSED	Trade has been refused
REFUNDED	Trade has been refunded
CHARGEBACK	Chargeback occurred
CHARGEBACK_REVERSED	Chargeback reversed

transfersmile will send notifications with the following schedule of retries and confirmation awaiting times. You must return an HTTP STATUS 200 (OK) with response data "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.

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 transfersmile and your server, so there will not be a physical user seeing any type of result.

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

Verifying signatures (optional)

The approximate content of the transfersmile-Signature header is as follows (here with line breaks for easy viewing, the actual content is all on one line):

transfersmile-Signature:

t=1577808000,

v2=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

The transfersmile-Signature header contains a timestamp and a signature. The timestamp is prefixed by t=, followed by a UNIX timestamp; the signature is prefixed by v2=, followed by the signature content.

Step 1 : Extract the timestamp and signatures from the header

Split the header using the [,] character as the separator, to get a list of elements. Then split each element using the [=] character as the separator, to get a prefix and value pair.

The value for the prefix [t] corresponds to the timestamp, and [v2] corresponds to the signature. You can discard all other elements.

Step 2 : Prepare the original RequestBody string

Get all the content in the RequestBody. Please pay attention here. Please do not use the program's self-built structure to format and/or serialize the RequestBody content. If you have similar requirements, please do it after getting the original data for verification to avoid unnecessary sorting of fields and the addition of characters affect the signature.

Step 3 : Determine the expected signature

Compute an HMAC with the SHA256 hash function. Use the SecretKey get from The merchant dashboard as the key(salt), and use the original RequestBody string as the message.

Step 4 : Compare the signatures

Compare the signature in the header to the expected signature. For an equality match, compute the difference between the current timestamp and the received timestamp, then decide if the difference is within your tolerance.

Notification Example

TIP

The following notification is only an example. Different methods can have more or less parameters in the real notification. Please refer to what you received when testing.

{
  Content-Type: application/json,
  Method: POST,
  Header: t=1645516741, v2=f6e345eca80d74c470ba456b7b559046f22b49fcaad9b81938ff1488b0f497ac,
  Body:
    {
      "amount":"12.01",
      "out_trade_no":"202201010354002",
      "method":"Boleto",
      "trade_status":"SUCCESS",
      "trade_no":"2022022201111100011",
      "currency":"BRL",
      "out_request_no":"",
      "app_id":"162************38",
      "timestamp":"1645516741",
      "user":{
        "buyer_id":"",
        "identify":{
          "type":"CPF",
          "number":"50284414727"
        },
        "name":"test user name",
        "phone":"75991435892",
        "email":"[email protected]"
      },
      "card":{
        "card_no":""
      }
    }
}

WARNING

Our notifications will be sent from these IP addresses, please add them to your whitelist.