Authentication in the API uses HTTP Bearer auth. You must include an Authorization header with type Bearer and your API key as value. For example:

Authorization: Bearer live_secretkey_3m9khmufqsgct1llddu1_13383aeb28127115180a92bac880957cc6faa71936b44529

There are two kinds of API keys:

• Secret keys: They have the privileges to do everything in your project. Use it only from server-side code. Do not embed it into apps or websites.
• Public keys: They only have privileges to create card tokens. You can safely embed them in your app or website to use it with client-side SDKs.

Decline codes gives more information about why a card operation was declined. You should programatically handle declined operations using these codes so you can guide your user's next steps the best possible way.

The Kernel Payments API supports idempotency via a custom HTTP header.

Idempotency allows you to safely retry failed requests. For example, if a request for making a transfer fails due to network reasons, you can retry it, knowing that the transfer won't be done twice by accident.

To make an idempotent request, you need to create an idempotency key, and pass it in the following header:

Idempotency-Key: my_idempotency_key_123456

Idempotency keys are scoped to a single project. When you retry an idempotent request you must pass the same parameters. Keys expire in 24 hours.

GET, PATCH and DELETE requests are already idempotent by definition, so the Idempotency-Key header is only allowed for POST requests.

The API uses cursor-based pagination. All list endpoints return data in reverse chronological order, and have the following common structure:

GET parameters

• limit: How many items to fetch, between 1 and 100, default 10.
• cursor: Value of cursor_next from a previous request. If not given, it will fetch the most recent items.

Response data

• data: The received items, in a JSON array.
• has_next: Whether there are more items to fetch.
• cursor_next: Cursor to fetch the next page of items. Only present if has_next is true.

Most API objects have a meta field you can use to store your own key-value data. For example, you can store a user's full name, or mappings to primary key IDs from your own database.

Metadata is not used by the API in any way.

Metadata keys starting with "_" are reserved for dashboard usage. Current keys used by the dashboard are:

• _name: Displayed name of the object (account, etc).
• _starred: If set, the object is starred.

Modifying these keys via the API is perfectly fine, and can be very useful. For example, creating an account via API with a name that will be displayed in the dashboard.

Everything in Kernel Payments APIs (Accounts, cards, transactions...) belongs to a Project. API keys are tied to projects too, and they give access only to the objects belonging to the project.

In most cases you only need a single project, but you may want to separate your operations into several projects to get finer-grained privilege separation.

An Account is a place where you can store funds. Think of them as a "virtual bank account".

Every account has its currency set on creation, and can only store funds in its currency. If you want to store funds in several currencies, you have to create multiple accounts.

Account creation and maintenance is and will always be free, so you can create as many accounts as you like. Some setup suggestions you may want depending on your use case are:

• One account per user with their funds, for a standard e-wallet app.
• Many accounts in many currencies per user, if you want to allow your users to hold many currencies and exchange between them.
• Two accounts per user: one for available funds and another for "held" funds.

You don't need to create one account for each of your users. For example, for a marketplace service you may want to create accounts only for the sellers, and perorm charges from the buyers' cards directly to the sellers' accounts.

Accounts can have negative balance if you set the allow_negative_balance flag, as long as the sum of balances of all accounts in your project is positive, calculated separatedly per currency.

Transactions are balance changes in an account.

One transaction concerns only one account. Operations that concern multiple accounts create multiple transactions. For example, doing a Transfer of 10 EUR from one account to another creates a transaction of -10 EUR on the source and another one of +10 EUR on the destination.

The type field and the several _id fields tell you the cause of the transaction.

All transactions are final: under no circumstances a transaction will be "reverted" or "disappear". All situations that could revert a transaction create instead another transaction of the opposite value.

A Customer represents a customer of your service. You can attach Accounts, Cards and BankAccounts to it.

If your service is subject to KYC/AML regulations because you're using Kernel APIs to hold your users' funds, you must create a Customer for each of your customers, attach all its accounts, cards and bank accounts to it, and fill in the necessary KYC information in the Customer object.

The required KYC information depends on the nature of your service, the role of the customer if applicable (e.g.: seller vs buyer), and the volume of funds transacted. Contact support for details.

If you're not subject to KYC/AML, you can still use Customer objects for convenience: it allows organizing your accounts, cards and bank accounts, and storing metadata in the customer.

A Transfer is an internal transfer between two Accounts.

If the two accounts have different currencies, a currency exchange operation is automatically performed.

Transfers are and will always be free. Transfers with a currency exchange do incur in foreign exchange costs based on market conditions (there is a "spread", which means the current best buy price is slightly higher than the current best sell price.)

Card tokens contain card data that has been uploaded to the Kernel Payments API, but hasn't been used yet.

Card tokens can be used to send the card data directly from your app or website to Kernel Payments, without going through your servers. If your servers don't handle card data, you are eligible for the simplest and cheapest form of PCI DSS compliance.

