Description

Independently of what your integration type is, our system sends notifications in JSON format to inform of the creation and progression of a transaction or payout. The URL used by our system is the one set in the notificationURL field of your transaction/payout.

🚧
Callbacks will not be automatically resent if reception is failed on your end. For assistance with missing notifications, contact our tech support group.

Transaction Notification

Transactions notifications will be sent when a transaction is created and every time it changes status until reaching a final status. Here is an example for each possible type of notification sent after a transaction is created.

{
  "uid": "50b23c5a-85aa-446f-a6f4-01030204",
  "type": "payment",
  "status": "PENDING",
  "message": null,
  "trackingId": "0986",
  "amount": 106,
  "currency": "USD",
  "amountChanged": false,
  "originalAmount": 0,
  "newCouponAmount": null,
  "newCouponCurrency": null,
  "description": "Test",
  "cardNumber": null,
  "createdAt": "2023-02-16T09:12:34",
  "updatedAt": "2023-02-16T09:12:34",
  "customer": {
    "firstName": "Test",
    "lastName": "Test",
    "email": "test@gmail.com",
    "country": "BR",
    "city": "sao paulo",
    "zip": "",
    "address": "User Address",
    "phone": "119458692521",
    "deviceId": "",
    "ip": "192.168.0.1",
    "personalId": "010209160"
  },
  "paymentMethod": {
    "id": "94f1224a-76bf-4971-8261-0102033ec8b06",
    "name": "PIX",
    "type": "Online"
  },
  "billing": {
    "currency": "BRL",
    "amount": 600
  }
}

{
  "uid": "50b23c5a-85aa-446f-a6f4-01030204",
  "type": "payment",
  "status": "FAILED",
  "message": null,
  "trackingId": "0986",
  "amount": 106,
  "currency": "USD",
  "amountChanged": false,
  "originalAmount": 0,
  "newCouponAmount": null,
  "newCouponCurrency": null,
  "description": "Test",
  "cardNumber": null,
  "createdAt": "2023-02-16T09:12:34",
  "updatedAt": "2023-02-16T09:12:34",
  "customer": {
    "firstName": "Test",
    "lastName": "Test",
    "email": "test@gmail.com",
    "country": "BR",
    "city": "sao paulo",
    "zip": "",
    "address": "User Address",
    "phone": "119458692521",
    "deviceId": "",
    "ip": "192.168.0.1",
    "personalId": "010209160"
  },
  "paymentMethod": {
    "id": "94f1224a-76bf-4971-8261-0102033ec8b06",
    "name": "PIX",
    "type": "Online"
  },
  "billing": {
    "currency": "BRL",
    "amount": 600
  }
}

{
  "uid": "50b23c5a-85aa-446f-a6f4-01030204",
  "type": "payment",
  "status": "APPROVED",
  "message": null,
  "trackingId": "0986",
  "amount": 106,
  "currency": "USD",
  "amountChanged": false,
  "originalAmount": 0,
  "newCouponAmount": null,
  "newCouponCurrency": null,
  "description": "Test",
  "cardNumber": null,
  "createdAt": "2023-02-16T09:12:34",
  "updatedAt": "2023-02-16T09:12:34",
  "customer": {
    "firstName": "Test",
    "lastName": "Test",
    "email": "test@gmail.com",
    "country": "BR",
    "city": "sao paulo",
    "zip": "",
    "address": "User Address",
    "phone": "119458692521",
    "deviceId": "",
    "ip": "192.168.0.1",
    "personalId": "010209160"
  },
  "paymentMethod": {
    "id": "94f1224a-76bf-4971-8261-0102033ec8b06",
    "name": "PIX",
    "type": "Online"
  },
  "billing": {
    "currency": "BRL",
    "amount": 600
  }
}

