Notification webhooks

Notified payment transactions

Webhooks are HTTPS callbacks that receive notification messages for payment transactions.
Our notifications inform you about updating the status of payments that are final (they are not modifiable).
End states: Collected, Transferred, Refunded, Cancelled, Voided, Failed.

To receive webhooks, in the payment creation service you must send the URI endpoint list in the notification_url field.

Payment notifications

Here are some examples of notifications you will get depending on the payment method you use.

Pix

{
   "status":{
      "type":"Collected",
      "date":"2021-01-01T00:00:00.000Z"
   },
   "transaction":{
      "reference_id":"REF0000001",
      "business_id":"BIZ0000001",
      "account":"SBX000",
      "amount":{
         "currency_code":"BRL",
         "value":1500.56
      },
      "provider_reference":{
         "tx_id":"20000000000000026628140042292",
         "end_to_end_id":"E0036030520211216092957cb99ed693"
      }
   },
   "provider":{
      "code":"ITAU"
   },
   "order_id":"9dd3f765-a51a-49d8-b6af-a51d5a0b3f7f"
}
{
   "status":{
      "type":"Refunded",
      "date":"2021-01-01T00:00:00.000Z"
   },
   "transaction":{
      "reference_id":"REF0000001",
      "business_id":"BIZ0000001",
      "account":"SBX000",
      "amount":{
         "currency_code":"BRL",
         "value":1500.56
      }
   },
   "order_id":"9dd3f765-a51a-49d8-b6af-a51d5a0b3f7f",
   "refund_id": "6efddc33-c023-24b9-a3f3-d6ca6087f2b0",
   "refund_amount":{
   		"currency_code":"BRL",
   		"value":500
   }
}
{
   "status":{
      "type":"Cancelled",
      "date":"2021-01-01T00:00:00.000Z"
   },
   "transaction":{
      "reference_id":"REF0000001",
      "business_id":"BIZ0000001",
      "account":"SBX000",
      "amount":{
         "currency_code":"BRL",
         "value":1500.56
      }
   },
   "provider_reference":{
      "tx_id":"20000000000000026628140042292"
   },
   "order_id":"9dd3f765-a51a-49d8-b6af-a51d5a0b3f7f"
}
{
   "status":{
      "type":"Failed",
      "date":"2021-01-01T00:00:00.000Z"
   },
   "transaction":{
      "reference_id":"REF0000001",
      "business_id":"BIZ0000001",
      "account":"SBX000",
      "amount":{
         "currency_code":"BRL",
         "value":1500.56
      }
   },
   "order_id":"9dd3f765-a51a-49d8-b6af-a51d5a0b3f7f"
}

Itaú Pay

provider.financing_terms is included once the payment is Collected and the provider sent at least one rate. Rates that were not sent are omitted. The object is omitted when no rate is available.

{
   "status":{
      "type":"Collected",
      "date":"2026-07-27T13:00:00.000Z"
   },
   "transaction":{
      "reference_id":"REF-ITAU-001",
      "account":"SBX000",
      "amount":{
         "currency_code":"BRL",
         "value":1500.56
      },
      "provider_reference":{
         "order_id":"6a5f5159-c5dc-43b2-b3d4-34471d9be94c",
         "payment_id":"82106789179776-1"
      }
   },
   "country_code":"BR",
   "channel":"SDK",
   "order_id":"9dd3f765-a51a-49d8-b6af-a51d5a0b3f7f",
   "provider":{
      "code":"ITAU",
      "payment_method_type":"CREDIT",
      "installments":15,
      "financing_terms":{
         "interest_rate_monthly":4.97,
         "interest_rate_yearly":80.42,
         "cet_monthly":5.55,
         "cet_yearly":92.89,
         "iof_rate":0.2
      }
   }
}
{
   "status":{
      "type":"Failed",
      "date":"2026-07-27T14:00:00.000Z",
      "error":{
         "code":"05",
         "message":"Insufficient funds"
      }
   },
   "transaction":{
      "reference_id":"REF-ITAU-001",
      "account":"SBX000",
      "amount":{
         "currency_code":"BRL",
         "value":1500.56
      }
   },
   "order_id":"9dd3f765-a51a-49d8-b6af-a51d5a0b3f7f",
   "refund_id":"6efddc33-c023-24b9-a3f3-d6ca6087f2b0",
   "refund_amount":{
      "currency_code":"BRL",
      "value":100
   }
}

PayPal

