Skip to main content

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"
}
}