Amili Docs
Home
Products
Products
  • Debt.collection
  • Account Receivable
  • Distribution
  • Pay
Go to amili.no
Home
Products
Products
  • Debt.collection
  • Account Receivable
  • Distribution
  • Pay
Go to amili.no
  1. PAY
  • Home
    • Welcome to Amili Docs
    • Responsible disclosure
    • Become a partner
  • Debt Collection
    • About the AutoCollect API
    • Getting started with the AutoCollect API
    • Webhooks
    • Example Workflow
    • Batches
      • GetBatchById
      • GetBatchesByOrganization
      • GetBatchById - Legacy (To be removed)
    • Collections
      • GetCasesByOrganization
      • AcceptDebtCollectionList
      • RejectDebtCollectionList
      • PauseCase
      • WithdrawCase
      • ResumeCase
      • AcceptEvictionRequest
      • RejectEvictionRequest
      • AcceptEvictionConfirmation
      • RejectEvictionConfirmation
      • GetCaseTimeline
      • GetTaskView
      • UpdateTask
      • GetCaseById
    • Correction
      • CreateCorrections
    • Invoice
      • CreateInvoices
      • GetInvoicesByOrganization
      • GetInvoiceById
    • Payment
      • CreatePayments
    • Settlement
      • GetSettlements
      • GetSettlement on Id
    • AutoCollect Legacy API
      • Attachment
        • /webapi/api/Attachment
      • Batch
        • /webapi/api/Batch
        • /webapi/api/Batch
      • Ping
        • /webapi/api/Ping
    • ErrorHandling
      • How to
      • Codes
        • DUPLICATE_UNIQUE_SOURCE_PAYMENT_ID
  • Accounts Receivable
    • Actions
      • POST (create) an action
      • POST (create) a reports action/generate a report
    • ArItems
      • GET a list of AR items
      • PUT (update) ar item details
      • GET one AR item
    • AutoPostings
      • POST (create) one or more auto postings
    • Batches
      • GET one batch
    • ClientConfigs
      • GET a list of client config values
      • GET values for one client config key
    • Codes
      • GET ARM system code values
    • Customers
      • POST (create) one customer
      • PUT (update) one customer
      • GET a list of customers
      • GET one customer
      • DELETE a customer
      • POST (create) a batch of customers
      • PUT (update) a batch of customers
    • DocumentBundles
      • GET a list of document bundles
      • GET one document bundle
    • Documents
      • POST (create) one document
      • GET a list of documents
      • GET one document
      • POST (create) a batch of documents
    • Files
      • GET one or more OS files
      • POST (upload) one or more OS files
      • GET one OS file
    • GlItems
      • Get one GL item
      • GET a list of GL items
    • GlMovements
      • Get movement/balance for the latest closed GL year/period
      • GET a list of GL movements/balances
    • Insights
      • GET a list of ADB intervals
    • LogItems
      • GET one log item
      • GET a list of log items
    • PaymentReservations
      • POST (create) a new payment reservation
    • Health
      • Check API health
  • PAY
    • AmiliPay API Introduction
    • Industry Categories Reference
    • Webhooks Reference
    • Merchant
      • List all customers
      • Create customer
      • Retrieve customer
      • Update customer
      • Create customer token
      • Retrieve pricing for a merchant
      • Update pricing for a merchant
      • List a customer's agreements
    • User
      • List users
      • Create user
      • Retrieve user
      • Update user
      • Delete user
    • Onboarding
      • Create onboarding application
      • Retrieve onboarding application
      • Update onboarding application
      • Delete onboarding application
      • Start processing onboarding
      • Delete onboarding shareholder
      • Create onboarding document
      • Retrieve onboarding document
      • Delete onboarding document
      • Retrieve available account agreements
      • Create onboarding agreement
      • Mark selected agreement as an accepted by the account
      • Retrieve a single agreement
      • Update onboarding agreement
      • Deactivate agreement
    • Invoice
      • List all invoices
      • Create invoice
      • Retrieve invoice
      • Update invoice
      • Delete invoice
      • Refund invoice
    • Transactions
      • Get invoice transactions
    • Payout
      • List all payouts
      • Retrieve payout
      • Retrieve payout details
      • Retrieve payout
      • Retrieve payout details
    • Product lines classification
      • Upload a CSV file
      • Get download link for a CSV file
      • Download a previously uploaded CSV file
  1. PAY