{
   "status":{
      "type":"Published",
      "date":"2026-07-27T13:00:00.000Z"
   },
   "transaction":{
      "transaction_id":"TRX0000001",
      "reference_id":"REF-PAYPAL-001",
      "account":"SBX001",
      "amount":{
         "currency_code":"ARS",
         "value":1500.56
      },
      "provider_reference":{
         "order_id":"6a5f5159-c5dc-43b2-b3d4-34471d9be94c",
         "payment_id":"82106789179776-1"
      }
   },
   "country_code":"AR",
   "channel":"SDK",
   "order_id":"9dd3f765-a51a-49d8-b6af-a51d5a0b3f7f",
   "payment_method":{
      "code":"PAYPAL",
      "expiration_date":"2026-07-27T15:00:00.000Z"
   },
   "provider":{
      "installments":1
   }
}
{
   "status":{
      "type":"Authorized",
      "date":"2026-07-27T13:00:00.000Z",
      "expiration":"2026-07-28T13:00:00.000Z"
   },
   "transaction":{
      "transaction_id":"TRX0000001",
      "reference_id":"REF-PAYPAL-001",
      "account":"SBX001",
      "amount":{
         "currency_code":"ARS",
         "value":1500.56
      },
      "provider_reference":{
         "order_id":"6a5f5159-c5dc-43b2-b3d4-34471d9be94c",
         "payment_id":"82106789179776-1"
      }
   },
   "country_code":"AR",
   "channel":"SDK",
   "order_id":"9dd3f765-a51a-49d8-b6af-a51d5a0b3f7f",
   "payment_method":{
      "code":"PAYPAL",
      "expiration_date":"2026-07-27T15:00:00.000Z"
   },
   "provider":{
      "installments":1
   }
}
{
   "status":{
      "type":"Collected",
      "date":"2026-07-27T14:00:00.000Z"
   },
   "transaction":{
      "transaction_id":"TRX0000001",
      "reference_id":"REF-PAYPAL-001",
      "account":"SBX001",
      "amount":{
         "currency_code":"ARS",
         "value":1500.56
      },
      "provider_reference":{
         "order_id":"6a5f5159-c5dc-43b2-b3d4-34471d9be94c",
         "payment_id":"82106789179776-1"
      }
   },
   "country_code":"AR",
   "channel":"SDK",
   "order_id":"9dd3f765-a51a-49d8-b6af-a51d5a0b3f7f",
   "payment_method":{
      "code":"PAYPAL",
      "expiration_date":"2026-07-27T15:00:00.000Z"
   },
   "provider":{
      "installments":1
   }
}

BNPL

{
   "status":{
      "type":"Waiting",
      "reason":"FirstPayment" | "EmailValidation" | "WhatsAppValidation",
      "date":"2021-01-01T00:00:00.000Z"
   },
   "store":{
      "code":"SBXSTORE",
      "category":"4816"
   },
   "transaction":{
      "reference_id":"REF0000001",
      "business_id":"BIZ0000001",
      "account":"SBX000",
      "amount":{
         "currency_code":"BRL",
         "value":1500.56
      }
   },
   "order_id":"9dd3f765-a51a-49d8-b6af-a51d5a0b3f7f",
   "installment_option":{
      "installments":5,
      "installment_rate":3.2,
      "installment_amount":271.84,
      "total_amount":2000,
      "currency_code":"BRL",
      "first_due_date":"2021-10-25T00:00:00Z"
   },
   "return_url":"https://payments.koin.com.br/checkout/17c9cc35-0ee6-42a0-9748-1ead98b1ed42"
}
{
   "status":{
      "type":"Pending",
      "reason":"ProviderReview",
      "date":"2021-01-01T00:00:00.000Z"
   },
   "store":{
      "code":"SBXSTORE",
      "category":"4816"
   },
   "transaction":{
      "reference_id":"REF0000001",
      "business_id":"BIZ0000001",
      "account":"SBX000",
      "amount":{
         "currency_code":"BRL",
         "value":1500.56
      }
   },
   "order_id":"9dd3f765-a51a-49d8-b6af-a51d5a0b3f7f",
   "installment_option":{
      "installments":5,
      "installment_rate":3.2,
      "installment_amount":271.84,
      "total_amount":2000,
      "currency_code":"BRL",
      "first_due_date":"2021-10-25T00:00:00Z"
   },
   "return_url":"https://payments.koin.com.br/checkout/17c9cc35-0ee6-42a0-9748-1ead98b1ed42"
}
{
   "status":{
      "type":"Collected",
      "date":"2021-01-01T00:00:00.000Z"
   },
   "store":{
      "code":"SBXSTORE",
      "category":"4816"
   },
   "transaction":{
      "reference_id":"REF0000001",
      "business_id":"BIZ0000001",
      "account":"SBX000",
      "amount":{
         "currency_code":"BRL",
         "value":1500.56
      }
   },
   "order_id":"9dd3f765-a51a-49d8-b6af-a51d5a0b3f7f",
   "installment_option":{
      "installments":5,
      "installment_rate":3.2,
      "installment_amount":271.84,
      "total_amount":2000,
      "currency_code":"BRL",
      "first_due_date":"2021-10-25T00:00:00Z"
   }
}
{
   "status":{
      "type":"Cancelled",
      "date":"2021-01-01T00:00:00.000Z"
   },
   "store":{
      "code":"SBXSTORE",
      "category":"4816"
   },
   "transaction":{
      "reference_id":"REF0000001",
      "business_id":"BIZ0000001",
      "account":"SBX000",
      "amount":{
         "currency_code":"BRL",
         "value":1500.56
      }
   },
   "order_id":"9dd3f765-a51a-49d8-b6af-a51d5a0b3f7f",
   "installment_option":{
      "installments":5,
      "installment_rate":3.2,
      "installment_amount":271.84,
      "total_amount":2000,
      "currency_code":"BRL",
      "first_due_date":"2021-10-25T00:00:00Z"
   },
   "return_url":"https://payments.koin.com.br/checkout/17c9cc35-0ee6-42a0-9748-1ead98b1ed42"
}