{
  "uid": "50b23c5a-85aa-446f-a6f4-01030204",
  "type": "payment",
  "status": "EXPIRED",
  "message": null,
  "trackingId": "0986",
  "amount": 106,
  "currency": "USD",
  "amountChanged": false,
  "originalAmount": 0,
  "newCouponAmount": null,
  "newCouponCurrency": null,
  "description": "Test",
  "cardNumber": null,
  "createdAt": "2023-02-16T09:12:34",
  "updatedAt": "2023-02-16T09:12:34",
  "customer": {
    "firstName": "Test",
    "lastName": "Test",
    "email": "test@gmail.com",
    "country": "BR",
    "city": "sao paulo",
    "zip": "",
    "address": "User Address",
    "phone": "119458692521",
    "deviceId": "",
    "ip": "192.168.0.1",
    "personalId": "010209160"
  },
  "paymentMethod": {
    "id": "94f1224a-76bf-4971-8261-0102033ec8b06",
    "name": "PIX",
    "type": "Online"
  },
  "billing": {
    "currency": "BRL",
    "amount": 600
  }
}

{
  "uid": "50b23c5a-85aa-446f-a6f4-01030204",
  "type": "payment",
  "status": "REJECTED",
  "message": null,
  "trackingId": "0986",
  "amount": 106,
  "currency": "USD",
  "amountChanged": false,
  "originalAmount": 0,
  "newCouponAmount": null,
  "newCouponCurrency": null,
  "description": "Test",
  "cardNumber": null,
  "createdAt": "2023-02-16T09:12:34",
  "updatedAt": "2023-02-16T09:12:34",
  "customer": {
    "firstName": "Test",
    "lastName": "Test",
    "email": "test@gmail.com",
    "country": "BR",
    "city": "sao paulo",
    "zip": "",
    "address": "User Address",
    "phone": "119458692521",
    "deviceId": "",
    "ip": "192.168.0.1",
    "personalId": "010209160"
  },
  "paymentMethod": {
    "id": "94f1224a-76bf-4971-8261-0102033ec8b06",
    "name": "PIX",
    "type": "Online"
  },
  "billing": {
    "currency": "BRL",
    "amount": 600
  }
}

{
  "uid": "50b23c5a-85aa-446f-a6f4-01030204",
  "type": "payment",
  "status": "CANCELLED",
  "message": "PAYMENT_COMPLIANCE_VALIDATION_FAILED",
  "trackingId": "0986",
  "amount": 106,
  "currency": "USD",
  "amountChanged": false,
  "originalAmount": 0,
  "newCouponAmount": null,
  "newCouponCurrency": null,
  "description": "Test",
  "cardNumber": null,
  "createdAt": "2023-02-16T09:12:34",
  "updatedAt": "2023-02-16T09:12:34",
  "customer": {
    "firstName": "Test",
    "lastName": "Test",
    "email": "test@gmail.com",
    "country": "BR",
    "city": "sao paulo",
    "zip": "",
    "address": "User Address",
    "phone": "119458692521",
    "deviceId": "",
    "ip": "192.168.0.1",
    "personalId": "010209160"
  },
  "paymentMethod": {
    "id": "94f1224a-76bf-4971-8261-0102033ec8b06",
    "name": "PIX",
    "type": "Online"
  },
  "billing": {
    "currency": "BRL",
    "amount": 600
  }
}

Payer Info

Additionally, you can opt to receive the payer information with the APPROVED and CANCELLED notification for select payment methods. This information will come in a new object called payer and will look like this:

"payer": {
        "payerName": "John Doe",
        "name": "John Doe",
        "lastName": null,
        "personalId": "12.345.678-9",
        "payoutAccountTypeCode": null,
        "accountused": "1234567890",
        "accountNumber": "1234567890",
        "accountAgencyNumber": null,
        "bankTrackingID": "Banco de Chile (Edwards Citi)",
        "bankName": "Banco de Chile (Edwards Citi)",
        "maskCardNumber": null
      }

When enabled, your APPROVED and CANCELLED notification webhooks will look like this:

