Notifications

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": "[email protected]",
    "country": "BR",
    "city": "sao paolo",
    "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": "[email protected]",
    "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": "[email protected]",
    "country": "BR",
    "city": "sao paulo",
		"state": "sao paolo",
    "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": "[email protected]",
    "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": "[email protected]",
    "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": "[email protected]",
    "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 appear as below. Note that the "state" field is included below - this will only be included where "type" is equal to "virtual account payment" for direct deposits (see next section).

{
  "uid": "50b23c5a-85aa-446f-a6f4-01030204",
  "type": "virtual_account_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": "[email protected]",
    "country": "BR",
    "city": "sao paulo",
		"state": "sao paolo",
    "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": "virtual_account_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": "[email protected]",
    "country": "BR",
    "city": "sao paulo",
		"state": "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, CVU/Alias Payments in Argentina and Bre-B in Colombia. We will continue to update this list as we add it to more payment methods.

Bre-B (Colombia)

For Bre-B transactions, the payer block includes the following populated sub-fields:

Sub-field	Description
`name`	Payer first name as registered with the Bre-B key owner's bank.
`lastName`	Payer last name as registered with the Bre-B key owner's bank.
`personalId`	Payer national document number (CC, CE, NIT, etc.) as registered with the bank.
`bankName`	Display name of the payer's originating bank.

Other sub-fields documented in the global payer block (e.g., accountNumber, accountAgencyNumber, bankTrackingID, maskCardNumber) are not populated for Bre-B because the rail routes by key rather than by account number, and account-level details are not exposed by the rail.

Virtual Account Payments

When Notifications are generated for Virtual Account Payments (deposits originated by the consumer without checking out in the Merchant website), the "type" property will be set to "virtual_account_payment". In addition, to enable customer deposit control in Argentina, the "state" field will be populated on the notification, based on the "state" property value submitted when creating the Customer.

Activation

To enable this feature for your shop, please reach out to our Integrations Team at [email protected]. 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"
  }
}