Webhooks Reference

Listen for events in your application so your integration can automatically triggers reactions.

AmiliPay uses webhooks to notify your application when an event happens in your account. Webhooks are particularly useful for events like when customer's invoice
has been paid or refused, when a customer started his onboarding and when onboarding status is changed.

Please note, that every date and time which is sent in the payload is using the UTC time zone.

Adding a webhook endpoint

Register a webhook endpoint yourself from the merchant/partner dashboard under Settings > Webhooks - enter your callback_url, choose which events to subscribe to, and save; this returns a signing secret used to verify deliveries. There is no partner-API endpoint for this today - it's dashboard-only, not something you can automate from your own backend.

Your application should respond to AmiliPay's webhook with a 2xx status. Otherwise we retry:

1st retry after 1 minute

2nd retry after 5 minutes

3rd retry after 15 minutes

4th retry after 60 minutes

(4 retries total, then we stop)

HMAC signature

Every event is signed with an HMAC-SHA256 signature over the JSON payload, sent in the X-AmiliPay-Signature header. The delivery time is sent alongside it in the X-AmiliPay-Timestamp header, but the timestamp is not itself part of the signed string.

The secret used to sign requests to a given endpoint is provided to you once, when the endpoint is set up.

Signing process on our side is done like this:

Verify this signature in your integration to confirm the payload hasn't been tampered with. As a general precaution, also reject any request where X-AmiliPay-Timestamp is more than 5 minutes old to guard against replay - this is a freshness check on that header's value, not something the signature itself binds.

Every delivery also carries X-AmiliPay-Event (the event type) and X-AmiliPay-Event-Id headers, and a User-Agent: AmiliPay-Webhooks/1.0.

Invoice webhooks

AmiliPay supports several types of invoice events:

INVOICE_PAYMENT_AUTHORIZED

INVOICE_PAYMENT_REFUSED

INVOICE_OVERDUE

INVOICE_REFUND_INITIATED

INVOICE_REFUNDED

INVOICE_REFUND_FAILED

INVOICE_CHARGEBACK

INVOICE_CHARGEBACK_REVERSED

INVOICE_SECOND_CHARGEBACK

10.

INVOICE_RECURRING_INITIATED

11.

INVOICE_RECURRING_TOKEN_DELETED

12.

INVOICE_DELIVERY_SUCCESS

13.

INVOICE_DELIVERY_FAILED

14.

INVOICE_PAYMENT_PAID

Invoice payment authorized event

Event of this type is sent when customer pays his invoice.

Payload sample

{
  "data": {
    "unique_id": "O5XRLP0Muabxufne6Eb62uFjAvj8D5nog3waANRQEI5Ce7zcC6",
    "account_id": 1,
    "invoice_id": "1",
    "amount": 15000,
    "customer_id": "1",
    "customer_reference": "PO-88231",
    "name": "FirstName LastName",
    "email": "firstname.lastname@mail.com",
    "phone": "+4444444444",
    "currency": "NOK",
    "notify_customer": true,
    "reminded": false,
    "payment_method": "visa",
    "opened": 1,
    "language": "no",
    "redirect_url": "https://www.customer.com/callback",
    "cancel_url": null,
    "due_date": "2022-02-08T00:00:00",
    "last_payment_date": "2022-02-15T00:00:00",
    "paid_at": "2022-02-07T13:23:38",
    "created_at": "2022-02-04T10:19:29",
    "updated_at": "2022-02-07T13:23:38",
    "deleted_at": null,
    "deactivated_at": null,
    "refunded_at": null,
    "payment_url": "http://pay.amili.no/pay-invoice/O5XRLP0Muabxufne6Eb62uFjAvj8D5nog3waANRQEI5Ce7zcC6",
    "is_recurring": false,
    "recurring_invoice_id": null
  },
  "event": "INVOICE_PAYMENT_AUTHORIZED",
  "message": "Invoice payment is authorized."
}

Notes on every invoice event payload below: date/time fields are ISO-8601 (e.g. "2022-02-07T13:23:38"), and an unset date is JSON null, not an empty string. is_recurring is always present (false on non-recurring invoices). details (card summary) appears only once the invoice has been paid. customer_reference is the merchant-supplied reference sent when the invoice was created; it is null when none was supplied.

Invoice payment refused event

Event of this type is sent when customer payment process failed (wrong CVC, card holder name, etc.).

Payload sample

{
  "data": {
    "unique_id": "O5XRLP0Muabxufne6Eb62uFjAvj8D5nog3waANRQEI5Ce7zcC6",
    "account_id": 1,
    "invoice_id": "1",
    "amount": 15000,
    "customer_id": "1",
    "customer_reference": "PO-88231",
    "name": "FirstName LastName",
    "email": "firstname.lastname@mail.com",
    "phone": "+4444444444",
    "currency": "NOK",
    "notify_customer": true,
    "reminded": false,
    "payment_method": "visa",
    "opened": 1,
    "language": "no",
    "redirect_url": "https://www.customer.com/callback",
    "cancel_url": null,
    "due_date": "2022-02-08T00:00:00",
    "last_payment_date": "2022-02-15T00:00:00",
    "paid_at": null,
    "created_at": "2022-02-04T10:19:29",
    "updated_at": "2022-02-07T13:23:38",
    "deleted_at": null,
    "deactivated_at": null,
    "refunded_at": null,
    "payment_url": "http://pay.amili.no/pay-invoice/O5XRLP0Muabxufne6Eb62uFjAvj8D5nog3waANRQEI5Ce7zcC6",
    "is_recurring": false,
    "recurring_invoice_id": null
  },
  "event": "INVOICE_PAYMENT_REFUSED",
  "message": "Invoice payment was refused."
}