Webhooks Reference

Listen for events in your application so your integration can react automatically.
AmiliPay uses webhooks to notify your application when an event happens in your account. Webhooks are useful for events like an invoice being paid or refused, a customer starting onboarding, and the onboarding status changing.
Every date and time in a payload is in the UTC time zone.

Adding a webhook endpoint#

Register webhook endpoints yourself in the dashboard under Settings > Webhooks. This is not available through the API.
Each endpoint belongs to one category and receives every event of that category. You can have one active endpoint per category.
CategoryEvents
Invoiceall INVOICE_* events except INVOICE_PAYMENT_PAID
Onboardingall ONBOARDING_* events
PayoutREPORT_AVAILABLE and INVOICE_PAYMENT_PAID
Product Classificationnot currently available
Give the endpoint a callback_url, pick its category, and enter a signing secret of your own choice. The secret is stored and used to sign every delivery, and it is not shown again in full. An endpoint without a secret receives no deliveries.

Who receives an event#

An event is sent to the endpoint of the account it belongs to. For some events a copy is also sent to the endpoint of the merchant's partner account (the partner needs an endpoint in the matching category).
Sent toEvents
Merchant onlyINVOICE_OVERDUE, INVOICE_REFUND_INITIATED, INVOICE_REFUNDED, INVOICE_REFUND_FAILED, INVOICE_CHARGEBACK, INVOICE_CHARGEBACK_REVERSED, INVOICE_SECOND_CHARGEBACK, INVOICE_RECURRING_INITIATED, INVOICE_RECURRING_TOKEN_DELETED, ONBOARDING_CREATED, ONBOARDING_ERROR_ADDED, ONBOARDING_ERROR_REMOVED, ONBOARDING_PROCESSING_FAILED
Merchant and partnerINVOICE_PAYMENT_AUTHORIZED, INVOICE_PAYMENT_REFUSED, INVOICE_DELIVERY_SUCCESS, INVOICE_DELIVERY_FAILED, INVOICE_PAYMENT_PAID, ONBOARDING_STATUS_UPDATED, REPORT_AVAILABLE

Delivery and retries#

Each event is sent as an HTTP POST with a JSON body. Your application must answer with a 2xx status within 30 seconds. A non-2xx answer, a timeout or a connection error counts as a failed attempt.
After a failed attempt we retry:

1st retry about 1 minute after the failed attempt

2nd retry about 5 minutes after the previous failed attempt

3rd retry about 15 minutes after the previous failed attempt

4th retry about 60 minutes after the previous failed attempt

That is 5 attempts in total (the first one plus 4 retries). Retries run on a 30 second schedule, so a retry can be up to 30 seconds late. After the last failed attempt we stop.
Retries carry the same X-AmiliPay-Event-Id, so use it to ignore duplicates.

HMAC signature#

Every delivery is signed with HMAC-SHA256, using your endpoint's signing secret as the key. The signature is sent as lowercase hex in the X-AmiliPay-Signature header.
The signature is calculated over the raw request body bytes, exactly as received. Verify it before you parse or re-encode the JSON, because re-encoding can change the bytes.
Every delivery carries the signature in both X-AmiliPay-Signature and Zettr-Signature (same value). Use X-AmiliPay-Signature. Zettr-Signature is deprecated and will be removed in a future release.
Verification example:
Other headers on every delivery:
HeaderValue
X-AmiliPay-EventThe event type, for example INVOICE_PAYMENT_AUTHORIZED.
X-AmiliPay-Event-IdIdentifier of the event. It stays the same on retries.
X-AmiliPay-TimestampTime of this attempt as Unix time in seconds (UTC), for example 1760000000.
User-AgentAmiliPay-Webhooks/1.0
The timestamp is not part of the signed data. To guard against replay, also reject requests where X-AmiliPay-Timestamp is more than 5 minutes old.

Invoice webhooks#

AmiliPay supports several types of invoice events:
1.
INVOICE_PAYMENT_AUTHORIZED
2.
INVOICE_PAYMENT_REFUSED
3.
INVOICE_OVERDUE
4.
INVOICE_REFUND_INITIATED
5.
INVOICE_REFUNDED
6.
INVOICE_REFUND_FAILED
7.
INVOICE_CHARGEBACK
8.
INVOICE_CHARGEBACK_REVERSED
9.
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 the customer pays the invoice.

