Notification

How to verify our notifications.

Once the payout is confirmed by the bank, Pagsmile will send a notification to the merchant notification URL informing you of the result of the transaction. This URL is defined when submitting the payout transaction, by using the notify_url parameter for each payout request. Notification will retry 6 times when your processing failed.

Notifcation

POST $notify_url which defined when submitting the payout transaction.

Notification Parameters

Headers

Name	Type	Description
Content-Type*	string	application/json; charset=UTF-8
Authorization*	string	SHA256($sorted_params + $app_key)

Request Body

Name	Type	Description
payoutId*	string	pagsmile transaction id
custom_code*	string	merchant custom_code
status*	string	PAID, REJECTED, REFUNDED or PARTIAL_REFUNDED
msg	string	success or rejected message
timestamp*	integer	unix timestamp

200 Merchant process the callback, and response "success"

success

Authorization Check

• Get callback's body parameters, and sort them ascendingly.

• Concatenate sorted_params with app_key.

• Use sha256(sorted_params + app_key) to generate App Authorization.

• Get Pagsmile Authorization from callback's Header.

• Verify if Pagsmile Authorization matches with App Authorization.

When sorting parameters, strip the ones with no value.

Notification Events

• PAID

• REJECTED

• REFUNDED

• PARTIAL_REFUNDED

• PIX (Brazil), BankTransfer (Brazil), SPEI (Mexico), BankTransfer (Chile), and Pagsmile Wallet supported REFUNDED notification.

• PIX (Brazil), and BankTransfer (Brazil) supported PARTIAL_REFUNDED notification. A payout transaction can receive multiple PARTIAL_REFUNDED notifications until the payout amount is fully refunded. When multiple partial refunds fully refund a payout transaction, a REFUNDED notification will be sent right after the PARTIAL_REFUNDED notification of the last partial refund.

Notification Example

PAID

curl --location --request POST ${MERCHANT_NOTIFY_URL} \
--header 'Authorization: ${SIGNATURE}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "payoutId": "TS202310121355544******7kJPB",
    "custom_code": "custom_code_test",
    "status": "PAID",
    "msg": "success",
    "timestamp": 1628564650
}'

REJECTED

curl --location --request POST ${MERCHANT_NOTIFY_URL} \
--header 'Authorization: ${SIGNATURE}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "payoutId": "TS202310121355544******7kJPB",
    "custom_code": "custom_code_test",
    "status": "REJECTED",
    "msg": "Rejected by bank",
    "timestamp": 1628564650
}'

REFUNDED

curl --location --request POST ${MERCHANT_NOTIFY_URL} \
--header 'Authorization: ${SIGNATURE}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "payoutId": "TS202310121355544******7kJPB",
    "custom_code": "custom_code_test",
    "status": "REFUNDED",
    "msg": "Refund by the recipient or the recipient's bank",
    "timestamp": 1628564650
}'

PARTIAL_REFUNDED

curl --location --request POST ${MERCHANT_NOTIFY_URL} \
--header 'Authorization: ${SIGNATURE}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "payoutId": "TS202310121355544******7kJPB",
    "custom_code": "custom_code_test",
    "status": "PARTIAL_REFUNDED",
    "refunded_id": "D182361*********************ca9d", //The refund id of this partial refund, usually start with D.
    "refunded_amount": "0.01", //The amount of this partial refund.
    "msg": "Refund by the recipient or the recipient's bank",
    "timestamp": 1628564650
}'

Notification Retries

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

Event	Time after 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

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