The specific decline reason (wrong CVC, card holder name, etc.) is not carried in message - it's a static string for this event type.

Invoice overdue event

Event of this type is sent when comes invoice overdue date.

Payload sample

{
  "data": {
    "unique_id": "O5XRLP0Muabxufne6Eb62uFjAvj8D5nog3waANRQEI5Ce7zcC6",
    "account_id": 1,
    "invoice_id": "1",
    "amount": 15000,
    "customer_id": "1",
    "customer_reference": "PO-88231",
    "name": "FirstName LastName",
    "email": "firstname.lastname@mail.com",
    "phone": "+4444444444",
    "currency": "NOK",
    "notify_customer": true,
    "reminded": false,
    "payment_method": "visa",
    "opened": 1,
    "language": "no",
    "redirect_url": "https://www.customer.com/callback",
    "cancel_url": null,
    "due_date": "2022-02-08T00:00:00",
    "last_payment_date": "2022-02-15T00:00:00",
    "paid_at": null,
    "created_at": "2022-02-04T10:19:29",
    "updated_at": "2022-02-07T13:23:38",
    "deleted_at": null,
    "deactivated_at": "2022-02-07T13:23:38",
    "refunded_at": null,
    "payment_url": "http://pay.amili.no/pay-invoice/O5XRLP0Muabxufne6Eb62uFjAvj8D5nog3waANRQEI5Ce7zcC6",
    "is_recurring": false,
    "recurring_invoice_id": null
  },
  "event": "INVOICE_OVERDUE",
  "message": "Invoice is overdue. Payment is disabled."
}

Invoice refund iniatiated event

Event of this type is sent when invoice refund is initiated.

Payload sample

{
  "data": {
    "unique_id": "O5XRLP0Muabxufne6Eb62uFjAvj8D5nog3waANRQEI5Ce7zcC6",
    "account_id": 1,
    "invoice_id": "1",
    "amount": 15000,
    "customer_id": "1",
    "customer_reference": "PO-88231",
    "name": "FirstName LastName",
    "email": "firstname.lastname@mail.com",
    "phone": "+4444444444",
    "currency": "NOK",
    "notify_customer": true,
    "reminded": false,
    "payment_method": "visa",
    "opened": 1,
    "language": "no",
    "redirect_url": "https://www.customer.com/callback",
    "cancel_url": null,
    "due_date": "2022-02-08T00:00:00",
    "last_payment_date": "2022-02-15T00:00:00",
    "paid_at": "2022-02-14T17:33:00",
    "created_at": "2022-02-04T10:19:29",
    "updated_at": "2022-02-14T17:33:00",
    "deleted_at": null,
    "deactivated_at": "2022-02-07T13:23:38",
    "refunded_at": null,
    "payment_url": "http://pay.amili.no/pay-invoice/O5XRLP0Muabxufne6Eb62uFjAvj8D5nog3waANRQEI5Ce7zcC6",
    "is_recurring": false,
    "recurring_invoice_id": null
  },
  "event": "INVOICE_REFUND_INITIATED",
  "message": "The refund (amount: 150.00 NOK) has been initiated."
}

Invoice refund event

Event of this type is sent when invoice is refunded.

Payload sample

{
  "data": {
    "unique_id": "O5XRLP0Muabxufne6Eb62uFjAvj8D5nog3waANRQEI5Ce7zcC6",
    "account_id": 1,
    "invoice_id": "1",
    "amount": 15000,
    "customer_id": "1",
    "customer_reference": "PO-88231",
    "name": "FirstName LastName",
    "email": "firstname.lastname@mail.com",
    "phone": "+4444444444",
    "currency": "NOK",
    "notify_customer": true,
    "reminded": false,
    "payment_method": "visa",
    "opened": 1,
    "language": "no",
    "redirect_url": "https://www.customer.com/callback",
    "cancel_url": null,
    "due_date": "2022-02-08T00:00:00",
    "last_payment_date": "2022-02-15T00:00:00",
    "paid_at": "2022-02-14T17:33:00",
    "created_at": "2022-02-04T10:19:29",
    "updated_at": "2022-02-15T12:43:00",
    "deleted_at": "2022-02-15T12:43:00",
    "deactivated_at": "2022-02-07T13:23:38",
    "refunded_at": "2022-02-15T12:43:00",
    "payment_url": "http://pay.amili.no/pay-invoice/O5XRLP0Muabxufne6Eb62uFjAvj8D5nog3waANRQEI5Ce7zcC6",
    "is_recurring": false,
    "recurring_invoice_id": null
  },
  "event": "INVOICE_REFUNDED",
  "message": "The refund (amount: 150.00 NOK) has been completed."
}

