AmiliPay API Introduction
This is the API documentation for managing the AmiliPay service.Endpoint#
We only allow HTTPS connections. Regular HTTP connections will be redirected to HTTPS. We have two environments:Build and test your integration against the testing environment first, then switch to production once you're ready to go live. The two are separate accounts/data stores - a customer, invoice, or token created in testing does not exist in production and vice versa.Allowed HTTP requests#
GET: Get a resource or list of resources
DELETE: Delete a resource
Send these headers with every request:Content-Type: application/json (for requests with a body)
Authentication#
Authenticate with a partner API key. Create and manage keys under Settings > Partner API Tokens (up to 10 active keys per account, each with its own scopes). Send the key on every request using one of:Authorization: ApiKey {token}
Authorization: Bearer {token} (recognized only when the token itself is prefixed apk_)
A key is not gated on the onboarding progress of any merchant you manage - it works regardless of how far along a given merchant's onboarding is. It is gated on the lifecycle status of the key's own owning account: a key belonging to a Suspended or Deactivated account stops authenticating.To act on behalf of a merchant you've onboarded, you can also create a merchant token with POST /customers/{id}/tokens. It works only with X-API-KEY or Authorization: ApiKey {token}, and is shown once.Rate Limiting#
You can make 450 requests every minute per API key (per IP if unauthenticated). Responses include X-RateLimit-Limit and X-RateLimit-Remaining headers; exceeding the limit returns 429 with a Retry-After header and the body {"message": "...", "retryAfter": 30} (seconds).Integration flow#
1. Onboard the merchant#
A merchant must complete onboarding and accept the current agreement(s) before you can create invoices for them. Call POST /customers to create the merchant account - this automatically creates an onboarding record and returns the customer id, an onboarding_token and an onboarding_id (use it as {id} in /onboardings/{id}).Hosted onboarding (recommended): hand the customer the onboarding_token and embed our onboarding widget - it walks them through agreement approval and KYC data collection.
Self-hosted onboarding: collect agreement approval and KYC data yourself and submit it against the onboarding record that was already created for you - PUT /onboardings/{id} (do not POST a new one, that creates a duplicate) plus POST /onboardings/{id}/documents - then call POST /onboardings/{id}/process to submit it for review.
Track progress with the ONBOARDING_STATUS_UPDATED webhook; a merchant can accept payments once its status is COMPLETED.2. Create a payment request#
Create an invoice with POST /invoices. A merchant key creates the invoice under its own account; a partner key must supply account_id (the customer id) to target one of its direct-child merchants - a partner cannot create an invoice without specifying which child merchant it belongs to. Required fields: amount, invoice_id, customer_id (your own reference for the payer - unrelated to the merchant's id), name, currency, due_date. Optionally supply customer_reference - your own free-text reference for the payer, up to 255 characters, stored and returned as-is. Set notify_customer: true (default) together with email/phone to have us notify the payer directly, or use the redirect_url returned in the response to send them to the payment page yourself.3. Handle webhooks#
Register a webhook endpoint 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 registering or managing webhook endpoints today - it's dashboard-only, not something you can automate from your own backend. We POST every event to your callback_url and wait up to 30 seconds for a 2xx status. If the delivery fails, we retry after 1, 5, 15 and 60 minutes (5 attempts in total). Endpoints without a signing secret get no deliveries.See the Webhooks reference for the full, current list of event types - it includes invoice events (INVOICE_PAYMENT_AUTHORIZED, INVOICE_PAYMENT_REFUSED, INVOICE_REFUNDED, INVOICE_CHARGEBACK, ...), onboarding events (ONBOARDING_STATUS_UPDATED, ONBOARDING_PROCESSING_FAILED, ...), and payout report events. The same list is shown on the dashboard's webhook settings page when choosing which events to subscribe to.{
"data": {
"unique_id": "i0n00sdQKSgyshUpV5CWYtID2k1judsrgGBl1lYxssycEBN1d1",
"account_id": 41,
"invoice_id": "RE-21243",
"amount": 10000,
"customer_id": "9131542",
"customer_reference": "PO-88231",
"kid": "1234567",
"account_number": "1234.56.78903",
"currency": "NOK",
"payment_url": "https://pay2.amili.no/pay/invoice/i0n00sdQKSgyshUpV5CWYtID2k1judsrgGBl1lYxssycEBN1d1"
},
"event": "INVOICE_PAYMENT_AUTHORIZED",
"message": "Invoice payment is authorized."
}
Every request is signed. Compute HMAC-SHA256 of the raw request body bytes with your secret, as lowercase hex, and compare it with the X-AmiliPay-Signature header. Sign the body exactly as received, not a re-encoded copy. The timestamp is not part of the signature. The X-AmiliPay-Timestamp header is the delivery time in Unix seconds (UTC); as a precaution, reject deliveries older than 5 minutes.Notice: for backward compatibility, the same signature is also sent under the legacy Zettr-Signature header. Migrate to X-AmiliPay-Signature as soon as possible - Zettr-Signature is deprecated and will be removed in a future release.
4. Recurring payments#
Recurring payments must be enabled by customer service for the merchant. To enable it, set the is_recurring flag when creating the invoice. From then on, reference the original invoice via recurring_invoice_id when creating new invoices for the same customer.The first time you pass is_recurring: true without recurring_invoice_id, you'll receive an INVOICE_RECURRING_INITIATED webhook - redirect the customer to the payment window to store their payment details.
After a successful payment you'll receive INVOICE_PAYMENT_AUTHORIZED with is_recurring: true and a unique_id - store that unique_id as the reference for this customer's stored payment details.
If a recurring charge fails, you'll receive INVOICE_PAYMENT_REFUSED - ask the customer to pay the invoice manually via the payment window.
If automatic payment fails 10 times with the same token, the token is deleted and you'll receive INVOICE_RECURRING_TOKEN_DELETED.
Errors#
Successful calls return 2xx. Errors use one of these body shapes:Validation errors (400): {"traceId": "...", "code": "INVALID_REQUEST", "message": "One or more fields contain invalid values.", "errors": {"Email": ["'Email' is required."]}}. errors lists every failing field, keyed by field name.
Business errors on invoices and a few other endpoints: {"traceId": "...", "code": "INVALID_SORT_BY", "message": "...", "errors": null}. Use code in your code, not message.
All other errors: {"message": "..."}.
401: missing or invalid API key, empty body.
403: your key cannot use this endpoint (for example partner-only endpoints).
404: the resource does not exist or is not yours. Both cases return the same response.
409: conflict, for example an email already used by another account.
415: the request body is not JSON.
422: the request is valid but cannot be processed, for example refunding an unpaid invoice.
429: rate limit exceeded, see Rate Limiting.
500: {"traceId": "...", "message": "An unexpected error occurred."}. Include the traceId when you contact support.
POST /customers and PUT /customers/{id}: 400 for validation errors, 409 when the email is already used by another account.
POST /invoices: 422 with errors.invoice_id when the invoice_id already exists for the account. Deleted invoices do not count. Fetch the existing one with GET /invoices?filters[invoice_id]=<invoice_id>.
Retry on 408, 502, 503 and on 429 (honour the Retry-After header).
Payouts#
Payouts to a merchant's bank account are swept automatically - daily by default, configurable to weekly or monthly per merchant. List and track them with GET /payouts and GET /payouts/{payout_id_or_uuid} (with GET /payouts/{payout_id_or_uuid}/details for the underlying transactions; the path accepts either the numeric id or the UUID). Status is one of Pending, Processing, Completed, Failed, or Returned (a bank-side failure that reverses a previously completed payout).Testing payments#
Sandbox testing uses test cards on the testing environment. To test different authorisation outcomes, change the name on the card to one of the values below.| Type | Card number | Expiry Date | Security Code (CVC/CVV/CID) |
|---|
| 3D Secure | 4917 6100 0000 0000 | 03/30 | 737 |
| Visa | 4111 1111 1111 1111 | 03/30 | 737 |
Response codes#
| # | holderName | refusalReason | resultCode |
|---|
| 0 | UNKNOWN | Unknown | Error |
| 1 | APPROVED | - | Authorised |
| 2 | DECLINED | Refused | Refused |
| 3 | REFERRAL | Referral | Refused |
| 4 | ERROR | Acquirer Error | Error |
| 5 | BLOCK_CARD | Blocked Card | Refused |
| 6 | CARD_EXPIRED | Expired Card | Refused |
| 7 | INVALID_AMOUNT | Invalid Amount | Refused |
| 8 | INVALID_CARD_NUMBER | Invalid Card Number | Refused |
| 9 | ISSUER_UNAVAILABLE | Issuer Unavailable | Refused |
| 10 | NOT_SUPPORTED | Not supported | Refused |
| 11 | NOT_3D_AUTHENTICATED | 3D Not Authenticated | Refused |
| 12 | NOT_ENOUGH_BALANCE | Not enough balance | Refused |
| 13 | PENDING | - | Received |
| 14 | ACQUIRER_FRAUD | Acquirer Fraud | Refused |
| 15 | CANCELLED | Cancelled | Refused |
| 16 | SHOPPER_CANCELLED | Shopper Cancelled | Refused |
| 17 | INVALID_PIN | Invalid Pin | Refused |
| 18 | PIN_TRIES_EXCEEDED | Pin tries exceeded | Refused |
| 19 | PIN_VALIDATION_NOT_POSSIBLE | Pin validation not possible | Refused |
| 20 | FRAUD | FRAUD | Refused |
| 21 | NOT_SUBMITTED | Not Submitted | Refused |
| 22 | FRAUD_CANCELLED | FRAUD-CANCELLED | Cancelled |
| 23 | TRANSACTION_NOT_PERMITTED | Transaction Not Permitted | Refused |
| 24 | CVC_DECLINED | CVC Declined | Refused |
| 25 | RESTRICTED_CARD | Restricted Card | Refused |
| 26 | REVOCATION_OF_AUTH | Revocation Of Auth | Refused |
| 27 | DECLINED_NON_GENERIC | Declined Non Generic | Refused |
| 28 | WITHDRAWAL_AMOUNT_EXCEEDED | Withdrawal amount exceeded | Refused |
| 29 | WITHDRAWAL_COUNT_EXCEEDED | Withdrawal count exceeded | Refused |
| 30 | PARTIALLY_APPROVED | - | Authorised |
| 31 | ISSUER_SUSPECTED_FRAUD | Issuer Suspected Fraud | Refused |
| 32 | AVS_DECLINED | AVS Declined | Refused |
| 33 | PIN_REQUIRED | Card requires online pin | Refused |
| 34 | NO_CHECKING_ACCOUNT_AVAILABLE_ON_CARD | No checking account available on Card | Refused |
| 35 | NO_SAVINGS_ACCOUNT_AVAILABLE_ON_CARD | No savings account available on Card | Refused |
| 36 | MOBILE_PIN_REQUIRED | Mobile PIN required | Refused |
| 37 | CONTACTLESS_FALLBACK | Contactless fallback | Refused |
| 38 | AUTHENTICATION_REQUIRED | Authentication required | Refused |
| 39 | RREQ_NOT_RECEIVED | RReq not received from DS | Refused |
The card numbers and outcome codes above are test-environment values. Confirm with your integration contact if you see a mismatch.Creating customer account#
"Customer" here means the merchant account you're onboarding. It is returned as id and is called account_id where other endpoints take it in the body. It is not the customer_id field on an invoice, which is your own free-text reference for the invoice's payer. customer_id and customer_reference are both your own free-text values on an invoice - use customer_id for the payer's identifier in your system and customer_reference for any additional reference (e.g. a PO number) you want echoed back on the invoice and its webhooks.There are two ways to complete onboarding once you've called POST /customers (see Integration flow, step 1):Hosted onboarding: use the onboarding_token from the response with the embedded widget - the customer approves the agreement and fills in their own KYC details.
Self-hosted onboarding: submit agreement approval and KYC data yourself against the onboarding record already created for you, then add onboarding documents for the company and its personas, then submit for review.
Register a webhook for onboarding events so you know when a merchant is COMPLETED and ready to accept payments.
To fully onboard a customer you must provide all required fields on both the onboarding and onboarding-documents endpoints.
It's recommended to do a full onboarding via the hosted flow first and inspect the resulting onboarding record to see how the endpoints fit together, or book a call with your integration contact for guidance.
Managing dashboard users#
Partner API keys can also manage the dashboard login accounts ("users") of your account and your direct customers via GET/POST /users and GET/PUT/DELETE /users/{user_id}. These are team-member logins for your own staff to access the dashboard - not customers or invoice payers. See the OpenAPI reference for the full request/response contract.The embedded widget gives a customer access to onboarding without leaving your platform. Create a customer via the API to get an onboarding_token, then load the widget script and pass the token to it:<pay-widget token="{onboarding_token}"></pay-widget>
<script type="text/javascript" src="https://pay2.amili.no/widget/widget.js"></script>
Use https://pay-qa.amili.no/widget/widget.js instead when integrating against the testing environment. The token does not expire, but treat it as a secret - anyone holding it can access that onboarding session.Element name: <pay-widget> is the current element name. <zettr-widget> is still supported for backward compatibility but is deprecated and will be removed in a future release - the script logs a console warning when it's used. Use only one of the two elements on a page; do not mix them.Embedding domain: to embed the widget on your own site, set the Allowed Domains setting (via PUT /settings/allowed-domains) to your site's domain(s) - a comma-separated list, e.g. partner.com,app.partner.com. This can be set on your own account, or on your parent partner account to share one allowlist across all its merchants - your own account's setting takes priority if both are set. Requests from an origin not on the resulting list are rejected with 403, as are requests from any account with neither set. Modified at 2026-11-12 15:48:30