Card

{
   "status":{
      "type":"Authorized",
      "date":"2021-09-03T15:27:28.000Z",
      "expiration":"2021-09-04T15:27:28.000Z"
   },
   "store":{
      "code":"SBXSTORE"
   },
   "transaction":{
      "reference_id":"REF0000001",
      "account":"SBX000",
      "authorization_code":"3239900",
      "acquirer":"FISERV",
      "commerce_number":"9236374834",
      "provider_reference": {
       	"order_id": "cd548679-bba2-4208-89ba-1db4dc1bd459",
       	"payment_id": "41da0f11-f4b3-4f85-8567-8d1fe52d6df5"
      }
   },
   "country_code":"BR",
   "order_id":"9dd3f765-a51a-49d8-b6af-a51d5a0b3f7f"
}
{
   "status":{
      "type":"Collected",
      "date":"2021-09-03T15:27:28.000Z"
   },
   "store":{
      "code":"SBXSTORE"
   },
   "transaction":{
      "reference_id":"REF0000001",
      "account":"SBX000",
      "authorization_code":"3239900",
      "acquirer":"FISERV",
      "commerce_number":"9236374834",
      "provider_reference": {
       	"order_id": "cd548679-bba2-4208-89ba-1db4dc1bd459",
       	"payment_id": "41da0f11-f4b3-4f85-8567-8d1fe52d6df5"
      }
   },
   "order_id":"9dd3f765-a51a-49d8-b6af-a51d5a0b3f7f"
}
{
    "status":{
      "type": "Cancelled",
      "date": "2021-09-03T15:27:28.000Z"
    },
    "store": {
      "code": "SBXSTORE"
    },
    "transaction": {
      "reference_id": "REF0000001",
      "account": "SBX000"
    },
    "order_id": "9dd3f765-a51a-49d8-b6af-a51d5a0b3f7f"
  }
{
   "status":{
      "type":"Voided",
      "date":"2021-09-03T15:27:28.000Z"
   },
   "store":{
      "code":"SBXSTORE"
   },
   "transaction":{
      "reference_id":"REF0000001",
      "account":"SBX000",
      "authorization_code":"3239900",
      "acquirer":"FISERV",
      "commerce_number":"9236374834"
   },
   "order_id":"9dd3f765-a51a-49d8-b6af-a51d5a0b3f7f"
}
{
    "status":{
      "type": "Refunded",
      "date": "2021-09-03T15:27:28.000Z"
    },
    "store": {
      "code": "SBXSTORE"
    },
    "transaction": {
      "reference_id": "REF0000001",
      "account": "SBX000"
    },
    "order_id": "9dd3f765-a51a-49d8-b6af-a51d5a0b3f7f"
  }
{
    "status": {
      "type": "Failed",
      "date": "2021-09-03T15:27:28.000Z",
      "reason": "Rejected"
    },
    "transaction": {
      "reference_id": "REF0000001",
      "account": "SBX000"
    },
    "order_id": "9dd3f765-a51a-49d8-b6af-a51d5a0b3f7f",
  }

Payout notifications

{
  "status": {
    "type": "Published",
    "date": "2021-01-01T00:00:00.000Z"
  },
  "transaction": {
    "reference_id": "REF0000001",
    "account": "SBX000PO",
    "amount": {
      "currency_code": "BRL",
      "value": "1500.56"
    }
  },
  "payout_id": "5t1bc9001-6b5a-4f21-b5ee-fd32m4f436c6"
}
{
  "status": {
    "type": "Transferred",
    "date": "2021-01-01T00:00:00.000Z"
  },
  "transaction": {
    "reference_id": "REF0000001",
    "account": "SBX000PO",
    "amount": {
      "currency_code": "BRL",
      "value": "1500.56"
    }
  },
  "payout_id": "5t1bc9001-6b5a-4f21-b5ee-fd32m4f436c6"
}
{
  "status": {
    "type": "Failed",
    "reason": "Rejected",
    "message": "Payout rejected",
    "date": "2021-01-01T00:00:00.000Z"
  },
  "transaction": {
    "reference_id": "REF0000001",
    "account": "SBX000PO",
    "amount": {
      "currency_code": "BRL",
      "value": "1500.56"
    }
  },
  "payout_id": "5t1bc9001-6b5a-4f21-b5ee-fd32m4f436c6"
}