{
  "uid": "50b23c5a-85aa-446f-a6f4-01030204",
  "type": "payment",
  "status": "APPROVED",
  "message": null,
  "trackingId": "0986",
  "amount": 106,
  "currency": "USD",
  "amountChanged": false,
  "originalAmount": 0,
  "newCouponAmount": null,
  "newCouponCurrency": null,
  "description": "Test",
  "cardNumber": null,
  "createdAt": "2023-02-16T09:12:34",
  "updatedAt": "2023-02-16T09:12:34",
  "customer": {
    "firstName": "Test",
    "lastName": "Test",
    "email": "test@gmail.com",
    "country": "BR",
    "city": "sao paulo",
    "zip": "",
    "address": "User Address",
    "phone": "119458692521",
    "deviceId": "",
    "ip": "192.168.0.1",
    "personalId": "010209160"
  },
  "paymentMethod": {
    "id": "94f1224a-76bf-4971-8261-0102033ec8b06",
    "name": "PIX",
    "type": "Online"
  },
  "billing": {
    "currency": "BRL",
    "amount": 600
  },
  "payer": {
    "payerName": "John Doe",
    "name": "John Doe",
    "lastName": null,
    "personalId": "12.345.678-9",
    "payoutAccountTypeCode": null,
    "accountused": "1234567890",
    "accountNumber": "1234567890",
    "accountAgencyNumber": null,
    "bankTrackingID": "Banco de Chile (Edwards Citi)",
    "bankName": "Banco de Chile (Edwards Citi)",
    "maskCardNumber": null
  }
}

{
  "uid": "50b23c5a-85aa-446f-a6f4-01030204",
  "type": "payment",
  "status": "CANCELLED",
  "message": "PAYMENT_COMPLIANCE_VALIDATION_FAILED",
  "trackingId": "0986",
  "amount": 106,
  "currency": "USD",
  "amountChanged": false,
  "originalAmount": 0,
  "newCouponAmount": null,
  "newCouponCurrency": null,
  "description": "Test",
  "cardNumber": null,
  "createdAt": "2023-02-16T09:12:34",
  "updatedAt": "2023-02-16T09:12:34",
  "customer": {
    "firstName": "Test",
    "lastName": "Test",
    "email": "test@gmail.com",
    "country": "BR",
    "city": "sao paulo",
    "zip": "",
    "address": "User Address",
    "phone": "119458692521",
    "deviceId": "",
    "ip": "192.168.0.1",
    "personalId": "010209160"
  },
  "paymentMethod": {
    "id": "94f1224a-76bf-4971-8261-0102033ec8b06",
    "name": "PIX",
    "type": "Online"
  },
  "billing": {
    "currency": "BRL",
    "amount": 600
  },
  "payer": {
    "payerName": "John Doe",
    "name": "John Doe",
    "lastName": null,
    "personalId": "12.345.678-9",
    "payoutAccountTypeCode": null,
    "accountused": "1234567890",
    "accountNumber": "1234567890",
    "accountAgencyNumber": null,
    "bankTrackingID": "Banco de Chile (Edwards Citi)",
    "bankName": "Banco de Chile (Edwards Citi)",
    "maskCardNumber": null
  }
}

This feature is currently available for Khipu in Chile, PIX in Brazil, SPEI in Mexico, and PagosOnline in Argentina. We will continue to update this list as we add it to more payment methods.

Activation

To enable this feature for your shop, please reach out to our Integrations Team at integrations@payretailers.com. Our team will assist you in activating this feature and answer any questions you may have.

Payout Notifications

In the same way as for transactions, payout notifications will be sent when a payout is created and every time it changes status until reaching a final status. Here is an example for each possible type of notification sent after a payout is created. Please note that the parameters are not the same as the ones used in the transaction notification.

📘
If your payout status is ERROR and you want to know why, the value of errorReason will be an error message. You can check its meaning on the Payout Error Messages page.

{
  "payoutId": 1234567,
  "shopId": 62,
  "beneficiaryFirstName": "John",
  "beneficiaryLastName": "Doe",
  "documentType": "40",
  "documentNumber": "12341234ASD",
  "email": null,
  "currencyCode": "MXN",
  "country": "MX",
  "bankName": "12312",
  "accountAgencyNumber": null,
  "accountNumber": "123123123123",
  "abaSwift": null,
  "amount": 200.08,
  "settlementAmount": 10.2,
  "address": null,
  "city": null,
  "gender": null,
  "paymentReason": "test payout",
  "errorReason": null,
  "statusTypeCode": "PENDING",
  "externalReference": "external1",
  "payoutAccountTypeCode": "0001",
  "phone": null,
  "payoutBatch": {
    "payoutBatchId": 39832,
    "description": "PAYOUT_BATCH_TEST_20220525091740",
    "date": "2022-05-25T09:17:40"
  }
}