Invoice refund failed event

Event of this type is sent when invoice refund is failed.

Payload sample

{
  "data": {
    "unique_id": "O5XRLP0Muabxufne6Eb62uFjAvj8D5nog3waANRQEI5Ce7zcC6",
    "account_id": 1,
    "invoice_id": "1",
    "amount": 15000,
    "customer_id": "1",
    "customer_reference": "PO-88231",
    "name": "FirstName LastName",
    "email": "firstname.lastname@mail.com",
    "phone": "+4444444444",
    "currency": "NOK",
    "notify_customer": true,
    "reminded": false,
    "payment_method": "visa",
    "opened": 1,
    "language": "no",
    "redirect_url": "https://www.customer.com/callback",
    "cancel_url": null,
    "due_date": "2022-02-08T00:00:00",
    "last_payment_date": "2022-02-15T00:00:00",
    "paid_at": "2022-02-14T17:33:00",
    "created_at": "2022-02-04T10:19:29",
    "updated_at": "2022-02-14T17:33:00",
    "deleted_at": null,
    "deactivated_at": "2022-02-07T13:23:38",
    "refunded_at": null,
    "payment_url": "http://pay.amili.no/pay-invoice/O5XRLP0Muabxufne6Eb62uFjAvj8D5nog3waANRQEI5Ce7zcC6",
    "is_recurring": false,
    "recurring_invoice_id": null
  },
  "event": "INVOICE_REFUND_FAILED",
  "message": "The refund request has failed."
}

message is a static string for this event type - it does not carry the specific failure reason (e.g. amount too high).

Invoice chargeback event

Event of this type is sent when invoice is charged back.

Payload sample

{
  "data": {
    "unique_id": "O5XRLP0Muabxufne6Eb62uFjAvj8D5nog3waANRQEI5Ce7zcC6",
    "account_id": 1,
    "invoice_id": "1",
    "amount": 15000,
    "customer_id": "1",
    "customer_reference": "PO-88231",
    "name": "FirstName LastName",
    "email": "firstname.lastname@mail.com",
    "phone": "+4444444444",
    "currency": "NOK",
    "notify_customer": true,
    "reminded": false,
    "payment_method": "visa",
    "opened": 1,
    "language": "no",
    "redirect_url": "https://www.customer.com/callback",
    "cancel_url": null,
    "due_date": "2022-02-08T00:00:00",
    "last_payment_date": "2022-02-15T00:00:00",
    "paid_at": null,
    "created_at": "2022-02-04T10:19:29",
    "updated_at": "2022-02-14T17:33:00",
    "deleted_at": "2022-02-14T17:33:00",
    "deactivated_at": "2022-02-07T13:23:38",
    "refunded_at": null,
    "payment_url": "http://pay.amili.no/pay-invoice/O5XRLP0Muabxufne6Eb62uFjAvj8D5nog3waANRQEI5Ce7zcC6",
    "is_recurring": false,
    "recurring_invoice_id": null
  },
  "event": "INVOICE_CHARGEBACK",
  "message": "The payment has been charged back."
}

Invoice chargeback reversed event

Event of this type is sent when invoice chargeback is reversed.

Payload sample

{
  "data": {
    "unique_id": "O5XRLP0Muabxufne6Eb62uFjAvj8D5nog3waANRQEI5Ce7zcC6",
    "account_id": 1,
    "invoice_id": "1",
    "amount": 15000,
    "customer_id": "1",
    "customer_reference": "PO-88231",
    "name": "FirstName LastName",
    "email": "firstname.lastname@mail.com",
    "phone": "+4444444444",
    "currency": "NOK",
    "notify_customer": true,
    "reminded": false,
    "payment_method": "visa",
    "opened": 1,
    "language": "no",
    "redirect_url": "https://www.customer.com/callback",
    "cancel_url": null,
    "due_date": "2022-02-08T00:00:00",
    "last_payment_date": "2022-02-15T00:00:00",
    "paid_at": "2022-02-14T17:33:00",
    "created_at": "2022-02-04T10:19:29",
    "updated_at": "2022-02-14T17:33:00",
    "deleted_at": "2022-02-14T17:33:00",
    "deactivated_at": "2022-02-07T13:23:38",
    "refunded_at": null,
    "payment_url": "http://pay.amili.no/pay-invoice/O5XRLP0Muabxufne6Eb62uFjAvj8D5nog3waANRQEI5Ce7zcC6",
    "is_recurring": false,
    "recurring_invoice_id": null
  },
  "event": "INVOICE_CHARGEBACK_REVERSED",
  "message": "The payment chargeback has been reversed."
}

Invoice second chargeback event

Event of this type is sent when invoice is charged back second time.

Payload sample

