Kernel Payments API Reference
Welcome to the Kernel Payments API reference. The Kernel Payments API is organized around the REST methodology, and it uses resource-oriented URLs, and common HTTP response codes to indicate API errors.
API Endpoint
https://api.kernelpay.com/v1
Contact: hello@kernelpay.com
Schemes: https
Version: 1.0.0
Authentication
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
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.
Decline code | Summary | Next steps |
---|---|---|
generic_decline | Generic decline code. | The payment was not authorized and should be attempted again. If the error persists the customer should contact their issuer bank. |
failed_to_authenticate | The cardholder failed to authenticate the operation. | Customer should be informed and suggested to try again using correct credentials. |
call_issuer | The operation was not authorized by the issuer bank for an unknown reason. | The customer should contact their issuer bank in order to collect more information. |
try_again | The operation was not authorized by the issuer bank. | If the problem persists, the customer should contact their issuer bank to collect more information. |
try_again_later | The operation was not authorized by the issuer bank. | Customer should attempt payment again after few minutes. |
card_not_supported | Kernel does not offer service to this card. | Should contact Kernel support to ask for more details. |
card_expired | Provided card is expired. | The customer should use another card. |
issuer_not_available | Payment was not authorized as the issuer did not send back a response. | The operation should be attempted again. If the problem persists the customer should contact their issuer bank. |
service_not_available | Payment was not authorized as the service is temporarily unavailable. | The operation should be attempted again. If the problem persists contact Kernel support. |
pin_try_exceeded | Payment was not authorized as the maximum number of tries was reached. | The customer must use a different card. |
invalid_cvc | The provided CVC is invalid. | The operation should be attempted again using a valid CVC. |
incorrect_cvc | The provided CVC is not correct. | The operation should be attempted again using the correct CVC. |
operation_not_supported | Card is not supported for the attempted kind of operation. | Customer should contact their issuer bank. |
do_not_try_again | Operation was not authorized. | Should contact Kernel support. |
processing_error | The operation was not authorized as there was an error while processing it. | The customer should be advised to attempt again. If problem persists, it should contact their issuer bank. |
sca_required | The operation was declined because it requires SCA authentication. | The operation should be attempted again using three_d_secure_2 authentication type. |
do_not_honor | The operation was not authorized by the issuer bank for an unknown reason. | Customer should contact their issuer bank. |
insufficient_funds | The card has insufficient funds to complete the operation. | The customer should be asked to try with a different card. |
not_permitted | The operation is not permitted. | Customer should contact their issuer bank. |
Idempotency
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.
Pagination
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 ofcursor_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 ifhas_next
is true.
Meta
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.
Project
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.
Get project
Success
Response Example (200 OK)
{
"id": "string (ProjectID)",
"created_at": "string (date-time)",
"meta": {
"key1": "value1",
"key2": "value2"
}
}
Edit project
Request Example
{
"meta": {
"key1": "value1",
"key2": "value2"
}
}
Success
Response Example (200 OK)
{
"id": "string (ProjectID)",
"created_at": "string (date-time)",
"meta": {
"key1": "value1",
"key2": "value2"
}
}
Accounts
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.
List accounts
How many items to return, at maximum.
Cursor, to fetch more pages of a long list. See Pagination
Success
Response Example (200 OK)
{
"data": [
{
"id": "string (AccountID)",
"created_at": "string (date-time)",
"project_id": "string (ProjectID)",
"customer_id": "string (CustomerID)",
"balance": {
"currency": "EUR",
"amount": 100
},
"allow_negative_balance": false,
"meta": {
"key1": "value1",
"key2": "value2"
}
}
],
"has_next": true,
"cursor_next": "string (cursor)"
}
Create account
Request Example
{
"currency": "EUR",
"allow_negative_balance": false,
"customer_id": "string (CustomerID)",
"meta": {
"key1": "value1",
"key2": "value2"
}
}
Success
Bad request
Response Example (200 OK)
{
"id": "string (AccountID)",
"created_at": "string (date-time)",
"project_id": "string (ProjectID)",
"customer_id": "string (CustomerID)",
"balance": {
"currency": "EUR",
"amount": 100
},
"allow_negative_balance": false,
"meta": {
"key1": "value1",
"key2": "value2"
}
}
Response Example (400 Bad Request)
{
"type": "invalid_request",
"message": "Only EUR requests are allowed"
}
Get account
Account ID
Success
Response Example (200 OK)
{
"id": "string (AccountID)",
"created_at": "string (date-time)",
"project_id": "string (ProjectID)",
"customer_id": "string (CustomerID)",
"balance": {
"currency": "EUR",
"amount": 100
},
"allow_negative_balance": false,
"meta": {
"key1": "value1",
"key2": "value2"
}
}
Edit account
Account ID
Request Example
{
"allow_negative_balance": "boolean",
"balance": {
"currency": "EUR",
"amount": 100
},
"meta": {
"key1": "value1",
"key2": "value2"
}
}
Success
Response Example (200 OK)
{
"id": "string (AccountID)",
"created_at": "string (date-time)",
"project_id": "string (ProjectID)",
"customer_id": "string (CustomerID)",
"balance": {
"currency": "EUR",
"amount": 100
},
"allow_negative_balance": false,
"meta": {
"key1": "value1",
"key2": "value2"
}
}
List account transactions
How many items to return, at maximum.
Cursor, to fetch more pages of a long list. See Pagination
Account ID
Success
Response Example (200 OK)
{
"data": [
{
"id": "string (TransactionID)",
"created_at": "string (date-time)",
"project_id": "string (ProjectID)",
"account_id": "string (AccountID)",
"type": "string",
"value": {
"currency": "EUR",
"amount": 100
},
"balance_after": {
"currency": "EUR",
"amount": 100
},
"transfer_id": "string (TransferID)",
"bank_payout_id": "string (BankPayoutID)",
"card_payin_id": "string (CardPayinID)",
"card_payin_refund_id": "string (CardPayinRefundID)"
}
],
"has_next": true,
"cursor_next": "string (cursor)"
}
Transactions
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.
List transactions
How many items to return, at maximum.
Cursor, to fetch more pages of a long list. See Pagination
Success
Response Example (200 OK)
{
"data": [
{
"id": "string (TransactionID)",
"created_at": "string (date-time)",
"project_id": "string (ProjectID)",
"account_id": "string (AccountID)",
"type": "string",
"value": {
"currency": "EUR",
"amount": 100
},
"balance_after": {
"currency": "EUR",
"amount": 100
},
"transfer_id": "string (TransferID)",
"bank_payout_id": "string (BankPayoutID)",
"card_payin_id": "string (CardPayinID)",
"card_payin_refund_id": "string (CardPayinRefundID)"
}
],
"has_next": true,
"cursor_next": "string (cursor)"
}
List account transactions
How many items to return, at maximum.
Cursor, to fetch more pages of a long list. See Pagination
Account ID
Success
Response Example (200 OK)
{
"data": [
{
"id": "string (TransactionID)",
"created_at": "string (date-time)",
"project_id": "string (ProjectID)",
"account_id": "string (AccountID)",
"type": "string",
"value": {
"currency": "EUR",
"amount": 100
},
"balance_after": {
"currency": "EUR",
"amount": 100
},
"transfer_id": "string (TransferID)",
"bank_payout_id": "string (BankPayoutID)",
"card_payin_id": "string (CardPayinID)",
"card_payin_refund_id": "string (CardPayinRefundID)"
}
],
"has_next": true,
"cursor_next": "string (cursor)"
}
Get transaction
Transaction ID
Success
Response Example (200 OK)
{
"id": "string (TransactionID)",
"created_at": "string (date-time)",
"project_id": "string (ProjectID)",
"account_id": "string (AccountID)",
"type": "string",
"value": {
"currency": "EUR",
"amount": 100
},
"balance_after": {
"currency": "EUR",
"amount": 100
},
"transfer_id": "string (TransferID)",
"bank_payout_id": "string (BankPayoutID)",
"card_payin_id": "string (CardPayinID)",
"card_payin_refund_id": "string (CardPayinRefundID)"
}
Customers
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.
List customers
How many items to return, at maximum.
Cursor, to fetch more pages of a long list. See Pagination
Success
Response Example (200 OK)
{
"data": [
{
"id": "string (CustomerID)",
"created_at": "string (date-time)",
"project_id": "string (ProjectID)",
"identity": {
"first_name": "John",
"last_name": "McJohn",
"email_address": "john@example.com",
"phone_number": 34666555444,
"nationality": "ES",
"employment_status": "self_employed",
"date_of_birth": {
"day": 8,
"month": 12,
"year": 1988
},
"address": {
"line_1": "Calle Ejemplo, 31",
"line_2": "2o 1a",
"postal_code": "08102",
"city": "L'Hospitalet de Llobregat",
"region": "Barcelona",
"country": "ES"
},
"document": {
"type": "string",
"country": "ES",
"number": "12345678R",
"expiration_date": "2018-12-25T00:00:00.000Z",
"front_file_id": "string (FileID)",
"back_file_id": "string (FileID)",
"selfie_file_id": "string (FileID)"
}
},
"meta": {
"key1": "value1",
"key2": "value2"
}
}
],
"has_next": true,
"cursor_next": "string (cursor)"
}
Create customer
Request Example
{
"identity": {
"first_name": "John",
"last_name": "McJohn",
"email_address": "john@example.com",
"phone_number": 34666555444,
"nationality": "ES",
"employment_status": "self_employed",
"date_of_birth": {
"day": 8,
"month": 12,
"year": 1988
},
"address": {
"line_1": "Calle Ejemplo, 31",
"line_2": "2o 1a",
"postal_code": "08102",
"city": "L'Hospitalet de Llobregat",
"region": "Barcelona",
"country": "ES"
},
"document": {
"type": "string",
"country": "ES",
"number": "12345678R",
"expiration_date": "2018-12-25T00:00:00.000Z",
"front_file_id": "string (FileID)",
"back_file_id": "string (FileID)",
"selfie_file_id": "string (FileID)"
}
},
"meta": {
"key1": "value1",
"key2": "value2"
}
}
Success
Response Example (200 OK)
{
"id": "string (CustomerID)",
"created_at": "string (date-time)",
"project_id": "string (ProjectID)",
"identity": {
"first_name": "John",
"last_name": "McJohn",
"email_address": "john@example.com",
"phone_number": 34666555444,
"nationality": "ES",
"employment_status": "self_employed",
"date_of_birth": {
"day": 8,
"month": 12,
"year": 1988
},
"address": {
"line_1": "Calle Ejemplo, 31",
"line_2": "2o 1a",
"postal_code": "08102",
"city": "L'Hospitalet de Llobregat",
"region": "Barcelona",
"country": "ES"
},
"document": {
"type": "string",
"country": "ES",
"number": "12345678R",
"expiration_date": "2018-12-25T00:00:00.000Z",
"front_file_id": "string (FileID)",
"back_file_id": "string (FileID)",
"selfie_file_id": "string (FileID)"
}
},
"meta": {
"key1": "value1",
"key2": "value2"
}
}
Get customer
Customer ID
Success
Response Example (200 OK)
{
"id": "string (CustomerID)",
"created_at": "string (date-time)",
"project_id": "string (ProjectID)",
"identity": {
"first_name": "John",
"last_name": "McJohn",
"email_address": "john@example.com",
"phone_number": 34666555444,
"nationality": "ES",
"employment_status": "self_employed",
"date_of_birth": {
"day": 8,
"month": 12,
"year": 1988
},
"address": {
"line_1": "Calle Ejemplo, 31",
"line_2": "2o 1a",
"postal_code": "08102",
"city": "L'Hospitalet de Llobregat",
"region": "Barcelona",
"country": "ES"
},
"document": {
"type": "string",
"country": "ES",
"number": "12345678R",
"expiration_date": "2018-12-25T00:00:00.000Z",
"front_file_id": "string (FileID)",
"back_file_id": "string (FileID)",
"selfie_file_id": "string (FileID)"
}
},
"meta": {
"key1": "value1",
"key2": "value2"
}
}
Edit customer
Customer ID
Request Example
{
"identity": {
"first_name": "John",
"last_name": "McJohn",
"email_address": "john@example.com",
"phone_number": 34666555444,
"nationality": "ES",
"employment_status": "self_employed",
"date_of_birth": {
"day": 8,
"month": 12,
"year": 1988
},
"address": {
"line_1": "Calle Ejemplo, 31",
"line_2": "2o 1a",
"postal_code": "08102",
"city": "L'Hospitalet de Llobregat",
"region": "Barcelona",
"country": "ES"
},
"document": {
"type": "string",
"country": "ES",
"number": "12345678R",
"expiration_date": "2018-12-25T00:00:00.000Z",
"front_file_id": "string (FileID)",
"back_file_id": "string (FileID)",
"selfie_file_id": "string (FileID)"
}
},
"meta": {
"key1": "value1",
"key2": "value2"
}
}
Success
Response Example (200 OK)
{
"id": "string (CustomerID)",
"created_at": "string (date-time)",
"project_id": "string (ProjectID)",
"identity": {
"first_name": "John",
"last_name": "McJohn",
"email_address": "john@example.com",
"phone_number": 34666555444,
"nationality": "ES",
"employment_status": "self_employed",
"date_of_birth": {
"day": 8,
"month": 12,
"year": 1988
},
"address": {
"line_1": "Calle Ejemplo, 31",
"line_2": "2o 1a",
"postal_code": "08102",
"city": "L'Hospitalet de Llobregat",
"region": "Barcelona",
"country": "ES"
},
"document": {
"type": "string",
"country": "ES",
"number": "12345678R",
"expiration_date": "2018-12-25T00:00:00.000Z",
"front_file_id": "string (FileID)",
"back_file_id": "string (FileID)",
"selfie_file_id": "string (FileID)"
}
},
"meta": {
"key1": "value1",
"key2": "value2"
}
}
Transfers
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.)
List transfers
How many items to return, at maximum.
Cursor, to fetch more pages of a long list. See Pagination
Success
Response Example (200 OK)
{
"data": [
{
"id": "string (TransferID)",
"created_at": "string (date-time)",
"project_id": "string (ProjectID)",
"source_account_id": "string (AccountID)",
"source_transaction_id": "string (TransactionID)",
"destination_account_id": "string (AccountID)",
"destination_transaction_id": "string (TransactionID)",
"value": {
"currency": "EUR",
"amount": 100
},
"meta": {
"key1": "value1",
"key2": "value2"
}
}
],
"has_next": true,
"cursor_next": "string (cursor)"
}
Create transfer
Request Example
{
"source_account_id": "string (AccountID)",
"destination_account_id": "string (AccountID)",
"value": {
"currency": "EUR",
"amount": 100
},
"meta": {
"key1": "value1",
"key2": "value2"
}
}
Success
Response Example (200 OK)
{
"id": "string (TransferID)",
"created_at": "string (date-time)",
"project_id": "string (ProjectID)",
"source_account_id": "string (AccountID)",
"source_transaction_id": "string (TransactionID)",
"destination_account_id": "string (AccountID)",
"destination_transaction_id": "string (TransactionID)",
"value": {
"currency": "EUR",
"amount": 100
},
"meta": {
"key1": "value1",
"key2": "value2"
}
}
Get transfer
Transfer ID
Success
Response Example (200 OK)
{
"id": "string (TransferID)",
"created_at": "string (date-time)",
"project_id": "string (ProjectID)",
"source_account_id": "string (AccountID)",
"source_transaction_id": "string (TransactionID)",
"destination_account_id": "string (AccountID)",
"destination_transaction_id": "string (TransactionID)",
"value": {
"currency": "EUR",
"amount": 100
},
"meta": {
"key1": "value1",
"key2": "value2"
}
}
Edit transfer
Request Example
{
"meta": {
"key1": "value1",
"key2": "value2"
}
}
Success
Response Example (200 OK)
{
"id": "string (TransferID)",
"created_at": "string (date-time)",
"project_id": "string (ProjectID)",
"source_account_id": "string (AccountID)",
"source_transaction_id": "string (TransactionID)",
"destination_account_id": "string (AccountID)",
"destination_transaction_id": "string (TransactionID)",
"value": {
"currency": "EUR",
"amount": 100
},
"meta": {
"key1": "value1",
"key2": "value2"
}
}
Card tokens
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.
Create card token
- card_info: CardInfoRequest
Request Example
{
"card_info": {
"number": "4114360123456785",
"expiration_month": 12,
"expiration_year": 2023,
"cvc": "123"
}
}
Success
Response Example (200 OK)
{
"id": "string (CardTokenID)",
"created_at": "string (date-time)",
"project_id": "string (ProjectID)",
"card_info": {
"number": "string (card)",
"expiration_month": 12,
"expiration_year": 2023,
"brand": "visa",
"fingerprint": "yFe94Qso636auIaB"
}
}
Get card token
CardToken ID
Success
Response Example (200 OK)
{
"id": "string (CardTokenID)",
"created_at": "string (date-time)",
"project_id": "string (ProjectID)",
"card_info": {
"number": "string (card)",
"expiration_month": 12,
"expiration_year": 2023,
"brand": "visa",
"fingerprint": "yFe94Qso636auIaB"
}
}
Cards
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.
List cards
How many items to return, at maximum.
Cursor, to fetch more pages of a long list. See Pagination
Success
Response Example (200 OK)
{
"data": [
{
"id": "string (CardID)",
"created_at": "string (date-time)",
"project_id": "string (ProjectID)",
"customer_id": "string (CustomerID)",
"card_info": {
"number": "string (card)",
"expiration_month": 12,
"expiration_year": 2023,
"brand": "visa",
"fingerprint": "yFe94Qso636auIaB"
},
"meta": {
"key1": "value1",
"key2": "value2"
}
}
],
"has_next": true,
"cursor_next": "string (cursor)"
}
Create card
- card_token_id: string (CardTokenID)
- card_info: CardInfoRequest
- customer_id: string (CustomerID) null
- meta: Meta
Metadata for this object.
Request Example
{
"card_token_id": "string (CardTokenID)",
"card_info": {
"number": "4114360123456785",
"expiration_month": 12,
"expiration_year": 2023,
"cvc": "123"
},
"customer_id": "string (CustomerID)",
"meta": {
"key1": "value1",
"key2": "value2"
}
}
Success
Response Example (200 OK)
{
"id": "string (CardID)",
"created_at": "string (date-time)",
"project_id": "string (ProjectID)",
"customer_id": "string (CustomerID)",
"card_info": {
"number": "string (card)",
"expiration_month": 12,
"expiration_year": 2023,
"brand": "visa",
"fingerprint": "yFe94Qso636auIaB"
},
"meta": {
"key1": "value1",
"key2": "value2"
}
}
Get card
Card ID
Success
Response Example (200 OK)
{
"id": "string (CardID)",
"created_at": "string (date-time)",
"project_id": "string (ProjectID)",
"customer_id": "string (CustomerID)",
"card_info": {
"number": "string (card)",
"expiration_month": 12,
"expiration_year": 2023,
"brand": "visa",
"fingerprint": "yFe94Qso636auIaB"
},
"meta": {
"key1": "value1",
"key2": "value2"
}
}
Edit card
Request Example
{
"meta": {
"key1": "value1",
"key2": "value2"
}
}
Success
Response Example (200 OK)
{
"id": "string (CardID)",
"created_at": "string (date-time)",
"project_id": "string (ProjectID)",
"customer_id": "string (CustomerID)",
"card_info": {
"number": "string (card)",
"expiration_month": 12,
"expiration_year": 2023,
"brand": "visa",
"fingerprint": "yFe94Qso636auIaB"
},
"meta": {
"key1": "value1",
"key2": "value2"
}
}
Delete card
Card ID
Success
Response Example (200 OK)
{
"id": "string (CardID)",
"created_at": "string (date-time)",
"project_id": "string (ProjectID)",
"customer_id": "string (CustomerID)",
"card_info": {
"number": "string (card)",
"expiration_month": 12,
"expiration_year": 2023,
"brand": "visa",
"fingerprint": "yFe94Qso636auIaB"
},
"meta": {
"key1": "value1",
"key2": "value2"
}
}
Card payins
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.
List card payins
How many items to return, at maximum.
Cursor, to fetch more pages of a long list. See Pagination
Success
Response Example (200 OK)
{
"data": [
{
"id": "string (CardPayinID)",
"created_at": "string (date-time)",
"project_id": "string (ProjectID)",
"state": "string",
"card_id": "string (CardID)",
"card_info": {
"number": "string (card)",
"expiration_month": 12,
"expiration_year": 2023,
"brand": "visa",
"fingerprint": "yFe94Qso636auIaB"
},
"account_id": "string (AccountID)",
"transaction_id": "string (TransactionID)",
"calculated_statement_descriptor": "Kernel Payments",
"authentication_type": "string",
"authentication_url": "https://gateway.kernelpay.com/start/910932071",
"authentication_redirect_url": "https://example.com/checkout",
"value": {
"currency": "EUR",
"amount": 100
},
"refunded_value": {
"currency": "EUR",
"amount": 100
},
"meta": {
"key1": "value1",
"key2": "value2"
}
}
],
"has_next": true,
"cursor_next": "string (cursor)"
}
Create card payin
- authentication_type: string none, three_d_secure, three_d_secure_2
Type of authentication (None, 3DSecure or 3DSecure 2 which is PSD2 compliant)
- authentication_redirect_url: string
URL to redirect to after authentication (if 3DSecure).
- card_info: CardInfoRequest
- card_token_id: string (CardTokenID)
- card_id: string (CardID)
- offline: bool
Only can be used for
three_d_secure_2
charges where the customer is not present.- account_id: string (AccountID)
- statement_descriptor_suffix: string
Can be used to build dynamic statement descriptors. Will be preprended by the prefix which is static.
- value: Value
- meta: Meta
Metadata for this object.
Request Example
{
"authentication_type": "string",
"authentication_redirect_url": "https://example.com/checkout",
"card_info": {
"number": "4114360123456785",
"expiration_month": 12,
"expiration_year": 2023,
"cvc": "123"
},
"card_token_id": "string (CardTokenID)",
"card_id": "string (CardID)",
"offline": "bool",
"account_id": "string (AccountID)",
"statement_descriptor_suffix": "string",
"value": {
"currency": "EUR",
"amount": 100
},
"meta": {
"key1": "value1",
"key2": "value2"
}
}
Success
Response Example (200 OK)
{
"id": "string (CardPayinID)",
"created_at": "string (date-time)",
"project_id": "string (ProjectID)",
"state": "string",
"card_id": "string (CardID)",
"card_info": {
"number": "string (card)",
"expiration_month": 12,
"expiration_year": 2023,
"brand": "visa",
"fingerprint": "yFe94Qso636auIaB"
},
"account_id": "string (AccountID)",
"transaction_id": "string (TransactionID)",
"calculated_statement_descriptor": "Kernel Payments",
"authentication_type": "string",
"authentication_url": "https://gateway.kernelpay.com/start/910932071",
"authentication_redirect_url": "https://example.com/checkout",
"value": {
"currency": "EUR",
"amount": 100
},
"refunded_value": {
"currency": "EUR",
"amount": 100
},
"meta": {
"key1": "value1",
"key2": "value2"
}
}
Get card payin
CardPayin ID
Success
Response Example (200 OK)
{
"id": "string (CardPayinID)",
"created_at": "string (date-time)",
"project_id": "string (ProjectID)",
"state": "string",
"card_id": "string (CardID)",
"card_info": {
"number": "string (card)",
"expiration_month": 12,
"expiration_year": 2023,
"brand": "visa",
"fingerprint": "yFe94Qso636auIaB"
},
"account_id": "string (AccountID)",
"transaction_id": "string (TransactionID)",
"calculated_statement_descriptor": "Kernel Payments",
"authentication_type": "string",
"authentication_url": "https://gateway.kernelpay.com/start/910932071",
"authentication_redirect_url": "https://example.com/checkout",
"value": {
"currency": "EUR",
"amount": 100
},
"refunded_value": {
"currency": "EUR",
"amount": 100
},
"meta": {
"key1": "value1",
"key2": "value2"
}
}
Edit card payin
Request Example
{
"meta": {
"key1": "value1",
"key2": "value2"
}
}
Success
Response Example (200 OK)
{
"id": "string (CardPayinID)",
"created_at": "string (date-time)",
"project_id": "string (ProjectID)",
"state": "string",
"card_id": "string (CardID)",
"card_info": {
"number": "string (card)",
"expiration_month": 12,
"expiration_year": 2023,
"brand": "visa",
"fingerprint": "yFe94Qso636auIaB"
},
"account_id": "string (AccountID)",
"transaction_id": "string (TransactionID)",
"calculated_statement_descriptor": "Kernel Payments",
"authentication_type": "string",
"authentication_url": "https://gateway.kernelpay.com/start/910932071",
"authentication_redirect_url": "https://example.com/checkout",
"value": {
"currency": "EUR",
"amount": 100
},
"refunded_value": {
"currency": "EUR",
"amount": 100
},
"meta": {
"key1": "value1",
"key2": "value2"
}
}
List card payin refunds
How many items to return, at maximum.
Cursor, to fetch more pages of a long list. See Pagination
CardPayin ID
Success
Response Example (200 OK)
{
"data": [
{
"id": "string (CardPayinRefundID)",
"created_at": "string (date-time)",
"project_id": "string (ProjectID)",
"card_payin_id": "string (CardPayinID)",
"state": "string",
"transaction_id": "string (TransactionID)",
"failure_transaction_id": "string (TransactionID)",
"value": {
"currency": "EUR",
"amount": 100
}
}
],
"has_next": true,
"cursor_next": "string (cursor)"
}
Create card payin refund
- value: Value
Optional. Amount to refund. If not present, the entire card payin amount will be refunded (or what's left to refund if partial refunds have been made).
- account_id: string (AccountID)
Optional. Account to get the funds from. If not present, it defaults to the account used for the card payin.
CardPayin ID
Request Example
{
"value": {
"currency": "EUR",
"amount": 100
},
"account_id": "string (AccountID)"
}
Success
Response Example (200 OK)
{
"id": "string (CardPayinRefundID)",
"created_at": "string (date-time)",
"project_id": "string (ProjectID)",
"card_payin_id": "string (CardPayinID)",
"state": "string",
"transaction_id": "string (TransactionID)",
"failure_transaction_id": "string (TransactionID)",
"value": {
"currency": "EUR",
"amount": 100
}
}
Simulate card payin settle
[SANDBOX ONLY]
In the live environment, CardPayins are automatically settled when the funds arrive from the card networks, usually next business day.
However, to allow quick testing in the sandbox environment, you can instantly settle a CardPayin that is in the authorized
state with this request.
This will change the CardPayin to the settled
state and credit the funds to the account, exactly as if the CardPayin had been settled by the card networks.
CardPayin ID
Request Example
"object"
Success
Response Example (200 OK)
{
"id": "string (CardPayinID)",
"created_at": "string (date-time)",
"project_id": "string (ProjectID)",
"state": "string",
"card_id": "string (CardID)",
"card_info": {
"number": "string (card)",
"expiration_month": 12,
"expiration_year": 2023,
"brand": "visa",
"fingerprint": "yFe94Qso636auIaB"
},
"account_id": "string (AccountID)",
"transaction_id": "string (TransactionID)",
"calculated_statement_descriptor": "Kernel Payments",
"authentication_type": "string",
"authentication_url": "https://gateway.kernelpay.com/start/910932071",
"authentication_redirect_url": "https://example.com/checkout",
"value": {
"currency": "EUR",
"amount": 100
},
"refunded_value": {
"currency": "EUR",
"amount": 100
},
"meta": {
"key1": "value1",
"key2": "value2"
}
}
Cancel card payin
Card payins that are in authentication_pending
state can be cancelled to prevent the user takes further action.
CardPayin ID
Success
Response Example (200 OK)
{
"id": "string (CardPayinID)",
"created_at": "string (date-time)",
"project_id": "string (ProjectID)",
"state": "string",
"card_id": "string (CardID)",
"card_info": {
"number": "string (card)",
"expiration_month": 12,
"expiration_year": 2023,
"brand": "visa",
"fingerprint": "yFe94Qso636auIaB"
},
"account_id": "string (AccountID)",
"transaction_id": "string (TransactionID)",
"calculated_statement_descriptor": "Kernel Payments",
"authentication_type": "string",
"authentication_url": "https://gateway.kernelpay.com/start/910932071",
"authentication_redirect_url": "https://example.com/checkout",
"value": {
"currency": "EUR",
"amount": 100
},
"refunded_value": {
"currency": "EUR",
"amount": 100
},
"meta": {
"key1": "value1",
"key2": "value2"
}
}
Bank accounts
You can use a BankAccount to store a customer's bank account.
List bank accounts
How many items to return, at maximum.
Cursor, to fetch more pages of a long list. See Pagination
Success
Response Example (200 OK)
{
"data": [
{
"id": "string (BankAccountID)",
"created_at": "string (date-time)",
"project_id": "string (ProjectID)",
"customer_id": "string (CustomerID)",
"bank_account_info": {
"iban": "ES9121000418450200051332",
"beneficiary_name": "Pepito Martinez"
},
"meta": {
"key1": "value1",
"key2": "value2"
}
}
],
"has_next": true,
"cursor_next": "string (cursor)"
}
Create bank account
- bank_account_info: BankAccountInfo
- customer_id: string (CustomerID) null
- meta: Meta
Metadata for this object.
Request Example
{
"bank_account_info": {
"iban": "ES9121000418450200051332",
"beneficiary_name": "Pepito Martinez"
},
"customer_id": "string (CustomerID)",
"meta": {
"key1": "value1",
"key2": "value2"
}
}
Success
Response Example (200 OK)
{
"id": "string (BankAccountID)",
"created_at": "string (date-time)",
"project_id": "string (ProjectID)",
"customer_id": "string (CustomerID)",
"bank_account_info": {
"iban": "ES9121000418450200051332",
"beneficiary_name": "Pepito Martinez"
},
"meta": {
"key1": "value1",
"key2": "value2"
}
}
Get bank account
BankAccount ID
Success
Response Example (200 OK)
{
"id": "string (BankAccountID)",
"created_at": "string (date-time)",
"project_id": "string (ProjectID)",
"customer_id": "string (CustomerID)",
"bank_account_info": {
"iban": "ES9121000418450200051332",
"beneficiary_name": "Pepito Martinez"
},
"meta": {
"key1": "value1",
"key2": "value2"
}
}
Edit bank account
Request Example
{
"meta": {
"key1": "value1",
"key2": "value2"
}
}
Success
Response Example (200 OK)
{
"id": "string (BankAccountID)",
"created_at": "string (date-time)",
"project_id": "string (ProjectID)",
"customer_id": "string (CustomerID)",
"bank_account_info": {
"iban": "ES9121000418450200051332",
"beneficiary_name": "Pepito Martinez"
},
"meta": {
"key1": "value1",
"key2": "value2"
}
}
Bank payouts
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.
List bank payouts
How many items to return, at maximum.
Cursor, to fetch more pages of a long list. See Pagination
Success
Response Example (200 OK)
{
"data": [
{
"id": "string (TransferID)",
"created_at": "string (date-time)",
"project_id": "string (ProjectID)",
"account_id": "string (AccountID)",
"bank_account_info": {
"iban": "ES9121000418450200051332",
"beneficiary_name": "Pepito Martinez"
},
"bank_account_id": "string (BankAccountID)",
"transaction_id": "string (TransactionID)",
"failure_transaction_id": "string (TransactionID)",
"state": "string",
"concept": "string",
"miniref": "string",
"value": {
"currency": "EUR",
"amount": 100
},
"processed_at": "string (date-time)",
"meta": {
"key1": "value1",
"key2": "value2"
}
}
],
"has_next": true,
"cursor_next": "string (cursor)"
}
Create bank payout
Request Example
{
"account_id": "string (AccountID)",
"bank_account_id": "string (BankAccountID)",
"concept": "string",
"value": {
"currency": "EUR",
"amount": 100
},
"meta": {
"key1": "value1",
"key2": "value2"
}
}
Success
Response Example (200 OK)
{
"id": "string (TransferID)",
"created_at": "string (date-time)",
"project_id": "string (ProjectID)",
"account_id": "string (AccountID)",
"bank_account_info": {
"iban": "ES9121000418450200051332",
"beneficiary_name": "Pepito Martinez"
},
"bank_account_id": "string (BankAccountID)",
"transaction_id": "string (TransactionID)",
"failure_transaction_id": "string (TransactionID)",
"state": "string",
"concept": "string",
"miniref": "string",
"value": {
"currency": "EUR",
"amount": 100
},
"processed_at": "string (date-time)",
"meta": {
"key1": "value1",
"key2": "value2"
}
}
Get bank payout
BankPayout ID
Success
Response Example (200 OK)
{
"id": "string (TransferID)",
"created_at": "string (date-time)",
"project_id": "string (ProjectID)",
"account_id": "string (AccountID)",
"bank_account_info": {
"iban": "ES9121000418450200051332",
"beneficiary_name": "Pepito Martinez"
},
"bank_account_id": "string (BankAccountID)",
"transaction_id": "string (TransactionID)",
"failure_transaction_id": "string (TransactionID)",
"state": "string",
"concept": "string",
"miniref": "string",
"value": {
"currency": "EUR",
"amount": 100
},
"processed_at": "string (date-time)",
"meta": {
"key1": "value1",
"key2": "value2"
}
}
Edit bank payout
BankPayout ID
Request Example
{
"allow_negative_balance": "boolean",
"meta": {
"key1": "value1",
"key2": "value2"
}
}
Success
Response Example (200 OK)
{
"id": "string (TransferID)",
"created_at": "string (date-time)",
"project_id": "string (ProjectID)",
"account_id": "string (AccountID)",
"bank_account_info": {
"iban": "ES9121000418450200051332",
"beneficiary_name": "Pepito Martinez"
},
"bank_account_id": "string (BankAccountID)",
"transaction_id": "string (TransactionID)",
"failure_transaction_id": "string (TransactionID)",
"state": "string",
"concept": "string",
"miniref": "string",
"value": {
"currency": "EUR",
"amount": 100
},
"processed_at": "string (date-time)",
"meta": {
"key1": "value1",
"key2": "value2"
}
}
Bank payins
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.
List bank payins
How many items to return, at maximum.
Cursor, to fetch more pages of a long list. See Pagination
Success
Response Example (200 OK)
{
"data": [
{
"id": "string (BankPayinID)",
"created_at": "string (date-time)",
"project_id": "string (ProjectID)",
"bank_payin_reference_id": "string (BankPayinReferenceID)",
"account_id": "string (AccountID)",
"transaction_id": "string (TransactionID)",
"concept": "string",
"value": {
"currency": "EUR",
"amount": 100
},
"meta": {
"key1": "value1",
"key2": "value2"
}
}
],
"has_next": true,
"cursor_next": "string (cursor)"
}
Get bank payin
BankPayin ID
Success
Response Example (200 OK)
{
"id": "string (BankPayinID)",
"created_at": "string (date-time)",
"project_id": "string (ProjectID)",
"bank_payin_reference_id": "string (BankPayinReferenceID)",
"account_id": "string (AccountID)",
"transaction_id": "string (TransactionID)",
"concept": "string",
"value": {
"currency": "EUR",
"amount": 100
},
"meta": {
"key1": "value1",
"key2": "value2"
}
}
Edit bank payin
Request Example
{
"meta": {
"key1": "value1",
"key2": "value2"
}
}
Success
Response Example (200 OK)
{
"id": "string (BankPayinID)",
"created_at": "string (date-time)",
"project_id": "string (ProjectID)",
"bank_payin_reference_id": "string (BankPayinReferenceID)",
"account_id": "string (AccountID)",
"transaction_id": "string (TransactionID)",
"concept": "string",
"value": {
"currency": "EUR",
"amount": 100
},
"meta": {
"key1": "value1",
"key2": "value2"
}
}
List bank payin references
How many items to return, at maximum.
Cursor, to fetch more pages of a long list. See Pagination
Success
Response Example (200 OK)
{
"data": [
{
"id": "string (BankPayinReferenceID)",
"created_at": "string (date-time)",
"project_id": "string (ProjectID)",
"account_id": "string (AccountID)",
"reference": "string",
"meta": {
"key1": "value1",
"key2": "value2"
}
}
],
"has_next": true,
"cursor_next": "string (cursor)"
}
Create bank payin reference
Request Example
{
"account_id": "string (AccountID)",
"meta": {
"key1": "value1",
"key2": "value2"
}
}
Success
Response Example (200 OK)
{
"id": "string (BankPayinReferenceID)",
"created_at": "string (date-time)",
"project_id": "string (ProjectID)",
"account_id": "string (AccountID)",
"reference": "string",
"meta": {
"key1": "value1",
"key2": "value2"
}
}
Get bank payin reference
BankPayinReference ID
Success
Response Example (200 OK)
{
"id": "string (BankPayinReferenceID)",
"created_at": "string (date-time)",
"project_id": "string (ProjectID)",
"account_id": "string (AccountID)",
"reference": "string",
"meta": {
"key1": "value1",
"key2": "value2"
}
}
Edit bank payin reference
BankPayinReference ID
Request Example
{
"account_id": "string (AccountID)",
"meta": {
"key1": "value1",
"key2": "value2"
}
}
Success
Response Example (200 OK)
{
"id": "string (BankPayinReferenceID)",
"created_at": "string (date-time)",
"project_id": "string (ProjectID)",
"account_id": "string (AccountID)",
"reference": "string",
"meta": {
"key1": "value1",
"key2": "value2"
}
}
Files
Upload files to use them as identity documents in Customer objects.
Upload file
Success
Response Example (200 OK)
{
"id": "string (FileID)",
"created_at": "string (date-time)",
"project_id": "string (ProjectID)",
"hash": "i62oqkyWBN+pLiaz6u5GiwdKoryjIqW93GqpVtGOaiM=",
"name": "IMG_20170823_001.jpg",
"size": 1938718,
"url": "https://storage.googleapis.com/kernel-files/b159cb9ce9d85a1dd9861fd105?Expires=1527184040&Signature=atgUlHzFKyS..."
}
Get file
File ID
Success
Response Example (200 OK)
{
"id": "string (FileID)",
"created_at": "string (date-time)",
"project_id": "string (ProjectID)",
"hash": "i62oqkyWBN+pLiaz6u5GiwdKoryjIqW93GqpVtGOaiM=",
"name": "IMG_20170823_001.jpg",
"size": 1938718,
"url": "https://storage.googleapis.com/kernel-files/b159cb9ce9d85a1dd9861fd105?Expires=1527184040&Signature=atgUlHzFKyS..."
}
Events
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.
List events
How many items to return, at maximum.
Cursor, to fetch more pages of a long list. See Pagination
Success
Response Example (200 OK)
{
"data": [
{
"id": "string (EventID)",
"created_at": "string (date-time)",
"project_id": "string (ProjectID)",
"type": "bank_payin_created",
"payload": {
"bank_payin": {
"id": "bpi_3merk33gt7ml3ltq5bg1",
"created_at": "2018-03-13T16:56:51.766836837Z",
"project_id": "prj_3merk33gt1v9ypgfzrp1",
"bank_payin_reference_id": "bpir_3merk33gt21kym11een1",
"account_id": "acc_3merk33gt3l525ryhcmh",
"transaction_id": "tx_3merk33gt345nu3dnkmh",
"concept": "string",
"value": {
"currency": "EUR",
"amount": 100
},
"meta": {
"key1": "value1",
"key2": "value2"
}
}
}
}
],
"has_next": true,
"cursor_next": "string (cursor)"
}
Get event
Event ID
Success
Response Example (200 OK)
{
"id": "string (EventID)",
"created_at": "string (date-time)",
"project_id": "string (ProjectID)",
"type": "bank_payin_created",
"payload": {
"bank_payin": {
"id": "bpi_3merk33gt7ml3ltq5bg1",
"created_at": "2018-03-13T16:56:51.766836837Z",
"project_id": "prj_3merk33gt1v9ypgfzrp1",
"bank_payin_reference_id": "bpir_3merk33gt21kym11een1",
"account_id": "acc_3merk33gt3l525ryhcmh",
"transaction_id": "tx_3merk33gt345nu3dnkmh",
"concept": "string",
"value": {
"currency": "EUR",
"amount": 100
},
"meta": {
"key1": "value1",
"key2": "value2"
}
}
}
}
Webhooks
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.
List webhooks
How many items to return, at maximum.
Cursor, to fetch more pages of a long list. See Pagination
Success
Response Example (200 OK)
{
"data": [
{
"id": "string (WebhookID)",
"created_at": "string (date-time)",
"project_id": "string (ProjectID)",
"event_types": {
"card_payin_dispute_created": true,
"card_payin_settled": true,
"bank_payin_created": true,
"bank_payout_completed": true,
"bank_payout_failed": true,
"bank_payout_refunded": true,
"card_payin_dispute_won": true,
"card_payin_dispute_lost": true,
"card_payin_authorized": true,
"card_payin_declined": true,
"transfer_created": true
},
"url": "https://api.example.com/v1/webhook_receiver",
"secret": "463edba8b57b37eebce1364b2d22fab8a4e4b60a8aa247db",
"is_enabled": true
}
],
"has_next": true,
"cursor_next": "string (cursor)"
}
Create webhook
- event_types: object
Event types to receive
- card_payin_dispute_created: boolean
- card_payin_settled: boolean
- bank_payin_created: boolean
- bank_payout_completed: boolean
- bank_payout_failed: boolean
- bank_payout_refunded: boolean
- card_payin_dispute_won: boolean
- card_payin_dispute_lost: boolean
- card_payin_authorized: boolean
- card_payin_declined: boolean
- transfer_created: boolean
- url: string
URL to send events to. Supports
http
andhttps
.- is_enabled: boolean
Whether this webhook is enabled or not. Disabled webhooks do not send notifications, and can be re-enabled later.
Request Example
{
"event_types": {
"card_payin_dispute_created": true,
"card_payin_settled": true,
"bank_payin_created": true,
"bank_payout_completed": true,
"bank_payout_failed": true,
"bank_payout_refunded": true,
"card_payin_dispute_won": true,
"card_payin_dispute_lost": true,
"card_payin_authorized": true,
"card_payin_declined": true,
"transfer_created": true
},
"url": "https://api.example.com/v1/webhook_receiver",
"is_enabled": true
}
Success
Response Example (200 OK)
{
"id": "string (WebhookID)",
"created_at": "string (date-time)",
"project_id": "string (ProjectID)",
"event_types": {
"card_payin_dispute_created": true,
"card_payin_settled": true,
"bank_payin_created": true,
"bank_payout_completed": true,
"bank_payout_failed": true,
"bank_payout_refunded": true,
"card_payin_dispute_won": true,
"card_payin_dispute_lost": true,
"card_payin_authorized": true,
"card_payin_declined": true,
"transfer_created": true
},
"url": "https://api.example.com/v1/webhook_receiver",
"secret": "463edba8b57b37eebce1364b2d22fab8a4e4b60a8aa247db",
"is_enabled": true
}
Get webhook
Webhook ID
Success
Response Example (200 OK)
{
"id": "string (WebhookID)",
"created_at": "string (date-time)",
"project_id": "string (ProjectID)",
"event_types": {
"card_payin_dispute_created": true,
"card_payin_settled": true,
"bank_payin_created": true,
"bank_payout_completed": true,
"bank_payout_failed": true,
"bank_payout_refunded": true,
"card_payin_dispute_won": true,
"card_payin_dispute_lost": true,
"card_payin_authorized": true,
"card_payin_declined": true,
"transfer_created": true
},
"url": "https://api.example.com/v1/webhook_receiver",
"secret": "463edba8b57b37eebce1364b2d22fab8a4e4b60a8aa247db",
"is_enabled": true
}
Edit webhook
- event_types: object
Event types to receive
- card_payin_dispute_created: boolean
- card_payin_settled: boolean
- bank_payin_created: boolean
- bank_payout_completed: boolean
- bank_payout_failed: boolean
- bank_payout_refunded: boolean
- card_payin_dispute_won: boolean
- card_payin_dispute_lost: boolean
- card_payin_authorized: boolean
- card_payin_declined: boolean
- transfer_created: boolean
- url: string
URL to send events to. Supports
http
andhttps
.- is_enabled: boolean
Whether this webhook is enabled or not. Disabled webhooks do not send notifications, and can be re-enabled later.
Webhook ID
Request Example
{
"event_types": {
"card_payin_dispute_created": true,
"card_payin_settled": true,
"bank_payin_created": true,
"bank_payout_completed": true,
"bank_payout_failed": true,
"bank_payout_refunded": true,
"card_payin_dispute_won": true,
"card_payin_dispute_lost": true,
"card_payin_authorized": true,
"card_payin_declined": true,
"transfer_created": true
},
"url": "https://api.example.com/v1/webhook_receiver",
"is_enabled": true
}
Success
Response Example (200 OK)
{
"id": "string (WebhookID)",
"created_at": "string (date-time)",
"project_id": "string (ProjectID)",
"event_types": {
"card_payin_dispute_created": true,
"card_payin_settled": true,
"bank_payin_created": true,
"bank_payout_completed": true,
"bank_payout_failed": true,
"bank_payout_refunded": true,
"card_payin_dispute_won": true,
"card_payin_dispute_lost": true,
"card_payin_authorized": true,
"card_payin_declined": true,
"transfer_created": true
},
"url": "https://api.example.com/v1/webhook_receiver",
"secret": "463edba8b57b37eebce1364b2d22fab8a4e4b60a8aa247db",
"is_enabled": true
}
Delete webhook
Webhook ID
Success
Response Example (200 OK)
{
"id": "string (WebhookID)",
"created_at": "string (date-time)",
"project_id": "string (ProjectID)",
"event_types": {
"card_payin_dispute_created": true,
"card_payin_settled": true,
"bank_payin_created": true,
"bank_payout_completed": true,
"bank_payout_failed": true,
"bank_payout_refunded": true,
"card_payin_dispute_won": true,
"card_payin_dispute_lost": true,
"card_payin_authorized": true,
"card_payin_declined": true,
"transfer_created": true
},
"url": "https://api.example.com/v1/webhook_receiver",
"secret": "463edba8b57b37eebce1364b2d22fab8a4e4b60a8aa247db",
"is_enabled": true
}
Schema Definitions
Value: object
All the monetary values in the API are represented with Value objects, consisting of an amount and a currency.
- currency: Currency
Currency
- amount: integer (int64)
Amount, represented in the smallest currency units as an integer. For example, cents for Euro amounts.
Example
{
"currency": "EUR",
"amount": 100
}
Account: object
- id: string (AccountID)
Unique identifier
- created_at: string (date-time)
Creation time for this object
- project_id: string (ProjectID)
Unique identifier of the Project this object belongs to..
- customer_id: string (CustomerID)
Customer this account's funds belong to. If null, the funds belong to you, the project owner.
- balance: Value
Balance of the account.
- allow_negative_balance: boolean
If true, operations that would result in negative balance are allowed for this account, as long as the total balance for the project is still positive.
- meta: Meta
Metadata for this object.
Example
{
"id": "string (AccountID)",
"created_at": "string (date-time)",
"project_id": "string (ProjectID)",
"customer_id": "string (CustomerID)",
"balance": {
"currency": "EUR",
"amount": 100
},
"allow_negative_balance": false,
"meta": {
"key1": "value1",
"key2": "value2"
}
}
Customer: object
Example
{
"id": "string (CustomerID)",
"created_at": "string (date-time)",
"project_id": "string (ProjectID)",
"identity": {
"first_name": "John",
"last_name": "McJohn",
"email_address": "john@example.com",
"phone_number": 34666555444,
"nationality": "ES",
"employment_status": "self_employed",
"date_of_birth": {
"day": 8,
"month": 12,
"year": 1988
},
"address": {
"line_1": "Calle Ejemplo, 31",
"line_2": "2o 1a",
"postal_code": "08102",
"city": "L'Hospitalet de Llobregat",
"region": "Barcelona",
"country": "ES"
},
"document": {
"type": "string",
"country": "ES",
"number": "12345678R",
"expiration_date": "2018-12-25T00:00:00.000Z",
"front_file_id": "string (FileID)",
"back_file_id": "string (FileID)",
"selfie_file_id": "string (FileID)"
}
},
"meta": {
"key1": "value1",
"key2": "value2"
}
}
Identity: object
- first_name: string
First name
- last_name: string
Last name
- email_address: string
Email address. Optional
- phone_number: string
Phone number in E164 format. Optional
- nationality: string
Country of nationality. 2-letter uppercase country code.
- employment_status: string student, employed, self_employed, searching, not_employed
Employment status, optional.
- date_of_birth: DateOfBirth
Date of birth.
- address: Address
Address. Optional.
- document: IdentityDocument
Identity document. Optional.
Example
{
"first_name": "John",
"last_name": "McJohn",
"email_address": "john@example.com",
"phone_number": 34666555444,
"nationality": "ES",
"employment_status": "self_employed",
"date_of_birth": {
"day": 8,
"month": 12,
"year": 1988
},
"address": {
"line_1": "Calle Ejemplo, 31",
"line_2": "2o 1a",
"postal_code": "08102",
"city": "L'Hospitalet de Llobregat",
"region": "Barcelona",
"country": "ES"
},
"document": {
"type": "string",
"country": "ES",
"number": "12345678R",
"expiration_date": "2018-12-25T00:00:00.000Z",
"front_file_id": "string (FileID)",
"back_file_id": "string (FileID)",
"selfie_file_id": "string (FileID)"
}
}
DateOfBirth: object
- day: integer (nullable)
Must be a number between 1 and 31
- month: integer (nullable)
Must be a number between 1 and 12
- year: integer (nullable)
Must be a four-digits positive number
Example
{
"day": 8,
"month": 12,
"year": 1988
}
Address: object
- line_1: string
Address line 1
- line_2: string
Address line 2
- postal_code: string
Postal or zip code.
- city: string
City
- region: string
Region of the city (Province, state or similar)
- country: string
Country, 2-letter uppercase country code.
Example
{
"line_1": "Calle Ejemplo, 31",
"line_2": "2o 1a",
"postal_code": "08102",
"city": "L'Hospitalet de Llobregat",
"region": "Barcelona",
"country": "ES"
}
IdentityDocument: object
- type: string national_id, passport
Document type
- country: string
Country that issued the document. 2-letter uppercase country code.
- number: string
Document number
- expiration_date: date
Document expiration date
- front_file_id: string (FileID)
Picture of the front of the document. Optional.
- back_file_id: string (FileID)
Picture of the back of the document. Optional. Not required in documents that don't have information in the back.
- selfie_file_id: string (FileID)
Selfie picture of the customer showing his face and document. Optional, useful for stronger verification.
Example
{
"type": "string",
"country": "ES",
"number": "12345678R",
"expiration_date": "2018-12-25T00:00:00.000Z",
"front_file_id": "string (FileID)",
"back_file_id": "string (FileID)",
"selfie_file_id": "string (FileID)"
}
Transaction: object
- id: string (TransactionID)
Unique identifier
- created_at: string (date-time)
Creation time for this object
- project_id: string (ProjectID)
Unique identifier of the Project this object belongs to..
- account_id: string (AccountID)
Account of this transaction
- type: string magic, transfer_source, transfer_destination, card_payin, card_payin_refund, card_payin_refund_failure, bank_payout, bank_payout_failure
Operation that caused this transaction.
- value: Value
Value of the transaction. Can be positive (funds added to the account) or negative (funds removed).
- balance_after: Value
Balance of the account immediately after this transaction.
- transfer_id: string (TransferID)
Transfer that caused this transaction
- bank_payout_id: string (BankPayoutID)
BankPayout that caused this transaction
- card_payin_id: string (CardPayinID)
CardPayin that caused this transaction
- card_payin_refund_id: string (CardPayinRefundID)
CardPayinRefund that caused this transaction
Example
{
"id": "string (TransactionID)",
"created_at": "string (date-time)",
"project_id": "string (ProjectID)",
"account_id": "string (AccountID)",
"type": "string",
"value": {
"currency": "EUR",
"amount": 100
},
"balance_after": {
"currency": "EUR",
"amount": 100
},
"transfer_id": "string (TransferID)",
"bank_payout_id": "string (BankPayoutID)",
"card_payin_id": "string (CardPayinID)",
"card_payin_refund_id": "string (CardPayinRefundID)"
}
Transfer: object
- id: string (TransferID)
Unique identifier
- created_at: string (date-time)
Creation time for this object
- project_id: string (ProjectID)
Unique identifier of the Project this object belongs to..
- source_account_id: string (AccountID)
Source account
- source_transaction_id: string (TransactionID)
Transaction removing the funds from the source account
- destination_account_id: string (AccountID)
Destination account
- destination_transaction_id: string (TransactionID)
Transaction adding the funds to the destination account
- value: Value
Value of the transfer. Always positive.
- meta: Meta
Metadata for this object.
Example
{
"id": "string (TransferID)",
"created_at": "string (date-time)",
"project_id": "string (ProjectID)",
"source_account_id": "string (AccountID)",
"source_transaction_id": "string (TransactionID)",
"destination_account_id": "string (AccountID)",
"destination_transaction_id": "string (TransactionID)",
"value": {
"currency": "EUR",
"amount": 100
},
"meta": {
"key1": "value1",
"key2": "value2"
}
}
CardInfo: object
- number: string (card)
Card number. When fetching card information from the API, this field will have all digits replaced with asterisks (
*
), except the first 6 and last 4 digits.- expiration_month: integer
Expiration month, from 1 to 12.
- expiration_year: integer
Expiration year, full 4-digit number. (ex:
2019
, not19
)- brand: string unknown, american_express, diners_club, discover, jcb, maestro, mastercard, unionpay, visa
Brand of the card.
- fingerprint: string
Card number fingerprint. Two cards, tokens or payins with the same card number in the same project will have the same fingerprint.
You can use it to check if two different customers are using the same card, for example.
Example
{
"number": "string (card)",
"expiration_month": 12,
"expiration_year": 2023,
"brand": "visa",
"fingerprint": "yFe94Qso636auIaB"
}
CardInfoRequest: object
- number: string (card)
Card number.
- expiration_month: integer
Expiration month, from 1 to 12.
- expiration_year: integer
Expiration year, full 4-digit number. (ex:
2019
, not19
)- cvc: string
CVC (or CVV) of the card. 3 or 4 digits.
Example
{
"number": "4114360123456785",
"expiration_month": 12,
"expiration_year": 2023,
"cvc": "123"
}
CardToken: object
Example
{
"id": "string (CardTokenID)",
"created_at": "string (date-time)",
"project_id": "string (ProjectID)",
"card_info": {
"number": "string (card)",
"expiration_month": 12,
"expiration_year": 2023,
"brand": "visa",
"fingerprint": "yFe94Qso636auIaB"
}
}
Card: object
- id: string (CardID)
Unique identifier
- created_at: string (date-time)
Creation time for this object
- project_id: string (ProjectID)
Unique identifier of the Project this object belongs to..
- customer_id: string (CustomerID)
Customer this card belongs to. If null, the card belongs to you, the project owner.
- card_info: CardInfo
- meta: Meta
Metadata for this object.
Example
{
"id": "string (CardID)",
"created_at": "string (date-time)",
"project_id": "string (ProjectID)",
"customer_id": "string (CustomerID)",
"card_info": {
"number": "string (card)",
"expiration_month": 12,
"expiration_year": 2023,
"brand": "visa",
"fingerprint": "yFe94Qso636auIaB"
},
"meta": {
"key1": "value1",
"key2": "value2"
}
}
CardPayin: object
- id: string (CardPayinID)
Unique identifier
- created_at: string (date-time)
Creation time for this object
- project_id: string (ProjectID)
Unique identifier of the Project this object belongs to..
- state: string processing, authorized, declined, settled, authentication_pending
State of the card payin.
processing
: The card payin is being processedauthorized
: The card issuer has authorized the payment, but it's not settled yet (the funds aren't in the destination account yet).declined
: The card issuer has declined the payment.settled
: The payment has been settled, which means the funds have been received in the destination account.authentication_pending
: The card payin has been created, but needs authentication to complete. Only happens whenauthentication_type
isthree_d_secure
orthree_d_secure_2
and not offline.cancelled
: The card payin which was inauthentication_pending
state has been cancelled.
- card_id: string (CardID)
Card used for the payment. Non-null if the CardPayin was created with a Card, null if the CardPayin was created with
card_info
or CardToken.- card_info: CardInfo
Card info used for the payment.
- account_id: string (AccountID)
Account the card payin funds will be received in.
- transaction_id: string (TransactionID)
Transaction receiving the funds of the card payin. Only present when
state
issettled
.- calculated_statement_descriptor: string
The statement descriptor of the card payin that will appear in the bank extract. This will be build from the suffix is provided or from the static statement descriptor.
- authentication_type: string none, three_d_secure
Type of authentication (None, or 3DSecure)
- authentication_url: string
URL to perform authentication
- authentication_redirect_url: string
URL to redirect to after authentication.
- value: Value
Value of the payment
- refunded_value: Value
Total value of all the refunds issued so far. Zero if no refund has been issued, equal to
value
if the entire payin has been refunded.- meta: Meta
Metadata for this object.
Example
{
"id": "string (CardPayinID)",
"created_at": "string (date-time)",
"project_id": "string (ProjectID)",
"state": "string",
"card_id": "string (CardID)",
"card_info": {
"number": "string (card)",
"expiration_month": 12,
"expiration_year": 2023,
"brand": "visa",
"fingerprint": "yFe94Qso636auIaB"
},
"account_id": "string (AccountID)",
"transaction_id": "string (TransactionID)",
"calculated_statement_descriptor": "Kernel Payments",
"authentication_type": "string",
"authentication_url": "https://gateway.kernelpay.com/start/910932071",
"authentication_redirect_url": "https://example.com/checkout",
"value": {
"currency": "EUR",
"amount": 100
},
"refunded_value": {
"currency": "EUR",
"amount": 100
},
"meta": {
"key1": "value1",
"key2": "value2"
}
}
CardPayinRefund: object
- id: string (CardPayinRefundID)
Unique identifier
- created_at: string (date-time)
Creation time for this object
- project_id: string (ProjectID)
Unique identifier of the Project this object belongs to..
- card_payin_id: string (CardPayinID)
Card payin the refund applies to.
- state: string processing, completed, failed
State of the refund.
processing
: The refund is being processed.completed
: The refund has been completed.failed
: The refund has failed.
- transaction_id: string (TransactionID)
ID of the transaction that removes the funds from the card payin account.
- failure_transaction_id: string (TransactionID)
ID of the transaction returning the funds to the card payin account if the refund failed.
- value: Value
Value of the refund. Positive, and the currency must match the CardPayin currency.
Example
{
"id": "string (CardPayinRefundID)",
"created_at": "string (date-time)",
"project_id": "string (ProjectID)",
"card_payin_id": "string (CardPayinID)",
"state": "string",
"transaction_id": "string (TransactionID)",
"failure_transaction_id": "string (TransactionID)",
"value": {
"currency": "EUR",
"amount": 100
}
}
CardPayinDispute: object
- id: string (CardPayinDisputeID)
Unique identifier
- created_at: string (date-time)
Creation time for this object
- project_id: string (ProjectID)
Unique identifier of the Project this object belongs to..
- card_payin_id: string (CardPayinID)
Card payin the dispute applies to.
- state: string processing, completed, failed
State of the dispute.
needs_response
: The dispute needs an action to be taken.processing_response
: The action is being processed.won
: The dispute has been won.lost
: The dispute has been lost.
- transaction_id: string (TransactionID)
ID of the transaction that removes the funds from the card payin account.
- refund_transaction_id: string (TransactionID)
ID of the transaction returning the funds to the card payin account if the dispute has been won.
- value: Value
Value of the dispute. Positive, and the currency must match the CardPayin currency.
- meta: Meta
Metadata for this object.
Example
{
"id": "string (CardPayinDisputeID)",
"created_at": "string (date-time)",
"project_id": "string (ProjectID)",
"card_payin_id": "string (CardPayinID)",
"state": "string",
"transaction_id": "string (TransactionID)",
"refund_transaction_id": "string (TransactionID)",
"value": {
"currency": "EUR",
"amount": 100
},
"meta": {
"key1": "value1",
"key2": "value2"
}
}
BankAccountInfo: object
- iban: string
Bank account number in IBAN format. Must be given wihout spaces.
- beneficiary_name: string
Full name of the account holder.
Example
{
"iban": "ES9121000418450200051332",
"beneficiary_name": "Pepito Martinez"
}
BankAccount: object
- id: string (BankAccountID)
Unique identifier
- created_at: string (date-time)
Creation time for this object
- project_id: string (ProjectID)
Unique identifier of the Project this object belongs to..
- customer_id: string (CustomerID)
Customer this bank account belongs to. If null, the bank account belongs to you, the project owner.
- bank_account_info: BankAccountInfo
- meta: Meta
Metadata for this object.
Example
{
"id": "string (BankAccountID)",
"created_at": "string (date-time)",
"project_id": "string (ProjectID)",
"customer_id": "string (CustomerID)",
"bank_account_info": {
"iban": "ES9121000418450200051332",
"beneficiary_name": "Pepito Martinez"
},
"meta": {
"key1": "value1",
"key2": "value2"
}
}
BankPayin: object
- id: string (BankPayinID)
Unique identifier
- created_at: string (date-time)
Creation time for this object
- project_id: string (ProjectID)
Unique identifier of the Project this object belongs to..
- bank_payin_reference_id: string (BankPayinReferenceID)
Reference that was used in the bank transfer for this BankPayin.
- account_id: string (AccountID)
Account this BankPayin was credited to.
- transaction_id: string (TransactionID)
Transaction for this BankPayin.
- concept: string
Concept of the incoming bank transfer for this BankPayin. Contains the reference, and potentially other info the sender included.
- value: Value
Value of the Bank Payin. Always positive.
- meta: Meta
Metadata for this object.
Example
{
"id": "string (BankPayinID)",
"created_at": "string (date-time)",
"project_id": "string (ProjectID)",
"bank_payin_reference_id": "string (BankPayinReferenceID)",
"account_id": "string (AccountID)",
"transaction_id": "string (TransactionID)",
"concept": "string",
"value": {
"currency": "EUR",
"amount": 100
},
"meta": {
"key1": "value1",
"key2": "value2"
}
}
BankPayinReference: object
- id: string (BankPayinReferenceID)
Unique identifier
- created_at: string (date-time)
Creation time for this object
- project_id: string (ProjectID)
Unique identifier of the Project this object belongs to..
- account_id: string (AccountID)
Account this BankPayin was credited to.
- reference: string
Reference code that must be included in incoming bank transfers' concepts.
- meta: Meta
Metadata for this object.
Example
{
"id": "string (BankPayinReferenceID)",
"created_at": "string (date-time)",
"project_id": "string (ProjectID)",
"account_id": "string (AccountID)",
"reference": "string",
"meta": {
"key1": "value1",
"key2": "value2"
}
}
BankPayout: object
- id: string (TransferID)
Unique identifier
- created_at: string (date-time)
Creation time for this object
- project_id: string (ProjectID)
Unique identifier of the Project this object belongs to..
- account_id: string (AccountID)
Source Kernel Payments account for the bank payout.
- bank_account_info: BankAccountInfo
Destination bank account info for the bank payout.
- bank_account_id: string (BankAccountID)
Destination bank account for the bank payout. Can be null if the BankPayout was created specifying
bank_account_info
.- transaction_id: string (TransactionID)
Transaction removing the funds from the source account.
- failure_transaction_id: string (TransactionID)
Transaction returning the funds from the source account. Will be non-null if
state
isfailed
orrefunded
.- state: string processing, completed, failed, refunded
State of the bank payout.
processing
: The bank transfer is being processed.completed
: The bank transfer has been successfully sent. Note that the destination bank can still send a refund transfer back, days later. There is no upper time limit for the destination bank to send a refund.failed
: The bank transfer sending has failed.refunded
: The bank transfer was successfully sent, but we received a refund transfer from the destination bank.
- concept: string
Bank transfer concept. This message is attached to the bank transfer and will be visible to the receiver. To make sure bank networks don't cut it, try to keep it under 20 characters.
- miniref: string
Mini reference ID. 4-6 characters. This is included in the bank transfer's concept, and is used to distinguish different transfers to the same IBAN.
Minirefs are unique per destination IBAN for 1 year (i.e. it is guaranteed that there won't be two BankPayouts to the same IBAN with the same miniref less than 1 year apart.). They are NOT globally unique.
- value: Value
Value of the refund. Must be positive.
- processed_at: string (date-time)
When the bank transfer was either completed or failed.
- meta: Meta
Metadata for this object.
Example
{
"id": "string (TransferID)",
"created_at": "string (date-time)",
"project_id": "string (ProjectID)",
"account_id": "string (AccountID)",
"bank_account_info": {
"iban": "ES9121000418450200051332",
"beneficiary_name": "Pepito Martinez"
},
"bank_account_id": "string (BankAccountID)",
"transaction_id": "string (TransactionID)",
"failure_transaction_id": "string (TransactionID)",
"state": "string",
"concept": "string",
"miniref": "string",
"value": {
"currency": "EUR",
"amount": 100
},
"processed_at": "string (date-time)",
"meta": {
"key1": "value1",
"key2": "value2"
}
}
File: object
- id: string (FileID)
Unique identifier
- created_at: string (date-time)
Creation time for this object
- project_id: string (ProjectID)
Unique identifier of the Project this object belongs to..
- hash: string (base64)
Hash of the file data. You can use this to see if two files are identical.
- name: string
Original file name of the upload
- size: integer
Size of the file in bytes
- url: string
URL where the file can be downloaded. This URL is signed, so it can be accessed without additional authentication. It expires after 1 hour of retrieval.
This can be useful to display files in your internal dashboard, for example.
Example
{
"id": "string (FileID)",
"created_at": "string (date-time)",
"project_id": "string (ProjectID)",
"hash": "i62oqkyWBN+pLiaz6u5GiwdKoryjIqW93GqpVtGOaiM=",
"name": "IMG_20170823_001.jpg",
"size": 1938718,
"url": "https://storage.googleapis.com/kernel-files/b159cb9ce9d85a1dd9861fd105?Expires=1527184040&Signature=atgUlHzFKyS..."
}
Event: object
- id: string (EventID)
Unique identifier
- created_at: string (date-time)
Creation time for this object
- project_id: string (ProjectID)
Unique identifier of the Project this object belongs to..
- type: string card_payin_dispute_created, card_payin_settled, bank_payin_created, bank_payout_completed, bank_payout_failed, bank_payout_refunded, card_payin_dispute_won, card_payin_dispute_lost, card_payin_authorized, card_payin_declined, transfer_created
Event type.
- payload: object
Event payload. The format depends on the event type.
Example
{
"id": "string (EventID)",
"created_at": "string (date-time)",
"project_id": "string (ProjectID)",
"type": "bank_payin_created",
"payload": {
"bank_payin": {
"id": "bpi_3merk33gt7ml3ltq5bg1",
"created_at": "2018-03-13T16:56:51.766836837Z",
"project_id": "prj_3merk33gt1v9ypgfzrp1",
"bank_payin_reference_id": "bpir_3merk33gt21kym11een1",
"account_id": "acc_3merk33gt3l525ryhcmh",
"transaction_id": "tx_3merk33gt345nu3dnkmh",
"concept": "string",
"value": {
"currency": "EUR",
"amount": 100
},
"meta": {
"key1": "value1",
"key2": "value2"
}
}
}
}
CardPayinDisputeCreatedEvent: object
- card_payin_dispute: CardPayinDispute
Card payin dispute that was just created
Example
{
"card_payin_dispute": {
"id": "string (CardPayinDisputeID)",
"created_at": "string (date-time)",
"project_id": "string (ProjectID)",
"card_payin_id": "string (CardPayinID)",
"state": "string",
"transaction_id": "string (TransactionID)",
"refund_transaction_id": "string (TransactionID)",
"value": {
"currency": "EUR",
"amount": 100
},
"meta": {
"key1": "value1",
"key2": "value2"
}
}
}
CardPayinSettledEvent: object
- card_payin: CardPayin
Card payin that was just settled
Example
{
"card_payin": {
"id": "string (CardPayinID)",
"created_at": "string (date-time)",
"project_id": "string (ProjectID)",
"state": "string",
"card_id": "string (CardID)",
"card_info": {
"number": "string (card)",
"expiration_month": 12,
"expiration_year": 2023,
"brand": "visa",
"fingerprint": "yFe94Qso636auIaB"
},
"account_id": "string (AccountID)",
"transaction_id": "string (TransactionID)",
"calculated_statement_descriptor": "Kernel Payments",
"authentication_type": "string",
"authentication_url": "https://gateway.kernelpay.com/start/910932071",
"authentication_redirect_url": "https://example.com/checkout",
"value": {
"currency": "EUR",
"amount": 100
},
"refunded_value": {
"currency": "EUR",
"amount": 100
},
"meta": {
"key1": "value1",
"key2": "value2"
}
}
}
BankPayinCreatedEvent: object
- bank_payin: BankPayin
Bank payin that was just created
Example
{
"bank_payin": {
"id": "string (BankPayinID)",
"created_at": "string (date-time)",
"project_id": "string (ProjectID)",
"bank_payin_reference_id": "string (BankPayinReferenceID)",
"account_id": "string (AccountID)",
"transaction_id": "string (TransactionID)",
"concept": "string",
"value": {
"currency": "EUR",
"amount": 100
},
"meta": {
"key1": "value1",
"key2": "value2"
}
}
}
BankPayoutCompletedEvent: object
- bank_payout: BankPayout
Bank payout that was completed
Example
{
"bank_payout": {
"id": "string (TransferID)",
"created_at": "string (date-time)",
"project_id": "string (ProjectID)",
"account_id": "string (AccountID)",
"bank_account_info": {
"iban": "ES9121000418450200051332",
"beneficiary_name": "Pepito Martinez"
},
"bank_account_id": "string (BankAccountID)",
"transaction_id": "string (TransactionID)",
"failure_transaction_id": "string (TransactionID)",
"state": "string",
"concept": "string",
"miniref": "string",
"value": {
"currency": "EUR",
"amount": 100
},
"processed_at": "string (date-time)",
"meta": {
"key1": "value1",
"key2": "value2"
}
}
}
BankPayoutFailedEvent: object
- bank_payout: BankPayout
Bank payout that was failed
Example
{
"bank_payout": {
"id": "string (TransferID)",
"created_at": "string (date-time)",
"project_id": "string (ProjectID)",
"account_id": "string (AccountID)",
"bank_account_info": {
"iban": "ES9121000418450200051332",
"beneficiary_name": "Pepito Martinez"
},
"bank_account_id": "string (BankAccountID)",
"transaction_id": "string (TransactionID)",
"failure_transaction_id": "string (TransactionID)",
"state": "string",
"concept": "string",
"miniref": "string",
"value": {
"currency": "EUR",
"amount": 100
},
"processed_at": "string (date-time)",
"meta": {
"key1": "value1",
"key2": "value2"
}
}
}
BankPayoutRefundedEvent: object
- bank_payout: BankPayout
Bank payout that was refunded
Example
{
"bank_payout": {
"id": "string (TransferID)",
"created_at": "string (date-time)",
"project_id": "string (ProjectID)",
"account_id": "string (AccountID)",
"bank_account_info": {
"iban": "ES9121000418450200051332",
"beneficiary_name": "Pepito Martinez"
},
"bank_account_id": "string (BankAccountID)",
"transaction_id": "string (TransactionID)",
"failure_transaction_id": "string (TransactionID)",
"state": "string",
"concept": "string",
"miniref": "string",
"value": {
"currency": "EUR",
"amount": 100
},
"processed_at": "string (date-time)",
"meta": {
"key1": "value1",
"key2": "value2"
}
}
}
CardPayinDisputeWonEvent: object
- card_payin_dispute: CardPayinDispute
Card payin dispute that was won
Example
{
"card_payin_dispute": {
"id": "string (CardPayinDisputeID)",
"created_at": "string (date-time)",
"project_id": "string (ProjectID)",
"card_payin_id": "string (CardPayinID)",
"state": "string",
"transaction_id": "string (TransactionID)",
"refund_transaction_id": "string (TransactionID)",
"value": {
"currency": "EUR",
"amount": 100
},
"meta": {
"key1": "value1",
"key2": "value2"
}
}
}
CardPayinDisputeLostEvent: object
- card_payin_dispute: CardPayinDispute
Card payin dispute that was lost
Example
{
"card_payin_dispute": {
"id": "string (CardPayinDisputeID)",
"created_at": "string (date-time)",
"project_id": "string (ProjectID)",
"card_payin_id": "string (CardPayinID)",
"state": "string",
"transaction_id": "string (TransactionID)",
"refund_transaction_id": "string (TransactionID)",
"value": {
"currency": "EUR",
"amount": 100
},
"meta": {
"key1": "value1",
"key2": "value2"
}
}
}
CardPayinAuthorizedEvent: object
- card_payin: CardPayin
Card payin that was just authorized
Example
{
"card_payin": {
"id": "string (CardPayinID)",
"created_at": "string (date-time)",
"project_id": "string (ProjectID)",
"state": "string",
"card_id": "string (CardID)",
"card_info": {
"number": "string (card)",
"expiration_month": 12,
"expiration_year": 2023,
"brand": "visa",
"fingerprint": "yFe94Qso636auIaB"
},
"account_id": "string (AccountID)",
"transaction_id": "string (TransactionID)",
"calculated_statement_descriptor": "Kernel Payments",
"authentication_type": "string",
"authentication_url": "https://gateway.kernelpay.com/start/910932071",
"authentication_redirect_url": "https://example.com/checkout",
"value": {
"currency": "EUR",
"amount": 100
},
"refunded_value": {
"currency": "EUR",
"amount": 100
},
"meta": {
"key1": "value1",
"key2": "value2"
}
}
}
CardPayinDeclinedEvent: object
- card_payin: CardPayin
Card payin that was just declined
Example
{
"card_payin": {
"id": "string (CardPayinID)",
"created_at": "string (date-time)",
"project_id": "string (ProjectID)",
"state": "string",
"card_id": "string (CardID)",
"card_info": {
"number": "string (card)",
"expiration_month": 12,
"expiration_year": 2023,
"brand": "visa",
"fingerprint": "yFe94Qso636auIaB"
},
"account_id": "string (AccountID)",
"transaction_id": "string (TransactionID)",
"calculated_statement_descriptor": "Kernel Payments",
"authentication_type": "string",
"authentication_url": "https://gateway.kernelpay.com/start/910932071",
"authentication_redirect_url": "https://example.com/checkout",
"value": {
"currency": "EUR",
"amount": 100
},
"refunded_value": {
"currency": "EUR",
"amount": 100
},
"meta": {
"key1": "value1",
"key2": "value2"
}
}
}
TransferCreatedEvent: object
- transfer: Transfer
Transfer that was just created
Example
{
"transfer": {
"id": "string (TransferID)",
"created_at": "string (date-time)",
"project_id": "string (ProjectID)",
"source_account_id": "string (AccountID)",
"source_transaction_id": "string (TransactionID)",
"destination_account_id": "string (AccountID)",
"destination_transaction_id": "string (TransactionID)",
"value": {
"currency": "EUR",
"amount": 100
},
"meta": {
"key1": "value1",
"key2": "value2"
}
}
}
Webhook: object
- id: string (WebhookID)
Unique identifier
- created_at: string (date-time)
Creation time for this object
- project_id: string (ProjectID)
Unique identifier of the Project this object belongs to..
- event_types: object
Event types to receive
- card_payin_dispute_created: boolean
- card_payin_settled: boolean
- bank_payin_created: boolean
- bank_payout_completed: boolean
- bank_payout_failed: boolean
- bank_payout_refunded: boolean
- card_payin_dispute_won: boolean
- card_payin_dispute_lost: boolean
- card_payin_authorized: boolean
- card_payin_declined: boolean
- transfer_created: boolean
- url: string
URL to send events to. Supports
http
andhttps
.- secret: string
Secret key used to sign webhook deliveries.
- is_enabled: boolean
Whether this webhook is enabled or not. Disabled webhooks do not send notifications, and can be re-enabled later.
Example
{
"id": "string (WebhookID)",
"created_at": "string (date-time)",
"project_id": "string (ProjectID)",
"event_types": {
"card_payin_dispute_created": true,
"card_payin_settled": true,
"bank_payin_created": true,
"bank_payout_completed": true,
"bank_payout_failed": true,
"bank_payout_refunded": true,
"card_payin_dispute_won": true,
"card_payin_dispute_lost": true,
"card_payin_authorized": true,
"card_payin_declined": true,
"transfer_created": true
},
"url": "https://api.example.com/v1/webhook_receiver",
"secret": "463edba8b57b37eebce1364b2d22fab8a4e4b60a8aa247db",
"is_enabled": true
}