How it works:

• Generate a "public API key", which is a special kind of API key that only has permission to create tokens.
• Embed the public API key into your app or website.
• When your customer enters a card, do a Create Token request from your app or website.
• Send the CardToken ID to your servers.
• From your servers, use the token ID to create a Card or a CardPayin, using your server-side secret API key.

Card tokens are single-use, and expire 10 minutes after creation.

To do a single payment, use the token to create a CardPayin.

To store the card for multiple/recurring payments, use the token to create a Card. The created Card doesn't expire and can be used for multiple CardPayins.

Cards contain card data stored in the Kernel Payments servers. This allows you to use the card for future or recurring payments without having to store the card information yourself, which would subject you to costly PCI DSS compliance.

To charge a card, create a CardPayin.

When creating a CardPayin you can specify either the card information directly, or a CardToken, or a Card.

When you create a CardPayin, you instantly know whether it has been authorized or declined by looking at its state field.

Being authorized means the card issuing bank has authorized the purchase, which guarantees (except in the case of a dispute) that you will receive the funds from the charge. However, the card networks take some time to settle the payments (usually 2 business days), so you won't receive the funds instantly. When the payment is settled, you will receive the funds (the transaction in the specified account will be created), and the CardPayin will change to the settled state.

Statement descriptors can be set also for card payins, these can be either static or dynamic.

A project can configure a static statement descriptor (must be between 4 and 25 characters) and a short prefix (must be between 2 and 10 characters). The static descriptor will be used always unless a statement descriptor suffix is provided when creating the card payin, in this case it will be preprended with the statement descriptor prefix, and if this is not set, the static statement descriptor (truncated up to 10 characters) will be used in its place.

You can use a BankAccount to store a customer's bank account.

A BankPayout is a bank transfer to a traditional bank account outisde Kernel Payments.

Bank transfers can take 2 business days to reach the destination.

The destination bank can refund a bank transfer. This is usually due to the destination account not existing, being blocked or closed, in which case the refund arrives in 2 business days. In more exceptional cases, such as the destination bank holding the transfer for manual review, the refund can arrive weeks or months after the initial transfer.

When creating a bank payout you can specify either the bank account information directly, or a stored BankAccount.

A BankPayin is an incoming bank transfer to a Kernel Payments account.

Since accounts don't have their own IBAN codes, incoming bank transfers must be sent to one of the Kernel Payments IBANs, indicating a reference code in the bank transfer concept.

To obtain a reference code, create a BankPayinReference associated to an Account. Then, make a bank transfer to a Kernel Payments IBAN, indicating the reference code in the concept. When the funds are received, the reference is automatically detected, and a BankPayin is created to the specified account.

Reference codes can be used for multiple bank payins, and they never expire.

Upload files to use them as identity documents in Customer objects.

An Event object is created every time an event of interest occurs. The Event type field specifies what occurred, and the Event payload adds details specific to the event type.

Use Events to keep up to date with the changes happening in your project. There are two ways to do so: periodically query the API for new events, or configure webhooks to get events delivered to your server.

Events are kept for 5 days, after which they are deleted.

Note: API objects in event payloads reflect their state at the exact time the event occurred, not at the time of querying the Event. (For example, if a bank_payout_completed and then a bank_payout_refunded events occur for the same bank payout, fetching the bank_payout_completed event will show the bank payout in completed state, even though it's refunded at the present). This can help you simplify event handling logic.

Use webhooks to get notifications sent to your backend servers every time an Event is created, in real time.

A Webhook object consists of a destination URL and a set of events types to receive. If an event matches multiple webhooks, it will be sent to all of them.

When an event happens, the URL is sent an HTTP POST request, with the event JSON as request body.

Signature header

Webhook delivery contents are cryptographically signed. This allows you to verify the webhook request comes indeed from Kernel Payments.

Verifying the signature and discarding incorrectly signed requests is strongly recommended. Not doing so allows any attacker on the internet to send fake events to your server. This can cause your server to think a payment has been received that in reality hasn't, for example.

The signature is included in the X-Kernel-Sig-SHA256 header, and contains the HMAC-SHA256 hash of the request body, using the webhook's secret as a key.

You can find working code snippets to validate signatures in this GitHub repo

Delivery

Webhook delivery is 'At Least Once'.

Kernel Payments expects a HTTP 200 OK response from your application. Any other HTTP status code, as well as inability to receive a response (due to network failures, TLS certificate errors, timeouts...) are treated as failures.

In case of failures, the delivery is retried with an exponential backoff, for up to 5 days after the event occurred.

Webhooks can be delivered out-of-order, especially in the case of delivery failures.

You can view the delivery logs in the dashboard, by clicking on a webhook. The logs include the request and your server's response, which can be useful in diagnosing delivery problems.