{
  "data": {
    "unique_id": "O5XRLP0Muabxufne6Eb62uFjAvj8D5nog3waANRQEI5Ce7zcC6",
    "account_id": 1,
    "invoice_id": "1",
    "amount": 15000,
    "customer_id": "1",
    "customer_reference": "PO-88231",
    "name": "FirstName LastName",
    "email": "firstname.lastname@mail.com",
    "phone": "+4444444444",
    "currency": "NOK",
    "notify_customer": true,
    "reminded": false,
    "payment_method": "visa",
    "opened": 1,
    "language": "no",
    "redirect_url": "https://www.customer.com/callback",
    "cancel_url": null,
    "due_date": "2022-02-08T00:00:00",
    "last_payment_date": "2022-02-15T00:00:00",
    "paid_at": null,
    "created_at": "2022-02-04T10:19:29",
    "updated_at": "2022-02-14T17:33:00",
    "deleted_at": "2022-02-14T17:33:00",
    "deactivated_at": "2022-02-07T13:23:38",
    "refunded_at": null,
    "payment_url": "http://pay.amili.no/pay-invoice/O5XRLP0Muabxufne6Eb62uFjAvj8D5nog3waANRQEI5Ce7zcC6",
    "is_recurring": false,
    "recurring_invoice_id": null
  },
  "event": "INVOICE_SECOND_CHARGEBACK",
  "message": "The payment has been charged back second time."
}

Invoice recurring payment initiated event

Event of this type is sent when we do not have any stored payment tokens for applying recurring payments.

This webhook informs you that you should redirect your customer to the payment window where the payment will be done manually for the first time.
After successful payment, we will store payment token which will be used for future recurring invoices.

Payload sample

{
"data": {
"unique_id": "O5XRLP0Muabxufne6Eb62uFjAvj8D5nog3waANRQEI5Ce7zcC6",
"account_id": 1,
"invoice_id": "1",
"amount": 15000,
"customer_id": "1",
"customer_reference": "PO-88231",
"name": "FirstName LastName",
"email": "firstname.lastname@mail.com",
"phone": "+4444444444",
"currency": "NOK",
"notify_customer": true,
"reminded": false,
"payment_method": "visa",
"opened": 1,
"language": "no",
"redirect_url": "https://www.customer.com/callback",
"cancel_url": null,
"due_date": "2022-02-08T00:00:00",
"last_payment_date": "2022-02-15T00:00:00",
"paid_at": null,
"created_at": "2022-02-04T10:19:29",
"updated_at": "2022-02-14T17:33:00",
"deleted_at": "2022-02-14T17:33:00",
"deactivated_at": "2022-02-07T13:23:38",
"refunded_at": null,
"payment_url": "http://pay.amili.no/pay-invoice/O5XRLP0Muabxufne6Eb62uFjAvj8D5nog3waANRQEI5Ce7zcC6",
"is_recurring": true,
"recurring_invoice_id": null
},
"event": "INVOICE_RECURRING_INITIATED",
"message": "Recurring payment initiated - customer must re-authenticate to capture token."
}

Invoice recurring payment token deleted

Event of this type is sent when automatic payment with the same token fails for 10 times. This webhook means that the token is deleted from our system
and adding it again next time you will receive a webhook INVOICE_RECURRING_INITIATED which means that your customer should go to the payment page
and pay manually the invoice.

{
"data": {
"unique_id": "O5XRLP0Muabxufne6Eb62uFjAvj8D5nog3waANRQEI5Ce7zcC6",
"account_id": 1,
"invoice_id": "1",
"amount": 15000,
"customer_id": "1",
"customer_reference": "PO-88231",
"name": "FirstName LastName",
"email": "firstname.lastname@mail.com",
"phone": "+4444444444",
"currency": "NOK",
"notify_customer": true,
"reminded": false,
"payment_method": "visa",
"opened": 1,
"language": "no",
"redirect_url": "https://www.customer.com/callback",
"cancel_url": null,
"due_date": "2022-02-08T00:00:00",
"last_payment_date": "2022-02-15T00:00:00",
"paid_at": null,
"created_at": "2022-02-04T10:19:29",
"updated_at": "2022-02-14T17:33:00",
"deleted_at": "2022-02-14T17:33:00",
"deactivated_at": "2022-02-07T13:23:38",
"refunded_at": null,
"payment_url": "http://pay.amili.no/pay-invoice/O5XRLP0Muabxufne6Eb62uFjAvj8D5nog3waANRQEI5Ce7zcC6",
"is_recurring": true,
"recurring_invoice_id": null
},
"event": "INVOICE_RECURRING_TOKEN_DELETED",
"message": "Recurring payment token deleted after 10 consecutive failures."
}

Invoice delivery success event

Event of this type is sent when the invoice email actually lands in your customer's inbox. We get delivery confirmation for every invoice email we send, so you don't have to guess whether the customer ever saw it.

This event is sent to the merchant only - it is never forwarded to a partner account, unlike most other invoice events.

Payload sample

{
  "data": {
    "unique_id": "O5XRLP0Muabxufne6Eb62uFjAvj8D5nog3waANRQEI5Ce7zcC6",
    "account_id": 1,
    "invoice_id": "1",
    "amount": 15000,
    "customer_id": "1",
    "customer_reference": "PO-88231",
    "name": "FirstName LastName",
    "email": "firstname.lastname@mail.com",
    "phone": "+4444444444",
    "currency": "NOK",
    "notify_customer": true,
    "reminded": false,
    "payment_method": "visa",
    "opened": 1,
    "language": "no",
    "redirect_url": "https://www.customer.com/callback",
    "cancel_url": null,
    "due_date": "2022-02-08T00:00:00",
    "last_payment_date": "2022-02-15T00:00:00",
    "paid_at": null,
    "created_at": "2022-02-04T10:19:29",
    "updated_at": "2022-02-04T10:19:35",
    "deleted_at": null,
    "deactivated_at": null,
    "refunded_at": null,
    "payment_url": "http://pay.amili.no/pay-invoice/O5XRLP0Muabxufne6Eb62uFjAvj8D5nog3waANRQEI5Ce7zcC6",
    "is_recurring": false,
    "recurring_invoice_id": null
  },
  "event": "INVOICE_DELIVERY_SUCCESS",
  "message": "Invoice was delivered to the customer.",
  "delivery_channel": "email"
}