Payload sample#

{
  "data": {
    "unique_id": "O5XRLP0Muabxufne6Eb62uFjAvj8D5nog3waANRQEI5Ce7zcC6",
    "account_id": 1,
    "invoice_id": "1",
    "amount": 15000,
    "customer_id": "1",
    "customer_reference": "PO-88231",
    "kid": "1234567890",
    "account_number": "15030012345",
    "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": "https://pay2.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: kid and account_number are the payment references set on the invoice (null when not set). 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 the customer's payment fails (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",
    "kid": "1234567890",
    "account_number": "15030012345",
    "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": "https://pay2.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 an invoice becomes overdue and payment is disabled.

Payload sample#

{
  "data": {
    "unique_id": "O5XRLP0Muabxufne6Eb62uFjAvj8D5nog3waANRQEI5Ce7zcC6",
    "account_id": 1,
    "invoice_id": "1",
    "amount": 15000,
    "customer_id": "1",
    "customer_reference": "PO-88231",
    "kid": "1234567890",
    "account_number": "15030012345",
    "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": "https://pay2.amili.no/pay/invoice/O5XRLP0Muabxufne6Eb62uFjAvj8D5nog3waANRQEI5Ce7zcC6",
    "is_recurring": false,
    "recurring_invoice_id": null
  },
  "event": "INVOICE_OVERDUE",
  "message": "Invoice is overdue. Payment is disabled."
}

Invoice refund initiated event#

Event of this type is sent when an invoice refund is initiated. The amount in message is in major units (for example 150.00).

Payload sample#

{
  "data": {
    "unique_id": "O5XRLP0Muabxufne6Eb62uFjAvj8D5nog3waANRQEI5Ce7zcC6",
    "account_id": 1,
    "invoice_id": "1",
    "amount": 15000,
    "customer_id": "1",
    "customer_reference": "PO-88231",
    "kid": "1234567890",
    "account_number": "15030012345",
    "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": "https://pay2.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 an invoice is refunded.

Payload sample#

{
  "data": {
    "unique_id": "O5XRLP0Muabxufne6Eb62uFjAvj8D5nog3waANRQEI5Ce7zcC6",
    "account_id": 1,
    "invoice_id": "1",
    "amount": 15000,
    "customer_id": "1",
    "customer_reference": "PO-88231",
    "kid": "1234567890",
    "account_number": "15030012345",
    "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": "https://pay2.amili.no/pay/invoice/O5XRLP0Muabxufne6Eb62uFjAvj8D5nog3waANRQEI5Ce7zcC6",
    "is_recurring": false,
    "recurring_invoice_id": null
  },
  "event": "INVOICE_REFUNDED",
  "message": "Invoice has been refunded."
}

Invoice refund failed event#

Event of this type is sent when an invoice refund fails.

Payload sample#

{
  "data": {
    "unique_id": "O5XRLP0Muabxufne6Eb62uFjAvj8D5nog3waANRQEI5Ce7zcC6",
    "account_id": 1,
    "invoice_id": "1",
    "amount": 15000,
    "customer_id": "1",
    "customer_reference": "PO-88231",
    "kid": "1234567890",
    "account_number": "15030012345",
    "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": "https://pay2.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 an invoice payment is charged back.

Payload sample#

{
  "data": {
    "unique_id": "O5XRLP0Muabxufne6Eb62uFjAvj8D5nog3waANRQEI5Ce7zcC6",
    "account_id": 1,
    "invoice_id": "1",
    "amount": 15000,
    "customer_id": "1",
    "customer_reference": "PO-88231",
    "kid": "1234567890",
    "account_number": "15030012345",
    "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": "https://pay2.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 a chargeback is reversed.

Payload sample#

{
  "data": {
    "unique_id": "O5XRLP0Muabxufne6Eb62uFjAvj8D5nog3waANRQEI5Ce7zcC6",
    "account_id": 1,
    "invoice_id": "1",
    "amount": 15000,
    "customer_id": "1",
    "customer_reference": "PO-88231",
    "kid": "1234567890",
    "account_number": "15030012345",
    "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": "https://pay2.amili.no/pay/invoice/O5XRLP0Muabxufne6Eb62uFjAvj8D5nog3waANRQEI5Ce7zcC6",
    "is_recurring": false,
    "recurring_invoice_id": null
  },
  "event": "INVOICE_CHARGEBACK_REVERSED",
  "message": "The chargeback has been reversed."
}

Invoice second chargeback event#

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

Payload sample#

{
  "data": {
    "unique_id": "O5XRLP0Muabxufne6Eb62uFjAvj8D5nog3waANRQEI5Ce7zcC6",
    "account_id": 1,
    "invoice_id": "1",
    "amount": 15000,
    "customer_id": "1",
    "customer_reference": "PO-88231",
    "kid": "1234567890",
    "account_number": "15030012345",
    "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": "https://pay2.amili.no/pay/invoice/O5XRLP0Muabxufne6Eb62uFjAvj8D5nog3waANRQEI5Ce7zcC6",
    "is_recurring": false,
    "recurring_invoice_id": null
  },
  "event": "INVOICE_SECOND_CHARGEBACK",
  "message": "A second chargeback has been received."
}

Invoice recurring payment initiated event#

Event of this type is sent when we have no stored payment token for a recurring payment.
Redirect your customer to the payment page to pay manually the first time. After a successful payment we store a payment token 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",
"kid": "1234567890",
"account_number": "15030012345",
"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": "https://pay2.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 10 times in a row. The token is deleted from our system. The next time a payment is due you receive INVOICE_RECURRING_INITIATED, which means your customer must open the payment page and pay manually.
{
"data": {
"unique_id": "O5XRLP0Muabxufne6Eb62uFjAvj8D5nog3waANRQEI5Ce7zcC6",
"account_id": 1,
"invoice_id": "1",
"amount": 15000,
"customer_id": "1",
"customer_reference": "PO-88231",
"kid": "1234567890",
"account_number": "15030012345",
"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": "https://pay2.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 message (email or SMS) is confirmed as delivered to your customer.
This event is sent to the merchant and to its partner account.

Payload sample#

{
  "data": {
    "unique_id": "O5XRLP0Muabxufne6Eb62uFjAvj8D5nog3waANRQEI5Ce7zcC6",
    "account_id": 1,
    "invoice_id": "1",
    "amount": 15000,
    "customer_id": "1",
    "customer_reference": "PO-88231",
    "kid": "1234567890",
    "account_number": "15030012345",
    "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": "https://pay2.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"
}
The extra delivery_channel field sits next to data, event and message (not inside data). It is the channel the invoice was sent on: email, sms or rcs.

Invoice delivery failed event#

Event of this type is sent when the invoice message could not be delivered, for example an email bounced, was blocked or was dropped, or an SMS was not delivered. Use it to find customers with a bad email address or phone number early.
A slow or temporarily deferred message is not reported here. We send this event only when delivery has permanently failed.
Like INVOICE_DELIVERY_SUCCESS, this event goes to the merchant and to its partner account.

Payload sample#

{
  "data": {
    "unique_id": "O5XRLP0Muabxufne6Eb62uFjAvj8D5nog3waANRQEI5Ce7zcC6",
    "account_id": 1,
    "invoice_id": "1",
    "amount": 15000,
    "customer_id": "1",
    "customer_reference": "PO-88231",
    "kid": "1234567890",
    "account_number": "15030012345",
    "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": "https://pay2.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 has the form Invoice delivery failed (<status>): <reason>. For email <status> is bounce, blocked or dropped. For SMS and RCS it is failed or undelivered. The reason is the text reported by the mail server or carrier. Unlike most other invoice events, message is not a fixed string. As with the success event, delivery_channel sits next to data and is email, sms or rcs.

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.
This event is sent to the merchant and to its partner account (when the merchant belongs to a partner). It belongs to the Payout category, so it goes to your Payout endpoint, not your Invoice endpoint.

Payload sample#

{
  "data": {
    "unique_id": "O5XRLP0Muabxufne6Eb62uFjAvj8D5nog3waANRQEI5Ce7zcC6",
    "account_id": 1,
    "invoice_id": "1",
    "amount": 15000,
    "customer_id": "1",
    "customer_reference": "PO-88231",
    "kid": "1234567890",
    "account_number": "15030012345",
    "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": "https://pay2.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 object used by every other invoice webhook. It has no payout information (amount, reference, etc.); get those from the matching REPORT_AVAILABLE event or the payouts endpoint.

Onboarding webhooks#

AmiliPay supports several types of onboarding events:
1.
ONBOARDING_CREATED
2.
ONBOARDING_STATUS_UPDATED
3.
ONBOARDING_ERROR_ADDED
4.
ONBOARDING_ERROR_REMOVED
5.
ONBOARDING_PROCESSING_FAILED

Onboarding created event#

Event of this type is sent when an onboarding is created for a customer.

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": "4522",
      "tax_id": "116963",
      "registration_code": "64543302",
      "address": {
        "city": "Oslo",
        "country": "AO",
        "street_address": "Storgata 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": "Storgata 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": ""
}
company, payout and shareholder id values are UUIDs. The onboarding is identified by the top-level id.

Onboarding status updated event#

This event is sent when a customer's onboarding status changes. Today it is sent when the onboarding is completed. It is sent to the merchant and to its partner account.
data.status (and the statuses in message) is one of CANCELED, COMPLETED, IN_PROGRESS, PENDING_REVIEW, REVIEW_FAILED, STARTED. In message the previous status is UNKNOWN when there was none. A merchant can accept payments once the status is COMPLETED.

Payload sample#

{
  "data": {
    "id": "3f2504e0-4f89-41d3-9a0c-0305e82c3301",
    "account_id": 3,
    "status": "COMPLETED",
    "status_changed_at": "2022-02-08 09:21:28",
    "ownership_category": "ownership_no_major",
    "company": {
      "id": "8f14e45f-ceea-467e-bd7b-6a35c5d18ea9",
      "industry_category": "4522",
      "tax_id": "116963",
      "registration_code": "64543302",
      "address": {
        "city": "Oslo",
        "country": "AO",
        "street_address": "Storgata 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": "Storgata 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 IN_PROGRESS to COMPLETED"
}
data has the same shape as in ONBOARDING_CREATED above.

Onboarding error added#

This event is sent when the payment provider reports a problem that the customer must fix (invalid input or a rejected item). One event is sent per problem. Missing data and terms-of-service items are not reported.
When the provider sends updated problems, the earlier errors are first sent as ONBOARDING_ERROR_REMOVED and the current ones as ONBOARDING_ERROR_ADDED.

Payload sample#

{
  "data": {
    "step": "receivePayments",
    "field": "companyRegistrationNumber",
    "notes": "The company registration number is invalid.",
    "created_at": "2022-02-08T08:53:26.1234567Z",
    "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": "4522",
          "tax_id": "116963",
          "registration_code": "64543302",
          "address": {
            "city": "Oslo",
            "country": "AO",
            "street_address": "Storgata 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": "Storgata 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.1234567Z"
  },
  "event": "ONBOARDING_ERROR_ADDED",
  "message": ""
}
Fields in data:
step: the capability the problem belongs to, for example receivePayments (the field name when none is known).
field: the field with the problem, or the capability when no field is named.
notes: the error text, followed by the suggested fix when there is one.
created_at, updated_at: when the error was created and last changed.
onboarding: the full onboarding, in the same shape as ONBOARDING_CREATED above.

Onboarding error removed#

This event is sent when an onboarding error is removed: it was replaced by an updated list of problems, or no problems remain.
Payload sample#
{
  "data": {
    "step": "receivePayments",
    "field": "companyRegistrationNumber",
    "notes": "The company registration number is invalid.",
    "created_at": "2022-02-08T08:53:26.1234567Z",
    "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": "4522",
          "tax_id": "116963",
          "registration_code": "64543302",
          "address": {
            "city": "Oslo",
            "country": "AO",
            "street_address": "Storgata 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": "Storgata 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.1234567Z"
  },
  "event": "ONBOARDING_ERROR_REMOVED",
  "message": ""
}
data has the same fields as in ONBOARDING_ERROR_ADDED above.

Onboarding processing failed event#

Sent when a step of the onboarding submission fails during 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 numeric identifier, not the UUID id used by the onboarding endpoints. It cannot be looked up through the public API.

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:
1.
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 and 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_or_uuid}.

Classification webhooks#

Product-line classification is not currently available.
Modified at 2026-11-12 15:49:07
Previous
Industry Categories Reference
Next
List all customers
Built with