Skip to main content
Version: v1

Webhooks

Once the state of the refund has changed, or a specific tranfer has been received from a creditor, the Getpaid refunds engine emits a webhook event in order to notify about the state, sending all the relevant data related to the refund or the transfer associated.

Setting the webhook URL​

The refund related webhook URL is specified when initiating a refund, by setting the urls.webhook field:

{
  "payment_id": "pay_926ap9a2ioesd1p0qsfjuk1bvv",
  "description": "Refund for ORD-123456",
  "reference": "REFUND-123456",
  "urls": {
    "webhook": "https://webhooks.haircutz.co/getpaid"
  }
}

For more details on the Initiate Refund API call, see Accept Payments.

Webhook Events​

tip

For a comprehensive reference on the schema of the refund webhooks, please see our API Reference.

Getpaid refunds engine sends the following webhooks:

Refund Initiated​

The refund_initiated event occurs when the refund associated to a specific payment is initiated.

Example Webhook​

{
  "id": "evt_4y7rv0p7zqv0f9arfsyr50864t",
  "type": "transfer_started",
  "occurred_at": "2019-08-24T14:15:22Z",
  "data": {
    "refund_id": "rfd_985qw1q0oiuyh4m1lkoima9lqz",
    "payment_id": "pay_473cr1y0ghbyc3m1yfbwvn3nxx",
    "amount_minor": 1000,
    "currency": "EUR",
    "reference": "ORD-123456"
  }
}

Transfer Received from Creditor​

The transfer_received_from_creditor event occurs when a transfer associated to a started payout has been received from the creditor. We will emit one event per actor involved in the payout.

Example Webhook​

{
  "id": "evt_4y7rv0p7zqv0f9arfsyr50864t",
  "type": "transfer_started",
  "occurred_at": "2019-08-24T14:15:22Z",
  "data": {
    "transfer_id": "tra_1a6po0p7zqv1q2arfsyr9548q",
    "refund_id": "rfd_985qw1q0oiuyh4m1lkoima9lqz",
    "payment_id": "pay_473cr1y0ghbyc3m1yfbwvn3nxx",
    "account_id": "acc_985qw1q0oiuyh4m1lkoima9lqz",
    "amount_minor": 1000,
    "currency": "EUR",
    "reference": "ORD-123456"
  }
}

Refund Started​

The refund_started event occurs once we have emitted the reimbursement to the debtor.

Example Webhook​

{
  "id": "evt_4y7rv0p7zqv0f9arfsyr50864t",
  "type": "refund_started",
  "occurred_at": "2019-08-24T14:15:22Z",
  "data": {
    "refund_id": "rfd_985qw1q0oiuyh4m1lkoima9lqz",
    "payment_id": "pay_473cr1y0ghbyc3m1yfbwvn3nxx",
    "amount_minor": 1000,
    "currency": "EUR",
    "reference": "ORD-123456"
  }
}

Refund Completed​

The refund_completed event occurs once the reimbursement has arrived at the debtor.

Example Webhook​

{
  "id": "evt_4y7rv0p7zqv0f9arfsyr50864t",
  "type": "refund_completed",
  "occurred_at": "2019-08-24T14:15:22Z",
  "data": {
    "refund_id": "rfd_985qw1q0oiuyh4m1lkoima9lqz",
    "payment_id": "pay_473cr1y0ghbyc3m1yfbwvn3nxx",
    "amount_minor": 1000,
    "currency": "EUR",
    "reference": "ORD-123456"
  }
}