Note the extra delivery_channel field sitting next to data/event/message (not inside data) - it tells you which channel the invoice was sent on. Today it is always "email".

Invoice delivery failed event

Event of this type is sent when the invoice email could not be delivered - for example the address bounced, was blocked, or was dropped by the mail server. Use this to catch customers with a bad email address early, before they miss their due date without ever seeing the invoice.

A slow or temporarily deferred email is not reported here - delivery is retried for up to 72 hours and usually succeeds, so we only fire this event once delivery has permanently failed.

Like INVOICE_DELIVERY_SUCCESS, this event goes to the merchant only, never to a partner account.

Payload sample

{
  "data": {
    "unique_id": "O5XRLP0Muabxufne6Eb62uFjAvj8D5nog3waANRQEI5Ce7zcC6",
    "account_id": 1,
    "invoice_id": "1",
    "amount": 15000,
    "customer_id": "1",
    "customer_reference": "PO-88231",
    "name": "FirstName LastName",
    "email": "firstname.lastname@mail.com",
    "phone": "+4444444444",
    "currency": "NOK",
    "notify_customer": true,
    "reminded": false,
    "payment_method": "visa",
    "opened": 1,
    "language": "no",
    "redirect_url": "https://www.customer.com/callback",
    "cancel_url": null,
    "due_date": "2022-02-08T00:00:00",
    "last_payment_date": "2022-02-15T00:00:00",
    "paid_at": null,
    "created_at": "2022-02-04T10:19:29",
    "updated_at": "2022-02-04T10:19:35",
    "deleted_at": null,
    "deactivated_at": null,
    "refunded_at": null,
    "payment_url": "http://pay.amili.no/pay-invoice/O5XRLP0Muabxufne6Eb62uFjAvj8D5nog3waANRQEI5Ce7zcC6",
    "is_recurring": false,
    "recurring_invoice_id": null
  },
  "event": "INVOICE_DELIVERY_FAILED",
  "message": "Invoice delivery failed (bounce): The email account does not exist.",
  "delivery_channel": "email"
}

message here includes the actual failure reason reported by the mail server (e.g. bounce/blocked/dropped), unlike most other invoice events where message is a fixed string. As with the success event, delivery_channel sits next to data, not inside it, and is currently always "email".

Invoice payment paid event

Event of this type is sent when an invoice's payment has actually been paid out to your bank account, as part of a payout batch. It follows the REPORT_AVAILABLE payout webhook (see Payout webhooks below) and fires once per invoice in that payout, one by one - so a payout settling 6 invoices sends 6 separate INVOICE_PAYMENT_PAID events, each naming exactly one invoice, rather than a single event listing all of them. This means you don't have to cross-reference the payout report yourself.

Unlike the delivery events above, this one is sent to both the merchant and the partner account (when the merchant belongs to a partner), the same fan-out as most other invoice events.

Payload sample

{
  "data": {
    "unique_id": "O5XRLP0Muabxufne6Eb62uFjAvj8D5nog3waANRQEI5Ce7zcC6",
    "account_id": 1,
    "invoice_id": "1",
    "amount": 15000,
    "customer_id": "1",
    "customer_reference": "PO-88231",
    "name": "FirstName LastName",
    "email": "firstname.lastname@mail.com",
    "phone": "+4444444444",
    "currency": "NOK",
    "notify_customer": true,
    "reminded": false,
    "payment_method": "visa",
    "opened": 1,
    "language": "no",
    "redirect_url": "https://www.customer.com/callback",
    "cancel_url": null,
    "due_date": "2022-02-08T00:00:00",
    "last_payment_date": "2022-02-15T00:00:00",
    "paid_at": "2022-02-07T13:23:38",
    "created_at": "2022-02-04T10:19:29",
    "updated_at": "2022-04-13T15:15:07",
    "deleted_at": null,
    "deactivated_at": null,
    "refunded_at": null,
    "payment_url": "http://pay.amili.no/pay-invoice/O5XRLP0Muabxufne6Eb62uFjAvj8D5nog3waANRQEI5Ce7zcC6",
    "is_recurring": false,
    "recurring_invoice_id": null
  },
  "event": "INVOICE_PAYMENT_PAID",
  "message": "Invoice payment has been paid out."
}

data is the same invoice shape used by every other invoice webhook - there is no extra payout information (amount, reference, etc.) in this payload; look those up on the matching REPORT_AVAILABLE event or via the payouts endpoint.

Onboarding webhooks

AmiliPay supports several types of onboarding events:

ONBOARDING_CREATED

ONBOARDING_STATUS_UPDATED

ONBOARDING_ERROR_ADDED

ONBOARDING_ERROR_REMOVED

ONBOARDING_PROCESSING_FAILED

Onboarding created event

Event of this type is sent when customer starts his onboarding process.

Payload sample

{
  "data": {
    "id": "3f2504e0-4f89-41d3-9a0c-0305e82c3301",
    "account_id": 3,
    "status": "STARTED",
    "status_changed_at": "2022-02-08 09:21:28",
    "ownership_category": "ownership_no_major",
    "company": {
      "id": "8f14e45f-ceea-467e-bd7b-6a35c5d18ea9",
      "industry_category": "0763",
      "tax_id": "116963",
      "registration_code": "64543302",
      "address": {
        "city": "Oslo",
        "country": "AO",
        "street_address": "Sæffleberggate 56",
        "zip": "0563"
      },
      "average_transaction": "250",
      "average_daily_transactions": "5",
      "documentation": [],
      "created_at": "2022-02-08 09:22:14",
      "updated_at": "2022-02-08 09:22:14"
    },
    "payout": {
      "id": "c9b1c1c1-6f2a-4f2a-8e2a-1a2b3c4d5e6f",
      "account_name": "Payout account",
      "bic": "NORWNOK1",
      "iban": "NO1111111111111",
      "currency": "NOK",
      "country": "NO",
      "city": "Oslo",
      "name": "Bank",
      "documentation": [],
      "created_at": "2022-02-08 09:22:14",
      "updated_at": "2022-02-08 09:22:14"
    },
    "shareholders": [
      {
        "id": "d4e5f6a7-b8c9-4d0e-9f1a-2b3c4d5e6f7a",
        "role": "procurator",
        "is_signatory": true,
        "ownership_percentage": 0,
        "procurator_is_confirmed": true,
        "first_name": "John",
        "last_name": "Doe",
        "gender": "male",
        "date_of_birth": "1966-01-31",
        "job_title": null,
        "address": {
          "city": "Oslo",
          "country": "NO",
          "street_address": "Sæffleberggate 56",
          "zip": "0563",
          "phone": "040123456"
        },
        "email": "customer@com.com",
        "nationality": "NO",
        "documentation": null,
        "created_at": "2022-02-08 09:22:01",
        "updated_at": "2022-02-08 09:22:01"
      }
    ],
    "created_at": "2022-02-08 09:21:28",
    "updated_at": "2022-02-08 09:21:28"
  },
  "event": "ONBOARDING_CREATED",
  "message": ""
}

Note: company/payout/shareholder id values are UUIDs, not integers, and there is no onboarding_id field anywhere inside these nested objects - the onboarding is identified only by the top-level id.

Onboarding status updated event

This type of event is sent to your integration when customer's onboarding status is changed.

Payload sample

{
  "data": {
    "id": "3f2504e0-4f89-41d3-9a0c-0305e82c3301",
    "account_id": 3,
    "status": "STARTED",
    "status_changed_at": "2022-02-08 09:21:28",
    "ownership_category": "ownership_no_major",
    "company": {
      "id": "8f14e45f-ceea-467e-bd7b-6a35c5d18ea9",
      "industry_category": "0763",
      "tax_id": "116963",
      "registration_code": "64543302",
      "address": {
        "city": "Oslo",
        "country": "AO",
        "street_address": "Sæffleberggate 56",
        "zip": "0563"
      },
      "average_transaction": "250",
      "average_daily_transactions": "5",
      "documentation": [],
      "created_at": "2022-02-08 09:22:14",
      "updated_at": "2022-02-08 09:22:14"
    },
    "payout": {
      "id": "c9b1c1c1-6f2a-4f2a-8e2a-1a2b3c4d5e6f",
      "account_name": "Payout account",
      "bic": "NORWNOK1",
      "iban": "NO1111111111111",
      "currency": "NOK",
      "country": "NO",
      "city": "Oslo",
      "name": "Bank",
      "documentation": [],
      "created_at": "2022-02-08 09:22:14",
      "updated_at": "2022-02-08 09:22:14"
    },
    "shareholders": [
      {
        "id": "d4e5f6a7-b8c9-4d0e-9f1a-2b3c4d5e6f7a",
        "role": "procurator",
        "is_signatory": true,
        "ownership_percentage": 0,
        "procurator_is_confirmed": true,
        "first_name": "John",
        "last_name": "Doe",
        "gender": "male",
        "date_of_birth": "1966-01-31",
        "job_title": null,
        "address": {
          "city": "Oslo",
          "country": "NO",
          "street_address": "Sæffleberggate 56",
          "zip": "0563",
          "phone": "040123456"
        },
        "email": "customer@com.com",
        "nationality": "NO",
        "documentation": null,
        "created_at": "2022-02-08 09:22:01",
        "updated_at": "2022-02-08 09:22:01"
      }
    ],
    "created_at": "2022-02-08 09:21:28",
    "updated_at": "2022-02-08 09:21:28"
  },
  "event": "ONBOARDING_STATUS_UPDATED",
  "message": "Status changed from PENDING_REVIEW to STARTED"
}