{
  "payoutId": 1234567,
  "shopId": 62,
  "beneficiaryFirstName": "John",
  "beneficiaryLastName": "Doe",
  "documentType": "40",
  "documentNumber": "12341234ASD",
  "email": null,
  "currencyCode": "MXN",
  "country": "MX",
  "bankName": "12312",
  "accountAgencyNumber": null,
  "accountNumber": "123123123123",
  "abaSwift": null,
  "amount": 200.08,
  "settlementAmount": 10.2,
  "address": null,
  "city": null,
  "gender": null,
  "paymentReason": "test payout",
  "errorReason": null,
  "statusTypeCode": "PROCESSED",
  "externalReference": "external1",
  "payoutAccountTypeCode": "0001",
  "phone": null,
  "payoutBatch": {
    "payoutBatchId": 39832,
    "description": "PAYOUT_BATCH_TEST_20220525091740",
    "date": "2022-05-25T09:17:40"
  }
}

{
  "payoutId": 1234567,
  "shopId": 62,
  "beneficiaryFirstName": "John",
  "beneficiaryLastName": "Doe",
  "documentType": "40",
  "documentNumber": "12341234ASD",
  "email": null,
  "currencyCode": "MXN",
  "country": "MX",
  "bankName": "12312",
  "accountAgencyNumber": null,
  "accountNumber": "123123123123",
  "abaSwift": null,
  "amount": 200.08,
  "settlementAmount": 10.2,
  "address": null,
  "city": null,
  "gender": null,
  "paymentReason": "test payout",
  "errorReason": null,
  "statusTypeCode": "ACCEPTED",
  "externalReference": "external1",
  "payoutAccountTypeCode": "0001",
  "phone": null,
  "payoutBatch": {
    "payoutBatchId": 39832,
    "description": "PAYOUT_BATCH_TEST_20220525091740",
    "date": "2022-05-25T09:17:40"
  }
}

{
  "payoutId": 1234567,
  "shopId": 62,
  "beneficiaryFirstName": "John",
  "beneficiaryLastName": "Doe",
  "documentType": "40",
  "documentNumber": "12341234ASD",
  "email": null,
  "currencyCode": "MXN",
  "country": "MX",
  "bankName": "12312",
  "accountAgencyNumber": null,
  "accountNumber": "123123123123",
  "abaSwift": null,
  "amount": 200.08,
  "settlementAmount": 10.2,
  "address": null,
  "city": null,
  "gender": null,
  "paymentReason": "test payout",
  "errorReason": null,
  "statusTypeCode": "FINISHED",
  "externalReference": "external1",
  "payoutAccountTypeCode": "0001",
  "phone": null,
  "payoutBatch": {
    "payoutBatchId": 39832,
    "description": "PAYOUT_BATCH_TEST_20220525091740",
    "date": "2022-05-25T09:17:40"
  }
}

{
  "payoutId": 1234567,
  "shopId": 62,
  "beneficiaryFirstName": "John",
  "beneficiaryLastName": "Doe",
  "documentType": "40",
  "documentNumber": "12341234ASD",
  "email": null,
  "currencyCode": "MXN",
  "country": "MX",
  "bankName": "12312",
  "accountAgencyNumber": null,
  "accountNumber": "123123123123",
  "abaSwift": null,
  "amount": 200.08,
  "settlementAmount": 10.2,
  "address": null,
  "city": null,
  "gender": null,
  "paymentReason": "test payout",
  "errorReason": "cuenta en dolares",
  "statusTypeCode": "ERROR",
  "externalReference": "external1",
  "payoutAccountTypeCode": "0001",
  "phone": null,
  "payoutBatch": {
    "payoutBatchId": 39832,
    "description": "PAYOUT_BATCH_TEST_20220525091740",
    "date": "2022-05-25T09:17:40"
  }
}