This is the same data shape as ONBOARDING_CREATED above - there is no separate account_bic/account_iban/account_number/account_bank_city/account_bank_name/account_deposit_currency/trading_name/onboarding_id/ownership_procurator_is_owner field anywhere in the real payload; the previous version of this sample used a stale, no-longer-accurate schema.

Onboarding error added

This event is sent when to the customer's onboarding an error was added.

Payload sample

{
  "data": {
    "step": "company",
    "field": "company-tax_id",
    "notes": null,
    "created_at": "2022-02-08T08:53:26.000000Z",
    "onboarding": {
        "id": "3f2504e0-4f89-41d3-9a0c-0305e82c3301",
        "account_id": 3,
        "status": "STARTED",
        "status_changed_at": "2022-02-08 09:21:28",
        "ownership_category": "ownership_no_major",
        "company": {
          "id": "8f14e45f-ceea-467e-bd7b-6a35c5d18ea9",
          "industry_category": "0763",
          "tax_id": "116963",
          "registration_code": "64543302",
          "address": {
            "city": "Oslo",
            "country": "AO",
            "street_address": "Sæffleberggate 56",
            "zip": "0563"
          },
          "average_transaction": "250",
          "average_daily_transactions": "5",
          "documentation": [],
          "created_at": "2022-02-08 09:22:14",
          "updated_at": "2022-02-08 09:22:14"
        },
        "payout": {
          "id": "c9b1c1c1-6f2a-4f2a-8e2a-1a2b3c4d5e6f",
          "account_name": "Payout account",
          "bic": "NORWNOK1",
          "iban": "NO1111111111111",
          "currency": "NOK",
          "country": "NO",
          "city": "Oslo",
          "name": "Bank",
          "documentation": [],
          "created_at": "2022-02-08 09:22:14",
          "updated_at": "2022-02-08 09:22:14"
        },
        "shareholders": [
          {
            "id": "d4e5f6a7-b8c9-4d0e-9f1a-2b3c4d5e6f7a",
            "role": "procurator",
            "is_signatory": true,
            "ownership_percentage": 0,
            "procurator_is_confirmed": true,
            "first_name": "John",
            "last_name": "Doe",
            "gender": "male",
            "date_of_birth": "1966-01-31",
            "job_title": null,
            "address": {
              "city": "Oslo",
              "country": "NO",
              "street_address": "Sæffleberggate 56",
              "zip": "0563",
              "phone": "040123456"
            },
            "email": "customer@com.com",
            "nationality": "NO",
            "documentation": null,
            "created_at": "2022-02-08 09:22:01",
            "updated_at": "2022-02-08 09:22:01"
          }
        ],
        "created_at": "2022-02-08 09:21:28",
        "updated_at": "2022-02-08 09:21:28"
      },
    "updated_at": "2022-02-08T08:53:26.000000Z"
  },
  "event": "ONBOARDING_ERROR_ADDED",
  "message": ""
}

onboarding uses the same real shape as ONBOARDING_CREATED above - the previous sample's account_bic/trading_name/onboarding_id/ownership_procurator_is_owner fields don't exist in the real payload.

Onboarding error removed

This event is sent when onboarding error was removed from the customer's application.

Payload sample

{
  "data": {
    "step": "company",
    "field": "company-tax_id",
    "notes": null,
    "created_at": "2022-02-08T08:53:26.000000Z",
    "onboarding": {
        "id": "3f2504e0-4f89-41d3-9a0c-0305e82c3301",
        "account_id": 3,
        "status": "STARTED",
        "status_changed_at": "2022-02-08 09:21:28",
        "ownership_category": "ownership_no_major",
        "company": {
          "id": "8f14e45f-ceea-467e-bd7b-6a35c5d18ea9",
          "industry_category": "0763",
          "tax_id": "116963",
          "registration_code": "64543302",
          "address": {
            "city": "Oslo",
            "country": "AO",
            "street_address": "Sæffleberggate 56",
            "zip": "0563"
          },
          "average_transaction": "250",
          "average_daily_transactions": "5",
          "documentation": [],
          "created_at": "2022-02-08 09:22:14",
          "updated_at": "2022-02-08 09:22:14"
        },
        "payout": {
          "id": "c9b1c1c1-6f2a-4f2a-8e2a-1a2b3c4d5e6f",
          "account_name": "Payout account",
          "bic": "NORWNOK1",
          "iban": "NO1111111111111",
          "currency": "NOK",
          "country": "NO",
          "city": "Oslo",
          "name": "Bank",
          "documentation": [],
          "created_at": "2022-02-08 09:22:14",
          "updated_at": "2022-02-08 09:22:14"
        },
        "shareholders": [
          {
            "id": "d4e5f6a7-b8c9-4d0e-9f1a-2b3c4d5e6f7a",
            "role": "procurator",
            "is_signatory": true,
            "ownership_percentage": 0,
            "procurator_is_confirmed": true,
            "first_name": "John",
            "last_name": "Doe",
            "gender": "male",
            "date_of_birth": "1966-01-31",
            "job_title": null,
            "address": {
              "city": "Oslo",
              "country": "NO",
              "street_address": "Sæffleberggate 56",
              "zip": "0563",
              "phone": "040123456"
            },
            "email": "customer@com.com",
            "nationality": "NO",
            "documentation": null,
            "created_at": "2022-02-08 09:22:01",
            "updated_at": "2022-02-08 09:22:01"
          }
        ],
        "created_at": "2022-02-08 09:21:28",
        "updated_at": "2022-02-08 09:21:28"
      },
    "updated_at": "2022-02-08T08:53:26.000000Z"
  },
  "event": "ONBOARDING_ERROR_REMOVED",
  "message": ""
}

onboarding uses the same real shape as ONBOARDING_CREATED above.

Onboarding processing failed event

Sent when a step of the onboarding submission fails during underwriting processing - step is one of organization_legal_entity, shareholder_legal_entity, bank_transfer_instrument, document_upload, or business_line, identifying which part of the submission failed. onboarding_id is the onboarding's internal numeric identifier, not the UUID id used by the onboarding endpoints elsewhere in this API - there is currently no way to resolve one from the other via a public endpoint.

Payload sample

{
  "data": {
    "step": "bank_transfer_instrument",
    "onboarding_id": 1,
    "errors": [
      { "field": "iban", "message": "The IBAN could not be validated by the payment provider." }
    ]
  },
  "event": "ONBOARDING_PROCESSING_FAILED",
  "message": "The IBAN could not be validated by the payment provider."
}

message is the joined text of every entry in errors (semicolon-separated when there's more than one).

Payout webhooks

AmiliPay supports one type of payout events:

REPORT_AVAILABLE

Payout report available event

Event of this type is sent when new payout report is available.

Payload sample

{
  "data": {
    "id": 1,
    "uuid": "98fb7eb8-64dc-4d37-a5f8-502fe25b0c4c",
    "reference": "8916497364063763",
    "currency": "NOK",
    "amount": 632519,
    "status": "Completed",
    "creation_date": "2022-04-12",
    "updated_at": "2022-04-13T15:15:07",
    "created_at": "2022-04-13T15:15:07",
    "account_id": 1,
    "account_name": "Acme Merchant AS",
    "processed_at": "2022-04-13T15:15:07",
    "credited_amount": 1433181,
    "rounding": 0,
    "balance_transfer": 0,
    "refund": 0,
    "refund_cost": 0,
    "chargeback": -757881,
    "chargeback_cost": -23359,
    "chargeback_reversed": 160,
    "chargeback_reversed_cost": 5,
    "second_chargeback": -89,
    "second_chargeback_cost": -3,
    "fees": -19495,
    "platform_fee": 0,
    "deposit_correction": 0,
    "next_balance_transfer": 0,
    "scheduled_at": null,
    "batch": null,
    "modification_reference": null,
    "transactions_count": 6
  },
  "event": "REPORT_AVAILABLE",
  "message": "Payout report is available."
}

Notes: creation_date is a plain date (no time component) - different from every other timestamp field here, which are full date-times. batch and modification_reference are reserved legacy columns that are never populated by any current code path - they are always null. status is one of Pending, Processing, Completed, Failed, Returned. transactions_count appears only on this webhook payload, not on GET /v1/payouts or GET /v1/payouts/{payout_id}.

Classification webhooks

Product-line classification is not currently available.

Adding a webhook endpoint#

HMAC signature#

Invoice webhooks#

Invoice payment authorized event#

Payload sample#

Invoice payment refused event#

Payload sample#

Invoice overdue event#

Payload sample#

Invoice refund iniatiated event#

Payload sample#

Invoice refund event#

Payload sample#

Invoice refund failed event#

Payload sample#

Invoice chargeback event#

Payload sample#

Invoice chargeback reversed event#

Payload sample#

Invoice second chargeback event#

Payload sample#

Invoice recurring payment initiated event#

Payload sample#

Invoice recurring payment token deleted#

Invoice delivery success event#

Payload sample#

Invoice delivery failed event#

Payload sample#

Invoice payment paid event#

Payload sample#

Onboarding webhooks#

Onboarding created event#

Payload sample#

Onboarding status updated event#

Payload sample#

Onboarding error added#

Payload sample#

Onboarding error removed#

Payload sample#

Onboarding processing failed event#

Payload sample#

Payout webhooks#

Payout report available event#

Payload sample#

Classification webhooks#

Adding a webhook endpoint

HMAC signature

Invoice webhooks

Invoice payment authorized event

Payload sample

Invoice payment refused event

Payload sample

Invoice overdue event

Payload sample

Invoice refund iniatiated event

Payload sample

Invoice refund event

Payload sample

Invoice refund failed event

Payload sample

Invoice chargeback event

Payload sample

Invoice chargeback reversed event

Payload sample

Invoice second chargeback event

Payload sample

Invoice recurring payment initiated event

Payload sample

Invoice recurring payment token deleted

Invoice delivery success event

Payload sample

Invoice delivery failed event

Payload sample

Invoice payment paid event

Payload sample

Onboarding webhooks

Onboarding created event

Payload sample

Onboarding status updated event

Payload sample

Onboarding error added

Payload sample

Onboarding error removed

Payload sample

Onboarding processing failed event

Payload sample

Payout webhooks

Payout report available event

Payload sample

Classification webhooks